Ch3. 승인/샌드박스 전략

Codex는 위험 작업에 대해 승인(approval) 기반으로 실행을 제어합니다. 시니어 개발자는 승인 정책을 표준화해 사고 범위를 줄여야 합니다.

승인과 샌드박스는 무엇이 다른가

• 승인(approvals): "언제 멈춰서 사용자 확인을 받을지"를 결정합니다(명령 실행/네트워크 접근 등).
• 샌드박스(sandbox): "무엇을 할 수 있는지(파일/네트워크/작업 루트)"의 실행 경계를 제공합니다.

승인 설계 원칙

• 기본은 on-request: 위험 작업은 항상 확인
• 자동 승인은 최소화: 반복·저위험 작업만 예외로 자동화
• 샌드박스 우선: 외부 영향이 큰 작업은 격리 환경에서 실행

추천 운영 매트릭스(팀 기본값)

CLI 플래그/설정 키(운영자가 알아야 할 것)

CLI

• --sandbox read-only|workspace-write|danger-full-access
• /permissions로 세션 중 Auto/Read-only/Full Access 계열 권한 전환
• --dangerously-bypass-approvals-and-sandbox (alias: --yolo, 비권장)

config.toml

• sandbox_mode = "read-only" | "workspace-write" | "danger-full-access"
• approval_policy = "untrusted" | "on-request" | "never" | { granular = { ... } }
• approvals_reviewer = "user" | "auto_review"
• default_permissions = ":read-only" | ":workspace" | ":danger-no-sandbox" | "<custom-profile>"

requirements.toml(관리자 강제)

조직이 허용하는 범위를 제한해, 개인이 실수로 never/danger-full-access를 쓰는 것을 막을 수 있습니다.

• allowed_approval_policies = [...]
• allowed_sandbox_modes = [...]

Unified Permissions Flow (0.102.0+)

최근 릴리스에서는 승인 UX가 "단순 yes/no"보다 권한 흐름 전체를 설명하는 방식으로 바뀌고 있습니다.

• 권한 이력 가시성: TUI에서 어떤 권한 요청이 있었는지 더 명확히 추적
• 디렉토리 접근 승격 경로: 막힌 디렉토리에 대해 추가 read access를 주는 전용 흐름 추가
• 네트워크 승인 구조화: host/protocol 정보가 승인 프롬프트에 더 풍부하게 표시

팀 운영에서는 "왜 막혔는지"를 사람에게 설명할 수 있어야 승인 품질이 올라갑니다. 네트워크나 파일 접근이 막혔을 때는 에이전트가 임의 우회하는 대신, 정식 권한 상승 경로를 타도록 표준화하세요.

승인 고도화 (0.105.0+)

최근 업데이트로 승인 제어가 더 유연해졌습니다:

• 추가 샌드박스 권한 요청: Codex가 명령 실행 시 추가 권한이 필요하면 사용자에게 요청할 수 있습니다
• 프롬프트 타입별 자동 거부: 특정 승인 프롬프트 타입을 자동 거부 설정해, 승인을 전체 끄지 않고도 세밀하게 제어할 수 있습니다

재개/서브에이전트 승인 운영 (0.107.0+)

• thread/resume가 pending approval/input까지 복원해, 장시간 세션 재개 시 컨텍스트 불일치가 줄었습니다
• child-thread approval이 더 잘 드러나서, 멀티에이전트 작업에서도 "어느 자식 스레드가 멈췄는지" 추적하기 쉬워졌습니다
• 승인 후 재실행되는 shell command가 원래 sandbox config를 유지하도록 보강돼, 재시도 과정에서 권한이 느슨해질 가능성이 줄었습니다
• zsh-fork skill 실행은 per-turn sandbox policy에 추가 권한을 병합하는 방식으로 정교화되었습니다(0.112.0)

Named Permission Profiles: 분리형 샌드박스 정책

최신 config reference에서는 default_permissions와 [permissions.<name>] 테이블로 파일시스템/네트워크 권한을 분리해서 선언합니다. 승인/샌드박스 전략 관점에서 핵심 변화는 다음과 같습니다:

• 파일시스템 정책: 절대 경로, :project_roots, glob을 read|write|none으로 선언
• 네트워크 정책: named profile 안에서 network mode, domain allow/deny, proxy/socket 정책을 선언
• 기본 프로필 선택: default_permissions로 sandboxed tool call에 적용할 기본 profile을 고정

[permissions.safe.filesystem]

[permissions.safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"
"secrets/**" = "none"

[permissions.safe.network]
enabled = true
mode = "limited"

[permissions.safe.network.domains]
"api.openai.com" = "allow"
"registry.npmjs.org" = "allow"

default_permissions = "safe"

네트워크 정책 강화

네트워크 정책은 "일단 전체 허용"보다 필요한 도메인만 allowlist로 여는 쪽이 안전합니다.

[permissions.safe.network.domains]
"api.openai.com" = "allow"
"registry.npmjs.org" = "allow"

팀에서 기존에 넓은 네트워크 허용을 사용하고 있었다면, 업데이트 전에 실제 필요한 host 목록으로 교체해야 합니다.

런타임 권한 요청 도구: request_permissions (0.113.0+)

0.113.0에서 내장 도구 request_permissions가 추가되었습니다. 에이전트가 실행 중 추가 권한이 필요할 때 사용자에게 명시적으로 요청할 수 있는 정식 경로입니다.

동작 방식

1. 에이전트가 현재 권한으로 수행할 수 없는 작업을 감지
2. request_permissions 도구를 호출해 필요한 권한을 명시
3. TUI에 승인 렌더링: 사용자에게 요청 내용이 구조화된 형태로 표시
4. 사용자가 승인/거부를 선택
5. 승인 시 해당 턴(또는 세션)에 권한이 확장

┌─ Permission Request ─────────────────────────────┐
│ Agent requests additional permissions:            │
│                                                   │
│  • filesystem: write access to ./deploy/          │
│  • network: access to registry.npmjs.org          │
│                                                   │
│ [Allow]  [Allow for session]  [Deny]              │
└───────────────────────────────────────────────────┘

팀 운영 가이드

• 승인 기준 문서화: 어떤 요청은 즉시 허용하고, 어떤 요청은 리드 확인이 필요한지 기준을 정하세요
• 세션 단위 허용 활용: 반복 요청이 잦은 권한은 "Allow for session"으로 노이즈를 줄이세요
• 감사 로그 확인: 권한 요청/승인 이력은 세션 로그에 남으므로, 사후 검토에 활용할 수 있습니다

Smart Approvals: Guardian Subagent (0.115.0+)

0.115.0에서 Smart Approvals가 guardian subagent를 통해 라우팅되도록 변경됐습니다.

• 일관된 승인 경험: TUI, App, app-server 등 모든 인터페이스에서 동일한 승인 로직이 적용됩니다
• 승인 판단 정확도 향상: guardian이 요청 컨텍스트를 더 깊이 분석해 불필요한 승인 요청이 줄어듭니다
• App 통합 개선: App integrations에서 Responses API tool-search를 사용하며, fallback 경로도 갖추고 있습니다

Automatic Approval Review + Permission State 정합성 (0.124.0~0.125.0)

0.124.0부터 app-server approvals는 사용자에게 승인 요청을 띄우기 전에 subagent review를 자동 실행할 수 있습니다. 바로 승인 팝업을 띄우는 대신, 먼저 변경안을 한 번 더 읽게 하는 방식입니다. App 26.423에서도 이 흐름이 리뷰 surface에 드러납니다.

• 적합한 경우: 자동 수정이 많지만, 사람이 최종 승인 전에 "무엇이 바뀌는지" 요약 검토를 받고 싶은 팀
• 장점: 단순한 허용/거부보다 리뷰 근거가 먼저 생겨 승인 품질이 올라감
• 한계: review subagent는 sandbox를 대체하지 않으므로, 위험 작업은 여전히 workspace-write/read-only와 승인 정책으로 제어해야 함

0.125.0에서는 permission profile 상태가 TUI user turn, MCP sandbox metadata, shell escalation permission, app-server API 사이에서 더 일관되게 round-trip됩니다. 최근 릴리즈에서 side conversation이나 tool 경유 후 permission state가 어긋나는 문제가 줄어든 이유입니다.

영구 권한 및 apply_patch 승인 수정 (0.114.0+)

0.114.0에서 승인 흐름의 두 가지 주요 버그가 수정되었습니다:

• 턴 간 영구 권한 유지: 이전에는 한 턴에서 승인한 권한이 다음 턴에서 초기화되는 경우가 있었습니다. 0.114.0부터 persistent permissions가 턴을 넘어서도 정확히 유지됩니다.
• apply_patch 승인 정합성: apply_patch 도구 실행 시 승인 프롬프트가 누락되거나, 새로운 permission profile과 맞지 않는 문제가 수정되었습니다.
• workspace-write 권한 처리 개선: workspace-write 모드에서 일부 쓰기 작업이 불필요하게 승인을 요구하던 문제가 해결되었습니다.

샌드박스 안정성·보호 강화 (0.116.0 → 0.118.0)

0.116.0 이후 릴리스에서 Linux/Windows 샌드박스와 프로젝트 보호가 추가로 강화되었습니다:

• 심볼릭 링크 체크아웃: 심볼릭 링크가 포함된 Git 체크아웃에서 샌드박스가 올바르게 동작합니다
• 누락된 writable root: writable root 경로가 존재하지 않을 때 발생하던 시작 실패가 수정되었습니다
• Ubuntu/AppArmor 호환성: AppArmor가 활성화된 Ubuntu 호스트에서의 샌드박스 시작 문제가 해결되었습니다
• 시스템 bwrap 우선 사용: 시스템에 설치된 bwrap(bubblewrap)이 사용 가능하면 번들 버전 대신 우선 사용하여 호스트 환경과의 호환성을 높입니다
• trusted bwrap 탐색 복구 (0.118.0): 다중 PATH 엔트리 환경에서도 신뢰 가능한 시스템 bwrap를 다시 안정적으로 찾습니다
• .codex 첫 생성 보호 (0.118.0): 프로젝트 로컬 .codex 파일이 최초 생성 시에도 정상 승인 흐름을 거치도록 보호됩니다
• Windows proxy-only 네트워크 강제 (0.118.0): Windows 샌드박스가 환경변수 우회가 아닌 OS 레벨 egress 규칙으로 proxy-only 네트워크를 강제할 수 있습니다

IDE/앱 모드 운영(권한 레벨)

• Auto(기본): 작업 디렉토리 안에서는 자동으로 읽기/수정/명령 실행이 가능하지만, 작업 디렉토리 밖 또는 네트워크 접근은 승인 필요
• Full Access: 네트워크 접근까지 승인 없이 수행(주의해서 사용)
• Read-only 전환: 세션 중 /permissions로 권한을 낮춰 "읽기 전용"으로 전환해 사고 확률을 줄일 수 있습니다

참고 문서

• 보안/권한 개요: https://developers.openai.com/codex/security (영어)
• config 고급(approval_policy): https://developers.openai.com/codex/config-advanced (영어)
• config 레퍼런스(approval_policy): https://developers.openai.com/codex/config-reference (영어)
• 비대화형 실행(sandbox 옵션): https://developers.openai.com/codex/noninteractive (영어)
• IDE 기능(승인/모드): https://developers.openai.com/codex/ide/features (영어)
• 슬래시 커맨드(승인 관련): https://developers.openai.com/codex/cli/slash-commands (영어)