에이전트 승인 및 보안

Codex는 코드와 데이터를 보호하고 오용 위험을 줄이는 데 도움이 됩니다.

기본적으로 에이전트는 네트워크 액세스가 꺼진 상태로 실행됩니다. 로컬에서 Codex는 접근할 수 있는 범위(일반적으로 현재 워크스페이스)를 제한하는 OS 강제 샌드박스와, 작업 전에 언제 중지하고 사용자에게 승인을 요청해야 하는지를 제어하는 승인 정책을 함께 사용합니다.

ChatGPT 데스크톱 앱, Codex CLI, IDE 확장 프로그램 전반에서 샌드박싱이 작동하는 방식에 관한 개괄적인 설명은 샌드박싱을 참조하세요. 더 폭넓은 엔터프라이즈 보안 개요는 Codex 보안 백서를 참조하세요.

샌드박스 및 승인

Codex 보안 제어는 함께 작동하는 두 계층으로 구성됩니다.

• 샌드박스 모드: 모델이 생성한 명령을 실행할 때 Codex가 기술적으로 수행할 수 있는 작업(예: 쓸 수 있는 위치 및 네트워크 접근 가능 여부)을 정합니다.
• 승인 정책: Codex가 작업을 실행하기 전에 사용자에게 승인을 요청해야 하는 시점(예: 샌드박스 이탈, 네트워크 사용 또는 신뢰할 수 있는 집합 외부의 명령 실행)을 정합니다.

Codex는 실행되는 위치에 따라 서로 다른 샌드박스 모드를 사용합니다.

• Codex cloud: 격리된 OpenAI 관리 컨테이너에서 실행되어 호스트 시스템이나 관련 없는 데이터에 접근하지 못하도록 합니다. 2단계 런타임 모델을 사용합니다. 설정은 에이전트 단계 전에 실행되며 지정된 종속 항목을 설치하기 위해 네트워크에 접근할 수 있습니다. 이후 에이전트 단계는 해당 환경에서 인터넷 액세스를 활성화하지 않는 한 기본적으로 오프라인으로 실행됩니다. 클라우드 환경에 구성된 비밀 정보는 설정 중에만 사용할 수 있으며 에이전트 단계가 시작되기 전에 제거됩니다.
• Codex CLI / IDE 확장 프로그램: OS 수준 메커니즘으로 샌드박스 정책을 강제합니다. 기본 설정에서는 네트워크에 접근할 수 없으며 쓰기 권한은 활성 워크스페이스로 제한됩니다. 위험 허용 수준에 따라 샌드박스, 승인 정책 및 네트워크 설정을 구성할 수 있습니다.

Auto 프리셋(예: --sandbox workspace-write --ask-for-approval on-request)에서 Codex는 작업 디렉터리의 파일을 읽고, 수정하고, 명령을 자동으로 실행할 수 있습니다.

Codex는 워크스페이스 외부의 파일을 수정하거나 네트워크 액세스가 필요한 명령을 실행할 때 승인을 요청합니다. 변경하지 않고 대화하거나 계획을 세우려면 /permissions 명령으로 read-only 모드로 전환하세요.

Codex는 작업이 셸 명령이나 파일 변경이 아니더라도 부작용이 있다고 명시된 앱(커넥터) 도구 호출에 대한 승인을 요청할 수도 있습니다. 앱/MCP 도구에 파괴적 작업이라는 주석이 명시되어 있으면 다른 힌트(예: 읽기 전용 힌트)도 함께 명시되어 있더라도 파괴적 도구 호출에는 항상 승인이 필요합니다.

네트워크 액세스

Codex cloud에서 전체 인터넷 액세스 또는 도메인 허용 목록을 활성화하려면 에이전트 인터넷 액세스를 참조하세요.

ChatGPT 데스크톱 앱, Codex CLI 또는 IDE 확장 프로그램에서는 구성에서 활성화하지 않는 한 기본 workspace-write 샌드박스 모드가 네트워크 액세스를 꺼진 상태로 유지합니다.

[sandbox_workspace_write]
network_access = true

네트워크 격리

네트워크 액세스는 명령이 생성한 스크립트, 프로그램 및 하위 프로세스에 적용되는 대상 규칙을 통해 제어됩니다. 명령의 네트워크 액세스가 이미 활성화되어 있으면 해당 트래픽을 구성한 네트워크 정책으로 제한하도록 network_proxy 기능을 켜세요.

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

일회성 CLI 세션에서는 전환 기능만 필요할 때 불리언 축약형을 사용하고, 정책 옵션도 함께 설정할 때는 테이블 형식을 사용하세요.

codex \
  -c 'features.network_proxy=true' \
  -c 'sandbox_workspace_write.network_access=true'

codex \
  -c 'features.network_proxy.enabled=true' \
  -c 'features.network_proxy.domains={ "api.openai.com" = "allow", "example.com" = "deny" }' \
  -c 'sandbox_workspace_write.network_access=true'

이 기능은 활성화된 네트워크 액세스를 적용하는 방식을 변경하지만, 그 자체로 네트워크 액세스 권한을 부여하지는 않습니다. 명령의 네트워크 액세스 허용 여부를 결정하려면 workspace-write 구성과 함께 sandbox_workspace_write.network_access을 사용하세요.

• 네트워크 꺼짐 + network_proxy 켜짐: 네트워크가 계속 꺼져 있으며 이 기능은 아무 작업도 하지 않습니다.
• 네트워크 켜짐 + network_proxy 꺼짐: 네트워크가 제한 없는 직접 아웃바운드 액세스가 가능한 상태로 유지됩니다.
• 네트워크 켜짐 + network_proxy 켜짐: 네트워크가 계속 켜져 있으며 아웃바운드 트래픽은 구성된 네트워크 정책의 제약을 받습니다.

관리자가 관리하는 experimental_network 요구 사항은 사용자 기능 전환과 별개입니다. 이러한 요구 사항은 features.network_proxy 없이 샌드박스 네트워킹을 구성하고 시작할 수 있지만, 활성 샌드박스가 네트워크 액세스를 차단하고 있다면 이를 켜지는 않습니다. 관리자 측 requirements.toml 구조는 관리형 구성을 참조하세요.

네트워크 정책

도메인 규칙은 허용 목록 우선 방식입니다.

• 정확한 호스트는 해당 호스트 자체에만 일치합니다.
• *.example.com은 api.example.com 같은 하위 도메인과 일치하지만 example.com과는 일치하지 않습니다.
• **.example.com은 루트 도메인과 하위 도메인 모두에 일치합니다.
• 전역 * 허용 규칙은 거부되지 않은 모든 공개 호스트와 일치합니다. *을 광범위한 네트워크 액세스로 간주하고 가능하면 범위가 한정된 규칙을 사용하세요.
• deny은 항상 allow보다 우선하며, 전역 *은 허용 규칙에만 유효합니다.

로컬 및 비공개 대상

기본적으로 allow_local_binding = false은 루프백, 링크 로컬 및 비공개 대상을 차단합니다.

• 특정 예외: 명령에 특정 로컬 대상이 필요한 경우 정확한 로컬 IP 리터럴 또는 localhost 허용 규칙을 추가하세요.
• 더 광범위한 액세스: 의도적으로 더 넓은 로컬/비공개 범위에 접근하려는 경우에만 allow_local_binding = true을 설정하세요.
• 와일드카드: 와일드카드 규칙은 명시적인 로컬 예외로 간주되지 않습니다.
• 확인된 주소: 허용 목록과 일치하더라도 로컬/비공개 IP로 확인되는 호스트 이름은 계속 차단됩니다.

DNS 리바인딩 보호

호스트 이름을 허용하기 전에 Codex는 최선의 방식으로 DNS 및 IP 분류 검사를 수행합니다.

• 실패하거나 시간 초과된 조회는 차단됩니다.
• 공개되지 않은 주소로 확인되는 호스트 이름은 차단됩니다.
• 이 검사는 DNS 리바인딩 위험을 줄이지만 완전히 제거하지는 못합니다. 리바인딩을 완전히 방지하려면 전송 계층 전체에서 확인된 IP를 고정해야 합니다.

악성 DNS가 위협 범위에 포함된다면 더 낮은 계층에서도 이그레스 제어를 적용하세요.

위험한 설정

다음 두 설정은 의도적으로 신뢰 경계를 확장합니다.

• dangerously_allow_non_loopback_proxy = true은 프록시 리스너를 루프백 외부에 노출할 수 있습니다.
• dangerously_allow_all_unix_sockets = true은 Unix 소켓 허용 목록을 우회합니다.

엄격히 통제된 환경에서만 사용하세요. Unix 소켓 프록시가 활성화되면 비루프백 바인딩을 요청했더라도 리스너는 루프백 전용으로 유지되므로, 샌드박스 네트워킹이 로컬 데몬으로 연결되는 원격 브리지가 되지 않습니다.

network_proxy은 기본적으로 꺼져 있습니다. 활성화하면 다음과 같이 작동합니다.

생성된 명령에 전체 네트워크 액세스 권한을 부여하지 않고 웹 검색 도구를 별도로 제어할 수도 있습니다. Codex는 기본적으로 웹 검색 캐시를 사용하여 결과에 접근합니다. 이 캐시는 OpenAI에서 유지 관리하는 웹 결과 인덱스이므로 캐시 모드에서는 실시간 페이지를 가져오는 대신 미리 색인된 결과를 반환합니다. 이렇게 하면 임의의 실시간 콘텐츠에서 발생할 수 있는 프롬프트 인젝션에 대한 노출을 줄일 수 있지만, 웹 결과는 여전히 신뢰할 수 없는 것으로 취급해야 합니다. --yolo 또는 다른 전체 액세스 샌드박스 설정을 사용하는 경우 웹 검색은 기본적으로 실시간 결과를 사용합니다. 실시간 탐색을 허용하려면 --search를 사용하거나 web_search = "live"을 설정하고, 도구를 끄려면 "disabled"로 설정하세요.

web_search = "cached"  # default
# web_search = "disabled"
# web_search = "live"  # same as --search

외부 웹 액세스를 검색 인덱스로 제한해야 할 때는 web_search = "indexed"을 설정하세요. Codex에서 네트워크 액세스 또는 웹 검색을 활성화할 때는 주의하세요. 프롬프트 인젝션으로 인해 에이전트가 신뢰할 수 없는 지침을 가져와 따를 수 있습니다.

기본값 및 권장 사항

• Codex는 시작할 때 폴더가 버전 관리되는지 감지하고 다음과 같이 권장합니다.
  • 버전 관리 폴더: Auto(워크스페이스 쓰기 + 요청 시 승인)
  • 버전 관리되지 않는 폴더: read-only
• 설정에 따라 작업 디렉터리를 명시적으로 신뢰할 때까지(예: 온보딩 프롬프트 또는 /permissions를 통해) Codex가 read-only에서 시작할 수도 있습니다.
• 워크스페이스에는 현재 디렉터리와 /tmp 같은 임시 디렉터리가 포함됩니다. 워크스페이스에 속한 디렉터리를 확인하려면 /status 명령을 사용하세요.
• 기본값을 적용하려면 codex를 실행하세요.
• 다음 항목을 명시적으로 설정할 수 있습니다.
  • codex --sandbox workspace-write --ask-for-approval on-request
  • codex --sandbox read-only --ask-for-approval on-request

쓰기 가능한 루트의 보호된 경로

기본 workspace-write 샌드박스 정책에서도 쓰기 가능한 루트에는 보호된 경로가 포함됩니다.

• <writable_root>/.git은 디렉터리로 존재하든 파일로 존재하든 읽기 전용으로 보호됩니다.
• <writable_root>/.git가 포인터 파일(gitdir: ...)인 경우, 확인된 Git 디렉터리 경로도 읽기 전용으로 보호됩니다.
• <writable_root>/.agents이 디렉터리로 존재하면 읽기 전용으로 보호됩니다.
• <writable_root>/.codex가 디렉터리로 존재하면 읽기 전용으로 보호됩니다.
• 보호는 재귀적으로 적용되므로 해당 경로 아래의 모든 항목이 읽기 전용입니다.

승인 프롬프트 없이 실행하기

--ask-for-approval never 또는 약식인 -a never를 사용하여 승인 프롬프트를 비활성화할 수 있습니다.

이 옵션은 모든 --sandbox 모드에서 작동하므로 Codex의 자율성 수준을 계속 제어할 수 있습니다. Codex는 사용자가 설정한 제약 조건 안에서 최선을 다합니다.

승인 프롬프트 없이 Codex가 파일을 읽고, 편집하고, 네트워크 액세스가 필요한 명령을 실행하도록 하려면 --sandbox danger-full-access(또는 --dangerously-bypass-approvals-and-sandbox 플래그)을 사용하세요. 이 옵션을 사용하기 전에 주의 깊게 검토하세요.

절충안으로 approval_policy = { granular = { ... } }을 사용하면 특정 승인 프롬프트 범주는 대화형으로 유지하면서 나머지는 자동으로 거부할 수 있습니다. 세분화된 정책은 샌드박스 승인, execpolicy 규칙 프롬프트, MCP 프롬프트, request_permissions 프롬프트 및 스킬 스크립트 승인을 다룹니다.

자동 승인 검토

기본적으로 승인 요청은 사용자에게 전달됩니다.

approvals_reviewer = "user"

자동 승인 검토는 approval_policy = "on-request" 또는 세분화된 승인 정책처럼 승인이 대화형인 경우에 적용됩니다. Codex가 요청을 실행하기 전에 검토 에이전트를 통해 검토 대상 승인 요청을 처리하도록 하려면 approvals_reviewer = "auto_review"을 설정하세요.

approval_policy = "on-request"
approvals_reviewer = "auto_review"

검토자의 전체 수명 주기, 트리거 조건, 구성 우선순위 및 실패 동작은 자동 검토를 참조하세요.

검토자는 샌드박스 권한 상승, 차단된 네트워크 요청, request_permissions 프롬프트 또는 부작용이 발생하는 앱 및 MCP 도구 호출처럼 이미 승인이 필요한 작업만 평가합니다. 샌드박스 내부에서 이루어지는 작업은 추가 검토 단계 없이 계속 진행됩니다.

검토자 정책은 데이터 유출, 자격 증명 탐색, 지속적인 보안 약화 및 파괴적인 작업 여부를 확인합니다. 정책에서 허용하는 경우 위험도가 낮거나 중간인 작업은 진행할 수 있습니다. 정책은 매우 위험한 작업을 거부합니다. 위험도가 높은 작업을 실행하려면 충분한 사용자 승인이 있어야 하며 일치하는 거부 규칙이 없어야 합니다. 프롬프트 생성, 검토 세션 및 구문 분석이 실패하면 안전을 위해 요청이 거부됩니다. 시간 초과는 별도로 표시되며, 이 경우에도 작업은 실행되지 않습니다.

기본 검토자 정책은 오픈 소스 Codex 저장소에 있습니다. 엔터프라이즈에서는 관리형 요구 사항의 guardian_policy_config을 사용하여 테넌트별 섹션을 대체할 수 있습니다. 로컬 [auto_review].policy 텍스트도 지원되지만 관리형 요구 사항이 우선합니다. 설정에 관한 자세한 내용은 관리형 구성을 참조하세요.

ChatGPT 데스크톱 앱에서 이러한 검토는 검토 중, 승인됨, 거부됨, 중단됨 또는 시간 초과 등의 상태가 있는 자동 검토 항목으로 표시됩니다. 검토된 요청의 위험 수준 및 사용자 승인 평가가 함께 표시될 수도 있습니다.

자동 검토는 추가 모델 호출을 사용하므로 Codex 사용량이 증가할 수 있습니다. 관리자는 allowed_approvals_reviewers을 사용하여 이를 제한할 수 있습니다.

일반적인 샌드박스 및 승인 조합

비대화형 실행에는 codex exec --sandbox workspace-write을 사용하세요. Codex는 이전 codex exec --full-auto 호출을 더 이상 권장되지 않는 호환성 경로로 유지하며 경고를 출력합니다.

--ask-for-approval untrusted을 사용하면 Codex는 안전한 것으로 알려진 읽기 작업만 자동으로 실행합니다. 상태를 변경하거나 외부 실행 경로를 트리거할 수 있는 명령(예: 파괴적인 Git 작업 또는 Git 출력/구성 재정의 플래그)에는 승인이 필요합니다.

config.toml에서 구성하기

더 광범위한 구성 워크플로는 구성 기본 사항, 고급 구성 및 구성 참조를 참조하세요.

# Always ask for approval mode
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false # optional hardening: disallow login shells for shell-based tools

# Optional: Allow network in workspace-write mode
[sandbox_workspace_write]
network_access = true

# Optional: granular approval policy
# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

사전 설정을 프로필 파일로 저장한 다음 codex --profile profile-name을 사용해 선택할 수도 있습니다.

# ~/.codex/full_auto.config.toml
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

# ~/.codex/readonly_quiet.config.toml
approval_policy = "never"
sandbox_mode    = "read-only"

로컬에서 샌드박스 테스트하기

Codex 샌드박스에서 명령을 실행할 때 어떤 일이 발생하는지 확인하려면 다음 Codex CLI 명령을 사용하세요.

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--permissions-profile <name>] [COMMAND]...
# Windows
codex sandbox windows [--permissions-profile <name>] [COMMAND]...

sandbox 명령은 codex debug로도 사용할 수 있으며, 플랫폼 도우미에도 별칭이 있습니다(예: codex sandbox seatbelt 및 codex sandbox landlock).

OS 수준 샌드박스

Codex는 사용 중인 OS에 따라 샌드박스를 다르게 적용합니다.

• macOS는 Seatbelt 정책을 사용하며, 선택한 --sandbox 모드에 해당하는 프로필(-p)과 함께 sandbox-exec을 사용하여 명령을 실행합니다. 제한된 읽기 액세스에서 플랫폼 기본값을 활성화하면 Codex는 일반적인 도구 호환성을 유지하기 위해 /System을 광범위하게 허용하는 대신 엄선된 macOS 플랫폼 정책을 추가합니다.
• Linux는 기본적으로 bwrap과 seccomp을 사용합니다.
• Windows는 Windows Subsystem for Linux 2 (WSL2)에서 실행할 때 Linux 샌드박스 구현을 사용합니다. WSL1은 Codex 0.114까지 지원되었습니다. 0.115부터 Linux 샌드박스가 bwrap로 이전되었으므로 WSL1은 더 이상 지원되지 않습니다. Windows에서 네이티브로 실행할 때 Codex는 Windows 샌드박스 구현을 사용합니다.

Windows에서 Codex IDE 확장을 사용하는 경우 WSL2가 직접 지원됩니다. WSL2를 사용할 수 있을 때 에이전트가 항상 WSL2 내부에서 실행되도록 VS Code 설정에서 다음 항목을 지정하세요.

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

이렇게 하면 호스트 OS가 Windows인 경우에도 IDE 확장이 명령, 승인 및 파일 시스템 액세스에 Linux 샌드박스 의미 체계를 적용합니다. 자세한 내용은 WSL 가이드를 참조하세요.

Windows에서 네이티브로 실행할 때는 config.toml에서 네이티브 샌드박스 모드를 구성하세요.

[windows]
sandbox = "unelevated" # or "elevated"
# sandbox_private_desktop = true  # default; set false only for compatibility

자세한 내용은 Windows 설정 가이드를 참조하세요.

Docker와 같은 컨테이너화된 환경에서 Linux를 실행할 때 호스트 또는 컨테이너 구성이 Codex에 필요한 네임스페이스, setuid bwrap 또는 seccomp 작업을 차단하면 샌드박스가 작동하지 않을 수 있습니다.

이 경우 필요한 격리를 제공하도록 Docker 컨테이너를 구성한 다음 컨테이너 내부에서 --sandbox danger-full-access(또는 --dangerously-bypass-approvals-and-sandbox 플래그)과 함께 codex을 실행하세요.

Dev Containers에서 Codex 실행하기

호스트에서 Linux 샌드박스를 직접 실행할 수 없거나 조직에서 이미 컨테이너 기반 개발을 표준으로 사용하는 경우 Dev Containers에서 Codex를 실행하고 Docker가 외부 격리 경계를 제공하도록 하세요. 이 방식은 Visual Studio Code Dev Containers 및 호환 도구에서 작동합니다.

Codex 보안 devcontainer 예제를 참조 구현으로 사용하세요. 이 예제는 Codex, 일반적인 개발 도구, bubblewrap 및 방화벽 기반 아웃바운드 제어를 설치합니다.

참조 구현에는 다음이 포함됩니다.

• Codex와 일반적인 개발 도구가 설치된 Ubuntu 24.04 기본 이미지
• 아웃바운드 액세스를 위한 허용 목록 기반 방화벽 프로필
• 컨테이너에서 작업 영역을 다시 열기 위한 VS Code 설정 및 확장 프로그램 권장 사항
• 명령 기록과 Codex 구성을 위한 영구 마운트
• bubblewrap. 컨테이너에서 필요한 기능을 허용할 때 Codex가 Linux 샌드박스를 계속 사용할 수 있도록 합니다.

사용해 보려면 다음 단계를 따르세요.

1. Visual Studio Code와 Dev Containers 확장 프로그램을 설치합니다.
2. Codex 예제 .devcontainer 설정을 저장소에 복사하거나 Codex 저장소에서 직접 시작합니다.
3. VS Code에서 **Dev Containers: Open Folder in Container...**를 실행하고 .devcontainer/devcontainer.secure.json을 선택합니다.
4. 컨테이너가 시작되면 터미널을 열고 codex을 실행합니다.

CLI에서 컨테이너를 시작할 수도 있습니다.

devcontainer up --workspace-folder . --config .devcontainer/devcontainer.secure.json

이 예제는 다음 세 가지 주요 요소로 구성됩니다.

• .devcontainer/devcontainer.secure.json은 컨테이너 설정, 기능, 마운트, 환경 변수 및 VS Code 확장 프로그램을 제어합니다.
• .devcontainer/Dockerfile.secure은 Ubuntu 기반 이미지와 설치할 도구를 정의합니다.
• .devcontainer/init-firewall.sh은 아웃바운드 네트워크 정책을 적용합니다.

참조 방화벽은 의도적으로 출발점으로만 제공됩니다. 격리를 위해 도메인 허용 목록에 의존한다면 TTL 인식 갱신이나 DNS 인식 방화벽과 같이 환경에 적합한 DNS 리바인딩 및 DNS 갱신 보호 기능을 구현하세요.

컨테이너 내부에서는 다음 모드 중 하나를 선택하세요.

• Dev Container 프로필에서 bwrap이 내부 샌드박스를 만드는 데 필요한 기능을 허용한다면 Codex의 Linux 샌드박스를 활성화된 상태로 유지합니다.
• 컨테이너를 의도한 보안 경계로 사용하는 경우 Codex가 두 번째 샌드박스 계층을 만들려고 하지 않도록 컨테이너 안에서 --sandbox danger-full-access을 사용하여 Codex를 실행합니다.

버전 관리

Codex는 버전 관리 워크플로와 함께 사용할 때 가장 효과적입니다.

• 기능 브랜치에서 작업하고 위임하기 전에 git status을 깨끗한 상태로 유지하세요. 이렇게 하면 Codex 패치를 더 쉽게 분리하고 되돌릴 수 있습니다.
• 추적 중인 파일을 직접 편집하기보다 패치 기반 워크플로(예: git diff/git apply)를 사용하는 것이 좋습니다. 작은 단위로 롤백할 수 있도록 자주 커밋하세요.
• Codex 제안을 다른 PR과 동일하게 취급하세요. 대상별 검증을 실행하고, diff를 검토하며, 감사를 위해 커밋 메시지에 결정 사항을 기록하세요.

모니터링 및 텔레메트리

Codex는 팀이 로컬 보안 기본값을 약화하지 않으면서 사용 현황을 감사하고, 문제를 조사하며, 규정 준수 요구 사항을 충족할 수 있도록 OpenTelemetry(OTel)를 통한 옵트인 모니터링을 지원합니다. 텔레메트리는 기본적으로 꺼져 있으므로 구성에서 명시적으로 활성화해야 합니다.

개요

• Codex는 로컬 실행이 자체적으로 완결되도록 기본적으로 OTel 내보내기를 끕니다.
• 활성화하면 Codex는 채팅, API 요청, SSE/WebSocket 스트림 활동, 사용자 프롬프트(기본적으로 수정 처리됨), 도구 승인 결정 및 도구 결과를 다루는 구조화된 로그 이벤트를 내보냅니다.
• Codex는 개발/스테이징/프로덕션 트래픽을 구분할 수 있도록 내보낸 이벤트에 service.name(실행 주체), CLI 버전 및 환경 레이블을 태그로 지정합니다.

OTel 활성화(옵트인)

Codex 구성(일반적으로 ~/.codex/config.toml)에 [otel] 블록을 추가하고, 내보내기 도구와 프롬프트 텍스트 기록 여부를 선택합니다.

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false     # redact prompt text unless policy allows

• exporter = "none"은 계측을 활성 상태로 유지하지만 데이터를 어디에도 전송하지 않습니다.
• 자체 수집기로 이벤트를 보내려면 다음 중 하나를 선택하세요.

[otel]
exporter = { otlp-http = {
  endpoint = "https://otel.example.com/v1/logs",
  protocol = "binary",
  headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}

[otel]
exporter = { otlp-grpc = {
  endpoint = "https://otel.example.com:4317",
  headers = { "x-otlp-meta" = "abc123" }
}}

Codex는 이벤트를 일괄 처리하고 종료할 때 플러시합니다. Codex는 자체 OTel 모듈에서 생성된 텔레메트리만 내보냅니다.

이벤트 범주

대표적인 이벤트 유형은 다음과 같습니다.

• codex.conversation_starts(모델, 추론 설정, 샌드박스/승인 정책)
• codex.api_request(시도, 상태/성공 여부, 소요 시간 및 오류 세부 정보)
• codex.sse_event(스트림 이벤트 종류, 성공/실패, 소요 시간 및 response.completed의 토큰 수)
• codex.websocket_request 및 codex.websocket_event(요청 소요 시간과 메시지별 종류/성공 여부/오류)
• codex.user_prompt(길이. 명시적으로 활성화하지 않는 한 콘텐츠는 수정 처리됨)
• codex.tool_decision(승인/거부, 출처: 구성 또는 사용자)
• codex.tool_result(소요 시간, 성공 여부, 출력 일부)

관련 OTel 메트릭(카운터와 소요 시간 히스토그램 쌍)에는 codex.api_request, codex.sse_event, codex.websocket.request, codex.websocket.event 및 codex.tool.call(각각 해당하는 .duration_ms 계측 포함)이 있습니다.

전체 이벤트 카탈로그와 구성 참조는 GitHub의 Codex 구성 문서를 참조하세요.

보안 및 개인정보 보호 지침

• 정책에서 프롬프트 콘텐츠 저장을 명시적으로 허용하지 않는 한 log_user_prompt = false을 유지하세요. 프롬프트에는 소스 코드와 민감한 데이터가 포함될 수 있습니다.
• 텔레메트리는 직접 제어하는 수집기로만 전송하고, 규정 준수 요구 사항에 맞는 보존 한도와 액세스 제어를 적용하세요.
• 도구 인수와 출력을 민감한 정보로 취급하세요. 가능하면 수집기 또는 SIEM에서 수정 처리하는 것이 좋습니다.
• Codex가 CODEX_HOME 아래에 세션 기록을 저장하지 않게 하려면 로컬 데이터 보존 설정(예: history.persistence / history.max_bytes)을 검토하세요. 고급 구성과 구성 참조를 참조하세요.
• 네트워크 액세스가 꺼진 상태로 CLI를 실행하면 OTel 내보내기가 수집기에 연결할 수 없습니다. 내보내려면 OTel 엔드포인트에 대해 workspace-write 모드에서 네트워크 액세스를 허용하거나, 수집기 도메인을 승인 목록에 추가한 상태로 Codex cloud에서 내보내세요.
• 승인/샌드박스 변경 사항과 예기치 않은 도구 실행이 있는지 이벤트를 정기적으로 검토하세요.

OTel은 선택 사항이며 위에서 설명한 샌드박스 및 승인 보호 기능을 대체하는 것이 아니라 보완하도록 설계되었습니다.

관리형 구성

엔터프라이즈 관리자는 관리형 구성에서 작업 영역의 Codex 보안 설정을 구성할 수 있습니다. 설정 및 정책에 관한 자세한 내용은 해당 페이지를 참조하세요.