에이전트 승인 및 보안

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가 포함되어 있어야 합니다.

샌드박스 및 승인

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 도구 호출에 파괴적 주석이 표시되어 있으면 항상 승인이 필요합니다. 단, 읽기 주석도 표시된 경우에는 읽기 주석이 우선합니다.

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

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

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

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

네트워크 액세스

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 켜짐: 네트워크가 계속 켜져 있으며 아웃바운드 트래픽이 구성된 네트워크 정책의 제한을 받습니다.

프록시 기능은 권한 프로필에도 적용됩니다. 프로필의 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 서버 연결, 브라우저 또는 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는 디렉터리로 존재할 때 읽기 전용으로 보호됩니다.
• 보호는 재귀적으로 적용되므로 해당 경로 아래의 모든 항목이 읽기 전용입니다.

승인 프롬프트 없이 실행

--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"

전체 검토 수명 주기, 트리거 조건, 구성 우선순위 및 실패 동작은 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을 사용하세요. Codex는 이전 codex exec --full-auto 호출을 더 이상 권장되지 않는 호환성 경로로 유지하고 경고를 출력합니다.

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 는 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 구성을 위한 영구 마운트
• 컨테이너가 필요한 기능을 부여할 때 Codex가 Linux 샌드박스를 계속 사용할 수 있도록 하는 bubblewrap

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

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 샌드박스를 활성화된 상태로 유지합니다.
• 컨테이너가 의도한 보안 경계라면 컨테이너 내부에서 --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 보안 설정을 구성할 수 있습니다. 설정 및 정책에 관한 자세한 내용은 해당 페이지를 참조하세요.