에이전트 승인과 보안

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

이 문서는 샌드박싱, 승인, 네트워크 접근을 포함해 Codex를 안전하게 운영하는 방법을 설명합니다.

기본적으로 에이전트는 네트워크 접근이 꺼진 상태로 실행됩니다. 로컬에서 Codex는 OS가 강제하는 샌드박스로 접근 범위를 제한하며, 보통 현재 workspace로 제한됩니다. 또한 승인 정책으로 Codex가 행동하기 전에 언제 멈추고 사용자에게 물어야 하는지 제어합니다.

Codex 앱, IDE 확장, CLI 전반에서 샌드박싱이 어떻게 동작하는지 상위 설명은 sandboxing을 참고하십시오. 더 넓은 엔터프라이즈 보안 개요는 Codex security white paper를 참고하십시오.

샌드박스와 승인

Codex 보안 제어는 함께 동작하는 두 계층에서 나옵니다.

• 샌드박스 모드: Codex가 모델이 생성한 명령을 실행할 때 기술적으로 무엇을 할 수 있는지 결정합니다. 예를 들어 어디에 쓸 수 있는지, 네트워크에 접근할 수 있는지를 제어합니다.
• 승인 정책: Codex가 작업을 실행하기 전에 언제 사용자에게 물어야 하는지 결정합니다. 예를 들어 샌드박스를 벗어나거나, 네트워크를 사용하거나, 신뢰된 집합 밖의 명령을 실행할 때입니다.

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

• Codex cloud: OpenAI가 관리하는 격리 container에서 실행되어 host system이나 관련 없는 데이터에 접근하지 못하게 합니다. 두 단계 runtime model을 사용합니다. Setup은 에이전트 단계 전에 실행되며 지정 dependency 설치를 위해 네트워크에 접근할 수 있습니다. 이후 agent phase는 해당 환경에 internet access를 켜지 않는 한 기본적으로 offline으로 실행됩니다. Cloud environment에 구성한 secret은 setup 중에만 사용할 수 있고 agent phase 시작 전 제거됩니다.
• Codex CLI / IDE 확장: OS-level mechanism이 샌드박스 정책을 강제합니다. 기본값에는 네트워크 접근 없음과 활성 workspace로 제한된 쓰기 권한이 포함됩니다. 위험 허용도에 따라 샌드박스, 승인 정책, 네트워크 설정을 구성할 수 있습니다.

Auto preset 예시인 --sandbox workspace-write --ask-for-approval on-request에서는 Codex가 작업 디렉터리에서 파일을 읽고, 편집하고, 명령을 자동 실행할 수 있습니다.

Codex는 workspace 밖 파일을 편집하거나 네트워크 접근이 필요한 명령을 실행하려면 승인을 요청합니다. 변경 없이 대화하거나 계획만 세우고 싶다면 /permissions 명령으로 read-only 모드로 전환합니다.

Codex는 shell 명령이나 파일 변경이 아니더라도 side effect를 advertise하는 app connector 도구 호출에 대해 승인을 요청할 수 있습니다. App/MCP 도구가 destructive annotation을 advertise하면, read-only hint 같은 다른 hint를 함께 advertise하더라도 destructive tool call은 항상 승인이 필요합니다.

네트워크 접근

Codex cloud에서 전체 internet access 또는 domain allow list를 켜는 방법은 agent internet access를 참고하십시오.

Codex 앱, CLI, IDE 확장에서 기본 workspace-write 샌드박스 모드는 구성에서 활성화하지 않는 한 네트워크 접근을 끕니다.

[sandbox_workspace_write]
network_access = true

생성된 명령에 전체 네트워크 접근을 부여하지 않고도 web search tool을 제어할 수 있습니다. Codex는 기본적으로 web search cache를 사용합니다. 이 cache는 OpenAI가 유지하는 웹 결과 index이므로 cached mode는 live page를 가져오는 대신 미리 index된 결과를 반환합니다. 임의 live content에서 오는 prompt injection 노출을 줄이지만, 웹 결과는 여전히 신뢰할 수 없는 것으로 취급해야 합니다. --yolo 또는 다른 full access sandbox 설정을 사용하면 웹 검색은 기본적으로 live 결과를 사용합니다. Live browsing을 허용하려면 --search를 사용하거나 web_search = "live"를 설정하고, 도구를 끄려면 "disabled"로 설정합니다.

web_search = "cached"  # 기본값
# web_search = "disabled"
# web_search = "live"  # --search와 동일

Codex에서 네트워크 접근이나 웹 검색을 켤 때는 주의하십시오. Prompt injection으로 에이전트가 신뢰할 수 없는 지침을 가져와 따를 수 있습니다.

기본값과 권장 사항

• 시작 시 Codex는 폴더가 version-controlled인지 감지하고 다음을 권장합니다.
  • Version-controlled 폴더: Auto, 즉 workspace write + on-request approvals
  • Version-controlled가 아닌 폴더: read-only
• 설정에 따라 Codex는 사용자가 작업 디렉터리를 명시적으로 신뢰할 때까지 read-only로 시작할 수도 있습니다. 예: onboarding prompt 또는 /permissions.
• Workspace에는 현재 디렉터리와 /tmp 같은 임시 디렉터리가 포함됩니다. Workspace에 포함된 디렉터리는 /status 명령으로 확인합니다.
• 기본값을 받아들이려면 codex를 실행합니다.
• 명시적으로 지정할 수도 있습니다.
  • codex --sandbox workspace-write --ask-for-approval on-request
  • codex --sandbox read-only --ask-for-approval on-request

Writable root의 보호 경로

기본 workspace-write 샌드박스 정책에서는 writable root 안에도 보호 경로가 있습니다.

• {writable_root}/.git은 디렉터리든 파일이든 read-only로 보호됩니다.
• {writable_root}/.git이 pointer file(gitdir: ...)이면 해석된 Git directory path도 read-only로 보호됩니다.
• {writable_root}/.agents가 디렉터리로 존재하면 read-only로 보호됩니다.
• {writable_root}/.codex가 디렉터리로 존재하면 read-only로 보호됩니다.
• 보호는 recursive이므로 해당 path 아래의 모든 항목이 read-only입니다.

파일 시스템 profile로 읽기 거부

Named permission profile은 정확한 path 또는 glob pattern에 대한 읽기도 거부할 수 있습니다. Workspace는 writable로 유지하면서 local environment file 같은 특정 민감 파일만 읽을 수 없게 해야 할 때 유용합니다.

default_permissions = "workspace"

[permissions.workspace.filesystem]
":project_roots" = { "." = "write", "**/*.env" = "none" }
glob_scan_max_depth = 3

Codex가 읽으면 안 되는 path 또는 glob에는 "none"을 사용합니다. 샌드박스 정책은 로컬 macOS와 Linux 명령 실행에서 glob을 평가합니다. 샌드박스 시작 전에 glob match를 미리 확장해야 하는 platform에서는 unbounded ** pattern에 glob_scan_max_depth를 설정하거나 *.env, */*.env, */*/*.env처럼 명시적 depth를 나열합니다.

승인 prompt 없이 실행

--ask-for-approval never 또는 축약형 -a never로 승인 prompt를 비활성화할 수 있습니다.

이 옵션은 모든 --sandbox 모드와 함께 동작하므로 Codex autonomy 수준은 계속 제어할 수 있습니다. Codex는 설정한 제약 안에서 최선 노력으로 작업합니다.

Codex가 승인 prompt 없이 파일을 읽고, 편집하고, 네트워크 접근이 있는 명령을 실행해야 한다면 --sandbox danger-full-access 또는 --dangerously-bypass-approvals-and-sandbox flag를 사용합니다. 사용 전 주의하십시오.

중간 지점이 필요하면 approval_policy = { granular = { ... } }를 사용해 특정 approval prompt category는 interactive로 유지하고 나머지는 자동 거절할 수 있습니다. Granular policy는 sandbox approval, execpolicy-rule prompt, MCP prompt, request_permissions prompt, skill-script approval을 다룹니다.

자동 승인 리뷰

기본적으로 승인 요청은 사용자에게 라우팅됩니다.

approvals_reviewer = "user"

자동 승인 리뷰는 approval_policy = "on-request" 또는 granular approval policy처럼 approval이 interactive인 경우 적용됩니다. 적격 승인 요청을 실행 전 reviewer agent로 보내려면 approvals_reviewer = "auto_review"를 설정합니다.

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

Reviewer lifecycle, trigger condition, 구성 우선순위, 실패 동작은 Auto-review를 참고하십시오.

Reviewer는 sandbox escalation, blocked network request, request_permissions prompt, side-effecting app/MCP tool call처럼 이미 승인이 필요한 action만 평가합니다. 샌드박스 안에 머무르는 action은 추가 review 없이 계속 진행됩니다.

Reviewer policy는 data exfiltration, credential probing, persistent security weakening, destructive action을 확인합니다. Low-risk와 medium-risk action은 policy가 허용하면 진행할 수 있습니다. Critical-risk action은 거부됩니다. High-risk action은 충분한 사용자 authorization이 있고 matching deny rule이 없어야 합니다. Prompt-build, review-session, parse failure는 fail closed됩니다. Timeout은 별도로 표시되며 action은 실행되지 않습니다.

기본 reviewer policy는 open-source Codex 저장소에 있습니다. Enterprise는 managed requirements의 guardian_policy_config로 tenant-specific 섹션을 대체할 수 있습니다. Local [auto_review].policy 텍스트도 지원되지만 managed requirements가 우선합니다.

Codex 앱에서는 이런 review가 Reviewing, Approved, Denied, Aborted, Timed out 같은 상태의 automatic review item으로 표시됩니다. Review된 request의 risk level과 user-authorization assessment도 포함될 수 있습니다.

Automatic review는 추가 모델 호출을 사용하므로 Codex 사용량이 늘 수 있습니다. Admin은 allowed_approvals_reviewers로 이를 제한할 수 있습니다.

자주 쓰는 샌드박스와 승인 조합

비대화형 실행에는 codex exec --sandbox workspace-write를 사용합니다. 기존 codex exec --full-auto 호출은 deprecated compatibility path로 유지되며 warning을 출력합니다.

--ask-for-approval untrusted에서는 Codex가 알려진 안전한 read operation만 자동 실행합니다. 상태를 바꾸거나 외부 실행 경로를 트리거할 수 있는 명령, 예를 들어 destructive Git operation이나 Git output/config-override flag는 승인이 필요합니다.

config.toml 구성

더 넓은 구성 workflow는 Config basics, Advanced Config, Configuration Reference를 참고하십시오.

# 항상 approval을 묻는 모드
approval_policy = "untrusted"
sandbox_mode    = "read-only"
allow_login_shell = false # hardening: shell 기반 도구의 login shell 거부

[sandbox_workspace_write]
network_access = true

# approval_policy = { granular = {
#   sandbox_approval = true,
#   rules = true,
#   mcp_elicitations = true,
#   request_permissions = false,
#   skill_approval = false
# } }

Preset을 profile로 저장한 뒤 codex --profile {name}으로 선택할 수도 있습니다.

[profiles.full_auto]
approval_policy = "on-request"
sandbox_mode    = "workspace-write"

[profiles.readonly_quiet]
approval_policy = "never"
sandbox_mode    = "read-only"

로컬에서 샌드박스 테스트

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로도 사용할 수 있으며, platform helper에는 codex sandbox seatbelt, codex sandbox landlock 같은 alias가 있습니다.

OS-level 샌드박스

Codex는 OS에 따라 샌드박스를 다르게 강제합니다.

• macOS: Seatbelt policy를 사용하고 선택한 --sandbox 모드에 대응하는 profile(-p)로 sandbox-exec를 통해 명령을 실행합니다. 제한된 읽기 접근이 platform default를 활성화하면 Codex는 /System을 넓게 허용하지 않고 일반 도구 호환성을 유지하는 curated macOS platform policy를 추가합니다.
• Linux: 기본적으로 bwrap와 seccomp를 사용합니다.
• Windows: Windows Subsystem for Linux 2(WSL2)에서 실행할 때 Linux sandbox 구현을 사용합니다. WSL1은 Codex 0.114까지 지원되었습니다. 0.115부터 Linux sandbox가 bwrap로 이동했으므로 WSL1은 더 이상 지원되지 않습니다. Windows native 실행에서는 Windows sandbox 구현을 사용합니다.

Windows의 Codex IDE extension에서 WSL2를 직접 사용하려면 VS Code settings에 다음을 설정합니다.

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

이 설정은 host OS가 Windows여도 IDE extension이 command, approval, filesystem access에 대해 Linux sandbox semantics를 상속하게 합니다. 자세한 내용은 Windows setup guide를 참고하십시오.

Windows native 실행에서는 config.toml에서 native sandbox mode를 구성합니다.

[windows]
sandbox = "unelevated" # 또는 "elevated"
# sandbox_private_desktop = true

자세한 내용은 Windows setup guide를 참고하십시오.

Docker 같은 containerized 환경에서 Linux를 실행하면 host 또는 container 구성이 Codex에 필요한 namespace, setuid bwrap, seccomp operation을 차단해 샌드박스가 작동하지 않을 수 있습니다.

이 경우 Docker container가 필요한 isolation을 제공하도록 구성한 다음, container 안에서 --sandbox danger-full-access 또는 --dangerously-bypass-approvals-and-sandbox로 codex를 실행합니다.

Dev Container에서 Codex 실행

Host가 Linux sandbox를 직접 실행할 수 없거나 조직이 이미 containerized development를 표준화했다면 Dev Containers로 Codex를 실행하고 Docker가 바깥 isolation boundary를 제공하게 합니다. Visual Studio Code Dev Containers 및 호환 도구에서 동작합니다.

Codex secure devcontainer example을 reference implementation으로 사용하십시오. 이 예시는 Codex, 일반 개발 도구, bubblewrap, firewall 기반 outbound control을 설치합니다.

Devcontainer는 상당한 보호를 제공하지만 모든 공격을 막지는 않습니다. Container 안에서 --sandbox danger-full-access 또는 --dangerously-bypass-approvals-and-sandbox로 Codex를 실행하면 악의적인 project가 Codex credential을 포함해 devcontainer 안에서 접근 가능한 모든 것을 exfiltrate할 수 있습니다. 이 패턴은 신뢰하는 저장소에서만 사용하고, 다른 elevated environment와 마찬가지로 Codex activity를 monitor하십시오.

Reference implementation에는 다음이 포함됩니다.

• Codex와 일반 개발 도구가 설치된 Ubuntu 24.04 base image
• Outbound access를 위한 allowlist-driven firewall profile
• Container에서 workspace를 다시 열기 위한 VS Code settings와 extension recommendation
• Command history와 Codex 구성의 persistent mount
• Container가 필요한 capability를 부여할 때 Codex가 Linux sandbox를 계속 사용할 수 있게 하는 bubblewrap

시도 절차:

1. Visual Studio Code와 Dev Containers extension을 설치합니다.
2. Codex 예시 .devcontainer 설정을 저장소에 복사하거나 Codex 저장소에서 바로 시작합니다.
3. VS Code에서 **Dev Containers: Open Folder in Container...**를 실행하고 .devcontainer/devcontainer.secure.json을 선택합니다.
4. Container가 시작되면 terminal을 열고 codex를 실행합니다.

CLI에서 container를 시작할 수도 있습니다.

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

예시는 세 부분으로 구성됩니다.

• .devcontainer/devcontainer.secure.json: container setting, capability, mount, environment variable, VS Code extension을 제어합니다.
• .devcontainer/Dockerfile.secure: Ubuntu 기반 image와 설치 도구를 정의합니다.
• .devcontainer/init-firewall.sh: outbound network policy를 적용합니다.

Reference firewall은 의도적으로 출발점입니다. Domain allowlisting에 isolation을 의존한다면 TTL-aware refresh나 DNS-aware firewall처럼 환경에 맞는 DNS rebinding 및 DNS refresh 보호를 구현하십시오.

Container 안에서는 다음 중 하나를 선택합니다.

• Dev Container profile이 bwrap가 inner sandbox를 만들 capability를 부여한다면 Codex의 Linux sandbox를 유지합니다.
• Container가 의도한 보안 경계라면 container 안에서 --sandbox danger-full-access로 Codex를 실행해 두 번째 sandbox layer를 만들지 않게 합니다.

Version control

Codex는 version control workflow와 함께 사용할 때 가장 잘 동작합니다.

• Feature branch에서 작업하고 위임 전 git status를 clean하게 유지합니다. 그러면 Codex patch를 더 쉽게 isolate하고 되돌릴 수 있습니다.
• Tracked file을 직접 편집하는 방식보다 git diff/git apply 같은 patch 기반 workflow를 선호합니다. 자주 commit해 작은 단위로 rollback할 수 있게 합니다.
• Codex 제안은 다른 PR처럼 취급합니다. Targeted verification을 실행하고, diff를 review하고, audit을 위해 commit message에 decision을 기록합니다.

Monitoring과 telemetry

Codex는 팀이 local security default를 약화하지 않고 usage를 audit하고 issue를 investigate하고 compliance requirement를 충족하도록 OpenTelemetry(OTel) 기반 opt-in monitoring을 지원합니다. Telemetry는 기본적으로 꺼져 있으며 구성에서 명시적으로 활성화해야 합니다.

개요

• Codex는 local run을 self-contained로 유지하기 위해 기본적으로 OTel export를 끕니다.
• 활성화하면 conversation, API request, SSE/WebSocket stream activity, user prompt(기본 redacted), tool approval decision, tool result를 다루는 structured log event를 내보냅니다.
• Codex는 exported event에 service.name, CLI version, dev/staging/prod traffic을 구분하는 environment label을 붙입니다.

OTel 활성화

Codex 구성, 보통 ~/.codex/config.toml에 [otel] block을 추가하고 exporter와 prompt text logging 여부를 선택합니다.

[otel]
environment = "staging"   # dev | staging | prod
exporter = "none"          # none | otlp-http | otlp-grpc
log_user_prompt = false    # policy가 허용하지 않으면 prompt text redaction 유지

• exporter = "none"은 instrumentation은 활성으로 두지만 어디에도 데이터를 보내지 않습니다.
• 자체 collector로 event를 보내려면 다음 중 하나를 선택합니다.

[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는 event를 batch하고 shutdown 시 flush합니다. Codex는 자체 OTel module이 만든 telemetry만 export합니다.

Event category

대표 event type:

• codex.conversation_starts: model, reasoning setting, sandbox/approval policy
• codex.api_request: attempt, status/success, duration, error detail
• codex.sse_event: stream event kind, success/failure, duration, response.completed의 token count
• codex.websocket_request 및 codex.websocket_event: request duration, per-message kind/success/error
• codex.user_prompt: 길이. 명시적으로 켜지 않으면 content redacted
• codex.tool_decision: approved/denied, source가 configuration인지 user인지
• codex.tool_result: duration, success, output snippet

관련 OTel metric에는 codex.api_request, codex.sse_event, codex.websocket.request, codex.websocket.event, codex.tool.call counter와 duration histogram pair가 포함됩니다.

전체 event catalog와 구성 reference는 GitHub의 Codex configuration 문서를 참고하십시오.

보안 및 개인정보 지침

• 정책이 prompt content 저장을 명시적으로 허용하지 않는 한 log_user_prompt = false를 유지합니다. Prompt에는 source code와 민감 데이터가 포함될 수 있습니다.
• Telemetry는 사용자가 제어하는 collector로만 route하고, compliance requirement에 맞는 retention limit와 access control을 적용합니다.
• Tool argument와 output을 민감 데이터로 취급합니다. 가능하면 collector 또는 SIEM에서 redaction을 적용합니다.
• Codex가 CODEX_HOME 아래에 session transcript를 저장하지 않게 하려면 local data retention 설정, 예를 들어 history.persistence와 history.max_bytes를 검토합니다.
• Network access가 꺼진 CLI 실행에서는 OTel export가 collector에 도달할 수 없습니다. Export하려면 OTel endpoint에 대해 workspace-write mode에서 network access를 허용하거나, approved list에 collector domain이 있는 Codex cloud에서 export합니다.
• Approval/sandbox 변경과 예상치 못한 tool execution을 주기적으로 review합니다.

OTel은 optional이며 위에서 설명한 샌드박스와 승인 보호를 대체하지 않고 보완하도록 설계되었습니다.