Codex CLI config.toml 심층 분석: 모든 설정 설명

요약 (TL;DR). Codex CLI의 config.toml은 sandbox (샌드박스), approvals (승인), permissions (권한), MCP, providers (제공자), TUI, hooks (훅), telemetry (텔레메트리), 그리고 feature flags (기능 플래그)에 이르기까지 문서화된 키가 150개를 넘어섰습니다. 대부분의 사용자는 그중 5개만 수정하며, 실제로 중요한 설정들(세밀한 승인, 권한 프로필, shell_environment_policy, features.network_proxy)은 놓치고 있습니다. 이 심층 분석에서는 모든 섹션을 살펴보고, 놀라운 기본값들을 지적하며, 바로 복사해서 다듬어 사용할 수 있는 계층적 설정을 제공하며 마무리합니다. 기본 ~/.codex/config.toml 파일이 비어 있는 데에는 이유가 있습니다. Codex는 합리적인 기본값을 제공하지만, Codex를 사용자의 셸보다 더 엄격한 샌드박스에 배치하거나 플래그십 모델보다 저렴한 모델을 사용하는 순간, 여러분은 10개의 설정을 건드리게 될 것이며, 그중 7개는 어떤 블로그 포스트에도 나와 있지 않을 것입니다.

파일의 위치 및 무시되는 항목

사용자 수준의 설정은 $CODEX_HOME/config.toml에 위치하며, macOS 및 Linux에서는 기본적으로 ~/.codex/config.toml에, Windows에서는 %USERPROFILE%\.codex\config.toml에 저장됩니다. 프로젝트 범위의 재정의(overrides)는 프로젝트 루트의 .codex/config.toml에 위치합니다.

병합은 계층적으로 이루어집니다: 관리형 설정 (관리자 푸시) → 사용자 설정 → 프로젝트 설정 → CLI 플래그. --profile NAME이 전달될 때 프로필(Profiles)이 사용자 설정과 프로젝트 설정 사이에 삽입됩니다. 안전을 위해 프로젝트 로컬 파일에서는 특정 키 세트가 의도적으로 **무시(ignored)**되며, 해당 파일에 작성하더라도 조용히 삭제됩니다:

• openai_base_url, chatgpt_base_url
• model_provider, model_providers
• notify, profile, profiles
• approval_policy, sandbox_mode, sandbox_workspace_write.*
• experimental_realtime_ws_base_url, otel.*, apps_mcp_product_sku

만약 위 항목 중 하나에 대해 프로젝트 설정이

model            = "gpt-5.4"          # 또는 제공업체가 노출하는 모든 ID
model_provider   = "openai"           # 내장: openai, ollama, lmstudio
approval_policy  = "on-request"       # untrusted | on-request | never | { granular = {...} }
...

이것이 설정의 80%를 차지합니다. 이 섹션 아래의 모든 내용은 샌드박스 (sandbox)를 강화하거나, 제공업체 (provider)를 교체하거나, 프로필 (profile)을 계층화하거나, MCP/훅 (hooks)/OTEL을 연결하는 설정들입니다.

model 필드에 관한 참고 사항: Codex의 기본값이 최근 gpt-5.4로 갱신되었으며, gpt-5.5는 현재 TUI의 컴포저 (composer) 내 ChatGPT-login 워크플로우를 통해 나타납니다. API 키 워크플로우의 경우 사용 가능한 ID는 제공업체마다 다르므로, 값을 고정하기 전에 codex models (또는 해당 제공업체의 카탈로그)를 확인하십시오. Codex CLI는 내장 카탈로그를 제공하며, 시작 시 사용자의 자체 JSON 카탈로그를 로드할 수 있는 선택적 model_catalog_json 키도 포함하고 있습니다.

샌드박스 (Sandbox) 및 승인 (approvals) — 이 쌍을 제대로 설정하지 않으면 다른 것은 중요하지 않습니다

sandbox_mode는 Codex가 기술적으로 허용된 작업 범위를 결정합니다. approval_policy는 Codex가 사용자에게 먼저 요청하는 시점을 결정합니다. 이 두 설정은 상호 작용하며, 기본값은 안전하지만 번거로운 설정으로 지정되어 있습니다.

sandbox_mode

값	파일 시스템 (Filesystem)	네트워크 (Network)
read-only	모든 곳을 읽을 수 있지만, 어디에도 쓸 수 없음	차단됨
...

대부분의 팀은 workspace-write 모드를 사용해야 합니다. 문서화가 덜 된 제어 옵션들은 [sandbox_workspace_write] 아래에 위치합니다:

[sandbox_workspace_write]
writable_roots         = ["~/work/notes"]   # 현재 작업 디렉토리(cwd) 이외의 추가 디렉토리
network_access         = false              # 샌드박스 내부에서 외부 HTTP 허용 여부
...

network_access = true는 pip install이나 npm install이 알 수 없는 이유로 멈춰 있을 때 사람들이 놓치기 쉬운 토글(toggle) 옵션입니다.

approval_policy

untrusted는 거의 모든 작업 전에 요청합니다. on-request는 Codex가 샌드박스에서 차단된 항목에 부딪혔을 때 요청합니다. never는 완전히 자율적입니다 (정말로 의도한 것이 아니라면 danger-full-access와 함께 사용해서는 안 됩니다).

더 세밀한 제어를 위해 테이블 형식을 사용하십시오:

[approval_policy.granular]
sandbox_approval     = true   # Codex가 샌드박스(sandbox) 이상의 권한 상승을 요청할 수 있도록 허용
request_permissions  = true   # request_permissions 도구가 프롬프트를 띄울 수 있도록 허용
...

이것은 "샌드박스 권한 상승은 요청해도 좋지만, 개별 MCP 유도(elicitations)에 대해 나에게 확인을 요청하는 것은 중단하라"라고 말하는 방식입니다. 대부분의 사용자는 이것이 필요하지 않겠지만, CI(지속적 통합) 환경에서의 무인 실행(unattended runs) 시에는 중요합니다.

동반 키인 approvals_reviewer는 자격이 있는 프롬프트를 누가 처리할지 선택합니다: user (기본값) 또는 auto_review (설정된 리뷰어 에이전트에게 위임)입니다.

추론(Reasoning), 상세도(verbosity), 그리고 플랜 모드(plan mode)

네 가지 키가 있으며, 모두 모델에 따라 달라집니다. GPT-5 제품군 모델과 함께 사용하십시오. 이전 모델이나 추론 기능이 없는 모델은 이를 무시합니다.

model_reasoning_effort     = "medium"  # minimal | low | medium | high | xhigh
model_reasoning_summary    = "auto"    # auto | concise | detailed | none
model_verbosity            = "medium"  # low | medium | high  (GPT-5 Responses API)
...

xhigh가 존재하지만 토큰을 많이 소모하므로, 가장 심각한 플랜 모드(plan-mode) 문제에만 사용하십시오. hide_agent_reasoning = true는 모델이 실제로 계산하는 내용은 변경하지 않으면서 TUI 및 codex exec 출력에서 추론(reasoning) 이벤트를 억제합니다. 이는 스크린샷 촬영, 로그 파이핑(log piping), 그리고 편집되지 않은 사고의 흐름(chain-of-thought)이 도움이 되기보다 방해가 되는 페어 프로그래밍(pair-programming) 세션에서 유용합니다. show_raw_agent_reasoning = true는 그 반대로 작동합니다: 제공자(provider)가 노출하는 경우 모델의 가공되지 않은 추론 내용을 표면화합니다.

model_supports_reasoning_summaries는 Codex가 추론 메타데이터를 보낼지 여부를 강제로 재정의(true/false)하는 설정입니다. 자신의 기능을 속이는 커스텀 제공자(custom provider)를 디버깅하는 경우가 아니라면 설정하지 않은 상태로 두십시오.

권한 프로필(Permissions profiles) — 액세스 범위를 지정하는 현대적인 방식

새로운 [permissions.NAME] 블록은 sandbox_workspace_write보다 더 표현력이 풍부하며, Codex가 지향하는 방식입니다. 이름이 지정된 프로필(:read-only, :workspace, :danger-full-access는 기본 내장됨)을 정의하고 default_permissions = "my-profile"로 하나를 선택할 수 있습니다.

[permissions.scoped]

[permissions.scoped.workspace_roots]
...

알아두면 좋은 몇 가지 사항:

• :workspace_roots 토큰은 그 아래의 규칙들을 workspace_roots에 선언된 모든 경로로 제한(scope)하는 특별한 키입니다. 이 제한용 래퍼(wrapper)가 없다면, **/*.env = "deny" 설정이 전역적으로 적용될 것입니다.
• glob_scan_max_depth가 존재하는 이유는 **/secret.json과 같은 거부(deny) 글로브(glob) 패턴을 거대한 저장소 전체에서 확장하는 작업은 비용이 많이 들기 때문입니다. Codex는 빠른 시작을 유지하기 위해 이 깊이를 제한합니다.
• network.mode = "limited"와 명시적인 도메인 허용 목록(allowlist)을 함께 사용하는 것이 프로덕션급(production-grade) 설정입니다. 여기에 dangerously_allow_non_loopback_proxy = false(기본값)를 결합하여 샌드박스 프록시가 루프백(loopback)에만 바인딩되도록 하세요.

네트워크 프록시 (Network proxy) — 대부분의 사람들이 건너뛰는 기능 플래그

만약 "Codex에서 pip install을 할 수 없다"는 문제에 직면했다면, 아마도 다음 설정이 필요할 것입니다:

[features.network_proxy]
enabled = true
proxy_url  = "http://127.0.0.1:3128"
...

이 설정은 sandbox_workspace_write.network_access처럼 단순히 네트워크 접속을 켜고 끄는 이진 방식이 아니라, 도메인 허용 목록을 가진 HTTP/SOCKS5 프록시를 샌드박스된 하위 프로세스(subprocess)에 제공합니다. dangerously_* 키들은 특수한 바인딩/리스너(bind/listener) 케이스를 위해 존재하므로, 실패 모드(failure mode)를 완전히 이해하지 못했다면 그대로 두는 것이 좋습니다.

MCP 서버 (MCP servers) — 가장 핵심적인 섹션

MCP 서버 설정은 [mcp_servers.<id>] 아래에 위치합니다. 스키마는 stdio 서버(command + args)와 HTTP 스트리밍 가능 서버(url + headers)를 모두 지원합니다.

[mcp_servers.docs]
command = "uvx"
args    = ["mcp-server-docs"]
...

startup_timeout_sec의 기본값은 10초입니다. 첫 요청 시 지연 로딩(lazy-load)을 수행하는 느린 Node MCP 서버의 경우 이 값을 높여주세요. tool_timeout_sec의 기본값은 60초이며, 실행 시간이 긴 셸(shell)이나 데이터베이스 도구는 더 많은 시간이 필요합니다. 워크플로우가 의존하는 서버라면 required = true로 설정하는 것이 올바른 선택입니다. 세션 중간에 문제를 발견하는 것보다 부팅 시점에 실패하는 것이 낫기 때문입니다.

default_tools_approval_mode와 tools.<name>.approval_mode를 사용하면, 커스텀 승인 훅(approval hooks)을 작성하지 않고도 "search는 자동 승인하고, delete_branch는 나에게 확인을 요청하라"와 같은 설정을 할 수 있습니다.

모델 제공자 (Model providers) — ofox를 포함한 커스텀 엔드포인트

내장된 제공자 ID (openai, ollama, lmstudio)는 예약되어 있습니다. 그 외의 모든 것은 [model_providers.<id>] 블록이 됩니다. GPT/Claude/Gemini/DeepSeek/Qwen 모델 전반에 걸쳐 하나의 키로 Codex를 라우팅하는 ofox 설정을 예로 들면 다음과 같습니다:

[model_providers.ofox]
name     = "ofox"
base_url = "https://api.ofox.ai/v1"
...

그 다음 기본값을 변경하거나:

model_provider = "ofox"
model          = "gpt-5.4"     # 또는 anthropic/claude-opus-4.6, google/gemini-3.1-pro-preview 등

…

프로필에 범위를 지정할 수 있습니다 (다음 섹션 참조). 명령어를 통한 인증 (auth-via-command), 쿼리 파라미터가 고정된 Azure 엔드포인트 (query-param-pinned Azure endpoints), 그리고 제공자별 헤더 주입 (per-provider header injection)을 포함한 전체 BYO (Bring Your Own) 가이드는 How to Use Any Model with Codex CLI에서 확인할 수 있습니다. 하나의 제공자 항목이 여러 모델로 분산되는 방식(fan out)을 사용하는 이유인 게이트웨이의 근거(gateway rationale)는 AI API aggregation guide에 설명되어 있습니다.

주의 깊게 살펴볼 몇 가지 키는 다음과 같습니다:

• wire_api는 Codex 0.59 (2026년 2월) 버전부터 `

만약 처음으로 순정 OpenAI 인증 (vanilla OpenAI auth)에서 벗어나려 한다면, OpenAI 클라이언트를 ofox로 마이그레이션하기 위한 SDK 가이드가 보조 자료가 될 것입니다.

Profiles — 기본 설정 위에 얹는 레이어 프리셋

[profiles.NAME]은 플랫 오버레이 (flat overlay)입니다. codex --profile NAME을 실행할 때 프로필 내부에 설정된 모든 최상위 키 (top-level key)가 우선권을 갖습니다.

[profiles.fast]
model                   = "gpt-5.4-mini"
model_reasoning_effort  = "low"
...

이곳은 프로필별로 model_provider를 설정할 수 있는 공간이기도 합니다. 이를 통해 기본 프로필은 OpenAI를 유지하면서, review 프로필은 ofox를 통한 Anthropic을 호출하도록 설정할 수 있습니다. 주의할 점은 model_provider와 profile 키 자체는 프로젝트 로컬 (project-local) 설정에서는 무시된다는 것입니다. 이들은 ~/.codex/config.toml에 정의하십시오.

실용적인 패턴 — 쉘 별칭 (shell aliases)과 결합된 fast/deep/review 프로필 — 에 대해서는 실전 Codex CLI 워크플로우 가이드를 참조하세요. fast/deep 모델 선택에 따른 가격 측면의 트레이드오프 (tradeoffs)는 Codex CLI API 구성 가이드에 설명되어 있습니다.

History, TUI, 그리고 file_opener

[history]
persistence = "save-all"   # save-all | none
max_bytes   = 5_242_880    # 5 MB 제한; 가장 오래된 항목 삭제
...

tui.notifications는 더 세밀한 제어를 위해 불리언 (boolean) 값 또는 이벤트 유형의 배열(["new-message", "tool-output"])을 모두 허용합니다. alternate_screen = "never"는 대체 화면 (alternate screen)이 스크롤백 (scrollback)을 삼켜버리는 tmux 환경에서 유용합니다. tui.theme는 케밥 케이스 (kebab-case) 테마 이름을 허용합니다 — catppuccin-mocha, gruvbox-dark, solarized-light 등이 있습니다.

file_opener는 Codex가 출력에서 파일을 인용할 때 방출하는 URI 스킴 (URI scheme)을 제어합니다. 기본값은 vscode이며, cursor, windsurf, vscode-insiders, 그리고 none (클릭 가능한 링크가 없는 일반 경로)이 대안으로 제공됩니다.

shell_environment_policy — OTEL에서만 눈치채게 될 유출

기본적으로 Codex는 서브프로세스 (subprocess)를 생성할 때 사용자의 전체 쉘 환경 (shell environment)을 상속받습니다. 이는 편리하지만, 환경 변수에 포함된 모든 AWS_*, GITHUB_*, OPENAI_* 변수에 모델이 실행하는 모든 쉘 도구가 접근할 수 있다는 사실을 깨닫기 전까지만 유효합니다.

[shell_environment_policy]
inherit                 = "core"          # all | core | none
ignore_default_excludes = false           # false일 경우, KEY/SECRET/TOKEN 이름이 먼저 제거됩니다
...

inherit = "core"는 최소한의 POSIX 스타일 집합만 유지하고 나머지는 버립니다. ignore_default_excludes = false (기본값)는 이름에 KEY, SECRET, 또는 TOKEN이 포함된 모든 항목이 사용자의 커스텀 include_only/exclude 설정이 실행되기 전에 먼저 필터링됨을 의미합니다. 이 설정은 그대로 유지하십시오.

experimental_use_profile = true는 서브프로세스를 생성할 때 사용자의 쉘 사용자 프로필 (.zshrc 등)을 호출합니다. 프로필에 모델이 의존하는 별칭 (alias)이 정의되어 있다면 더 깔끔한 출력을 얻을 수 있지만, 어떤 경우든 시작 속도는 느려집니다.