查询完整配置项

本篇是 Codex 配置文件的可搜索参考。

如果你需要概念和示例，先看：

Config basics：https://developers.openai.com/codex/config-basic
Advanced Config：https://developers.openai.com/codex/config-advanced

`config.toml`

User-level configuration 位于：

~/.codex/config.toml

你也可以在项目中添加 project-scoped overrides：

.codex/config.toml

Codex 只会在你 trust project（信任项目）后加载 project-scoped config files。

Sandbox 和 approval 相关键，例如 approval_policy、sandbox_mode、sandbox_workspace_write.*，建议同时参考：

Sandbox and approvals：https://developers.openai.com/codex/agent-approvals-security#sandbox-and-approvals
Protected paths in writable roots：https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots
Network access：https://developers.openai.com/codex/agent-approvals-security#network-access

核心模型和 provider 配置

Key	Type	Description
`model`	`string`	使用的模型，例如 `gpt-5.5`。
`review_model`	`string`	`/review` 使用的可选模型覆盖值；默认使用当前 session model。
`model_provider`	`string`	`model_providers` 中的 provider id，默认 `openai`。
`openai_base_url`	`string`	内置 `openai` model provider 的 base URL override。
`model_context_window`	`number`	当前模型可用的 context window tokens。
`model_auto_compact_token_limit`	`number`	触发 automatic history compaction 的 token threshold；未设置时使用模型默认值。
`model_catalog_json`	`string (path)`	启动时加载的可选 JSON model catalog 路径；profile-level `profiles.<name>.model_catalog_json` 可按 profile 覆盖。
`oss_provider`	`lmstudio` / `ollama`	使用 `--oss` 时的默认本地 provider；未设置时会提示选择。

审批和沙箱配置

Key	Type	Description
`approval_policy`	`untrusted` / `on-request` / `never` / granular table	控制 Codex 执行命令前什么时候暂停等待 approval。也可用 `approval_policy = { granular = { ... } }` 细分 prompt categories。`on-failure` 已 deprecated；interactive runs 用 `on-request`，non-interactive runs 用 `never`。
`approval_policy.granular.sandbox_approval`	`boolean`	为 `true` 时，允许 sandbox escalation approval prompts 出现。
`approval_policy.granular.rules`	`boolean`	为 `true` 时，允许 execpolicy `prompt` rules 触发的 approvals 出现。
`approval_policy.granular.mcp_elicitations`	`boolean`	为 `true` 时，MCP elicitation prompts 可出现；否则 auto-rejected。
`approval_policy.granular.request_permissions`	`boolean`	为 `true` 时，`request_permissions` tool 的 prompts 可出现。
`approval_policy.granular.skill_approval`	`boolean`	为 `true` 时，skill-script approval prompts 可出现。
`approvals_reviewer`	`user` / `auto_review`	谁 review eligible approval prompts。默认 `user`；`auto_review` 使用 reviewer subagent。它不改变 sandboxing 或 sandbox 内已允许的 actions。
`auto_review.policy`	`string`	Automatic review 的本地 Markdown policy instructions。Managed `guardian_policy_config` 优先；空值忽略。
`allow_login_shell`	`boolean`	是否允许 shell-based tools 使用 login-shell semantics。默认 `true`；为 `false` 时拒绝 `login = true`，未写 `login` 时默认 non-login shell。
`sandbox_mode`	`read-only` / `workspace-write` / `danger-full-access`	命令执行时的 filesystem 和 network access sandbox policy。
`sandbox_workspace_write.writable_roots`	`array<string>`	`sandbox_mode = "workspace-write"` 时额外 writable roots。
`sandbox_workspace_write.network_access`	`boolean`	workspace-write sandbox 内是否允许 outbound network access。
`sandbox_workspace_write.exclude_tmpdir_env_var`	`boolean`	workspace-write mode 中是否排除 `$TMPDIR` writable root。
`sandbox_workspace_write.exclude_slash_tmp`	`boolean`	workspace-write mode 中是否排除 `/tmp` writable root。
`windows.sandbox`	`unelevated` / `elevated`	Windows 原生运行 Codex 时的 native sandbox mode。
`windows.sandbox_private_desktop`	`boolean`	Native Windows 上默认把最终 sandboxed child process 放到 private desktop。只有为了兼容旧 `Winsta0\\Default` 行为时才设为 `false`。

通知、analytics 和指令配置

Key	Type	Description
`notify`	`array<string>`	通知命令；Codex 会传入 JSON payload。
`check_for_update_on_startup`	`boolean`	启动时检查 Codex 更新。只有集中管理更新时才设为 `false`。
`feedback.enabled`	`boolean`	是否在 Codex surfaces 中启用 `/feedback`；默认 `true`。
`analytics.enabled`	`boolean`	本机或 profile 是否启用 analytics。未设置时使用 client default。
`instructions`	`string`	预留给未来使用；当前优先使用 `model_instructions_file` 或 `AGENTS.md`。
`developer_instructions`	`string`	注入 session 的额外 developer instructions，可选。
`log_dir`	`string (path)`	Codex 写 log files 的目录，例如 `codex-tui.log`；默认 `$CODEX_HOME/log`。
`sqlite_home`	`string (path)`	Codex 存储 SQLite-backed state DB 的目录，用于 agent jobs 和其他 resumable runtime state。
`compact_prompt`	`string`	History compaction prompt 的 inline override。
`commit_attribution`	`string`	覆盖 commit co-author trailer text。设为空字符串可关闭 automatic attribution。
`model_instructions_file`	`string (path)`	用文件替换 built-in instructions，而不是使用 `AGENTS.md`。
`personality`	`none` / `friendly` / `pragmatic`	支持 `supportsPersonality` 的模型默认 communication style；可按 thread / turn 或 `/personality` 覆盖。
`service_tier`	`flex` / `fast`	新 turns 的 preferred service tier。
`experimental_compact_prompt_file`	`string (path)`	从文件加载 compaction prompt override。Experimental。

Skills 和 apps 配置

Key	Type	Description
`skills.config`	`array<object>`	保存在 `config.toml` 中的 per-skill enablement overrides。
`skills.config.<index>.path`	`string (path)`	包含 `SKILL.md` 的 skill folder 路径。
`skills.config.<index>.enabled`	`boolean`	启用或禁用该 skill。
`apps.<id>.enabled`	`boolean`	按 id 启用或禁用具体 app / connector，默认 `true`。
`apps._default.enabled`	`boolean`	所有 apps 的默认 enabled state，除非 app 单独覆盖。
`apps._default.destructive_enabled`	`boolean`	对 `destructive_hint = true` 的 app tools 默认允许或拒绝。
`apps._default.open_world_enabled`	`boolean`	对 `open_world_hint = true` 的 app tools 默认允许或拒绝。
`apps.<id>.destructive_enabled`	`boolean`	对该 app 中声明 `destructive_hint = true` 的 tools 允许或阻止。
`apps.<id>.open_world_enabled`	`boolean`	对该 app 中声明 `open_world_hint = true` 的 tools 允许或阻止。
`apps.<id>.default_tools_enabled`	`boolean`	该 app tools 的默认 enabled state，除非有 per-tool override。
`apps.<id>.default_tools_approval_mode`	`auto` / `prompt` / `approve`	该 app tools 默认 approval behavior，除非有 per-tool override。
`apps.<id>.tools.<tool>.enabled`	`boolean`	某个 app tool 的 per-tool enabled override，例如 `repos/list`。
`apps.<id>.tools.<tool>.approval_mode`	`auto` / `prompt` / `approve`	单个 app tool 的 approval behavior override。
`tool_suggest.discoverables`	`array<table>`	允许对额外 discoverable connectors 或 plugins 提示工具建议。每项使用 `type = "connector"` 或 `"plugin"` 和一个 `id`。
`tool_suggest.disabled_tools`	`array<table>`	禁用特定 discoverable connectors 或 plugins 的建议。每项使用 `type = "connector"` 或 `"plugin"` 和一个 `id`。

功能开关

Key	Type	Description
`features.apps`	`boolean`	启用 ChatGPT Apps / connectors support。Experimental。
`features.codex_hooks`	`boolean`	启用从 `hooks.json` 或 inline `[hooks]` config 加载 lifecycle hooks。
`hooks`	`table`	在 `config.toml` 中 inline 配置 lifecycle hooks。事件 schema 与 `hooks.json` 相同；示例和事件见 Hooks guide。
`features.memories`	`boolean`	启用 Memories，默认关闭：https://developers.openai.com/codex/memories
`features.unified_exec`	`boolean`	使用 PTY-backed unified exec tool。Stable；除 Windows 外默认启用。
`features.shell_snapshot`	`boolean`	Snapshot shell environment，加速重复命令。Stable；默认启用。
`features.undo`	`boolean`	启用 undo support。Stable；默认关闭。
`features.multi_agent`	`boolean`	启用 multi-agent collaboration tools：`spawn_agent`、`send_input`、`resume_agent`、`wait_agent`、`close_agent`。Stable；默认启用。
`features.personality`	`boolean`	启用 personality selection controls。Stable；默认启用。
`features.web_search`	`boolean`	Deprecated legacy toggle；优先使用顶层 `web_search`。
`features.web_search_cached`	`boolean`	Deprecated legacy toggle。`web_search` 未设置时，`true` 映射到 `web_search = "cached"`。
`features.web_search_request`	`boolean`	Deprecated legacy toggle。`web_search` 未设置时，`true` 映射到 `web_search = "live"`。
`features.shell_tool`	`boolean`	启用默认 `shell` tool 运行命令。Stable；默认启用。
`features.enable_request_compression`	`boolean`	支持时用 zstd 压缩 streaming request bodies。Stable；默认启用。
`features.skill_mcp_dependency_install`	`boolean`	允许为 skills 提示并安装缺失 MCP dependencies。Stable；默认启用。
`features.fast_mode`	`boolean`	启用 Fast mode selection 和 `service_tier = "fast"` 路径。Stable；默认启用。
`features.prevent_idle_sleep`	`boolean`	turn 正在运行时阻止机器 sleep。Experimental；默认关闭。
`suppress_unstable_features_warning`	`boolean`	启用 under-development feature flags 时，不显示 warning。

MCP servers 配置

Key	Type	Description
`mcp_servers.<id>.command`	`string`	MCP stdio server 的 launcher command。
`mcp_servers.<id>.args`	`array<string>`	传给 MCP stdio server command 的 arguments。
`mcp_servers.<id>.env`	`map<string,string>`	转发给 MCP stdio server 的 environment variables。
`mcp_servers.<id>.env_vars`	`array<string \| { name = string, source = "local" \| "remote" }>`	额外 allowlist 的 environment variables。字符串默认 `source = "local"`；`source = "remote"` 只用于 executor-backed remote stdio。
`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 headers。
`mcp_servers.<id>.env_http_headers`	`map<string,string>`	从环境变量填充的 MCP HTTP server headers。
`mcp_servers.<id>.enabled`	`boolean`	不删除配置的情况下禁用 MCP server。
`mcp_servers.<id>.required`	`boolean`	为 `true` 时，如果 enabled MCP server 无法初始化，则 startup / resume 失败。
`mcp_servers.<id>.startup_timeout_sec`	`number`	覆盖 MCP server 默认 10s startup timeout。
`mcp_servers.<id>.startup_timeout_ms`	`number`	`startup_timeout_sec` 的毫秒别名。
`mcp_servers.<id>.tool_timeout_sec`	`number`	覆盖 MCP server 默认 60s per-tool timeout。
`mcp_servers.<id>.enabled_tools`	`array<string>`	MCP server 暴露工具的 allow list。
`mcp_servers.<id>.disabled_tools`	`array<string>`	MCP server 工具 deny list；在 `enabled_tools` 后应用。
`mcp_servers.<id>.scopes`	`array<string>`	认证该 MCP server 时请求的 OAuth scopes。
`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 servers；streamable HTTP remote placement 尚未实现。

agents 和记忆配置

Key	Type	Description
`agents.max_threads`	`number`	可同时打开的 agent threads 最大数量。未设置默认 `6`。
`agents.max_depth`	`number`	允许 spawned agent threads 的最大 nesting depth；root session 深度为 0，默认 1。
`agents.job_max_runtime_seconds`	`number`	`spawn_agents_on_csv` jobs 的默认 per-worker timeout。未设置时每个 worker 默认 1800 秒。
`agents.<name>.description`	`string`	Codex 选择并 spawn 该 agent type 时看到的 role guidance。
`agents.<name>.config_file`	`string (path)`	该 role 的 TOML config layer 路径；relative paths 相对声明 role 的 config file。
`agents.<name>.nickname_candidates`	`array<string>`	该 role spawned agents 的可选 display nicknames 池。
`memories.generate_memories`	`boolean`	为 `false` 时，新 threads 不会存为 memory-generation inputs。默认 `true`。
`memories.use_memories`	`boolean`	为 `false` 时，Codex 不向 future sessions 注入 existing memories。默认 `true`。
`memories.disable_on_external_context`	`boolean`	为 `true` 时，使用 MCP tool calls、web search 或 tool search 等 external context 的 threads 不参与 memory generation。默认 `false`。Legacy alias: `memories.no_memories_if_mcp_or_web_search`。
`memories.max_raw_memories_for_consolidation`	`number`	Global consolidation 保留的 recent raw memories 最大数量。默认 `256`，上限 `4096`。
`memories.max_unused_days`	`number`	memory last used 超过多少天后不再参与 consolidation。默认 `30`，范围 `0-365`。
`memories.max_rollout_age_days`	`number`	memory generation 考虑的 threads 最大 age。默认 `30`，范围 `0-90`。
`memories.max_rollouts_per_startup`	`number`	每次 startup pass 处理的 rollout candidates 最大数量。默认 `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 windows 中需要保留的最小百分比。默认 `25`，范围 `0-100`。
`memories.extract_model`	`string`	Per-thread memory extraction 的可选模型覆盖。
`memories.consolidation_model`	`string`	Global memory consolidation 的可选模型覆盖。

模型 providers 配置

Key	Type	Description
`model_providers.<id>`	`table`	Custom provider definition。内置 provider IDs `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 direct bearer token。不建议使用；优先 `env_key`。
`model_providers.<id>.requires_openai_auth`	`boolean`	Provider 是否使用 OpenAI authentication，默认 false。
`model_providers.<id>.wire_api`	`responses`	Provider 使用的 protocol。`responses` 是唯一支持值；省略时默认 `responses`。
`model_providers.<id>.query_params`	`map<string,string>`	附加到 provider requests 的 extra query parameters。
`model_providers.<id>.http_headers`	`map<string,string>`	加到 provider requests 的 static HTTP headers。
`model_providers.<id>.env_http_headers`	`map<string,string>`	从环境变量填充 HTTP headers。
`model_providers.<id>.request_max_retries`	`number`	Provider HTTP requests 的 retry count，默认 4。
`model_providers.<id>.stream_max_retries`	`number`	SSE streaming interruptions 的 retry count，默认 5。
`model_providers.<id>.stream_idle_timeout_ms`	`number`	SSE streams idle timeout，单位 ms，默认 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。必须把 token 打印到 stdout。
`model_providers.<id>.auth.args`	`array<string>`	传给 token command 的 arguments。
`model_providers.<id>.auth.timeout_ms`	`number`	Token command 最大运行时间，默认 5000 ms。
`model_providers.<id>.auth.refresh_interval_ms`	`number`	Codex 主动刷新 token 的间隔，默认 300000 ms。设为 `0` 时，只在 authentication retry 后刷新。
`model_providers.<id>.auth.cwd`	`string (path)`	Token command 的 working directory。
`model_providers.amazon-bedrock.aws.profile`	`string`	内置 `amazon-bedrock` provider 使用的 AWS profile name。
`model_providers.amazon-bedrock.aws.region`	`string`	内置 `amazon-bedrock` provider 使用的 AWS region。

推理和 shell 环境配置

Key	Type	Description
`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 override。未设置时 Plan mode 使用内置 preset 默认值。
`model_reasoning_summary`	`auto` / `concise` / `detailed` / `none`	选择 reasoning summary 详细程度，或完全禁用 summaries。
`model_verbosity`	`low` / `medium` / `high`	GPT-5 Responses API verbosity override；未设置时使用模型 / preset 默认值。
`model_supports_reasoning_summaries`	`boolean`	强制 Codex 发送或不发送 reasoning metadata。
`shell_environment_policy.inherit`	`all` / `core` / `none`	启动 subprocesses 时 baseline environment inheritance。
`shell_environment_policy.ignore_default_excludes`	`boolean`	在其他 filters 运行前保留包含 KEY / SECRET / TOKEN 的变量。
`shell_environment_policy.exclude`	`array<string>`	默认过滤后移除 environment variables 的 glob patterns。
`shell_environment_policy.include_only`	`array<string>`	Whitelist patterns；设置后只保留匹配变量。
`shell_environment_policy.set`	`map<string,string>`	注入每个 subprocess 的 explicit environment overrides。
`shell_environment_policy.experimental_use_profile`	`boolean`	启动 subprocesses 时使用 user shell profile。

项目、profiles 和历史配置

Key	Type	Description
`project_root_markers`	`array<string>`	查找 parent directories 时用于识别 project root 的 marker filenames。
`project_doc_max_bytes`	`number`	构建 project instructions 时，从 `AGENTS.md` 读取的最大 bytes。
`project_doc_fallback_filenames`	`array<string>`	`AGENTS.md` 缺失时额外尝试的 filenames。
`profile`	`string`	启动时应用的 default profile，等同 `--profile`。
`profiles.<name>.*`	various	Profile-scoped overrides，可覆盖支持的配置键。
`profiles.<name>.service_tier`	`flex` / `fast`	Profile-scoped service tier preference。
`profiles.<name>.plan_mode_reasoning_effort`	`none` / `minimal` / `low` / `medium` / `high` / `xhigh`	Profile-scoped Plan-mode reasoning override。
`profiles.<name>.web_search`	`disabled` / `cached` / `live`	Profile-scoped web search mode override，默认 `"cached"`。
`profiles.<name>.personality`	`none` / `friendly` / `pragmatic`	支持模型的 profile-scoped communication style override。
`profiles.<name>.model_catalog_json`	`string (path)`	Profile-scoped model catalog JSON path override，只在 startup 应用，并覆盖 top-level `model_catalog_json`。
`profiles.<name>.model_instructions_file`	`string (path)`	Profile-scoped built-in instruction file replacement。
`profiles.<name>.experimental_use_unified_exec_tool`	`boolean`	启用 unified exec 的 legacy name；优先 `[features].unified_exec`。
`profiles.<name>.oss_provider`	`lmstudio` / `ollama`	`--oss` sessions 的 profile-scoped OSS provider。
`profiles.<name>.tools_view_image`	`boolean`	在该 profile 中启用或禁用 `view_image` tool。
`profiles.<name>.analytics.enabled`	`boolean`	Profile-scoped analytics enablement override。
`profiles.<name>.windows.sandbox`	`unelevated` / `elevated`	Profile-scoped Windows sandbox mode override。
`history.persistence`	`save-all` / `none`	是否把 session transcripts 保存到 `history.jsonl`。
`tool_output_token_limit`	`number`	存储单个 tool / function outputs 到 history 时的 token budget。
`background_terminal_max_timeout`	`number`	空 `write_stdin` polls 的最大 poll window，单位 ms，默认 `300000`。替代旧 `background_terminal_timeout`。
`history.max_bytes`	`number`	设置后，以 bytes 限制 history file size，并丢弃 oldest entries。
`file_opener`	`vscode` / `vscode-insiders` / `windsurf` / `cursor` / `none`	Codex output 中 citations 打开的 URI scheme，默认 `vscode`。

OpenTelemetry 配置

Key	Type	Description
`otel.environment`	`string`	OpenTelemetry events 的 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`	是否把 raw user prompts 导出到 OpenTelemetry logs。
`otel.exporter.<id>.endpoint`	`string`	OTEL logs exporter endpoint。
`otel.exporter.<id>.protocol`	`binary` / `json`	OTLP / HTTP exporter 使用的 protocol。
`otel.exporter.<id>.headers`	`map<string,string>`	OTEL exporter requests 附带的 static headers。
`otel.trace_exporter.<id>.endpoint`	`string`	OTEL logs 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 requests 附带的 static headers。
`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 和本地界面配置

Key	Type	Description
`tui`	`table`	TUI-specific options，例如 inline desktop notifications。
`tui.notifications`	`boolean` / `array<string>`	启用 TUI notifications，也可限制为 specific event types。
`tui.notification_method`	`auto` / `osc9` / `bel`	Terminal notifications 的方法，默认 `auto`。
`tui.notification_condition`	`unfocused` / `always`	TUI notifications 只在 terminal unfocused 时触发，还是无论 focus 都触发。默认 `unfocused`。
`tui.animations`	`boolean`	启用 terminal animations，例如 welcome screen、shimmer、spinner。默认 `true`。
`tui.alternate_screen`	`auto` / `always` / `never`	控制 TUI alternate screen usage。默认 `auto`；Zellij 中 auto 会跳过以保留 scrollback。
`tui.show_tooltips`	`boolean`	在 TUI welcome screen 显示 onboarding tooltips，默认 `true`。
`tui.status_line`	`array<string>` / `null`	TUI footer status-line item identifiers 的有序列表；`null` 禁用 status line。
`tui.terminal_title`	`array<string>` / `null`	Terminal window / tab title item identifiers 的有序列表。默认 `["spinner", "project"]`；`null` 禁用 title updates。
`tui.theme`	`string`	Syntax-highlighting theme override，使用 kebab-case theme name。
`tui.keymap.<context>.<action>`	`string` / `array<string>`	TUI action 的 keyboard shortcut binding。Contexts 包括 `global`、`chat`、`composer`、`editor`、`pager`、`list`、`approval`；context-specific bindings 覆盖 `tui.keymap.global`。
`tui.keymap.<context>.<action> = []`	empty array	在该 keymap context 中 unbind action。Key names 使用 `ctrl-a`、`shift-enter`、`page-down` 等 normalized strings。
`tui.model_availability_nux.<model>`	`integer`	按 model slug 记录 internal startup-tooltip state。
`hide_agent_reasoning`	`boolean`	在 TUI 和 `codex exec` output 中 suppress reasoning events。
`show_raw_agent_reasoning`	`boolean`	Active model 发出 raw reasoning content 时显示它。
`disable_paste_burst`	`boolean`	禁用 TUI 中的 burst-paste detection。
`windows_wsl_setup_acknowledged`	`boolean`	记录 Windows onboarding acknowledgement。Windows only。

认证、网页搜索、权限和提示配置

Key	Type	Description
`chatgpt_base_url`	`string`	ChatGPT login flow 使用的 base URL override。
`cli_auth_credentials_store`	`file` / `keyring` / `auto`	CLI 存储 cached credentials 的位置：file-based `auth.json` 或 OS keychain。
`mcp_oauth_credentials_store`	`auto` / `file` / `keyring`	MCP OAuth credentials 的首选 store。
`mcp_oauth_callback_port`	`integer`	MCP OAuth login 的 local HTTP callback server 固定端口。未设置时由 OS 选择 ephemeral port。
`mcp_oauth_callback_url`	`string`	MCP OAuth login 的 redirect URI override，例如 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` / object	可选 web search tool 配置。Legacy boolean 仍被接受；object 形式可设置 context size、allowed domains、approximate user location。
`tools.view_image`	`boolean`	启用 local-image attachment tool `view_image`。
`web_search`	`disabled` / `cached` / `live`	Web search mode。默认 `"cached"`；cached 使用 OpenAI-maintained index，不抓 live pages。使用 `--yolo` 或其他 full access sandbox setting 时默认 `"live"`。
`default_permissions`	`string`	默认应用到 sandboxed tool calls 的 permissions profile 名称。内置：`:read-only`、`:workspace`、`:danger-no-sandbox`；custom names 需要 `[permissions.<name>]`。
`permissions.<name>.filesystem`	`table`	Named filesystem permission profile。每个 key 可以是 absolute path 或 `:minimal`、`:project_roots` 等 special token。
`permissions.<name>.filesystem.glob_scan_max_depth`	`number`	对需要在 sandbox startup 前 snapshot matches 的平台，扩展 deny-read glob patterns 的最大深度。设置时至少为 `1`。
`permissions.<name>.filesystem.<path-or-glob>`	`"read"` / `"write"` / `"none"` / table	给 path、glob pattern 或 special token 授予 direct access，或在 root 下 scope nested entries。用 `"none"` deny reads。
`permissions.<name>.filesystem.":project_roots".<subpath-or-glob>`	`"read"` / `"write"` / `"none"`	相对于 detected project roots 的 scoped filesystem access。`"."` 表示 root；`"*/.env"` 这类 glob subpaths 可用 `"none"` deny reads。
`permissions.<name>.network.enabled`	`boolean`	为 named permissions profile 启用 network access。
`permissions.<name>.network.proxy_url`	`string`	Named permissions profile 启用 managed network proxy 时使用的 HTTP proxy endpoint。
`permissions.<name>.network.enable_socks5`	`boolean`	启用 managed network proxy 时暴露 SOCKS5 listener。
`permissions.<name>.network.socks_url`	`string`	该 permissions profile 使用的 SOCKS5 proxy endpoint。
`permissions.<name>.network.enable_socks5_udp`	`boolean`	启用时允许 UDP over SOCKS5 listener。
`permissions.<name>.network.allow_upstream_proxy`	`boolean`	允许 managed proxy 链接到另一个 upstream proxy。
`permissions.<name>.network.dangerously_allow_non_loopback_proxy`	`boolean`	允许 managed proxy listener 使用 non-loopback bind addresses。
`permissions.<name>.network.dangerously_allow_all_unix_sockets`	`boolean`	允许 proxy 使用 arbitrary Unix sockets，而不是默认 restricted set。
`permissions.<name>.network.mode`	`limited` / `full`	Subprocess traffic 使用的 network proxy mode。
`permissions.<name>.network.domains`	`map<string, allow \| deny>`	Managed proxy 的 domain rules。key 使用 domain names 或 wildcard patterns，value 为 `allow` 或 `deny`。
`permissions.<name>.network.unix_sockets`	`map<string, allow \| none>`	Managed proxy 的 Unix socket rules。key 为 socket paths，value 为 `allow` 或 `none`。
`permissions.<name>.network.allow_local_binding`	`boolean`	允许通过 managed proxy 进行 local bind / listen operations。
`projects.<path>.trust_level`	`string`	标记 project 或 worktree 为 `"trusted"` 或 `"untrusted"`。Untrusted projects 会跳过 project-scoped `.codex/` layers，包括 project-local config、hooks、rules。
`notice.hide_full_access_warning`	`boolean`	记录 full access warning prompt 是否已确认。
`notice.hide_world_writable_warning`	`boolean`	记录 Windows world-writable directories warning 是否已确认。
`notice.hide_rate_limit_model_nudge`	`boolean`	记录是否关闭 rate limit model switch reminder。
`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 migrations，形式为 old -> new。
`forced_login_method`	`chatgpt` / `api`	限制 Codex 只能使用指定 authentication method。
`forced_chatgpt_workspace_id`	`string (uuid)`	将 ChatGPT logins 限制到指定 workspace identifier。

JSON schema 配置

最新 config.toml JSON schema：

https://developers.openai.com/codex/config-schema.json

如果想在 VS Code 或 Cursor 中编辑 config.toml 时获得 autocompletion 和 diagnostics，可以安装 Even Better TOML：

https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml

然后在 config.toml 顶部加入：

#:schema https://developers.openai.com/codex/config-schema.json

注意：把旧的 experimental_instructions_file 改名为 model_instructions_file。Codex 已弃用旧 key，现有配置应迁移到新名称。

`requirements.toml`

requirements.toml 是 admin-enforced configuration file（管理员强制配置文件），用于限制用户不能覆盖的 security-sensitive settings。

位置、示例和细节见 Admin-enforced requirements：

https://developers.openai.com/codex/enterprise/managed-configuration#admin-enforced-requirements-requirementstoml

ChatGPT Business 和 Enterprise 用户还可以应用 cloud-fetched requirements。优先级见 security page。

在 requirements.toml 中使用 [features]，可以用与 config.toml 相同的 canonical keys 固定 feature flags。省略的 keys 不受限制。

requirements 字段

Key	Type	Description
`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`	Automatic review 的 managed Markdown policy instructions。优先级高于本地 `[auto_review].policy`；空值忽略。
`allowed_sandbox_modes`	`array<string>`	允许的 `sandbox_mode` 值。
`remote_sandbox_config`	`array<table>`	Host-specific sandbox requirements。第一个匹配 resolved host name 的 `hostname_patterns` entry 会覆盖该 requirements source 的顶层 `allowed_sandbox_modes`。目前 host-specific entries 只覆盖 sandbox modes。
`remote_sandbox_config[].hostname_patterns`	`array<string>`	Case-insensitive host name patterns。支持 `*` 匹配任意字符序列，`?` 匹配一个字符。
`remote_sandbox_config[].allowed_sandbox_modes`	`array<string>`	Host-specific entry 命中时应用的 allowed sandbox modes。
`allowed_web_search_modes`	`array<string>`	允许的 `web_search` 值：`disabled`、`cached`、`live`。`disabled` 永远允许；空 list 实际上只允许 `disabled`。
`features`	`table`	按 `config.toml` `[features]` canonical names 固定 feature values。
`features.<name>`	`boolean`	要求具体 canonical feature key 保持 enabled 或 disabled。
`features.in_app_browser`	`boolean`	在 `requirements.toml` 中设为 `false` 可禁用 in-app browser pane。
`features.browser_use`	`boolean`	设为 `false` 可禁用 Browser Use 和 Browser Agent availability。
`features.computer_use`	`boolean`	设为 `false` 可禁用 Computer Use availability 及相关 install / enablement flows。
`hooks`	`table`	Admin-enforced managed lifecycle hooks。需要 managed hook directory，事件 schema 与 `config.toml` inline `[hooks]` 相同。
`hooks.managed_dir`	`string (absolute path)`	macOS 和 Linux 上包含 managed hook scripts 的目录。Codex 会验证它是 absolute 且存在。
`hooks.windows_managed_dir`	`string (absolute path)`	Windows 上包含 managed hook scripts 的目录。Codex 会验证它是 absolute 且存在。
`hooks.<Event>`	`array<table>`	某个 hook event 的 matcher groups，例如 `PreToolUse`、`PostToolUse`、`PermissionRequest`、`SessionStart`、`UserPromptSubmit`、`Stop`。
`hooks.<Event>[].hooks`	`array<table>`	Matcher group 的 hook handlers。当前支持 command hooks；prompt 和 agent hook handlers 会被解析但跳过。
`permissions.filesystem.deny_read`	`array<string>`	Admin-enforced filesystem read denials。Entries 可以是 paths 或 glob patterns，用户不能用 local config 削弱。
`mcp_servers`	`table`	允许启用的 MCP servers allowlist。Server name (`<id>`) 和 identity 都必须匹配，MCP server 才会启用；未在 allowlist 中或 identity 不匹配的 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 匹配时，允许 MCP stdio server。
`mcp_servers.<id>.identity.url`	`string`	当 `mcp_servers.<id>.url` 与此 URL 匹配时，允许 MCP streamable HTTP server。
`rules`	`table`	与 `.rules` files 合并的 admin-enforced command rules。Requirements rules 必须是 restrictive。
`rules.prefix_rules`	`array<table>`	Enforced prefix rules 列表。每条 rule 必须包含 `pattern` 和 `decision`。
`rules.prefix_rules[].pattern`	`array<table>`	用 pattern tokens 表示的 command prefix。每个 token 设置 `token` 或 `any_of`。
`rules.prefix_rules[].pattern[].token`	`string`	该位置的单个 literal token。
`rules.prefix_rules[].pattern[].any_of`	`array<string>`	该位置允许的 alternative tokens 列表。
`rules.prefix_rules[].decision`	`prompt` / `forbidden`	必填。Requirements rules 只能 prompt 或 forbid，不能 allow。
`rules.prefix_rules[].justification`	`string`	可选 non-empty rationale，会显示在 approval prompts 或 rejection messages 中。

On this page