Codex config.toml을 설정할 때 첫 질문은 “무슨 값을 넣을까”가 아니라 “이 설정의 소유자가 누구인가”입니다. 개인 기본값은 ~/.codex/config.toml, 신뢰한 프로젝트 정책은 .codex/config.toml, 한 번만 쓰는 실험은 CLI flag나 --config, 반복해서 쓰는 CLI mode는 profile이 맡는 편이 안전합니다.
OpenAI의 Codex config, MCP, authentication, sandbox 문서는 2026년 4월 21일 기준으로 확인했습니다. 아래 CLI 예시는 로컬 codex-cli 0.121.0 help 출력과 맞춰 적었습니다.
먼저 설정 계층을 고르세요
| 바꾸려는 것 | 가장 좋은 위치 | 이유 |
|---|---|---|
| 기본 모델, approval 습관, 알림, credential store | ~/.codex/config.toml | 개인 환경에 따라야 합니다 |
| repo instructions, 보수적 sandbox, 팀 MCP defaults | trusted project의 .codex/config.toml | 저장소 정책으로 review 가능합니다 |
| 일회성 model, sandbox, nested key | CLI flag 또는 --config | 영구 파일을 오염시키지 않습니다 |
| review나 local edit 같은 반복 mode | [profiles.<name>] | --profile로 명시 선택합니다 |
| 새 MCP server | 먼저 codex mcp add | helper가 TOML과 env 처리를 덜 위험하게 만듭니다 |
Codex를 subscription으로 쓸지 API key로 쓸지 헷갈린다면 Codex API key와 subscription 차이를 먼저 보세요. 사용량 문제라면 Codex usage limits guide가 맞는 출발점입니다.
우선순위: 충돌하면 무엇이 이기나
현재 우선순위는 강한 순서대로 다음과 같습니다.
| 순위 | 계층 | 의미 |
|---|---|---|
| 1 | CLI flags와 --config | 한 번의 명령이 아래 파일을 덮어쓸 수 있습니다 |
| 2 | --profile <name>로 선택한 profile | named preset이 보통 defaults를 이깁니다 |
| 3 | Project .codex/config.toml | trusted project에서만 적용되고 cwd에 가까운 trusted config가 우선합니다 |
| 4 | User ~/.codex/config.toml | 개인 default layer입니다 |
| 5 | System /etc/codex/config.toml | machine-wide default입니다 |
| 6 | Built-in defaults | 위에서 아무 값도 없을 때 사용됩니다 |
따라서 “config.toml을 수정했는데 적용되지 않는다”는 증상은 보통 더 강한 계층이 이기고 있다는 뜻입니다. shell alias, selected profile, command flag, cwd, project trust를 먼저 확인하세요.
User config: 개인 기본값만 담기
처음에는 짧은 personal config가 좋습니다.
toml#:schema https://developers.openai.com/codex/config-schema.json model = "gpt-5.4" approval_policy = "on-request" sandbox_mode = "workspace-write" allow_login_shell = false cli_auth_credentials_store = "keyring"
이 예시는 모델, approval, workspace write, login shell, credential store를 정합니다. API key를 하드코딩하는 예시가 아닙니다. auth.json에는 access token이 들어갈 수 있으므로 공유하거나 commit하면 안 됩니다.
Project config: 공유 정책만 남기기
프로젝트 설정은 저장소가 책임질 수 있는 내용만 담아야 합니다.
toml#:schema https://developers.openai.com/codex/config-schema.json approval_policy = "untrusted" sandbox_mode = "workspace-write" allow_login_shell = false developer_instructions = """ Follow this repository's AGENTS.md. Keep generated assets in documented project paths. Do not commit credentials, auth state, or provider tokens. """
이것은 shared policy입니다. token도 없고, 전체 컴퓨터 권한도 없습니다. 공유 프로젝트에 danger-full-access나 approval_policy = "never"를 넣는다면, 격리된 자동화 환경이라는 근거가 있어야 합니다.
MCP와 provider 설정은 짧고 간접적으로
MCP는 먼저 helper로 추가하세요.
bashcodex mcp add docs --env DOCS_TOKEN="$DOCS_TOKEN" -- node ./mcp/docs-server.mjs codex mcp get docs --json
직접 TOML을 쓸 때도 secret은 env로 넘깁니다.
toml[mcp_servers.docs] command = "node" args = ["./mcp/docs-server.mjs"] env_vars = ["DOCS_TOKEN"] startup_timeout_sec = 10 tool_timeout_sec = 60 required = true
openai_base_url은 built-in OpenAI provider의 요청 endpoint를 바꾸는 설정입니다. 이 값이 subscription billing, API key billing, workspace policy를 자동으로 설명해 주지는 않습니다.
Sandbox, approvals, profiles
일반 개발에서는 workspace-write와 on-request가 실용적인 시작점입니다. review만 할 때는 read-only가 낫고, danger-full-access는 격리된 환경에서만 명시적으로 쓰는 편이 안전합니다.
일회성 실험은 영구 파일을 수정하지 말고 command로 처리하세요.
bashcodex --model gpt-5.4-mini codex --sandbox read-only codex --config model='"gpt-5.4"' codex --config sandbox_workspace_write.network_access=true
반복되는 CLI preset은 profile로 둡니다.
toml[profiles.review] model = "gpt-5.4" sandbox_mode = "read-only" approval_policy = "on-request"
bashcodex --profile review
단, OpenAI는 profiles를 experimental로 설명하고 IDE extension에서는 지원하지 않는다고 적고 있습니다. CLI 편의 기능이지 모든 Codex surface의 공통 정책은 아닙니다.
설정이 적용되지 않을 때
| 확인 순서 | 볼 것 |
|---|---|
| Current command | shell alias, flags, --config, --profile |
| Current directory | pwd, repo root, nested .codex/config.toml |
| Project trust | untrusted project에서는 project config가 건너뛰어집니다 |
| TOML syntax | quotes, arrays, table names, schema hint |
| Key support | official config reference와 local codex --help |
| MCP server | codex mcp get <name> --json |
| Auth state | auth.json, keyring, env vars |
브라우저나 desktop app을 제어하는 문제라면 config.toml만으로 해결하려고 하지 마세요. 그 영역은 Codex Computer Use guide가 더 가깝습니다.
FAQ
Codex config.toml은 어디에 있나요?
user config는 ~/.codex/config.toml입니다. trusted project는 .codex/config.toml을 둘 수 있고, system config는 /etc/codex/config.toml입니다.
API key를 config.toml에 넣어도 되나요?
공유 project config에는 넣지 마세요. environment variables, OS keyring, private secret manager를 사용하세요.
project config가 왜 적용되지 않나요?
project trust, cwd, 더 가까운 .codex/config.toml, selected profile, CLI flags, --config를 확인하세요.
--config는 언제 쓰나요?
한 번만 시험하는 model, sandbox, nested key에 씁니다. 반복되는 값은 user config나 profile로 옮기세요.
danger-full-access는 써도 되나요?
격리된 환경에서 broad access가 실제로 필요할 때만 쓰세요. 공유 저장소의 기본값으로는 부적절합니다.
공식 schema는 어디에 있나요?
https://developers.openai.com/codex/config-schema.json입니다. TOML 상단에 #:schema https://developers.openai.com/codex/config-schema.json를 넣으면 editor 도움을 받을 수 있습니다.