AI 코딩 도구 설치·레퍼런스 (5/7) — Codex CLI 고급 설정: config.toml로 approval·sandbox 제어

← 4/7 Codex CLI 설치📚 시리즈 목차6/7 Hermes Agent 설치 →

공식 Config Reference 기준 실전 예제 · 프로파일 · Windows 네이티브 · 안전한 진입 경로

---

핵심 요약

• 대상 독자: Codex CLI 기본 설치는 끝났고(설치 완전판), 이제 ~/.codex/config.toml을 써서 승인·샌드박스·모델·MCP를 제어하고 싶은 사용자.
• 얻을 것: 공식 Config Reference 기준 자주 쓰는 8개 카테고리 실전 스니펫, approval 3종+granular, sandbox-write 세부, 멀티 provider (OpenAI/Azure/Ollama), MCP 서버 등록, 프로파일, Windows 네이티브 옵션.
• 선행 조건: Codex 설치 완료, AGENTS.md 기초 이해.

---

1. config.toml 위치와 레이어

공식 경로:

• 사용자 레벨: ~/.codex/config.toml (macOS/Linux) 또는 %USERPROFILE%\.codex\config.toml (Windows)
• 프로젝트 레벨: .codex/config.toml (프로젝트 루트, 선택)
• admin 강제: ~/.codex/requirements.toml (조직 정책)

레이어링: 프로젝트 > 사용자 > 기본값. 단 requirements.toml은 모든 사용자 설정을 강제로 제약 (users can't weaken).

~/.codex/는 Codex가 처음 실행될 때 자동 생성되지 않을 수 있다. 직접 mkdir -p ~/.codex 후 편집.

---

2. 최소 실용 구성 — 시작 템플릿

~/.codex/config.toml:

model = "gpt-5-codex"
model_provider = "openai"

approval_policy = "on-request"

sandbox_mode = "workspace-write"

model_reasoning_effort = "medium"

web_search = "cached"

이 6줄만 있어도 실전 개발에 충분. 필요할 때 아래 섹션에서 꺼내 붙인다.

---

3. Approval Policy 3종 + granular

approval_policy는 Codex가 언제 사용자에게 승인을 묻는지 결정한다.

값	동작
untrusted	read-only 안전 명령만 자동 실행, 나머지는 무조건 프롬프트
on-request (기본)	모델이 판단해서 필요할 때 요청
never	절대 묻지 않음 (자동화 전용, 위험)

3.1 Granular — 카테고리별 세밀 제어

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

• sandbox_approval — 샌드박스 벗어날 때 승인 요청
• rules — prefix rule (execpolicy)에 걸릴 때
• mcp_elicitations — MCP 서버가 사용자 입력 요청할 때
• request_permissions — 권한 변경 요청
• skill_approval — 스킬 승인

"사용자 상호작용이 필요한 것만 막고 나머지는 자동"이 목표라면 granular가 유리.

3.2 Approvals Reviewer

approvals_reviewer = "user"  # user (기본) | auto_review

auto_review는 별도 리뷰어 모델이 자동 판정 (엔터프라이즈 용).

---

4. Sandbox Mode 3종 + workspace-write 세부

모드	파일 읽기	파일 쓰기	네트워크
read-only	✅	❌	❌
workspace-write	✅	✅ (cwd 내)	❌ (기본)
danger-full-access	✅	✅ 무제한	✅

4.1 workspace-write 세부 설정

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
writable_roots = ["/tmp/build", "/var/log/myapp"]

network_access = false

exclude_tmpdir_env_var = false

exclude_slash_tmp = false

network_access = true는 빌드 중 의존성 fetch가 필요할 때만 켠다. 늘 켜두면 샌드박스 의미가 약해진다.

4.2 Permissions Profile로 세밀화

default_permissions = "workspace"

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

:project_roots 토큰은 프로젝트 상대 경로. **/*.env는 프로젝트 안 어디든 env 파일을 읽기조차 거부.

---

5. 추론·응답 제어

5.1 효과 레벨

model_reasoning_effort = "medium"

plan_mode_reasoning_effort = "high"

model_reasoning_summary = "auto"

model_verbosity = "medium"

5.2 컨텍스트·토큰 제한

tool_output_token_limit = 12000

긴 로그를 자주 읽는 프로젝트라면 tool_output_token_limit을 8000~20000 사이로 조정해 컨텍스트 관리.

---

6. 멀티 Model Provider

공식 내장 ID: openai, ollama, lmstudio (덮어쓸 수 없음). 커스텀은 다른 ID로 등록.

6.1 OpenAI Data Residency

[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1"
wire_api = "responses"

6.2 Azure OpenAI

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"
env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"

6.3 로컬 Ollama (OSS 모델)

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
wire_api = "responses"

세션에서 전환:

/model gpt-oss-120b@local_ollama

6.4 Command-backed 토큰 인증

프록시나 단기 토큰이 필요한 환경:

[model_providers.proxy]
name = "OpenAI via LLM proxy"
base_url = "https://proxy.example.com/v1"
wire_api = "responses"

[model_providers.proxy.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

command가 stdout에 JWT를 출력하면 Codex가 헤더에 주입. 5분마다 재발급.

---

7. MCP 서버 등록

두 가지 transport를 지원.

7.1 STDIO (로컬 프로세스)

[mcp_servers.docs]
enabled = true
command = "docs-server"
args = ["--port", "4000"]
env = { "API_KEY" = "value" }
cwd = "/path/to/server"
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]
disabled_tools = ["slow-tool"]

7.2 Streamable HTTP

[mcp_servers.github]
enabled = true
url = "https://github-mcp.example.com/mcp"
bearer_token_env_var = "GITHUB_TOKEN"
http_headers = { "X-Example" = "value" }
env_http_headers = { "X-Auth" = "AUTH_ENV" }
scopes = ["repo"]

bearer_token_env_var는 해당 환경변수 값을 Authorization: Bearer <token> 헤더로 자동 주입. 인증이 필요한 대부분의 MCP 서버에 적합.

7.3 필수 서버 설정

[mcp_servers.critical]
command = "critical-server"
required = true  # 초기화 실패 시 Codex 자체 기동 중단

프로덕션 자동화에서 특정 MCP 서버 없이는 작업하면 안 될 때 사용.

---

8. Profile — 시나리오별 preset 전환

여러 작업 모드를 한 config.toml에 두고 전환한다.

profile = "safe"  # 기본 프로파일

[profiles.safe]
sandbox_mode = "read-only"
approval_policy = "untrusted"
model_reasoning_effort = "low"

[profiles.dev]
sandbox_mode = "workspace-write"
approval_policy = "on-request"
model_reasoning_effort = "medium"

[profiles.ci]
sandbox_mode = "workspace-write"
approval_policy = "never"
model_reasoning_effort = "minimal"
web_search = "disabled"

실행 시 프로파일 지정:

codex --profile dev
codex --profile ci exec "lint the codebase and fix issues"

safe로 기본 두고, 실전 작업 시에만 dev로 전환하는 패턴이 실수를 줄인다.

---

9. History·상태·쉘 환경

9.1 History persistence

[history]
persistence = "save-all"  # save-all (기본) | none
max_bytes = 5242880  # 5 MB

none은 API 인증·외부 감사 환경에서 기록 남지 않도록.

9.2 Shell Environment Policy

Codex가 spawn하는 쉘의 환경변수 제어:

[shell_environment_policy]
inherit = "all"

ignore_default_excludes = false

exclude = ["AWS_*", "AZURE_*"]

set = { "CI" = "true" }

include_only = []

보안이 민감한 환경에서는 inherit = "core" + include_only = ["PATH", "HOME"]로 최소만 전달.

9.3 SQLite 상태 위치

sqlite_home = "/path/to/codex-state"  # 기본 $CODEX_HOME
log_dir = "/path/to/codex-logs"

---

10. Windows 네이티브 전용

[windows]
sandbox = "unelevated"  # unelevated | elevated

elevated는 관리자 권한으로 샌드박스 실행 — 레지스트리 수정·시스템 폴더 접근 등 드문 케이스. 일반적인 개발은 unelevated 기본값이 맞다.

Windows가 아닌 환경에서 [windows] 섹션은 무시된다.

---

11. TUI 커스터마이즈 (선택)

[tui]
theme = "catppuccin-mocha"

notifications = false  # true | false | ["agent-turn-complete", "approval-requested"]

animations = true

status_line = ["model", "context-remaining", "git-branch"]

terminal_title = ["spinner", "project"]

커스텀 .tmTheme 파일은 $CODEX_HOME/themes/에 넣으면 /theme 목록에 자동 등록.

---

12. Features 플래그

[features]

기본값을 그대로 두고, 필요할 때만 override. 전부 적어두면 업데이트 시 예기치 못한 동작이 생길 수 있다.

---

13. 안전한 진입 경로 — 점진 확장

새 프로젝트에 Codex를 도입할 때 권장 순서.

1. Day 1: sandbox_mode = "read-only" + approval_policy = "untrusted" + model = "gpt-5-codex". 읽고 분석만.
2. Day 2~: Codex가 제안하는 변경을 사람이 검토·수동 적용. 익숙해지면 workspace-write로 전환.
3. Week 2~: on-request로 승인 프롬프트 완화. 긴 태스크는 프로파일(dev)로 전환.
4. 자동화 단계: 격리된 CI 환경에서만 never + workspace-write. 프로덕션 레포에 직접 never는 금기.

요령: approval과 sandbox는 직교 축이다. 둘 다 felt-safe한 조합에 도달할 때까지 한쪽씩 완화한다. 동시에 둘 다 완화하면 사고 시 원인 파악이 어렵다.

---

14. 반대 시나리오 — config.toml을 건드리지 말아야 할 때

• Codex를 처음 써본다 → 기본값으로 며칠 써보면서 불편 지점을 수집. 튜닝은 그 뒤에.
• 팀 전원이 같은 설정이 필요 → 사용자 홈의 config.toml로는 공유 불가. requirements.toml + MDM 배포를 고려.
• 한 번만 쓰는 커스텀 → CLI 플래그(codex --sandbox-mode read-only)로 충분. 설정 파일에 박지 말 것.
• 엔터프라이즈 정책상 전체 제약 필요 → requirements.toml로 allowed_approval_policies, allowed_sandbox_modes 등을 강제.

---

15. 다음 단계

고급 설정이 익숙해졌다면:

1. Codex + Claude Code 병행 워크플로우 — 역할 분담 실전 (예정).
2. Codex 설치 완전판 — 설치·인증·AGENTS.md 기본.
3. Claude Code 훅 완전 가이드 — Codex에는 없는 훅 시스템 참고용.

---

참고

• 공식 Config Reference
• Sample config.toml (공식 템플릿)
• Advanced Configuration
• Sandbox 개념
• AGENTS.md 가이드

---

이 글은 "AI 코딩 CLI 진입 가이드" 시리즈의 7/15 편입니다. last verified: 2026-04-25 (OpenAI 공식 Codex Config Reference 기준).

시리즈 전체 안내: 시리즈 목차

← 4/7 Codex CLI 설치📚 시리즈 목차6/7 Hermes Agent 설치 →