구성 참조
이 페이지는 Codex 구성 파일을 검색하며 확인할 수 있는 참조 문서입니다. 개념 설명과 예시는 기본 구성과 고급 구성부터 참고하십시오.
config.toml
사용자 수준 구성은 ~/.codex/config.toml에 저장됩니다. .codex/config.toml 파일로 프로젝트 범위의 오버라이드를 추가할 수도 있습니다. Codex는 사용자가 프로젝트를 신뢰한 경우에만 프로젝트 범위의 구성 파일을 로드합니다.
Sandbox와 승인 관련 key(approval_policy, sandbox_mode, sandbox_workspace_write.*)는 이 참조 문서와 함께 Sandbox와 승인, writable root 안의 보호 경로, 네트워크 접근을 같이 확인하십시오.
| Key | 타입 | 설명 |
|---|---|---|
model | string | 사용할 모델입니다(예: gpt-5.5). |
review_model | string | /review에서 사용할 선택적 모델 오버라이드입니다. 기본값은 현재 세션 모델입니다. |
model_provider | string | model_providers의 provider id입니다(기본값: openai). |
openai_base_url | string | 내장 openai model provider에 사용할 base URL 오버라이드입니다. |
model_context_window | number | 활성 모델에서 사용할 수 있는 context window token 수입니다. |
model_auto_compact_token_limit | number | 자동 history compaction을 트리거하는 token threshold입니다. 설정하지 않으면 모델 기본값을 사용합니다. |
model_catalog_json | string (path) | 시작 시 로드할 선택적 JSON model catalog 경로입니다. Profile 수준의 profiles.<name>.model_catalog_json으로 profile별 오버라이드를 지정할 수 있습니다. |
oss_provider | lmstudio | ollama | --oss로 실행할 때 사용할 기본 local provider입니다. 설정하지 않으면 Codex가 물어봅니다. |
approval_policy | untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } } | Codex가 명령을 실행하기 전에 언제 승인을 요청하며 멈출지 제어합니다. approval_policy = { granular = { ... } }로 특정 prompt category를 허용하거나 자동 거절하면서 다른 prompt는 interactive 상태로 둘 수 있습니다. on-failure는 deprecated입니다. Interactive 실행에는 on-request, non-interactive 실행에는 never를 사용하십시오. |
approval_policy.granular.sandbox_approval | boolean | true이면 sandbox escalation 승인 prompt를 표시할 수 있습니다. |
approval_policy.granular.rules | boolean | true이면 execpolicy prompt rule이 트리거한 승인을 표시할 수 있습니다. |
approval_policy.granular.mcp_elicitations | boolean | true이면 MCP elicitation prompt를 자동 거절하지 않고 표시할 수 있습니다. |
approval_policy.granular.request_permissions | boolean | true이면 request_permissions tool의 prompt를 표시할 수 있습니다. |
approval_policy.granular.skill_approval | boolean | true이면 skill-script 승인 prompt를 표시할 수 있습니다. |
approvals_reviewer | user | auto_review | on-request 또는 granular approval policy에서 승인 가능한 prompt를 누가 검토할지 지정합니다. 기본값은 user이며, auto_review는 reviewer subagent를 사용합니다. 이 설정은 sandboxing이나 sandbox 안에서 이미 허용된 review action을 바꾸지 않습니다. |
auto_review.policy | string | 자동 review에 사용할 local Markdown policy 지침입니다. 관리형 guardian_policy_config가 우선합니다. 빈 값은 무시됩니다. |
allow_login_shell | boolean | Shell 기반 tool이 login-shell semantics를 사용할 수 있게 합니다. 기본값은 true입니다. false이면 login = true 요청이 거절되고, login이 생략된 경우 non-login shell이 기본값이 됩니다. |
sandbox_mode | read-only | workspace-write | danger-full-access | 명령 실행 중 파일 시스템과 네트워크 접근에 적용할 sandbox 정책입니다. |
sandbox_workspace_write.writable_roots | array<string> | sandbox_mode = "workspace-write"일 때 추가로 쓰기 가능한 root입니다. |
sandbox_workspace_write.network_access | boolean | workspace-write sandbox 안에서 outbound network access를 허용합니다. |
sandbox_workspace_write.exclude_tmpdir_env_var | boolean | workspace-write 모드에서 $TMPDIR를 writable root에서 제외합니다. |
sandbox_workspace_write.exclude_slash_tmp | boolean | workspace-write 모드에서 /tmp를 writable root에서 제외합니다. |
windows.sandbox | unelevated | elevated | Windows에서 Codex를 native로 실행할 때 사용하는 Windows 전용 native sandbox mode입니다. |
windows.sandbox_private_desktop | boolean | Native Windows에서 최종 sandboxed child process를 기본적으로 private desktop에서 실행합니다. 기존 Winsta0\\Default 동작과의 호환성이 필요할 때만 false로 설정하십시오. |
notify | array<string> | 알림을 위해 호출할 command입니다. Codex에서 JSON payload를 받습니다. |
check_for_update_on_startup | boolean | 시작할 때 Codex update를 확인합니다. 중앙에서 update를 관리할 때만 false로 설정하십시오. |
feedback.enabled | boolean | Codex surface 전반에서 /feedback을 통한 feedback 제출을 활성화합니다(기본값: true). |
analytics.enabled | boolean | 이 machine/profile의 analytics를 켜거나 끕니다. 설정하지 않으면 client 기본값을 사용합니다. |
instructions | string | 향후 사용을 위해 예약된 key입니다. model_instructions_file 또는 AGENTS.md 사용을 권장합니다. |
developer_instructions | string | 세션에 주입할 추가 developer instruction입니다(선택 사항). |
log_dir | string (path) | Codex가 log file(예: codex-tui.log)을 쓰는 디렉터리입니다. 기본값은 $CODEX_HOME/log입니다. |
sqlite_home | string (path) | Agent job과 기타 resume 가능한 runtime state에서 사용하는 SQLite 기반 state DB를 Codex가 저장할 디렉터리입니다. |
compact_prompt | string | History compaction prompt의 inline 오버라이드입니다. |
commit_attribution | string | [features].codex_git_commit이 켜져 있을 때 사용할 commit co-author trailer입니다. 기본값은 Codex <noreply@openai.com>이며, 비활성화하려면 ""로 설정합니다. |
model_instructions_file | string (path) | AGENTS.md 대신 사용할 내장 지침 대체 파일입니다. |
personality | none | friendly | pragmatic | supportsPersonality를 지원한다고 표시한 모델의 기본 커뮤니케이션 스타일입니다. Thread/turn 단위 또는 /personality로 오버라이드할 수 있습니다. |
service_tier | flex | fast | 새 turn에 사용할 선호 service tier입니다. |
experimental_compact_prompt_file | string (path) | Compaction prompt 오버라이드를 파일에서 로드합니다(실험적 기능). |
skills.config | array<object> | config.toml에 저장되는 skill별 enablement override입니다. |
skills.config.<index>.path | string (path) | SKILL.md가 들어 있는 skill folder의 경로입니다. |
skills.config.<index>.enabled | boolean | 참조된 skill을 활성화하거나 비활성화합니다. |
apps.<id>.enabled | boolean | 특정 app/connector를 id 기준으로 활성화하거나 비활성화합니다(기본값: true). |
apps._default.enabled | boolean | App별 오버라이드가 없을 때 모든 app에 적용할 기본 enabled 상태입니다. |
apps._default.destructive_enabled | boolean | destructive_hint = true인 app tool을 기본적으로 허용할지 거부할지 지정합니다. |
apps._default.open_world_enabled | boolean | open_world_hint = true인 app tool을 기본적으로 허용할지 거부할지 지정합니다. |
apps.<id>.destructive_enabled | boolean | 이 app에서 destructive_hint = true라고 표시된 tool을 허용하거나 차단합니다. |
apps.<id>.open_world_enabled | boolean | 이 app에서 open_world_hint = true라고 표시된 tool을 허용하거나 차단합니다. |
apps.<id>.default_tools_enabled | boolean | Tool별 오버라이드가 없을 때 이 app의 tool에 적용할 기본 enabled 상태입니다. |
apps.<id>.default_tools_approval_mode | auto | prompt | approve | Tool별 오버라이드가 없을 때 이 app의 tool에 적용할 기본 승인 동작입니다. |
apps.<id>.tools.<tool>.enabled | boolean | App tool 하나에 대한 tool별 enabled 오버라이드입니다(예: repos/list). |
apps.<id>.tools.<tool>.approval_mode | auto | prompt | approve | App tool 하나에 대한 tool별 승인 동작 오버라이드입니다. |
tool_suggest.discoverables | array<table> | 추가로 발견 가능한 connector 또는 plugin에 대해 tool suggestion을 허용합니다. 각 entry는 type = "connector" 또는 "plugin"과 id를 사용합니다. |
tool_suggest.disabled_tools | array<table> | 특정 discoverable connector 또는 plugin에 대한 suggestion을 비활성화합니다. 각 entry는 type = "connector" 또는 "plugin"과 id를 사용합니다. |
features.apps | boolean | ChatGPT Apps/connectors 지원을 활성화합니다(실험적 기능). |
features.codex_hooks | boolean | hooks.json 또는 inline [hooks] config에서 로드한 lifecycle hook을 활성화합니다. |
features.codex_git_commit | boolean | Codex가 생성하는 git commit을 활성화합니다. 이 기능이 켜져 있으면 Codex는 commit_attribution을 사용해 생성된 commit message에 Co-authored-by: trailer를 추가합니다. |
hooks | table | config.toml 안에 inline으로 구성한 lifecycle hook입니다. hooks.json과 같은 event schema를 사용합니다. 예시와 지원 event는 Hooks guide를 참고하십시오. |
features.memories | boolean | Memories를 활성화합니다(기본값: off). |
mcp_servers.<id>.command | string | MCP stdio server를 시작할 launcher command입니다. |
mcp_servers.<id>.args | array<string> | MCP stdio server command에 전달할 argument입니다. |
mcp_servers.<id>.env | map<string,string> | MCP stdio server에 전달할 환경 변수입니다. |
mcp_servers.<id>.env_vars | array<string | { name = string, source = "local" | "remote" }> | MCP stdio server에 대해 추가로 allowlist에 넣을 환경 변수입니다. String entry는 기본적으로 source = "local"이며, executor-backed remote stdio에서만 source = "remote"를 사용하십시오. |
mcp_servers.<id>.cwd | string | MCP stdio server process의 working directory입니다. |
mcp_servers.<id>.url | string | MCP streamable HTTP server의 endpoint입니다. |
mcp_servers.<id>.bearer_token_env_var | string | MCP HTTP server의 bearer token을 가져올 환경 변수입니다. |
mcp_servers.<id>.http_headers | map<string,string> | 각 MCP HTTP request에 포함할 static HTTP header입니다. |
mcp_servers.<id>.env_http_headers | map<string,string> | MCP HTTP server에서 환경 변수로 채울 HTTP header입니다. |
mcp_servers.<id>.enabled | boolean | 구성을 제거하지 않고 MCP server를 비활성화합니다. |
mcp_servers.<id>.required | boolean | true이면 활성화된 이 MCP server를 초기화할 수 없을 때 startup/resume이 실패합니다. |
mcp_servers.<id>.startup_timeout_sec | number | MCP server의 기본 10초 startup timeout을 오버라이드합니다. |
mcp_servers.<id>.startup_timeout_ms | number | startup_timeout_sec의 millisecond 단위 alias입니다. |
mcp_servers.<id>.tool_timeout_sec | number | MCP server tool별 기본 60초 timeout을 오버라이드합니다. |
mcp_servers.<id>.enabled_tools | array<string> | MCP server가 노출하는 tool name allow list입니다. |
mcp_servers.<id>.disabled_tools | array<string> | MCP server에 대해 enabled_tools 뒤에 적용되는 deny list입니다. |
mcp_servers.<id>.scopes | array<string> | 해당 MCP server에 인증할 때 요청할 OAuth scope입니다. |
mcp_servers.<id>.oauth_resource | string | MCP login 중 포함할 선택적 RFC 8707 OAuth resource parameter입니다. |
mcp_servers.<id>.experimental_environment | local | remote | MCP server의 실험적 placement입니다. remote는 remote executor environment를 통해 stdio server를 시작합니다. Streamable HTTP remote placement는 구현되어 있지 않습니다. |
agents.max_threads | number | 동시에 열 수 있는 agent thread의 최대 수입니다. 설정하지 않으면 기본값 6입니다. |
agents.max_depth | number | Spawn된 agent thread에 허용되는 최대 nesting depth입니다. Root session은 depth 0에서 시작하며, 기본값은 1입니다. |
agents.job_max_runtime_seconds | number | spawn_agents_on_csv job에서 worker별 기본 timeout입니다. 설정하지 않으면 tool은 worker당 1800초를 사용합니다. |
agents.<name>.description | string | Codex가 해당 agent type을 선택하고 spawn할 때 참고하는 role guidance입니다. |
agents.<name>.config_file | string (path) | 해당 role에 적용할 TOML config layer 경로입니다. 상대 경로는 role을 선언한 config file 기준으로 해석됩니다. |
agents.<name>.nickname_candidates | array<string> | 해당 role에서 spawn된 agent에 사용할 선택적 display nickname pool입니다. |
memories.generate_memories | boolean | false이면 새로 생성된 thread가 memory-generation input으로 저장되지 않습니다. 기본값은 true입니다. |
memories.use_memories | boolean | false이면 Codex가 future session에 기존 memory를 주입하지 않습니다. 기본값은 true입니다. |
memories.disable_on_external_context | boolean | true이면 MCP tool call, 웹 검색, tool search 같은 external context를 사용하는 thread를 memory generation에서 제외합니다. 기본값은 false입니다. Legacy alias: memories.no_memories_if_mcp_or_web_search. |
memories.max_raw_memories_for_consolidation | number | Global consolidation을 위해 보관할 최근 raw memory의 최대 수입니다. 기본값은 256이며 최대 4096까지 허용됩니다. |
memories.max_unused_days | number | 마지막으로 사용된 뒤 consolidation 대상에서 제외되기 전까지 허용되는 최대 일수입니다. 기본값은 30이며 0-365로 제한됩니다. |
memories.max_rollout_age_days | number | Memory generation 대상으로 고려할 thread의 최대 age입니다. 기본값은 30이며 0-90으로 제한됩니다. |
memories.max_rollouts_per_startup | number | Startup pass마다 처리할 rollout candidate의 최대 수입니다. 기본값은 16이며 최대 128까지 허용됩니다. |
memories.min_rollout_idle_hours | number | Thread를 memory generation 대상으로 고려하기 전 필요한 최소 idle time입니다. 기본값은 6이며 1-48로 제한됩니다. |
memories.min_rate_limit_remaining_percent | number | Memory generation을 시작하기 전에 Codex rate-limit window에 남아 있어야 하는 최소 비율입니다. 기본값은 25이며 0-100으로 제한됩니다. |
memories.extract_model | string | Thread별 memory extraction에 사용할 선택적 모델 오버라이드입니다. |
memories.consolidation_model | string | Global memory consolidation에 사용할 선택적 모델 오버라이드입니다. |
features.unified_exec | boolean | 통합 PTY 기반 exec tool을 사용합니다. 안정화된 기능이며, Windows를 제외하고 기본적으로 켜져 있습니다. |
features.shell_snapshot | boolean | 반복 명령을 빠르게 실행하기 위해 shell environment snapshot을 만듭니다. 안정화된 기능이며 기본적으로 켜져 있습니다. |
features.undo | boolean | Undo support를 활성화합니다. 안정화된 기능이며 기본값은 off입니다. |
features.multi_agent | boolean | Multi-agent collaboration tool(spawn_agent, send_input, resume_agent, wait_agent, close_agent)을 활성화합니다. 안정화된 기능이며 기본적으로 켜져 있습니다. |
features.personality | boolean | Personality selection control을 활성화합니다. 안정화된 기능이며 기본적으로 켜져 있습니다. |
features.web_search | boolean | Deprecated legacy toggle입니다. 최상위 web_search 설정을 권장합니다. |
features.web_search_cached | boolean | Deprecated legacy toggle입니다. web_search가 unset이면 true가 web_search = "cached"로 매핑됩니다. |
features.web_search_request | boolean | Deprecated legacy toggle입니다. web_search가 unset이면 true가 web_search = "live"로 매핑됩니다. |
features.shell_tool | boolean | 명령 실행에 사용할 기본 shell tool을 활성화합니다. 안정화된 기능이며 기본적으로 켜져 있습니다. |
features.enable_request_compression | boolean | 지원되는 경우 streaming request body를 zstd로 압축합니다. 안정화된 기능이며 기본적으로 켜져 있습니다. |
features.skill_mcp_dependency_install | boolean | Skill에 필요한 MCP dependency가 없을 때 prompt를 표시하고 설치할 수 있게 합니다. 안정화된 기능이며 기본적으로 켜져 있습니다. |
features.fast_mode | boolean | Fast mode 선택과 service_tier = "fast" 경로를 활성화합니다. 안정화된 기능이며 기본적으로 켜져 있습니다. |
features.prevent_idle_sleep | boolean | Turn이 실행 중일 때 machine이 sleep 상태로 들어가지 않게 합니다. 실험적 기능이며 기본값은 off입니다. |
suppress_unstable_features_warning | boolean | 개발 중인 feature flag가 활성화되었을 때 나타나는 경고를 숨깁니다. |
model_providers.<id> | table | Custom provider 정의입니다. Built-in provider ID(openai, ollama, lmstudio)는 예약되어 있으며 오버라이드할 수 없습니다. |
model_providers.<id>.name | string | Custom model provider의 display name입니다. |
model_providers.<id>.base_url | string | Model provider의 API base URL입니다. |
model_providers.<id>.env_key | string | Provider API key를 제공하는 환경 변수입니다. |
model_providers.<id>.env_key_instructions | string | Provider API key 설정에 대한 선택적 안내 문구입니다. |
model_providers.<id>.experimental_bearer_token | string | Provider에 직접 전달할 bearer token입니다. 권장하지 않으며 env_key를 사용하십시오. |
model_providers.<id>.requires_openai_auth | boolean | Provider가 OpenAI authentication을 사용하는지 지정합니다. 기본값은 false입니다. |
model_providers.<id>.wire_api | responses | Provider가 사용하는 protocol입니다. responses만 지원되며, 생략하면 기본값입니다. |
model_providers.<id>.query_params | map<string,string> | Provider request에 덧붙일 추가 query parameter입니다. |
model_providers.<id>.http_headers | map<string,string> | Provider request에 추가할 static HTTP header입니다. |
model_providers.<id>.env_http_headers | map<string,string> | 존재할 경우 환경 변수에서 채우는 HTTP header입니다. |
model_providers.<id>.request_max_retries | number | Provider로 보내는 HTTP request의 retry 횟수입니다(기본값: 4). |
model_providers.<id>.stream_max_retries | number | SSE streaming interruption의 retry 횟수입니다(기본값: 5). |
model_providers.<id>.stream_idle_timeout_ms | number | SSE stream의 idle timeout입니다. 단위는 millisecond입니다(기본값: 300000). |
model_providers.<id>.supports_websockets | boolean | 해당 provider가 Responses API WebSocket transport를 지원하는지 지정합니다. |
model_providers.<id>.auth | table | Custom provider를 위한 command-backed bearer token 구성입니다. env_key, experimental_bearer_token, requires_openai_auth와 함께 사용하지 마십시오. |
model_providers.<id>.auth.command | string | Codex가 bearer token을 필요로 할 때 실행할 command입니다. 이 command는 token을 stdout에 출력해야 합니다. |
model_providers.<id>.auth.args | array<string> | Token command에 전달할 argument입니다. |
model_providers.<id>.auth.timeout_ms | number | Token command의 최대 runtime입니다. 단위는 millisecond입니다(기본값: 5000). |
model_providers.<id>.auth.refresh_interval_ms | number | Codex가 token을 proactive하게 refresh하는 주기입니다. 단위는 millisecond입니다(기본값: 300000). 인증 retry 이후에만 refresh하려면 0으로 설정합니다. |
model_providers.<id>.auth.cwd | string (path) | Token command의 working directory입니다. |
model_providers.amazon-bedrock.aws.profile | string | Built-in amazon-bedrock provider가 사용할 AWS profile name입니다. |
model_providers.amazon-bedrock.aws.region | string | Built-in amazon-bedrock provider가 사용할 AWS region입니다. |
model_reasoning_effort | minimal | low | medium | high | xhigh | 지원되는 모델의 reasoning effort를 조정합니다. Responses API 전용이며, xhigh 지원 여부는 모델에 따라 다릅니다. |
plan_mode_reasoning_effort | none | minimal | low | medium | high | xhigh | Plan mode 전용 reasoning 오버라이드입니다. 설정하지 않으면 Plan mode의 내장 preset 기본값을 사용합니다. |
model_reasoning_summary | auto | concise | detailed | none | Reasoning summary의 detail 수준을 선택하거나 summary를 완전히 끕니다. |
model_verbosity | low | medium | high | GPT-5 Responses API의 선택적 verbosity 오버라이드입니다. 설정하지 않으면 선택한 모델/preset 기본값을 사용합니다. |
model_supports_reasoning_summaries | boolean | Codex가 reasoning metadata를 보낼지 여부를 강제로 지정합니다. |
shell_environment_policy.inherit | all | core | none | Subprocess를 생성할 때의 기본 environment inheritance입니다. |
shell_environment_policy.ignore_default_excludes | boolean | 다른 filter가 실행되기 전에 KEY/SECRET/TOKEN이 포함된 variable을 유지합니다. |
shell_environment_policy.exclude | array<string> | 기본값 적용 이후 제거할 환경 변수 glob pattern입니다. |
shell_environment_policy.include_only | array<string> | Pattern allowlist입니다. 설정하면 match되는 variable만 유지합니다. |
shell_environment_policy.set | map<string,string> | 모든 subprocess에 주입할 명시적 environment override입니다. |
shell_environment_policy.experimental_use_profile | boolean | Subprocess를 생성할 때 사용자 shell profile을 사용합니다. |
project_root_markers | array<string> | Project root를 찾기 위해 parent directory를 검색할 때 사용하는 marker filename 목록입니다. |
project_doc_max_bytes | number | Project instruction을 만들 때 AGENTS.md에서 읽을 최대 byte 수입니다. |
project_doc_fallback_filenames | array<string> | AGENTS.md가 없을 때 추가로 시도할 filename입니다. |
profile | string | Startup 시 기본으로 적용할 profile입니다(--profile과 동일). |
profiles.<name>.* | various | 지원되는 구성 key에 대한 profile 범위의 오버라이드입니다. |
profiles.<name>.service_tier | flex | fast | 새 turn에 대한 profile 범위의 service tier preference입니다. |
profiles.<name>.plan_mode_reasoning_effort | none | minimal | low | medium | high | xhigh | Profile 범위의 Plan mode reasoning 오버라이드입니다. |
profiles.<name>.web_search | disabled | cached | live | Profile 범위의 web search mode 오버라이드입니다(기본값: "cached"). |
profiles.<name>.personality | none | friendly | pragmatic | 지원되는 모델에 대한 profile 범위의 커뮤니케이션 스타일 오버라이드입니다. |
profiles.<name>.model_catalog_json | string (path) | Profile 범위의 model catalog JSON path 오버라이드입니다. 시작 시에만 적용되며, 해당 profile의 최상위 model_catalog_json을 오버라이드합니다. |
profiles.<name>.model_instructions_file | string (path) | Profile 범위에서 built-in instruction file을 대체할 파일입니다. |
profiles.<name>.experimental_use_unified_exec_tool | boolean | Unified exec를 활성화하는 legacy name입니다. [features].unified_exec 사용을 권장합니다. |
profiles.<name>.oss_provider | lmstudio | ollama | --oss session에 사용할 profile 범위의 OSS provider입니다. |
profiles.<name>.tools_view_image | boolean | 해당 profile에서 view_image tool을 활성화하거나 비활성화합니다. |
profiles.<name>.analytics.enabled | boolean | Profile 범위의 analytics enablement 오버라이드입니다. |
profiles.<name>.windows.sandbox | unelevated | elevated | Profile 범위의 Windows sandbox mode 오버라이드입니다. |
history.persistence | save-all | none | Codex가 session transcript를 history.jsonl에 저장할지 제어합니다. |
tool_output_token_limit | number | 개별 tool/function output을 history에 저장할 때의 token budget입니다. |
background_terminal_max_timeout | number | 빈 write_stdin poll의 최대 poll window입니다. 단위는 millisecond입니다(background terminal polling). 기본값: 300000(5분). 이전 background_terminal_timeout key를 대체합니다. |
history.max_bytes | number | 설정하면 history file 크기를 byte 단위로 제한하고, 오래된 entry부터 삭제합니다. |
file_opener | vscode | vscode-insiders | windsurf | cursor | none | Codex output의 citation을 여는 데 사용할 URI scheme입니다(기본값: vscode). |
otel.environment | string | 전송되는 OpenTelemetry event에 적용할 environment tag입니다(기본값: dev). |
otel.exporter | none | otlp-http | otlp-grpc | OpenTelemetry exporter를 선택하고 endpoint metadata를 제공합니다. |
otel.trace_exporter | none | otlp-http | otlp-grpc | OpenTelemetry trace exporter를 선택하고 endpoint metadata를 제공합니다. |
otel.metrics_exporter | none | statsig | otlp-http | otlp-grpc | OpenTelemetry metrics exporter를 선택합니다(기본값: statsig). |
otel.log_user_prompt | boolean | OpenTelemetry log에 raw user prompt를 export하도록 opt in합니다. |
otel.exporter.<id>.endpoint | string | OTEL log exporter endpoint입니다. |
otel.exporter.<id>.protocol | binary | json | OTLP/HTTP exporter가 사용하는 protocol입니다. |
otel.exporter.<id>.headers | map<string,string> | OTEL exporter request에 포함할 static header입니다. |
otel.trace_exporter.<id>.endpoint | string | OTEL log의 trace exporter endpoint입니다. |
otel.trace_exporter.<id>.protocol | binary | json | OTLP/HTTP trace exporter가 사용하는 protocol입니다. |
otel.trace_exporter.<id>.headers | map<string,string> | OTEL trace exporter request에 포함할 static header입니다. |
otel.exporter.<id>.tls.ca-certificate | string | OTEL exporter TLS의 CA certificate path입니다. |
otel.exporter.<id>.tls.client-certificate | string | OTEL exporter TLS의 client certificate path입니다. |
otel.exporter.<id>.tls.client-private-key | string | OTEL exporter TLS의 client private key path입니다. |
otel.trace_exporter.<id>.tls.ca-certificate | string | OTEL trace exporter TLS의 CA certificate path입니다. |
otel.trace_exporter.<id>.tls.client-certificate | string | OTEL trace exporter TLS의 client certificate path입니다. |
otel.trace_exporter.<id>.tls.client-private-key | string | OTEL trace exporter TLS의 client private key path입니다. |
tui | table | Inline desktop notification 활성화 같은 TUI 전용 옵션입니다. |
tui.notifications | boolean | array<string> | TUI notification을 활성화합니다. 특정 event type으로 제한할 수도 있습니다. |
tui.notification_method | auto | osc9 | bel | Terminal notification 방식입니다(기본값: auto). |
tui.notification_condition | unfocused | always | TUI notification을 terminal에 focus가 없을 때만 보낼지, focus와 관계없이 보낼지 제어합니다. 기본값은 unfocused입니다. |
tui.animations | boolean | Terminal animation(welcome screen, shimmer, spinner)을 활성화합니다(기본값: true). |
tui.alternate_screen | auto | always | never | TUI의 alternate screen 사용을 제어합니다. 기본값은 auto이며, auto는 Zellij에서 scrollback 보존을 위해 건너뜁니다. |
tui.show_tooltips | boolean | TUI welcome screen에서 onboarding tooltip을 표시합니다(기본값: true). |
tui.status_line | array<string> | null | TUI footer status-line item identifier의 순서 있는 목록입니다. null은 status line을 비활성화합니다. |
tui.terminal_title | array<string> | null | Terminal window/tab title item identifier의 순서 있는 목록입니다. 기본값은 ["spinner", "project"]이며, null은 title update를 비활성화합니다. |
tui.theme | string | Syntax-highlighting theme 오버라이드입니다(kebab-case theme name). |
tui.keymap.<context>.<action> | string | array<string> | TUI action에 대한 keyboard shortcut binding입니다. 지원 context에는 global, chat, composer, editor, pager, list, approval이 있으며, context-specific binding은 tui.keymap.global을 오버라이드합니다. |
tui.keymap.<context>.<action> = [] | empty array | 해당 keymap context에서 action binding을 해제합니다. Key name은 ctrl-a, shift-enter, page-down 같은 normalized string을 사용합니다. |
tui.model_availability_nux.<model> | integer | Model slug를 key로 쓰는 내부 startup-tooltip state입니다. |
hide_agent_reasoning | boolean | TUI와 codex exec output 모두에서 reasoning event를 숨깁니다. |
show_raw_agent_reasoning | boolean | 활성 모델이 raw reasoning content를 emit할 때 이를 표시합니다. |
disable_paste_burst | boolean | TUI에서 burst-paste 감지를 비활성화합니다. |
windows_wsl_setup_acknowledged | boolean | Windows onboarding acknowledgement를 추적합니다(Windows 전용). |
chatgpt_base_url | string | ChatGPT login flow에서 사용하는 base URL을 오버라이드합니다. |
cli_auth_credentials_store | file | keyring | auto | CLI가 cached credential을 저장할 위치를 제어합니다(file-based auth.json 또는 OS keychain). |
mcp_oauth_credentials_store | auto | file | keyring | MCP OAuth credential의 선호 저장소입니다. |
mcp_oauth_callback_port | integer | MCP OAuth login 중 local HTTP callback server에 사용할 선택적 고정 port입니다. 설정하지 않으면 Codex가 OS가 선택한 ephemeral port에 bind합니다. |
mcp_oauth_callback_url | string | MCP OAuth login의 선택적 redirect URI 오버라이드입니다(예: devbox ingress URL). mcp_oauth_callback_port는 여전히 callback listener port를 제어합니다. |
experimental_use_unified_exec_tool | boolean | Unified exec를 활성화하는 legacy name입니다. [features].unified_exec 또는 codex --enable unified_exec 사용을 권장합니다. |
tools.web_search | boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } } | 선택적 web search tool 구성입니다. Legacy boolean form도 여전히 허용되지만, object form을 쓰면 search context size, allowed domain, 대략적인 user location을 설정할 수 있습니다. |
tools.view_image | boolean | Local-image attachment tool view_image를 활성화합니다. |
web_search | disabled | cached | live | Web search mode입니다(기본값: "cached"). cached는 OpenAI가 관리하는 index를 사용하고 live page를 가져오지 않습니다. --yolo 또는 다른 full access sandbox 설정을 사용하면 기본값은 "live"가 됩니다. 웹에서 최신 데이터를 가져오려면 "live"를, tool을 제거하려면 "disabled"를 사용하십시오. |
default_permissions | string | Sandboxed tool call에 적용할 기본 permissions profile 이름입니다. Built-in은 :read-only, :workspace, :danger-no-sandbox이며, custom profile name을 쓰려면 대응하는 [permissions.<name>] table이 필요합니다. |
permissions.<name>.filesystem | table | 이름이 붙은 filesystem permission profile입니다. 각 key는 absolute path 또는 :minimal, :project_roots 같은 special token입니다. |
permissions.<name>.filesystem.glob_scan_max_depth | number | Sandbox startup 전에 match를 snapshot하는 platform에서 deny-read glob pattern을 확장할 최대 depth입니다. 설정할 경우 최소 1이어야 합니다. |
permissions.<name>.filesystem.<path-or-glob> | "read" | "write" | "none" | table | Path, glob pattern, special token에 직접 access를 부여하거나, 해당 root 아래에 nested entry를 scope합니다. Match되는 path의 read를 거부하려면 "none"을 사용합니다. |
permissions.<name>.filesystem.":project_roots".<subpath-or-glob> | "read" | "write" | "none" | 감지된 project root를 기준으로 한 filesystem access입니다. Root 자체에는 "."를 사용하며, "**/*.env" 같은 glob subpath는 "none"으로 read를 거부할 수 있습니다. |
permissions.<name>.network.enabled | boolean | 이 named permissions profile에 network access를 활성화합니다. |
permissions.<name>.network.proxy_url | string | 이 permissions profile이 managed network proxy를 활성화할 때 사용할 HTTP proxy endpoint입니다. |
permissions.<name>.network.enable_socks5 | boolean | 이 permissions profile이 managed network proxy를 활성화할 때 SOCKS5 listener를 노출합니다. |
permissions.<name>.network.socks_url | string | 이 permissions profile에서 사용할 SOCKS5 proxy endpoint입니다. |
permissions.<name>.network.enable_socks5_udp | boolean | 활성화되면 SOCKS5 listener를 통한 UDP를 허용합니다. |
permissions.<name>.network.allow_upstream_proxy | boolean | Managed proxy가 다른 upstream proxy에 chain할 수 있게 합니다. |
permissions.<name>.network.dangerously_allow_non_loopback_proxy | boolean | Managed proxy listener가 non-loopback bind address를 사용할 수 있게 합니다. |
permissions.<name>.network.dangerously_allow_all_unix_sockets | boolean | Proxy가 기본 제한 set 대신 임의의 Unix socket을 사용할 수 있게 합니다. |
permissions.<name>.network.mode | limited | full | Subprocess traffic에 사용할 network proxy mode입니다. |
permissions.<name>.network.domains | map<string, allow | deny> | Managed proxy의 domain rule입니다. Domain name이나 wildcard pattern을 key로 쓰고, 값은 allow 또는 deny를 사용합니다. |
permissions.<name>.network.unix_sockets | map<string, allow | none> | Managed proxy의 Unix socket rule입니다. Socket path를 key로 쓰고, 값은 allow 또는 none을 사용합니다. |
permissions.<name>.network.allow_local_binding | boolean | Managed proxy를 통한 local bind/listen 작업을 허용합니다. |
projects.<path>.trust_level | string | Project 또는 worktree를 trusted 또는 untrusted로 표시합니다("trusted" | "untrusted"). Untrusted project에서는 project-local config, hook, rule을 포함한 project-scoped .codex/ layer를 건너뜁니다. |
notice.hide_full_access_warning | boolean | Full access warning prompt를 확인했는지 추적합니다. |
notice.hide_world_writable_warning | boolean | Windows world-writable directory warning을 확인했는지 추적합니다. |
notice.hide_rate_limit_model_nudge | boolean | Rate limit model switch reminder를 opt out했는지 추적합니다. |
notice.hide_gpt5_1_migration_prompt | boolean | GPT-5.1 migration prompt를 확인했는지 추적합니다. |
notice.hide_gpt-5.1-codex-max_migration_prompt | boolean | gpt-5.1-codex-max migration prompt를 확인했는지 추적합니다. |
notice.model_migrations | map<string,string> | 확인한 model migration을 old->new mapping으로 추적합니다. |
forced_login_method | chatgpt | api | Codex를 특정 authentication method로 제한합니다. |
forced_chatgpt_workspace_id | string (uuid) | ChatGPT login을 특정 workspace identifier로 제한합니다. |
최신 config.toml JSON schema는 여기에서 확인할 수 있습니다.
VS Code 또는 Cursor에서 config.toml을 편집할 때 autocompletion과 diagnostics를 사용하려면 Even Better TOML extension을 설치하고 config.toml 맨 위에 다음 줄을 추가합니다.
#:schema https://developers.openai.com/codex/config-schema.json
참고: experimental_instructions_file은 model_instructions_file로 이름을 바꾸십시오. Codex는 이전 key를 deprecated 처리하므로 기존 config를 새 이름으로 업데이트해야 합니다.
requirements.toml
requirements.toml은 관리자가 강제하는 구성 파일로, 사용자가 오버라이드할 수 없는 보안 민감 설정을 제한합니다. 자세한 설명, 위치, 예시는 관리자가 강제하는 요구 사항을 참고하십시오.
ChatGPT Business 및 Enterprise 사용자에게는 Codex가 cloud에서 가져온 requirements도 적용할 수 있습니다. 우선순위 세부 정보는 security page를 참고하십시오.
requirements.toml에서 [features]를 사용하면 config.toml과 같은 canonical key로 feature flag를 고정할 수 있습니다. 생략된 key에는 제약이 적용되지 않습니다.
| Key | 타입 | 설명 |
|---|---|---|
allowed_approval_policies | array<string> | approval_policy에 허용되는 값입니다(예: untrusted, on-request, never, granular). |
allowed_approvals_reviewers | array<string> | approvals_reviewer에 허용되는 값입니다. 예: user, auto_review. |
guardian_policy_config | string | 자동 review에 사용할 관리형 Markdown policy 지침입니다. Local [auto_review].policy보다 우선합니다. 빈 값은 무시됩니다. |
allowed_sandbox_modes | array<string> | sandbox_mode에 허용되는 값입니다. |
remote_sandbox_config | array<table> | Host별 sandbox requirement입니다. hostname_patterns가 resolved host name과 match되는 첫 entry가 해당 requirements source의 최상위 allowed_sandbox_modes를 오버라이드합니다. 현재 host-specific entry는 sandbox mode만 오버라이드합니다. |
remote_sandbox_config[].hostname_patterns | array<string> | 대소문자를 구분하지 않는 host name pattern입니다. *는 임의 길이의 문자 sequence, ?는 한 글자를 의미합니다. |
remote_sandbox_config[].allowed_sandbox_modes | array<string> | 이 host-specific entry가 match될 때 적용할 허용 sandbox mode입니다. |
allowed_web_search_modes | array<string> | web_search에 허용되는 값입니다(disabled, cached, live). disabled는 항상 허용됩니다. 빈 list는 사실상 disabled만 허용합니다. |
features | table | config.toml의 [features] table에 있는 canonical name을 key로 삼아 고정한 feature value입니다. |
features.<name> | boolean | 특정 canonical feature key가 활성화 또는 비활성화 상태로 유지되도록 요구합니다. |
features.in_app_browser | boolean | requirements.toml에서 false로 설정하면 in-app browser pane을 비활성화합니다. |
features.browser_use | boolean | requirements.toml에서 false로 설정하면 Browser Use와 Browser Agent 사용 가능 상태를 비활성화합니다. |
features.computer_use | boolean | requirements.toml에서 false로 설정하면 Computer Use 사용 가능 상태와 관련 install/enablement flow를 비활성화합니다. |
hooks | table | 관리자가 강제하는 managed lifecycle hook입니다. Managed hook directory가 필요하며, config.toml의 inline [hooks]와 같은 event schema를 사용합니다. |
hooks.managed_dir | string (absolute path) | macOS와 Linux에서 managed hook script가 들어 있는 디렉터리입니다. Codex는 이 경로가 absolute이고 존재하는지 확인한 뒤 managed hook을 로드합니다. |
hooks.windows_managed_dir | string (absolute path) | Windows에서 managed hook script가 들어 있는 디렉터리입니다. Codex는 이 경로가 absolute이고 존재하는지 확인한 뒤 managed hook을 로드합니다. |
hooks.<Event> | array<table> | PreToolUse, PostToolUse, PermissionRequest, SessionStart, UserPromptSubmit, Stop 같은 hook event의 matcher group입니다. |
hooks.<Event>[].hooks | array<table> | Matcher group의 hook handler입니다. 현재 command hook이 지원되며, prompt와 agent hook handler는 parse되지만 건너뜁니다. |
permissions.filesystem.deny_read | array<string> | 관리자가 강제하는 filesystem read denial입니다. Entry는 path 또는 glob pattern일 수 있으며, 사용자는 local config로 이를 약화할 수 없습니다. |
mcp_servers | table | 활성화할 수 있는 MCP server allowlist입니다. MCP server가 활성화되려면 server name(<id>)과 identity가 모두 match되어야 합니다. Allowlist에 없거나 identity가 맞지 않는 구성된 MCP server는 비활성화됩니다. |
mcp_servers.<id>.identity | table | 단일 MCP server의 identity rule입니다. command(stdio) 또는 url(streamable HTTP) 중 하나를 설정합니다. |
mcp_servers.<id>.identity.command | string | mcp_servers.<id>.command가 이 command와 match될 때 MCP stdio server를 허용합니다. |
mcp_servers.<id>.identity.url | string | mcp_servers.<id>.url이 이 URL과 match될 때 MCP streamable HTTP server를 허용합니다. |
rules | table | .rules file과 merge되는 관리자가 강제하는 command rule입니다. Requirements rule은 제한적인 형태여야 합니다. |
rules.prefix_rules | array<table> | 강제되는 prefix rule 목록입니다. 각 rule에는 pattern과 decision이 필요합니다. |
rules.prefix_rules[].pattern | array<table> | Pattern token으로 표현한 command prefix입니다. 각 token은 token 또는 any_of 중 하나를 설정합니다. |
rules.prefix_rules[].pattern[].token | string | 이 위치의 단일 literal token입니다. |
rules.prefix_rules[].pattern[].any_of | array<string> | 이 위치에 허용되는 alternative token 목록입니다. |
rules.prefix_rules[].decision | prompt | forbidden | 필수 항목입니다. Requirements rule은 prompt 또는 forbid만 가능하며 allow는 불가능합니다. |
rules.prefix_rules[].justification | string | 승인 prompt 또는 rejection message에 표시할 선택적 non-empty rationale입니다. |