에이전트 승인 및 보안

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

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

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

지원이 종료된 untrusted 승인 정책에서 마이그레이션

Codex와 ChatGPT Work는 더 이상 approval_policy = "untrusted"를 지원하지 않습니다. 지원이 종료된 이 설정 때문에 두 클라이언트 모두 시작하지 못할 수 있습니다. 사용자 또는 프로젝트 구성, 프로필 파일, 시작 스크립트, 관리되는 기본값에서 이 설정을 제거합니다. 대화형 읽기 전용으로 사용하려면 다음과 같이 설정합니다.

sandbox_mode = "read-only"
approval_policy = "on-request"

또는 codex --sandbox read-only --ask-for-approval on-request를 실행합니다.

on-request를 사용하면 샌드박스에서 허용된 명령은 승인 없이 실행되고, 접근 가능한 파일을 읽으며, 네트워크 접근이 활성화되어 있다면 네트워크를 사용할 수 있습니다.

더 엄격한 명령 승인 규칙을 유지하려면 명시적인 approval_policy 설정을 생략하고 사용자 수준의 ~/.codex/config.toml에 프로젝트 항목을 추가합니다.

[projects."/path/to/project"]
trust_level = "untrusted"

그러면 실행 정책 규칙에서 허용하지 않는 명령에는 승인이 필요합니다. 프로젝트 로컬 구성도 비활성화됩니다. on-request를 명시적으로 설정하면 프로젝트에서 도출된 정책보다 우선합니다. 이 프로젝트 정책을 허용하려면 관리되는 allowed_approval_policies에 untrusted가 포함되어 있어야 합니다.

샌드박스 및 승인

Work Cloud를 통한 로컬 컴퓨터 액세스에는 로컬 실행과 클라우드 실행을 위한 별도의 정책이 있습니다.

• 클라우드 실행: Work 클라우드 컨테이너는 기존 Work Cloud 정책을 사용합니다.
• 로컬 실행: 로컬 실행 요구 사항은 연결된 컴퓨터에 적용됩니다. MDM 및 기존 관리형 기기 요구 사항은 Agent Security보다 우선하며, Agent Security는 기기의 시스템 요구 사항 파일보다 우선합니다.

로컬 액세스를 사용하는 Work와 dots에서는 관리형 정책이 활성화되어 있을 때 지원되는 Global 정책이 공유 클라우드 오케스트레이터에 적용됩니다. Work 클라우드 컨테이너와 dots 클라우드 컴퓨터는 자체 실행 구성과 요구 사항을 사용합니다. 로컬 제어와 클라우드 제어를 별도로 테스트하세요. 승인과 웹 검색을 포함한 오케스트레이터 제어는 Global에 유지하세요. 사용 가능한 경우 전용 허용 승인 정책 및 허용 웹 검색 모드 제어를 사용하고, 그 외 지원되는 필드에는 TOML을 사용하세요. Codex 예제를 Work Cloud의 로컬 컴퓨터 액세스에 적용하기 전에 구성 참조에서 필드 목록과 실행 범위를 확인하세요.

데스크톱, 웹, 모바일 간에 전환해도 다른 컴퓨터에 대한 액세스 권한이 부여되지는 않습니다. 동기화를 활성화하거나 액세스 범위를 확장하기 전에 Agent Security 기준을 검토하고 각 실행 환경에서 허용된 작업과 차단된 작업을 테스트하세요. 관리형 구성을 참조하세요.

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

• 샌드박스 모드: 모델이 생성한 명령을 실행할 때 Codex가 기술적으로 수행할 수 있는 작업을 결정합니다. 예를 들어 쓰기 가능한 위치와 네트워크 접근 가능 여부를 제어합니다.
• 승인 정책: Codex가 작업을 실행하기 전에 사용자에게 물어봐야 하는 시점을 결정합니다. 예를 들어 샌드박스를 벗어나거나 네트워크를 사용하거나 신뢰할 수 있는 집합에 속하지 않는 명령을 실행하는 경우입니다.

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

• Codex Cloud (Legacy): OpenAI가 관리하는 격리된 컨테이너에서 실행되어 호스트 시스템이나 관련 없는 데이터에 대한 액세스를 방지합니다. 런타임은 두 단계로 구성됩니다. 에이전트 단계 전에 설정 단계가 실행되며, 이 단계에서는 지정된 종속성을 설치하기 위해 네트워크에 액세스할 수 있습니다. 이후 에이전트 단계는 해당 환경의 인터넷 액세스를 활성화하지 않는 한 기본적으로 오프라인으로 실행됩니다. 클라우드 환경에 구성된 시크릿은 설정 단계에서만 사용할 수 있으며 에이전트 단계가 시작되기 전에 제거됩니다.
• 현재 Codex Cloud: 설정 및 작업 중 자격 증명이 처리되는 방식은 환경 변수 및 네트워크 시크릿을 참조하세요.
• Codex CLI / IDE 확장 프로그램: OS 수준의 메커니즘이 샌드박스 정책을 강제 적용합니다. 기본적으로 네트워크 액세스가 차단되며 쓰기 권한은 활성 작업 공간으로 제한됩니다. 위험 허용 수준에 따라 샌드박스, 승인 정책, 네트워크 설정을 구성할 수 있습니다.

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

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

작업이 셸 명령이나 파일 변경이 아니더라도 앱(커넥터) 도구 호출에 부작용이 있다고 표시되어 있으면 Codex가 승인을 요청할 수도 있습니다. 앱/MCP 도구 호출에 파괴적 주석이 표시되어 있으면 항상 승인이 필요합니다. 단, 읽기 주석도 표시된 경우에는 읽기 주석이 우선합니다.

안전 모니터링 및 일시 중지된 작업

GPT-6 Astra는 Codex와 ChatGPT Work에 안전 모니터링 기능을 포함합니다. 모니터링은 비동기식으로 실행되며 잠재적으로 안전하지 않은 모델 동작을 감지하면 작업을 일시 중지할 수 있습니다. 일시 중지는 이를 촉발한 활동 이후에 발생할 수 있습니다. 모니터링은 샌드박싱, 권한 또는 결과 검토를 대체하지 않습니다.

작업이 일시 중지되면 알림을 읽고 조사 결과가 제공될 때 이를 검토하세요. 작업을 안전하게 계속할 수 있는지 확인한 후에만 재개하세요. 알림에 작업이 종료되었다고 표시되거나 재개 옵션이 없으면 해당 화면에서는 작업을 재개할 수 없습니다.

안전 모니터링은 작업 중 모델 동작을 평가합니다. 자동 승인 검토는 개별 작업이 실행되기 전에 이미 승인이 필요한 작업을 평가합니다. 자동 승인 검토에서 승인된 작업도 나중에 모니터링으로 일시 중지되는 작업의 일부일 수 있습니다.

네트워크 액세스 위험 증가

현재 Codex Cloud의 네트워크 설정은 서비스 연결을 참조하세요. Codex Cloud (Legacy)에서 전체 인터넷 액세스 또는 도메인 허용 목록을 활성화하려면 에이전트 인터넷 액세스를 참조하세요.

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

[sandbox_workspace_write]
network_access = true

네트워크 격리

지원되는 관리형 Codex Cloud 실행 경로에서는 Agent Security 요구 사항이 명령의 네트워크 통신을 제한합니다. Codex Cloud 환경의 인터넷 설정은 별도로 적용됩니다. Agent Security에서 허용된 도메인이라도 Cloud 환경의 인터넷 설정에 있는 제한을 무시할 수는 없습니다. 이러한 명령 네트워크 제어만으로는 호스팅 웹 검색, 앱 또는 MCP가 비활성화되지 않습니다. ChatGPT Work Cloud는 별도의 기능 권한을 사용하며 이러한 Agent Security 요구 사항을 상속하지 않습니다.

관리형 명령 허용 목록은 관리형 프록시를 사용하는 명령에 적용됩니다. 정책이 샌드박스 권한의 전면적인 상향을 허용하고 승인이 이루어지면 해당 실행은 명령 프록시를 우회할 수 있습니다. 제한적인 네트워크 권한 부여는 샌드박스 권한의 전면적인 상향과 다릅니다. 의도한 경계에 맞게 강제 적용할 승인 및 샌드박스 요구 사항을 구성하고, 일반 명령과 권한이 상향된 명령을 모두 테스트하세요. 관리형 구성을 참조하세요.

네트워크 액세스는 명령이 생성한 스크립트, 프로그램 및 하위 프로세스에 적용되는 대상 규칙을 통해 제어됩니다. 명령의 네트워크 액세스가 이미 활성화된 경우 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 켜짐: 네트워크가 계속 켜져 있으며 아웃바운드 트래픽이 구성된 네트워크 정책의 제한을 받습니다.

프록시 기능은 권한 프로필에도 적용됩니다. 프로필의 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 server 연결, 브라우저 또는 Computer Use 활동, Codex cloud 작업이나 클라이언트의 모델 및 인증 요청은 필터링하지 않습니다. 이러한 화면은 별도의 서비스 연결, 기능 설정, 워크스페이스 정책 또는 환경 제어를 사용합니다.

브라우저 도구는 오리진에 접근하기 전에 관리형 네트워크 거부 목록과 배타적 허용 목록을 별도로 확인합니다. 브라우저 오리진 정책은 사이트 액세스, 업로드, 다운로드 및 개발자 도구를 추가로 제한할 수 있습니다. 관리형 브라우저 제어를 참조하세요.

관리형 사용자의 경우 명령 네트워크 정책을 allowed_web_search_modes, 승인된 mcp_servers 및 앱, 플러그인, 브라우저 또는 Computer Use의 기능 요구 사항 같은 제어와 함께 사용하세요. 관리형 구성을 참조하세요.

생성된 명령에 전체 네트워크 액세스를 부여하지 않고도 웹 검색 도구를 제어할 수 있습니다. 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는 디렉터리로 존재할 때 읽기 전용으로 보호됩니다.
• <writable_root>/.aws는 디렉터리로 존재할 때 읽기 전용으로 보호됩니다.
• 보호는 재귀적으로 적용되므로 해당 경로 아래의 모든 항목이 읽기 전용입니다.

승인 프롬프트 없이 실행

--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 데스크톱 앱에서 이러한 검토는 Reviewing, Approved, Denied, Aborted 또는 Timed out 같은 상태를 가진 자동 검토 항목으로 표시됩니다. 검토된 요청의 위험 수준과 사용자 승인 평가도 포함될 수 있습니다.

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

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

비대화형 실행에는 codex exec --sandbox workspace-write를 사용합니다.

config.toml의 구성

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

# Interactive approvals with a read-only sandbox
approval_policy = "on-request"
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 는 MXC를 지원하며, elevated과 unelevated을 레거시 대체 수단으로 제공합니다. Windows Subsystem for Linux 2 (WSL2)에서 Codex는 Linux 샌드박스 구현을 사용합니다. WSL1은 Codex 0.114까지 지원되었습니다. 0.115부터 Linux 샌드박스가 bwrap로 전환되었으므로 WSL1은 더 이상 지원되지 않습니다.

Windows에서 Codex IDE 확장 프로그램을 사용하면 WSL2를 직접 지원합니다. WSL2를 사용할 수 있을 때 에이전트가 항상 WSL2 내부에서 작동하도록 VS Code 설정에서 다음 항목을 지정하세요.

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

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

Windows에서 실행할 때 장치와 정책이 MXC를 지원한다면 config.toml에 다음을 설정하여 MXC를 우선 사용하세요.

[features]
prefer_mxc = true

대체 구현으로 사용할 수 있도록 windows.sandbox에 허용된 기존 구현을 유지합니다. 구성 및 호환성 제한은 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 및 호환 도구에서 작동합니다.

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

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

• Dev Container 프로필이 bwrap에서 내부 샌드박스를 생성하는 데 필요한 기능을 부여한다면 Codex의 Linux 샌드박스를 활성화된 상태로 유지합니다.
• 컨테이너가 의도한 보안 경계라면 컨테이너 내부에서 --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 활성화(옵트인)

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 내보내기가 수집기에 도달할 수 없습니다. 내보내려면 workspace-write 모드에서 OTel 엔드포인트에 대한 네트워크 액세스를 허용하거나 승인된 목록에 수집기 도메인을 추가한 상태로 Codex cloud에서 내보내세요.
• 승인/샌드박스 변경 및 예기치 않은 도구 실행이 있는지 이벤트를 주기적으로 검토하세요.

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

관리형 구성

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