logo

구성 참조

이 페이지는 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입니다.
Previous
Config 고급
Next
인증