Codex 설정이 적용되지 않을 때 가장 위험한 해결책은 “완성형” config.toml을 통째로 복사하는 것입니다. model만 바꾸려다가 sandbox와 approval을 풀고, 다른 provider를 선택하고, 알 수 없는 feature를 켜고, MCP process까지 추가할 수 있습니다. 파일이 파싱되더라도 원하는 동작이 나온다는 보장은 없습니다.
안전한 출발점은 설정의 소유자를 먼저 정하는 것입니다. 개인 기본값은 ~/.codex/config.toml, 특정 trusted repository의 동작은 .codex/config.toml, 반복해서 전환할 작업 모드는 별도 profile, 한 번만 시험할 값은 CLI override가 담당합니다. Codex CLI와 IDE extension은 같은 host의 설정 레이어를 공유합니다. 공식 위치와 범위는 Config basics에서 확인할 수 있습니다.
수정 전에는 대상 파일만 백업하세요. 하나의 잘못된 table 때문에 ~/.codex 전체를 지우면 정상적인 auth, profiles, rules까지 잃을 수 있습니다.
먼저 실제로 이기는 값을 찾는다
Codex는 일반 값을 다음 순서로 적용합니다.
- CLI flag와
--config - trusted project의
.codex/config.toml— 현재 디렉터리에 가까운 레이어 우선 --profile로 선택한 파일- 사용자
~/.codex/config.toml - Unix의
/etc/codex/config.toml - built-in default
이 순서는 공식 Configuration precedence에 명시되어 있습니다. user config를 바꿨는데 그대로라면 파일 저장보다 먼저 project/profile/CLI override를 확인해야 합니다.
| 원하는 결과 | 적절한 위치 | 주의점 |
|---|---|---|
| 개인 model, reasoning, 알림, 개인 MCP | user config | 여러 repo에 공통 적용 |
| 한 repo의 실행 경계 | trusted project config | 신뢰하지 않은 repo에서는 로드되지 않음 |
| read-only review 같은 반복 모드 | 별도 profile | base 전체를 복제하지 않음 |
| 일회성 비교 | CLI override | 영구값으로 남지 않음 |
| 조직이 강제할 보안 정책 | managed requirements | 일반 local config로 우회하지 않음 |
project config가 모든 값을 이길 수 있는 것은 아닙니다. machine-local provider/auth, profile 선택, notification, telemetry 계열은 프로젝트가 덮어쓸 수 없습니다. 현재 목록에는 model_provider, model_providers, profile, otel 등이 포함됩니다. 정확한 키는 Configuration reference에서 확인하고 user 레이어에 둡니다.
기본 파일은 다섯 가지 판단만 담아도 된다
다음은 작게 시작하는 예시입니다.
tomlmodel = "gpt-5.6" model_reasoning_effort = "high" approval_policy = "on-request" sandbox_mode = "workspace-write" web_search = "cached"
model ID는 현재 client/account에서 이용 가능한지 확인해야 하며 영구적인 추천값이 아닙니다. 설치 버전의 default가 목적에 맞는 키는 굳이 고정하지 않는 편이 좋습니다. 지속 값이 적을수록 update 후 원인을 추적하기 쉽습니다.
approval_policy는 언제 승인을 요청할지 결정하고, sandbox_mode는 command가 어디까지 접근할지 결정합니다. OpenAI는 workspace-write와 on-request를 비교적 낮은 위험의 local automation 조합으로 설명합니다. danger-full-access와 never는 두 경계를 모두 제거하므로 일상 설정으로 쓰지 않는 편이 안전합니다. 현재 의미는 Sandbox: Configure defaults에 있습니다.
web_search도 별도 결정입니다. 현재 top-level 값은 cached, indexed, live, disabled입니다. 구형 [features] web-search toggle은 deprecated이므로 오래된 예제에서 가져오지 마세요.
Feature는 기본값과 버전을 먼저 확인한다
feature를 영구히 켜기 전에 설치된 CLI가 그 이름을 알고 있는지 확인합니다.
bashcodex features list codex features --help
현재 공식 config 문서는 apps, goals, hooks, fast_mode, multi_agent 등 일부 feature의 maturity와 default를 표시합니다. 기본으로 켜진 기능을 다시 true로 고정하면 얻는 것은 없고, 나중에 deprecated 키만 남을 수 있습니다. 목적이 명확할 때만 [features]에 값을 저장하세요.
profile도 현재 형식을 확인해야 합니다. 반복할 감사 모드는 별도 파일로 만듭니다.
toml# ~/.codex/audit.config.toml model_reasoning_effort = "xhigh" approval_policy = "on-request" sandbox_mode = "read-only"
bashcodex --profile audit
Codex 0.134.0부터 --profile은 main config의 [profiles.audit]를 읽지 않고, top-level profile = "audit"도 지원하지 않습니다. 현재 별도 파일 방식은 Advanced Config: Profiles에 설명되어 있습니다.
MCP는 table, transport, auth, tool을 나눠 본다
STDIO server 예시는 command와 전달할 환경 변수를 분명히 둡니다.
toml[mcp_servers.docs] command = "docs-server" args = ["--read-only"] env_vars = ["DOCS_TOKEN"] startup_timeout_sec = 20 tool_timeout_sec = 60 enabled = true
Streamable HTTP server는 URL과 token source를 분리합니다.
toml[mcp_servers.tasks] url = "https://mcp.example.internal/mcp" bearer_token_env_var = "TASKS_MCP_TOKEN" enabled = true
실제 token을 repo, 글, 지원 메시지에 붙여 넣지 마세요. OpenAI의 MCP documentation은 STDIO, streamable HTTP, OAuth, environment header, timeout, tool allow/deny를 각각 정의합니다.
설정 후에는 설치 버전이 제공하는 명령으로 읽힌 server를 확인합니다.
bashcodex mcp list codex mcp --help
OAuth server는 codex mcp login <server-name>을 사용할 수 있습니다. 목록에 나온다는 사실은 table이 읽혔다는 뜻일 뿐, executable/URL, auth, 개별 tool의 정상 동작을 증명하지 않습니다.
오류 메시지보다 앞선 경계를 확인한다
최근 CLI는 --strict-config와 doctor를 제공합니다. 설치 버전에서 실제 지원되는지 먼저 확인하세요.
bashcodex --version codex --help codex doctor --help
지원된다면 read-only 점검을 실행할 수 있습니다.
bashcodex --strict-config doctor --summary
strict config는 인식하지 못하는 field를 오류로 만들고, doctor는 installation, config, auth, runtime 상태를 살핍니다. 이것이 성공해도 provider request나 MCP tool이 성공했다는 뜻은 아닙니다.
| 증상 | 첫 체크포인트 |
|---|---|
| 한 repo에서만 값이 무시됨 | trust와 가까운 .codex/config.toml |
| CLI는 되지만 IDE는 key가 없음 | IDE process의 environment visibility |
| unknown field로 시작 실패 | client version과 current reference |
| model을 바꿨는데 route가 유지됨 | model_provider, profile, project, CLI |
| MCP는 보이지만 tool을 못 씀 | command/URL, auth, timeout, tool |
| 회사 장비에서 고권한 모드가 거부됨 | 관리되는 requirements.toml |
Business/Enterprise 관리 환경에서는 requirements.toml이 approval, permission profile, web search, MCP allowlist, plugin, feature를 제한할 수 있습니다. local 값이 강제 규칙과 충돌하면 허용된 값으로 fallback하고 알림을 표시할 수 있습니다. Admin-enforced requirements에 설명된 정책이므로 다른 local 파일로 옮겨 우회할 문제가 아닙니다.
한 번의 수정에는 하나의 관찰 가능한 목표만 두세요. 레이어를 선택하고, 백업하고, 관련 block 하나를 바꾸고, parse와 우선순위를 확인한 뒤 낮은 위험의 작업으로 결과를 봅니다. 실패하면 가장 앞의 미확인 경계로 돌아가면 됩니다.
설정법이 아니라 coding agent 선택이 필요하다면 Claude Code와 Codex 비교를 참고하세요.
