에이전트 승인 및 보안

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

기본적으로 에이전트는 네트워크 액세스가 꺼진 상태로 실행됩니다. 로컬에서 Codex는 OS가 적용하는 샌드박스로 접근 범위를 제한하며, 이 범위는 일반적으로 현재 워크스페이스입니다. 또한 승인 정책을 통해 작업을 실행하기 전에 중단하고 사용자에게 승인을 요청해야 하는 시점을 제어합니다.

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

샌드박스 및 승인

Codex의 보안 제어는 서로 연동되는 두 계층으로 구성됩니다:

• 샌드박스 모드: Codex가 모델이 생성한 명령어를 실행할 때 기술적으로 수행할 수 있는 작업을 결정합니다. 예를 들어 파일을 쓸 수 있는 위치와 네트워크에 액세스할 수 있는지를 제어합니다.
• 승인 정책: Codex가 작업을 실행하기 전에 사용자에게 승인을 요청해야 하는 시점을 결정합니다. 예를 들어 샌드박스를 벗어나거나 네트워크를 사용하거나 신뢰할 수 있는 집합에 포함되지 않은 명령어를 실행하는 경우에 적용됩니다.

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

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

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

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

Codex는 해당 작업이 셸 명령어나 파일 변경이 아니더라도 사이드 이펙트가 명시된 앱(커넥터) 도구 호출에 대해 승인을 요청할 수 있습니다. 도구에 파괴적 작업을 나타내는 어노테이션이 있으면 파괴적인 앱/MCP 도구 호출에는 항상 승인이 필요합니다. 단, 도구에 읽기 어노테이션도 있으면 읽기 어노테이션이 우선합니다.

네트워크 액세스 Elevated Risk

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

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'

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

• 네트워크 꺼짐 + network_proxy 켜짐: 네트워크는 계속 꺼져 있으며 이 기능은 아무런 영향을 주지 않습니다.
• 네트워크 켜짐 + network_proxy 꺼짐: 네트워크는 계속 켜져 있으며 제한 없이 직접 아웃바운드 액세스가 가능합니다.
• 네트워크 켜짐 + network_proxy 켜짐: 네트워크는 계속 켜져 있으며 아웃바운드 트래픽은 구성된 네트워크 정책에 따라 제한됩니다.

프록시 기능은 권한 프로필에도 적용됩니다. 프로필의 network.enabled = true 설정은 명령어의 네트워크 액세스를 허용하고, features.network_proxy = true 설정은 해당 프로필의 도메인 규칙 적용을 활성화합니다:

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
extends = ":workspace"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"

이 예시에서 프록시 기능을 생략하면 명령어가 네트워크에 직접 액세스하며 api.openai.com 허용 규칙은 접속 대상을 제한하지 않습니다.

관리자가 관리하는 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 기능은 기본적으로 꺼져 있습니다. 이를 활성화하면 다음과 같이 동작합니다:

명령어 네트워크 프록시 외부의 트래픽

네트워크 프록시는 로컬 명령어 샌드박스에서 실행되는 스크립트, 프로그램, 하위 프로세스를 필터링합니다. 웹 검색, 앱 또는 커넥터 도구 호출, MCP 서버 연결, 브라우저 또는 컴퓨터 사용 활동, Codex 클라우드 작업, 클라이언트의 모델 및 인증 요청은 필터링하지 않습니다. 이러한 기능에는 별도의 서비스 연결, 기능 설정, 워크스페이스 정책 또는 환경 제어가 적용됩니다.

관리 대상 사용자에게는 명령어 네트워크 정책을 allowed_web_search_modes, 승인된 mcp_servers, 앱, 플러그인, 브라우저 또는 컴퓨터 사용에 적용되는 기능 요구 사항 등의 제어 수단과 함께 적용하세요. 자세한 내용은 관리형 구성을 참조하세요.

실행되는 명령어에 전체 네트워크 액세스 권한을 부여하지 않고도 웹 검색 도구를 제어할 수 있습니다. 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
• 설정에 따라 Codex는 작업 디렉터리를 명시적으로 신뢰할 때까지 read-only 모드로 시작할 수도 있습니다(예: 온보딩 프롬프트 또는 /permissions).
• 워크스페이스에는 현재 디렉터리와 /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-rule 프롬프트, MCP 프롬프트, request_permissions 프롬프트, 스킬 스크립트 승인에 적용됩니다.

승인 요청 자동 검토

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

approvals_reviewer = "user"

승인 요청 자동 검토는 approval_policy = "on-request" 설정이나 세분화된 승인 정책처럼 승인이 대화형으로 처리되는 경우에 적용됩니다. approvals_reviewer = "auto_review"로 설정하면 검토 대상 승인 요청을 Codex가 작업을 실행하기 전에 검토 에이전트에게 전달할 수 있습니다:

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 호출을 사용 중단 예정(deprecated)인 호환성 경로로 유지하며 경고를 표시합니다.

--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 기반으로 전환되어 더 이상 지원되지 않습니다. 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 컨테이너를 구성한 다음, 컨테이너 안에서 codex를 --sandbox danger-full-access 옵션 또는 --dangerously-bypass-approvals-and-sandbox 플래그와 함께 실행하세요.

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 버전, 환경 레이블을 태그로 추가해 dev/staging/prod 트래픽을 구분합니다.

OTel 활성화(옵트인)

[otel] 블록을 Codex 구성(일반적으로 ~/.codex/config.toml)에 추가하고 익스포터와 프롬프트 텍스트 기록 여부를 선택하세요.

[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는 이벤트를 배치로 처리하고 종료 시 플러시합니다. 자체 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 데이터를 수집기로 내보낼 수 없습니다. 내보내려면 workspace-write 모드에서 OTel 엔드포인트에 대한 네트워크 액세스를 허용하거나, 수집기 도메인을 승인 목록에 추가한 후 Codex 클라우드에서 내보내세요.
• 승인이나 샌드박스 관련 변경 사항과 예상치 못한 도구 실행이 있는지 이벤트를 주기적으로 검토하세요.

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

관리형 구성

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