에이전트 승인 및 보안

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

기본적으로 에이전트는 네트워크 액세스가 꺼진 상태에서 실행됩니다. 로컬에서 Codex는 운영체제가 강제하는 샌드박스를 사용해 접근 범위를 제한합니다. 일반적으로 현재 워크스페이스까지만 접근할 수 있습니다. 승인 정책은 Codex가 작업을 멈추고 사용자에게 먼저 승인을 요청해야 하는 시점을 정합니다.

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와 dot에서는 관리형 정책이 활성화되어 있으면 Global에서 지원하는 정책이 공유 클라우드 오케스트레이터에 적용됩니다. Work 클라우드 컨테이너와 dot 클라우드 컴퓨터에는 각각 자체 실행 설정과 요구 사항이 적용됩니다. 로컬과 클라우드 제어를 따로 테스트하세요. 승인과 웹 검색을 비롯한 오케스트레이터 제어는 Global에서 관리하세요. 허용할 승인 정책과 웹 검색 모드를 지정하는 전용 설정이 있으면 해당 설정을 사용하고, 그 밖의 지원 필드에는 TOML을 사용하세요. Work Cloud를 통한 로컬 컴퓨터 액세스에 Codex 예시를 적용하기 전에 설정 레퍼런스에서 필드 목록과 실행 범위를 확인하세요.

데스크톱, 웹, 모바일 간에 전환해도 다른 컴퓨터에 접근할 권한이 생기지는 않습니다. 동기화를 켜거나 접근 범위를 넓히기 전에 Agent Security의 기본 보안 정책을 검토하고 각 실행 환경에서 허용되는 작업과 차단되는 작업을 하나씩 테스트하세요. 관리형 설정을 참고하세요.

Codex에서는 다음 두 계층이 함께 보안을 제어합니다.

• 샌드박스 모드: 모델이 생성한 명령어를 실행할 때 Codex가 수행할 수 있는 작업 범위를 정합니다. 예를 들어 쓰기가 가능한 위치와 네트워크 접근 가능 여부를 결정합니다.
• 승인 정책: Codex가 어떤 작업을 실행하기 전에 사용자에게 승인을 요청해야 하는지 정합니다. 예를 들어 샌드박스 밖에서 실행하거나, 네트워크를 사용하거나, 신뢰하는 명령어 집합에 없는 명령어를 실행하는 경우입니다.

Codex가 사용하는 샌드박스 모드는 실행 환경에 따라 다릅니다.

• Codex Cloud(레거시): OpenAI가 관리하는 격리된 컨테이너에서 실행되므로 호스트 시스템이나 작업과 무관한 데이터에 접근할 수 없습니다. 실행 과정은 두 단계로 나뉩니다. 먼저 설정 단계에서 네트워크에 접근해 지정된 종속성을 설치할 수 있습니다. 이어지는 에이전트 단계는 해당 환경에서 인터넷 액세스를 활성화하지 않는 한 기본적으로 오프라인으로 실행됩니다. 클라우드 환경에 설정한 시크릿은 설정 단계에서만 사용할 수 있으며 에이전트 단계가 시작되기 전에 제거됩니다.
• 현재 Codex Cloud: 설정 단계와 작업 실행 중에 자격 증명을 처리하는 방법은 환경 변수 및 네트워크 시크릿을 참고하세요.
• Codex CLI / IDE 확장 프로그램: 운영체제 수준에서 샌드박스 정책을 강제합니다. 기본적으로 네트워크 액세스는 꺼져 있고 쓰기 권한은 현재 워크스페이스로 제한됩니다. 허용할 위험 수준에 맞게 샌드박스, 승인 정책, 네트워크 설정을 구성할 수 있습니다.

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

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

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

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

GPT-6 Astra는 Codex와 ChatGPT Work에서 안전 모니터링을 제공합니다. 모니터링은 비동기로 실행되며 잠재적으로 위험한 모델 행동을 감지하면 작업을 일시 중지할 수 있습니다. 원인이 된 활동이 일어난 뒤에 작업이 일시 중지될 수 있습니다. 모니터링을 사용하더라도 샌드박스, 권한 제어, 결과 검토는 여전히 필요합니다.

작업이 일시 중지되면 안내를 읽고 보안 이슈가 제공되는 경우 그 내용을 검토하세요. 작업을 안전하게 계속할 수 있는지 확인한 뒤에만 재개하세요. 안내에 작업이 종료되었다고 표시되거나 재개 옵션이 없으면 해당 인터페이스에서는 작업을 재개할 수 없습니다.

안전 모니터링은 작업 중에 모델의 행동을 평가합니다. 자동 승인 검토는 이미 승인이 필요한 개별 동작을 실행 전에 평가합니다. 자동 승인 검토에서 승인된 동작이 포함된 작업도 이후 모니터링을 통해 일시 중지될 수 있습니다.

네트워크 액세스 Elevated Risk

현재 Codex Cloud의 네트워크 설정은 서비스 연결을 참고하세요. Codex Cloud(레거시)에서 전체 인터넷 액세스를 허용하거나 도메인 허용 목록을 사용하려면 에이전트 인터넷 액세스를 참고하세요.

ChatGPT 데스크톱 앱, Codex CLI, IDE 확장 프로그램의 기본 workspace-write 샌드박스 모드에서는 다음과 같이 설정에서 활성화하지 않는 한 네트워크 액세스가 꺼져 있습니다.

[sandbox_workspace_write]
network_access = true

네트워크 격리

Codex Cloud에서 지원하는 관리형 실행 경로에서는 Agent Security 요구 사항이 명령어의 네트워크 사용을 제한합니다. Codex Cloud 환경의 인터넷 설정은 별도로 적용됩니다. Agent Security에서 도메인을 허용해도 클라우드 환경의 인터넷 설정에서 제한하면 접근할 수 없습니다. 명령어에 적용되는 이러한 네트워크 제어만으로는 호스팅된 웹 검색, 앱 또는 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'

이 기능은 이미 활성화된 네트워크 액세스에 정책을 적용하는 방식을 바꿉니다. 기능을 켜는 것만으로 네트워크 권한이 부여되지는 않습니다. 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를 설정하세요.
• 와일드카드: 와일드카드 규칙은 명시적인 로컬 예외로 인정되지 않습니다.
• DNS 조회 결과: 호스트 이름이 허용 목록과 일치하더라도 조회 결과가 로컬 또는 사설 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가 디렉터리로 존재하면 읽기 전용으로 보호됩니다.
• <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 = { ... } }를 사용하세요. 특정 유형의 승인 요청은 사용자가 직접 처리하고 나머지는 자동으로 거부하도록 설정할 수 있습니다. 세분화된 정책은 샌드박스 승인, 실행 정책 규칙에 따른 요청, 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 도구 호출이 포함됩니다. 명령어 규칙에 따라 샌드박스 안에서 실행하는 명령어도 검토가 필요할 수 있습니다.

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

로컬 환경이나 조직 전체에서 검토 정책을 교체하려면 자동 검토 설정을 참고하세요.

ChatGPT 데스크톱 앱에서는 이러한 검토가 자동 검토 항목으로 표시되며 검토 중, 승인, 거부, 중단, 시간 초과 등의 상태를 확인할 수 있습니다. 검토한 요청의 위험 수준과 사용자의 허가 여부에 대한 평가도 표시될 수 있습니다.

자동 검토는 모델을 추가로 호출하므로 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).

운영체제 수준의 샌드박스

Codex가 샌드박스를 강제하는 방식은 운영체제에 따라 다릅니다.

• macOS에서는 Seatbelt 정책을 사용합니다. sandbox-exec로 명령어를 실행하며 프로필(-p)은 선택한 --sandbox 모드에 따라 결정됩니다. 읽기 액세스를 제한하면서 플랫폼 기본값을 활성화하면 Codex는 /System에 대한 접근을 광범위하게 허용하는 대신 선별된 macOS 플랫폼 정책을 추가해 일반적으로 사용하는 도구와의 호환성을 유지합니다.
• Linux에서는 기본적으로 bwrap과 seccomp를 함께 사용합니다.
• Windows에서는 MXC를 지원하며, 대체 수단으로 기존 elevated 및 unelevated 구현을 사용할 수 있습니다. Linux용 Windows 하위 시스템 2(WSL2)에서 Codex는 Linux 샌드박스 구현을 사용합니다. WSL1은 Codex 0.114까지 지원되었습니다. 0.115부터 Linux 샌드박스가 bwrap으로 전환되어 WSL1은 더 이상 지원되지 않습니다.

Windows용 Codex IDE 확장 프로그램은 WSL2를 직접 지원합니다. WSL2를 사용할 수 있을 때마다 에이전트가 WSL2 안에서 실행되도록 VS Code 설정에 다음 항목을 지정하세요.

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

이렇게 하면 호스트 운영체제가 Windows여도 IDE 확장 프로그램에서 명령어 실행, 승인, 파일 시스템 액세스에 Linux 샌드박스와 동일한 규칙이 적용됩니다. 자세한 내용은 WSL 가이드를 참고하세요.

Windows에서 기기와 정책이 MXC를 지원한다면 config.toml에 다음 설정을 추가해 MXC를 우선 사용하세요.

[features]
prefer_mxc = true

MXC를 사용할 수 없는 경우에 대비해 windows.sandbox에는 정책이 허용하는 기존 구현을 지정해 두세요. 설정 방법과 호환성 제한은 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 및 호환 도구에서 이 방식을 사용할 수 있습니다.

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

• Dev Container 프로필이 bwrap으로 내부 샌드박스를 만드는 데 필요한 권한을 부여한다면 Codex의 Linux 샌드박스를 켜 두세요.
• 컨테이너를 보안 경계로 사용하려면 컨테이너 안에서 --sandbox danger-full-access로 Codex를 실행하세요. 그러면 Codex가 두 번째 샌드박스 계층을 만들려고 시도하지 않습니다.

버전 관리

버전 관리 워크플로우를 사용하면 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 설정에 [otel] 블록을 추가하세요. 설정 파일은 일반적으로 ~/.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는 이벤트를 일괄 처리하며 종료 시 버퍼에 남은 이벤트를 내보냅니다. 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에서 민감한 내용을 가리세요.
• 로컬 데이터 보관 설정(예: history.persistence / history.max_bytes)을 검토해 Codex가 CODEX_HOME 아래에 세션 기록을 저장할지 제어하세요. 고급 설정과 설정 레퍼런스를 참고하세요.
• 네트워크 액세스를 끈 상태에서 CLI를 실행하면 OTel 데이터를 수집기로 보낼 수 없습니다. 내보내려면 workspace-write 모드에서 OTel 엔드포인트에 대한 네트워크 액세스를 허용하거나, 수집기 도메인을 허용 목록에 추가한 뒤 Codex Cloud에서 내보내세요.
• 이벤트를 주기적으로 검토해 승인 또는 샌드박스 설정이 변경되었는지, 예상하지 못한 도구 실행이 있었는지 확인하세요.

OTel은 선택 사항이며 위에서 설명한 샌드박스 및 승인 보호 기능을 보완합니다. 이러한 보호 기능을 대체하지는 않습니다.

관리형 설정

엔터프라이즈 관리자는 관리형 설정에서 워크스페이스의 Codex 보안 설정을 구성할 수 있습니다. 설정 방법과 정책 세부 정보는 해당 페이지를 참고하세요.