把本页作为 Codex 配置文件的可搜索参考。概念说明和示例请先从 Config basics 和 Advanced Config 开始。
config.toml
用户级配置位于 ~/.codex/config.toml。你也可以通过 .codex/config.toml 文件添加项目级覆盖。Codex 只会在你信任该项目时加载项目级配置文件。
Project-scoped config can’t override machine-local provider, auth, host-owned app request metadata, notification, configuration profile selection, 或 telemetry routing keys。Codex ignores openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url, 和 otel 当 they appear in a project-local .codex/config.toml；put provider, notification, 和 telemetry keys in user-level config instead。Config profile files live next 到 config.toml as $CODEX_HOME/profile-name.config.toml；选择 one 使用 --profile profile-name.
For sandbox 和 approval keys (approval_policy, sandbox_mode, 和 sandbox_workspace_write.*), pair this reference 使用 Sandbox 和 approvals , Protected paths in writable roots , 和 Network access 。For beta permission profiles, see Permissions .
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| agents.<name>.config_file | string (path) | Path 到 a TOML config layer for that role；relative paths resolve 从 the config file that declares the role. |
| agents.<name>.description | string | Role guidance shown 到 Codex 当 choosing 和 spawning that agent 输入. |
| agents.<name>.nickname_candidates | array<string> | Optional pool of display nicknames for spawned agents in that role. |
| agents.job_max_runtime_seconds | number | Default per-worker timeout for spawn_agents_on_csv jobs。当 unset, the tool falls back 到 1800 seconds per worker. |
| agents.max_depth | number | Maximum nesting depth allowed for spawned agent threads (root sessions 启动 at depth 0；默认：1). |
| agents.max_threads | number | Maximum number of agent threads that can be 打开 concurrently。Defaults 到 6 当 unset. |
| allow_login_shell | boolean | Allow shell-based tools 到 使用 login-shell semantics。Defaults 到 true；当 false, login = true requests are rejected 和 omitted login 默认s 到 non-login shells. |
| analytics.enabled | boolean | Enable 或 disable analytics for this machine/profile。当 unset, the client 默认 applies. |
| approval_policy | untrusted / on-request / never / { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } } | Controls 当 Codex pauses for approval 之前 executing commands。You can also 使用 approval_policy = { granular = { ..。} } 到 allow 或 auto-reject specific prompt categories while keeping other prompts interactive。on-failure is deprecated；使用 on-request for interactive runs 或 never for non-interactive runs. |
| approval_policy.granular.mcp_elicitations | boolean | 当 true, MCP elicitation prompts are allowed 到 surface 而不是 being auto-rejected. |
| approval_policy.granular.request_permissions | boolean | 当 true, prompts 从 the request_permissions tool are allowed 到 surface. |
| approval_policy.granular.rules | boolean | 当 true, approvals triggered by execpolicy prompt rules are allowed 到 surface. |
| approval_policy.granular.sandbox_approval | boolean | 当 true, sandbox escalation approval prompts are allowed 到 surface. |
| approval_policy.granular.skill_approval | boolean | 当 true, skill-script approval prompts are allowed 到 surface. |
| approvals_reviewer | user / auto_review | Who reviews eligible approval prompts under on-request 或 granular approval policies。Defaults 到 user；auto_review uses the reviewer subagent。This setting doesn't change sandboxing 或 检查 actions already allowed inside the sandbox. |
| apps._默认.approvals_reviewer | user / auto_review | Default reviewer for app tool approval prompts unless overridden per app。当 omitted, apps inherit the top-level approvals_reviewer value. |
| apps._默认.默认_tools_approval_mode | auto / prompt / approve | Default approval behavior for app tools 不使用 per-app 或 per-tool overrides. |
| apps._默认.destructive_enabled | boolean | Default allow/deny for app tools 使用 destructive_hint = true. |
| apps._默认.enabled | boolean | Default app enabled state for all apps unless overridden per app. |
| apps._默认.open_world_enabled | boolean | Default allow/deny for app tools 使用 open_world_hint = true. |
| apps.<id>.approvals_reviewer | user / auto_review | Reviewer for this app's tool approval prompts。Overrides apps._默认.approvals_reviewer. |
| apps.<id>.默认_tools_approval_mode | auto / prompt / approve | Default approval behavior for tools in this app unless a per-tool override exists. |
| apps.<id>.默认_tools_enabled | boolean | Default enabled state for tools in this app unless a per-tool override exists. |
| apps.<id>.destructive_enabled | boolean | Allow 或 block tools in this app that advertise destructive_hint = true. |
| apps.<id>.enabled | boolean | Enable 或 disable a specific app/connector by id (默认：true). |
| apps.<id>.open_world_enabled | boolean | Allow 或 block tools in this app that advertise open_world_hint = true. |
| apps.<id>.tools.<tool>.approval_mode | auto / prompt / approve | Per-tool approval behavior override for a single app tool. |
| apps.<id>.tools.<tool>.enabled | boolean | Per-tool enabled override for an app tool (例如 repos/列出). |
| auto_review.policy | string | Local Markdown policy instructions for automatic 检查。Managed guardian_policy_config takes precedence。Blank values are ignored. |
| background_terminal_max_timeout | number | Maximum poll window in milliseconds for empty write_stdin polls (background terminal polling)。Default：300000 (5 minutes)。Replaces the older background_terminal_timeout key. |
| chatgpt_base_url | string | Override the base URL used during the ChatGPT login flow. |
| check_for_update_on_startup | boolean | Check for Codex updates on startup (设置 到 false only 当 updates are centrally managed). |
| cli_auth_credentials_store | file / keyring / auto | Control where the CLI stores cached credentials (file-based auth.json vs OS keychain). |
| commit_attribution | string | Commit co-author trailer used 当 [features].codex_git_commit is enabled。Defaults 到 Codex <noreply@openai.com>；设置 "" 到 disable. |
| compact_prompt | string | Inline override for the history compaction prompt. |
| 默认_permissions | string | Name of the 默认 permissions profile 到 应用 到 sandboxed tool calls。Built-ins are :读取-only, :workspace, 和 :danger-full-access；custom profile names require matching [permissions.<name>] tables。Don't combine 使用 sandbox_mode 或 [sandbox_workspace_write]. |
| developer_instructions | string | Additional developer instructions injected into session (可选). |
| disable_paste_burst | boolean | Disable burst-paste detection in the TUI. |
| experimental_compact_prompt_file | string (path) | Load the compaction prompt override 从 a file (experimental). |
| experimental_use_unified_exec_tool | boolean | Legacy name for enabling unified exec；prefer [features].unified_exec 或 codex --enable unified_exec. |
| features.apps | boolean | Enable ChatGPT Apps/connectors support (experimental). |
| features.code_mode.direct_only_tool_namespaces | array<string> | Tool namespaces code mode can 使用 only through direct tool calls. |
| features.code_mode.enabled | boolean | Enable code mode feature configuration。This feature is under development 和 off by 默认. |
| features.code_mode.excluded_tool_namespaces | array<string> | Tool namespaces code mode excludes 从 nested code-mode tool guidance 和 executor exposure. |
| features.codex_git_commit | boolean | Enable Codex-generated git commits. When enabled, Codex uses commit_attribution 到 append a Co-authored-by：trailer 到 generated commit messages. |
| features.enable_request_compression | boolean | Compress streaming request bodies 使用 zstd 当 支持的 (stable；on by 默认). |
| features.fast_mode | boolean | Enable model-catalog service tier selection in the TUI, including Fast-tier commands 当 the active model advertises them (stable；on by 默认). |
| features.hooks | boolean | Enable lifecycle hooks loaded 从 hooks.json 或 inline [hooks] config。features.codex_hooks is a deprecated alias. |
| features.memories | boolean | Enable Memories (off by 默认). |
| features.multi_agent | boolean | Enable multi-agent collaboration tools (spawn_agent, send_input, resume_agent, wait_agent, 和 close_agent) (stable；on by 默认). |
| features.network_proxy | boolean / table | Enable sandboxed networking。使用 a table form 当 setting network policy options such as domains (experimental；off by 默认). |
| features.network_proxy.allow_local_binding | boolean | Allow broader local/private-network access。Defaults 到 false；exact local IP literal 或 localhost allow rules can still permit specific local targets. |
| features.network_proxy.allow_upstream_proxy | boolean | Allow chaining through an upstream proxy 从 the environment。Defaults 到 true. |
| features.network_proxy.dangerously_allow_all_unix_sockets | boolean | Permit arbitrary Unix socket destinations 而不是 allowlist-only access。Defaults 到 false；使用 only in tightly controlled environments. |
| features.network_proxy.dangerously_allow_non_loopback_proxy | boolean | Permit non-loopback listener addresses。Defaults 到 false；enabling it can expose proxy listeners beyond localhost. |
| features.network_proxy.domains | map<string, allow / deny> | Domain policy for sandboxed networking。Unset by 默认, which means no external destinations are allowed until you 添加 allow rules。Supports exact hosts, *.example.com for subdomains only, **.example.com for apex plus subdomains, 和 global * allow rules；prefer scoped rules because * broadly opens public outbound access。添加 deny rules for blocked destinations；deny wins on conflicts. |
| features.network_proxy.enable_socks5 | boolean | Expose SOCKS5 support。Defaults 到 true. |
| features.network_proxy.enable_socks5_udp | boolean | Allow UDP over SOCKS5。Defaults 到 true. |
| features.network_proxy.enabled | boolean | Enable sandboxed networking。Defaults 到 false. |
| features.network_proxy.proxy_url | string | HTTP listener URL for sandboxed networking。Defaults 到 "http://127.0.0.1:3128". |
| features.network_proxy.socks_url | string | SOCKS5 listener URL。Defaults 到 "http://127.0.0.1:8081". |
| features.network_proxy.unix_sockets | map<string, allow / deny> | Unix socket policy for sandboxed networking。Unset by 默认；添加 allow entries for permitted sockets. |
| features.personality | boolean | Enable personality selection controls (stable；on by 默认). |
| features.prevent_idle_sleep | boolean | Prevent the machine 从 sleeping while a turn is actively running (experimental；off by 默认). |
| features.rollout_budget.enabled | boolean | Enable rollout budget tracking。This feature is under development 和 off by 默认。当 enabled, features.rollout_budget.limit_tokens is 必需. |
| features.rollout_budget.limit_tokens | integer | Positive token limit for rollout budget tracking。Required 当 rollout budget is enabled. |
| features.rollout_budget.prefill_token_weight | number | Finite non-negative multiplier for prefill tokens in rollout budget accounting。Defaults 到 1.0. |
| features.rollout_budget.reminder_interval_tokens | integer | Positive token interval between rollout budget reminders。Defaults 到 10% of limit_tokens, 使用 a minimum of 1 token. |
| features.rollout_budget.sampling_token_weight | number | Finite non-negative multiplier for sampled tokens in rollout budget accounting。Defaults 到 1.0. |
| features.shell_snapshot | boolean | Snapshot shell environment 到 speed up repeated commands (stable；on by 默认). |
| features.shell_tool | boolean | Enable the 默认 shell tool for running commands (stable；on by 默认). |
| features.skill_mcp_dependency_install | boolean | Allow prompting 和 installing missing MCP dependencies for skills (stable；on by 默认). |
| features.undo | boolean | Enable undo support (stable；off by 默认). |
| features.unified_exec | boolean | 使用 the unified PTY-backed exec tool (stable；enabled by 默认 except on Windows). |
| features.web_search | boolean | Deprecated legacy 切换；prefer the top-level web_search setting. |
| features.web_search_cached | boolean | Deprecated legacy 切换。当 web_search is unset, true maps 到 web_search = "cached". |
| features.web_search_request | boolean | Deprecated legacy 切换。当 web_search is unset, true maps 到 web_search = "live". |
| feedback.enabled | boolean | Enable feedback submission via /feedback across Codex surfaces (默认：true). |
| file_opener | vscode / vscode-insiders / windsurf / cursor / none | URI scheme used 到 打开 citations 从 Codex output (默认：vscode). |
| forced_chatgpt_workspace_id | string (uuid) | Limit ChatGPT logins 到 a specific workspace identifier. |
| forced_login_method | chatgpt / api | Restrict Codex 到 a specific authentication method. |
| hide_agent_reasoning | boolean | Suppress reasoning events in both the TUI 和 codex exec output. |
| history.max_bytes | number | 如果 设置, caps the history file size in bytes by dropping oldest entries. |
| history.持久化ence | save-all / none | Control whether Codex saves session transcripts 到 history.jsonl. |
| hooks | table | Lifecycle hooks configured inline in config.toml。Uses the same event schema as hooks.json；see the Hooks guide for examples 和 支持的 events. |
| hooks.<Event> | array<table> | Matcher groups for hook events such as PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SubagentStart, SubagentStop, UserPromptSubmit, 或 Stop. |
| hooks.<Event>[].hooks | array<table> | Hook handlers for a matcher group。Command hooks are currently 支持的；prompt 和 agent hook handlers are parsed but skipped. |
| hooks.<Event>[].hooks[].commandWindows | string | Windows-only command override for command hooks。The TOML alias command_windows is also accepted. |
| instructions | string | Reserved for future 使用；prefer model_instructions_file 或 AGENTS.md. |
| log_dir | string (path) | Directory where Codex writes log files；默认s 到 $CODEX_HOME/log。Setting this explicitly also enables the opt-in plaintext TUI log, codex-tui.log, in that directory. |
| mcp_oauth_callback_port | integer | Optional fixed port for the local HTTP callback server used during MCP OAuth login。当 unset, Codex binds 到 an ephemeral port chosen by the OS. |
| mcp_oauth_callback_url | string | Optional base callback URL override for MCP OAuth login (例如, a devbox ingress URL)。Codex appends a server-specific callback ID 之前 sending the final OAuth redirect_uri, so register the full derived URI 使用 your provider。mcp_oauth_callback_port still controls the callback listener port. |
| mcp_oauth_credentials_store | auto / file / keyring | Preferred store for MCP OAuth credentials. |
| mcp_servers.<id>.args | array<string> | Arguments passed 到 the MCP stdio server command. |
| mcp_servers.<id>.bearer_token_env_var | string | Environment variable sourcing the bearer token for an MCP HTTP server. |
| mcp_servers.<id>.command | string | Launcher command for an MCP stdio server. |
| mcp_servers.<id>.cwd | string | Working directory for the MCP stdio server process. |
| mcp_servers.<id>.默认_tools_approval_mode | auto / prompt / approve | Default approval behavior for MCP tools on this server unless a per-tool override exists. |
| mcp_servers.<id>.disabled_tools | array<string> | Deny 列出 applied 之后 enabled_tools for the MCP server. |
| mcp_servers.<id>.enabled | boolean | Disable an MCP server 不使用 removing its configuration. |
| mcp_servers.<id>.enabled_tools | array<string> | Allow 列出 of tool names exposed by the MCP server. |
| mcp_servers.<id>.env | map<string,string> | Environment variables forwarded 到 the MCP stdio server. |
| mcp_servers.<id>.env_http_headers | map<string,string> | HTTP headers populated 从 environment variables for an MCP HTTP server. |
| mcp_servers.<id>.env_vars | array<string / { name = string, source = "local" / "remote" }> | Additional environment variables 到 whitelist for an MCP stdio server。String entries 默认 到 source = "local"；使用 source = "remote" only 使用 executor-backed remote stdio. |
| mcp_servers.<id>.experimental_environment | local / remote | Experimental placement for an MCP server。remote starts stdio servers through a remote executor environment；streamable HTTP remote placement is not implemented. |
| mcp_servers.<id>.http_headers | map<string,string> | Static HTTP headers included 使用 each MCP HTTP request. |
| mcp_servers.<id>.oauth_resource | string | Optional RFC 8707 OAuth resource parameter 到 include during MCP login. |
| mcp_servers.<id>.必需 | boolean | 当 true, fail startup/恢复 如果 this enabled MCP server cannot initialize. |
| mcp_servers.<id>.scopes | array<string> | OAuth scopes 到 request 当 authenticating 到 that MCP server. |
| mcp_servers.<id>.startup_timeout_ms | number | Alias for startup_timeout_sec in milliseconds. |
| mcp_servers.<id>.startup_timeout_sec | number | Override the 默认 10s startup timeout for an MCP server. |
| mcp_servers.<id>.tool_timeout_sec | number | Override the 默认 60s per-tool timeout for an MCP server. |
| mcp_servers.<id>.tools.<tool>.approval_mode | auto / prompt / approve | Per-tool approval behavior override for one MCP tool on this server. |
| mcp_servers.<id>.url | string | Endpoint for an MCP streamable HTTP server. |
| memories.consolidation_model | string | Optional model override for global memory consolidation. |
| memories.disable_on_external_context | boolean | 当 true, threads that 使用 external context such as MCP tool calls, web 搜索, 或 tool 搜索 are kept out of memory generation。Defaults 到 false。Legacy alias：memories.no_memories_if_mcp_or_web_search. |
| memories.extract_model | string | Optional model override for per-thread memory extraction. |
| memories.generate_memories | boolean | 当 false, newly created threads are not stored as memory-generation inputs。Defaults 到 true. |
| memories.max_raw_memories_for_consolidation | number | Maximum 最近 raw memories retained for global consolidation。Defaults 到 256 和 is capped at 4096. |
| memories.max_rollout_age_days | number | Maximum age of threads considered for memory generation。Defaults 到 30 和 is clamped 到 0-90. |
| memories.max_rollouts_per_startup | number | Maximum rollout candidates processed per startup pass。Defaults 到 16 和 is capped at 128. |
| memories.max_unused_days | number | Maximum days since a memory was last used 之前 it becomes ineligible for consolidation。Defaults 到 30 和 is clamped 到 0-365. |
| memories.min_rate_limit_remaining_percent | number | Minimum remaining percentage 必需 in Codex rate-limit windows 之前 memory generation starts。Defaults 到 25 和 is clamped 到 0-100. |
| memories.min_rollout_idle_hours | number | Minimum idle time 之前 a thread is considered for memory generation。Defaults 到 6 和 is clamped 到 1-48. |
| memories.use_memories | boolean | 当 false, Codex skips injecting 已有 memories into future sessions。Defaults 到 true. |
| model | string | Model 到 使用 (e.g., gpt-5.5). |
| model_auto_compact_token_limit | number | Token threshold that triggers automatic history compaction (unset uses model 默认s). |
| model_catalog_json | string (path) | Optional path 到 a JSON model catalog loaded on startup。A selected $CODEX_HOME/profile-name.config.toml profile file can override this per profile. |
| model_context_window | number | Context window tokens 可用 到 the active model. |
| model_instructions_file | string (path) | Replacement for built-in instructions 而不是 AGENTS.md. |
| model_provider | string | Provider id 从 model_providers (默认：openai). |
| model_providers.<id> | table | Custom provider definition。Built-in provider IDs (openai, ollama, 和 lmstudio) are reserved 和 cannot be overridden. |
| model_providers.<id>.auth | table | Command-backed bearer token configuration for a custom provider。Do not combine 使用 env_key, experimental_bearer_token, 或 requires_openai_auth. |
| model_providers.<id>.auth.args | array<string> | Arguments passed 到 the token command. |
| model_providers.<id>.auth.command | string | Command 到 运行 当 Codex needs a bearer token。The command must 打印 the token 到 stdout. |
| model_providers.<id>.auth.cwd | string (path) | Working directory for the token command. |
| model_providers.<id>.auth.refresh_interval_ms | number | How often Codex proactively refreshes the token in milliseconds (默认：300000)。设置 到 0 到 refresh only 之后 an authentication retry. |
| model_providers.<id>.auth.timeout_ms | number | Maximum token command runtime in milliseconds (默认：5000). |
| model_providers.<id>.base_url | string | API base URL for the model provider. |
| model_providers.<id>.env_http_headers | map<string,string> | HTTP headers populated 从 environment variables 当 present. |
| model_providers.<id>.env_key | string | Environment variable supplying the provider API key. |
| model_providers.<id>.env_key_instructions | string | Optional setup guidance for the provider API key. |
| model_providers.<id>.experimental_bearer_token | string | Direct bearer token for the provider (discouraged；使用 env_key). |
| model_providers.<id>.http_headers | map<string,string> | Static HTTP headers added 到 provider requests. |
| model_providers.<id>.name | string | Display name for a custom model provider. |
| model_providers.<id>.query_params | map<string,string> | Extra query parameters appended 到 provider requests. |
| model_providers.<id>.request_max_retries | number | Retry count for HTTP requests 到 the provider (默认：4). |
| model_providers.<id>.requires_openai_auth | boolean | The provider uses 打开AI authentication (默认s 到 false). |
| model_providers.<id>.stream_idle_timeout_ms | number | Idle timeout for SSE streams in milliseconds (默认：300000). |
| model_providers.<id>.stream_max_retries | number | Retry count for SSE streaming interruptions (默认：5). |
| model_providers.<id>.supports_websockets | boolean | Whether that provider supports the Responses API WebSocket transport. |
| model_providers.<id>.wire_api | responses | Protocol used by the provider。responses is the only 支持的 value, 和 it is the 默认 当 omitted. |
| model_providers.amazon-bedrock.aws.profile | string | AWS profile name used by the built-in amazon-bedrock provider. |
| model_providers.amazon-bedrock.aws.region | string | AWS region used by the built-in amazon-bedrock provider. |
| model_reasoning_effort | minimal / low / medium / high / xhigh | Adjust reasoning effort for 支持的 models (Responses API only；xhigh is model-dependent). |
| model_reasoning_summary | auto / concise / detailed / none | 选择 reasoning summary detail 或 disable summaries entirely. |
| model_supports_reasoning_summaries | boolean | Force Codex 到 send 或 not send reasoning metadata. |
| model_verbosity | low / medium / high | Optional GPT-5 Responses API verbosity override；当 unset, the selected model/preset 默认 is used. |
| notice.hide_full_access_warning | boolean | Track acknowledgement of the full access warning prompt. |
| notice.hide_gpt-5.1-codex-max_migration_prompt | boolean | Track acknowledgement of the gpt-5.1-codex-max migration prompt. |
| notice.hide_gpt5_1_migration_prompt | boolean | Track acknowledgement of the GPT-5.1 migration prompt. |
| notice.hide_rate_limit_model_nudge | boolean | Track opt-out of the rate limit model 切换 reminder. |
| notice.hide_world_writable_warning | boolean | Track acknowledgement of the Windows world-writable directories warning. |
| notice.model_migrations | map<string,string> | Track acknowledged model migrations as old->新的 mappings. |
| notify | array<string> | Command invoked for notifications；receives a JSON payload 从 Codex. |
| openai_base_url | string | Base URL override for the built-in openai model provider. |
| oss_provider | lmstudio / ollama | Default local provider used 当 running 使用 --oss (默认s 到 prompting 如果 unset). |
| otel.environment | string | Environment tag applied 到 emitted OpenTelemetry events (默认：dev). |
| otel.exporter | none / otlp-http / otlp-grpc | 选择 the OpenTelemetry exporter 和 provide any endpoint metadata. |
| otel.exporter.<id>.endpoint | string | Exporter endpoint for OTEL logs. |
| otel.exporter.<id>.headers | map<string,string> | Static headers included 使用 OTEL exporter requests. |
| otel.exporter.<id>.protocol | binary / json | Protocol used by the OTLP/HTTP exporter. |
| otel.exporter.<id>.tls.ca-certificate | string | CA certificate path for OTEL exporter TLS. |
| otel.exporter.<id>.tls.client-certificate | string | Client certificate path for OTEL exporter TLS. |
| otel.exporter.<id>.tls.client-private-key | string | Client private key path for OTEL exporter TLS. |
| otel.log_user_prompt | boolean | Opt in 到 exporting raw user prompts 使用 OpenTelemetry logs. |
| otel.metrics_exporter | none / statsig / otlp-http / otlp-grpc | 选择 the OpenTelemetry metrics exporter (默认s 到 statsig). |
| otel.trace_exporter | none / otlp-http / otlp-grpc | 选择 the OpenTelemetry trace exporter 和 provide any endpoint metadata. |
| otel.trace_exporter.<id>.endpoint | string | Trace exporter endpoint for OTEL logs. |
| otel.trace_exporter.<id>.headers | map<string,string> | Static headers included 使用 OTEL trace exporter requests. |
| otel.trace_exporter.<id>.protocol | binary / json | Protocol used by the OTLP/HTTP trace exporter. |
| otel.trace_exporter.<id>.tls.ca-certificate | string | CA certificate path for OTEL trace exporter TLS. |
| otel.trace_exporter.<id>.tls.client-certificate | string | Client certificate path for OTEL trace exporter TLS. |
| otel.trace_exporter.<id>.tls.client-private-key | string | Client private key path for OTEL trace exporter TLS. |
| permissions.<name>.description | string | Human-readable description for this named profile。A profile does not inherit its parent's description through extends. |
| permissions.<name>.extends | string | Optional parent profile applied 之前 this named profile。设置 it 到 another named profile, :读取-only, 或 :workspace；:danger-full-access, undefined parents, 和 cycles are rejected. |
| permissions.<name>.filesystem | table | Named filesystem permission profile。Each key is an absolute path 或 special token such as :minimal 或 :workspace_roots. |
| permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob> | "读取" / "写入" / "deny" | Scoped filesystem access relative 到 each effective workspace root。使用 "." for the root itself；glob subpaths such as "**/*.env" can deny reads 使用 "deny". |
| permissions.<name>.filesystem.<path-or-glob> | "读取" / "写入" / "deny" / table | Grant direct access for a path, glob pattern, 或 special token, 或 scope nested entries under that root。使用 "deny" 到 deny reads for matching paths. |
| permissions.<name>.filesystem.glob_scan_max_depth | number | Maximum depth for expanding deny-read glob patterns on platforms that snapshot matches 之前 sandbox startup。Must be at least 1 当 设置. |
| permissions.<name>.network.allow_local_binding | boolean | Permit broader local/private-network access through sandboxed networking。Exact local IP literal 或 localhost allow rules can still permit specific local targets 当 this stays false. |
| permissions.<name>.network.allow_upstream_proxy | boolean | Allow sandboxed networking 到 chain through another upstream proxy. |
| permissions.<name>.network.dangerously_allow_all_unix_sockets | boolean | Allow arbitrary Unix socket destinations 而不是 the 默认 restricted 设置。使用 only in tightly controlled environments. |
| permissions.<name>.network.dangerously_allow_non_loopback_proxy | boolean | Permit non-loopback bind addresses for sandboxed networking listeners。Enabling it can expose listeners beyond localhost. |
| permissions.<name>.network.domains | table | Domain rules for sandboxed networking。Supports exact hosts, *.example.com for subdomains only, **.example.com for apex plus subdomains, 和 global * allow rules。deny wins on conflicts. |
| permissions.<name>.network.domains.<pattern> | allow / deny | Allow 或 deny an exact host 或 scoped wildcard pattern such as *.example.com 或 **.example.com. |
| permissions.<name>.network.enable_socks5 | boolean | Expose SOCKS5 support 当 this permissions profile enables sandboxed networking. |
| permissions.<name>.network.enable_socks5_udp | boolean | Allow UDP over the SOCKS5 listener 当 enabled. |
| permissions.<name>.network.enabled | boolean | Enable network access for this named permissions profile。This changes the sandbox network policy；it does not 启动 the network proxy by itself. |
| permissions.<name>.network.mode | limited / full | Network proxy mode used for subprocess traffic. |
| permissions.<name>.network.proxy_url | string | HTTP listener URL used 当 this permissions profile enables sandboxed networking. |
| permissions.<name>.network.socks_url | string | SOCKS5 proxy endpoint used by this permissions profile. |
| permissions.<name>.network.unix_sockets | table | Unix socket allowlist overrides for sandboxed networking。使用 socket paths as keys；allow adds a path, 和 deny rejects it. |
| permissions.<name>.network.unix_sockets.<path> | allow / deny | 添加 an absolute Unix socket path 到 the effective allowlist 使用 allow, 或 reject it 使用 deny。Denied entries are omitted 从 the effective allowlist. |
| permissions.<name>.workspace_roots | table | Profile-defined workspace roots that receive :workspace_roots filesystem rules alongside session's runtime workspace roots. |
| permissions.<name>.workspace_roots.<path> | boolean | Opt a path into the profile's workspace root 设置 当 true。Disabled entries remain inactive. |
| personality | none / friendly / pragmatic | Default communication style for models that advertise supportsPersonality；can be overridden per thread/turn 或 via /personality. |
| plan_mode_reasoning_effort | none / minimal / low / medium / high / xhigh | Plan-mode-specific reasoning override。当 unset, Plan mode uses its built-in preset 默认. |
| plugins.<plugin>.mcp_servers.<server>.默认_tools_approval_mode | auto / prompt / approve | Default approval behavior for tools on a plugin-provided MCP server. |
| plugins.<plugin>.mcp_servers.<server>.disabled_tools | array<string> | Deny 列出 applied 之后 enabled_tools for a plugin-provided MCP server. |
| plugins.<plugin>.mcp_servers.<server>.enabled | boolean | Enable 或 disable an MCP server bundled by an installed plugin 不使用 changing the plugin manifest. |
| plugins.<plugin>.mcp_servers.<server>.enabled_tools | array<string> | Allow 列出 of tools exposed 从 a plugin-provided MCP server. |
| plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode | auto / prompt / approve | Per-tool approval behavior override for a plugin-provided MCP tool. |
| project_doc_fallback_filenames | array<string> | Additional filenames 到 try 当 AGENTS.md is missing. |
| project_doc_max_bytes | number | Maximum bytes 读取 从 AGENTS.md 当 building project instructions. |
| project_root_markers | array<string> | 列出 of project root marker filenames；used 当 searching parent directories for the project root. |
| projects.<path>.trust_level | string | Mark a project 或 worktree as trusted 或 untrusted ("trusted" / "untrusted")。Untrusted projects skip project-scoped .codex/ layers, including project-local config, hooks, 和 rules. |
| review_model | string | Optional model override used by /检查 (默认s 到 the 当前 session model). |
| sandbox_mode | 读取-only / workspace-write / danger-full-access | Sandbox policy for filesystem 和 network access during command execution. |
| sandbox_workspace_write.exclude_slash_tmp | boolean | Exclude /tmp 从 writable roots in workspace-write mode. |
| sandbox_workspace_write.exclude_tmpdir_env_var | boolean | Exclude $TMPDIR 从 writable roots in workspace-write mode. |
| sandbox_workspace_write.network_access | boolean | Allow outbound network access inside workspace-write sandbox. |
| sandbox_workspace_write.writable_roots | array<string> | Additional writable roots 当 sandbox_mode = "workspace-write". |
| service_tier | string | Preferred service tier for 新的 turns。Built-in values include flex 和 fast；legacy fast config maps 到 the request value priority, 和 catalog-provided tier IDs can also be stored. |
| shell_environment_policy.exclude | array<string> | Glob patterns for removing environment variables 之后 the 默认s. |
| shell_environment_policy.experimental_use_profile | boolean | 使用 the user shell profile 当 spawning subprocesses. |
| shell_environment_policy.ignore_默认_excludes | boolean | Keep variables containing KEY/SECRET/TOKEN 之前 other filters 运行. |
| shell_environment_policy.include_only | array<string> | Whitelist of patterns；当 设置 only matching variables are kept. |
| shell_environment_policy.inherit | all / core / none | Baseline environment inheritance 当 spawning subprocesses. |
| shell_environment_policy.设置 | map<string,string> | Explicit environment overrides injected into every subprocess. |
| show_raw_agent_reasoning | boolean | Surface raw reasoning content 当 the active model emits it. |
| skills.config | array<object> | Per-skill enablement overrides stored in config.toml. |
| skills.config.<index>.enabled | boolean | Enable 或 disable the referenced skill. |
| skills.config.<index>.path | string (path) | Path 到 a skill folder containing SKILL.md. |
| sqlite_home | string (path) | Directory where Codex stores the SQLite-backed state DB used by agent jobs 和 other resumable runtime state. |
| suppress_unstable_features_warning | boolean | Suppress the warning that appears 当 under-development feature flags are enabled. |
| tool_output_token_limit | number | Token budget for storing individual tool/function outputs in history. |
| tool_suggest.disabled_tools | array<table> | Disable suggestions for specific discoverable connectors 或 plugins。Each entry uses 输入 = "connector" 或 "plugin" 和 an id. |
| tool_suggest.discoverables | array<table> | Allow tool suggestions for additional discoverable connectors 或 plugins。Each entry uses 输入 = "connector" 或 "plugin" 和 an id. |
| tools.view_image | boolean | Enable the local-image attachment tool view_image. |
| tools.web_search | boolean / { context_size = "low / medium / high", allowed_domains = [string], location = { country, region, city, timezone } } | Optional web 搜索 tool configuration。The legacy boolean form is still accepted, but the object form lets you 设置 搜索 context size, allowed domains, 和 approximate user location. |
| tui | table | TUI-specific options such as enabling inline desktop notifications. |
| tui.alternate_screen | auto / always / never | Control alternate screen usage for the TUI (默认：auto；auto skips it in Zellij 到 preserve scrollback). |
| tui.animations | boolean | Enable terminal animations (welcome screen, shimmer, spinner) (默认：true). |
| tui.keymap.<context>.<action> | string / array<string> | Keyboard shortcut binding for a TUI action。Supported contexts include global, chat, composer, editor, vim_normal, vim_operator, vim_text_object, pager, 列出, 和 approval。Selected composer actions fall back 到 matching tui.keymap.global bindings；context-specific bindings take precedence 当 支持的. |
| tui.keymap.<context>.<action> = [] | empty array | Unbind the action in that keymap context。Key names 使用 normalized strings such as ctrl-a, shift-enter, page-down, 或 minus. |
| tui.model_availability_nux.<model> | integer | Internal startup-tooltip state keyed by model slug. |
| tui.notification_condition | unfocused / always | Control whether TUI notifications fire only 当 the terminal is unfocused 或 regardless of focus。Defaults 到 unfocused. |
| tui.notification_method | auto / osc9 / bel | Notification method for terminal notifications (默认：auto). |
| tui.notifications | boolean / array<string> | Enable TUI notifications；可选ly restrict 到 specific event types. |
| tui.raw_output_mode | boolean | 启动 the TUI in raw scrollback mode for 复制-friendly terminal selection (默认：false)。You can 切换 it 使用 /raw 或 the 默认 alt-r key binding. |
| tui.show_tooltips | boolean | 显示 onboarding tooltips in the TUI welcome screen (默认：true). |
| tui.status_line | array<string> / null | Ordered 列出 of TUI footer status-line item identifiers。null disables the status line. |
| tui.terminal_title | array<string> / null | Ordered 列出 of terminal window/tab title item identifiers。Defaults 到 ["spinner", "project"]；null disables title updates. |
| tui.theme | string | Syntax-highlighting theme override (kebab-case theme name). |
| tui.vim_mode_默认 | boolean | 启动 the composer in Vim normal mode 而不是 insert mode (默认：false)。You can still 切换 it per session 使用 /vim. |
| web_search | disabled / cached / live | Web 搜索 mode (默认："cached"；cached uses an 打开AI-maintained index 和 does not fetch live pages；如果 you 使用 --yolo 或 another full access sandbox setting, it 默认s 到 "live")。使用 "live" 到 fetch the most 最近 data 从 the web, 或 "disabled" 到 移除 the tool. |
| windows_wsl_setup_acknowledged | boolean | Track Windows onboarding acknowledgement (Windows only). |
| windows.sandbox | unelevated / elevated | Windows-only native sandbox mode 当 running Codex natively on Windows. |
| windows.sandbox_private_desktop | boolean | 运行 the final sandboxed child process on a private desktop by 默认 on native Windows。设置 false only for compatibility 使用 the older Winsta0\\Default behavior. |
你可以在这里找到最新的 config.toml JSON schema。
如果希望在 VS Code 或 Cursor 中编辑 config.toml 时获得自动补全和诊断，可以安装 Even Better TOML 扩展，并把下面这一行加到 config.toml 顶部：
#:schema https://learn.chatgpt.com/docs/config-schema.json注意：请把 experimental_instructions_file 重命名为 model_instructions_file。Codex 已弃用旧 key；请把现有配置更新为新名称。
requirements.toml
requirements.toml 是 admin-enforced 配置文件，用来约束用户无法覆盖的安全敏感设置。详情、位置和示例请参见 Admin-enforced requirements 。
对于 ChatGPT Business 和 Enterprise 用户，Codex 还可以应用从 cloud 获取的 requirements。优先级详情请参见 security page。
在 requirements.toml 中使用 [features]，可以用与 config.toml 相同的规范 key 固定 feature flags。省略的 key 不受约束。
Managed permission-profile allowlists 需要 Codex 0.138.0 或更高版本。Codex 0.137.0 及更早版本会忽略 allowed_permission_profiles 和 managed default_permissions。
allowed_sandbox_modes 应与 sandbox_mode 搭配使用。对于 permission-profile 部署，请将 allowed_permission_profiles 与 managed default_permissions 搭配使用。
| Key | 类型 / 取值 | 说明 |
|---|---|---|
| allow_appshots | boolean | 设置 到 false 到 disable Appshots for managed users。如果 omitted, Appshots remain unconstrained by requirements 和 follow normal product availability. |
| allow_managed_hooks_only | boolean | 当 true, Codex skips user, project, session, 和 plugin hooks while still allowing managed hooks 从 requirements.toml 和 other managed config layers. |
| allow_remote_control | boolean | 设置 到 false 到 disable device remote control for managed users。如果 omitted, device remote control remains unconstrained by requirements 和 follows normal product availability. |
| allowed_approval_policies | array<string> | Allowed values for approval_policy (例如 untrusted, on-request, never, 和 granular). |
| allowed_approvals_reviewers | array<string> | Allowed values for approvals_reviewer, such as user 和 auto_review. |
| allowed_permission_profiles | table<boolean> | Complete 列出 of allowed permission profiles。Profiles 设置 到 true are allowed。Profiles that are omitted 或 设置 到 false are denied, including profiles added in future versions。当 requirements sources are combined, entries are matched by profile name. |
| allowed_permission_profiles.<name> | boolean | Allow 或 deny a built-in 或 custom permission profile defined in a loaded config 或 requirements source。An earlier requirements source can 使用 false 到 turn off a profile allowed by a later source. |
| allowed_sandbox_modes | array<string> | Allowed values for sandbox_mode. |
| allowed_web_search_modes | array<string> | Allowed values for web_search (disabled, cached, live)。disabled is always allowed；an empty 列出 effectively allows only disabled. |
| apps | table | Managed app requirements keyed by app identifier。Requirements can disable an app 或 constrain approval behavior for individual tools. |
| apps.<id>.enabled | boolean | 设置 到 false 到 disable an app。A disabled requirement remains restrictive 当 multiple requirements sources are merged. |
| apps.<id>.tools.<tool>.approval_mode | auto / prompt / approve | 设置 the managed approval mode for one app tool. |
| computer_use | table | Computer 使用 requirements enforced 从 requirements.toml. |
| computer_use.allow_locked_computer_use | boolean | 设置 到 false 到 prevent Computer 使用 从 operating 之后 a managed macOS device locks。如果 omitted, locked 使用 remains unconstrained by requirements. |
| 默认_permissions | string | Managed 默认 permission profile。The profile must be allowed by allowed_permission_profiles。设置 this explicitly for predictable behavior；如果 omitted, Codex 默认s 到 :workspace only 当 both :workspace 和 :读取-only are explicitly allowed. |
| enforce_residency | string | Require Codex service traffic 到 使用 a 支持的 data residency。Currently accepts us. |
| experimental_network | table | Network access requirements enforced 从 requirements.toml。These constraints are separate 从 features.network_proxy 和 can 配置 sandboxed networking 不使用 the user feature flag. |
| experimental_network.allow_local_binding | boolean | Permit broader local/private-network access for sandboxed networking。Exact local IP literal 或 localhost allow rules can still permit specific local targets 当 this stays false. |
| experimental_network.allow_upstream_proxy | boolean | Allow sandboxed networking 到 chain through an upstream proxy 从 the environment. |
| experimental_network.allowed_domains | array<string> | 列出-shaped administrator allow rules for sandboxed networking。Do not combine this 使用 experimental_network.domains. |
| experimental_network.dangerously_allow_all_unix_sockets | boolean | Permit arbitrary Unix socket destinations 而不是 allowlist-only access。使用 only in tightly controlled environments. |
| experimental_network.dangerously_allow_non_loopback_proxy | boolean | Permit non-loopback listener addresses for [experimental_network] requirements。Enabling it can expose listeners beyond localhost. |
| experimental_network.denied_domains | array<string> | 列出-shaped administrator deny rules for sandboxed networking。Do not combine this 使用 experimental_network.domains. |
| experimental_network.domains | map<string, allow / deny> | Map-shaped administrator domain policy for sandboxed networking。Supports exact hosts, *.example.com for subdomains only, **.example.com for apex plus subdomains, 和 global * allow rules；prefer scoped rules because * broadly opens public outbound access。deny wins on conflicts。Do not combine this 使用 experimental_network.allowed_domains 或 experimental_network.denied_domains. |
| experimental_network.enabled | boolean | Enable sandboxed networking requirements。This does not grant network access 当 the active sandbox keeps command networking off. |
| experimental_network.http_port | integer | Loopback HTTP listener port 到 使用 for [experimental_network] requirements. |
| experimental_network.managed_allowed_domains_only | boolean | 当 true, only administrator-managed allow rules remain effective while sandboxed networking requirements are active；user allowlist additions are ignored。Without managed allow rules, user-added domain allow rules do not remain effective. |
| experimental_network.socks_port | integer | Loopback SOCKS5 listener port 到 使用 for [experimental_network] requirements. |
| experimental_network.unix_sockets | map<string, allow / deny> | Administrator-managed Unix socket policy for sandboxed networking. |
| features | table | Pinned feature values keyed by the canonical names 从 config.toml's [features] table. |
| features.<name> | boolean | Require a specific canonical feature key 到 stay enabled 或 disabled. |
| features.apps | boolean | Pin Apps integration availability on 或 off for managed users. |
| features.browser_use | boolean | 设置 到 false in requirements.toml 到 disable Browser 使用 和 Browser Agent availability. |
| features.browser_use_external | boolean | 设置 到 false in requirements.toml 到 disable external-browser Browser 使用 availability. |
| features.browser_use_full_cdp_access | boolean | 设置 到 false in requirements.toml 到 prevent users 从 enabling full Chrome DevTools Protocol access in Browser Developer mode。如果 omitted, normal product availability applies. |
| features.computer_use | boolean | 设置 到 false in requirements.toml 到 disable Computer 使用, Record & Replay, 和 related 安装 或 enablement flows. |
| features.fast_mode | boolean | Pin the canonical fast_mode feature on 或 off for managed users. |
| features.guardian_approval | boolean | Pin Guardian approval availability on 或 off for managed users. |
| features.in_app_browser | boolean | 设置 到 false in requirements.toml 到 disable the in-app browser pane. |
| features.memories | boolean | Pin Memories availability on 或 off for managed users. |
| features.multi_agent | boolean | Pin multi-agent availability on 或 off for managed users. |
| features.plugin_sharing | boolean | 设置 到 false in cloud-managed requirements.toml 到 disable workspace sharing for locally built plugins. |
| features.plugins | boolean | Pin plugin availability on 或 off for managed users. |
| features.workspace_dependencies | boolean | Pin bundled workspace-dependency runtime availability on 或 off for managed users. |
| guardian_policy_config | string | Managed Markdown policy instructions for automatic 检查。This takes precedence over local [auto_review].policy。Blank values are ignored. |
| hooks | table | Admin-enforced managed lifecycle hooks。Requires a managed hook directory 和 uses the same event schema as inline [hooks] in config.toml. |
| hooks.<Event> | array<table> | Matcher groups for a hook event such as PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SubagentStart, SubagentStop, UserPromptSubmit, 或 Stop. |
| hooks.<Event>[].hooks | array<table> | Hook handlers for a matcher group。Command hooks are currently 支持的；prompt 和 agent hook handlers are parsed but skipped. |
| hooks.<Event>[].hooks[].commandWindows | string | Windows-only command override for command hooks。The TOML alias command_windows is also accepted. |
| hooks.managed_dir | string (absolute path) | Directory containing managed hook scripts on macOS 和 Linux。Codex validates that it is absolute 和 exists 之前 loading managed hooks. |
| hooks.windows_managed_dir | string (absolute path) | Directory containing managed hook scripts on Windows。Codex validates that it is absolute 和 exists 之前 loading managed hooks. |
| mcp_servers | table | Allowlist of MCP servers that may be enabled。Both the server name (<id>) 和 its identity must match for the MCP server 到 be enabled。Any configured MCP server not in the allowlist (或 使用 a mismatched identity) is disabled. |
| mcp_servers.<id>.identity | table | Identity rule for a single MCP server。设置 either command (stdio) 或 url (streamable HTTP). |
| mcp_servers.<id>.identity.command | string | Allow an MCP stdio server 当 its mcp_servers.<id>.command matches this command. |
| mcp_servers.<id>.identity.url | string | Allow an MCP streamable HTTP server 当 its mcp_servers.<id>.url matches this URL. |
| permissions | table | Admin-defined permission profiles keyed by profile name。Uses the same profile fields as config.toml. |
| permissions.<name> | table | Admin-defined permission profile。The name can't 启动 使用 :, 使用 the reserved name filesystem, 或 duplicate a profile 从 a loaded config。Uses the same profile fields as config.toml；see the Permissions guide for the complete profile schema. |
| permissions.filesystem.deny_read | array<string> | Admin-enforced filesystem 读取 denials。Entries can be paths 或 glob patterns, 和 users cannot weaken them 使用 local config. |
| plugins | table | Plugin-specific MCP server allowlists keyed by plugin identifier. |
| plugins.<plugin>.mcp_servers.<server>.identity.command | string | Allow a plugin's stdio MCP server 当 its configured command matches this value. |
| plugins.<plugin>.mcp_servers.<server>.identity.url | string | Allow a plugin's streamable HTTP MCP server 当 its configured URL matches this value. |
| remote_sandbox_config | array<table> | Host-specific sandbox requirements。The first entry whose hostname_patterns match the resolved host name overrides top-level allowed_sandbox_modes for that requirements source。Host-specific entries currently override sandbox modes only. |
| remote_sandbox_config[].allowed_sandbox_modes | array<string> | Allowed sandbox modes 到 应用 当 this host-specific entry matches. |
| remote_sandbox_config[].hostname_patterns | array<string> | Case-insensitive host name patterns。Supports * for any sequence of characters 和 ? for one character. |
| rules | table | Admin-enforced command rules merged 使用 .rules files。Requirements rules must be restrictive. |
| rules.prefix_rules | array<table> | 列出 of enforced prefix rules。Each rule must include pattern 和 decision. |
| rules.prefix_rules[].decision | prompt / forbidden | Required。Requirements rules can only prompt 或 forbid (not allow). |
| rules.prefix_rules[].justification | string | Optional non-empty rationale surfaced in approval prompts 或 rejection messages. |
| rules.prefix_rules[].pattern | array<table> | Command prefix expressed as pattern tokens。Each token sets either token 或 any_of. |
| rules.prefix_rules[].pattern[].any_of | array<string> | A 列出 of allowed alternative tokens at this position. |
| rules.prefix_rules[].pattern[].token | string | A single literal token at this position. |
| windows | table | Native Windows sandbox requirements. |
| windows.allowed_sandbox_implementations | array<string> | Allowed native Windows sandbox implementations for windows.sandbox (elevated 和 unelevated)。The 列出 must not be empty。当 both are allowed 和 no mode is selected, Codex prefers elevated. |