配置参考 – Codex | OpenAI 开发者平台

将此页面作为 Codex 配置文件的可搜索参考。如需获取概念性指南和示例，请先阅读配置基础 and 高级配置.

`config.toml`

用户级配置位于 ~/.codex/config.toml。你还可以在以下位置添加项目级覆盖: .codex/config.toml 文件中。Codex 仅在您信任该项目时才加载项目范围的配置文件。

项目范围的配置无法覆盖本机的提供商、身份验证、主机拥有的应用请求元数据、通知、配置文件选择或遥测路由密钥。当其出现在项目本地的 openai_base_url, chatgpt_base_url, apps_mcp_product_sku, model_provider, model_providers, notify, profile, profiles, experimental_realtime_ws_base_url，且 otel 中时，Codex 会忽略 .codex/config.toml；请改为将提供商、通知和遥测密钥放在用户级别的配置中。配置配置文件实时连接到 config.toml as $CODEX_HOME/profile-name.config.toml；选择一个包含 --profile profile-name.

对于沙盒和审批密钥（approval_policy, sandbox_mode，且 sandbox_workspace_write.*），请将此引用与沙盒与审批, 可写根目录中的受保护路径，且网络访问。有关 beta 权限 profile,请参阅权限.

键	类型 / 值	详情
`agents.<name>.config_file`	`string (path)`	该角色的 TOML 配置层路径；相对路径将从声明该角色的配置文件开始解析。
`agents.<name>.description`	`string`	在选择和生成该代理类型时向 Codex 展示的角色指导。
`agents.<name>.nickname_candidates`	`array<string>`	该角色下已生成代理的可选显示昵称池。
`agents.job_max_runtime_seconds`	`number`	的每个 worker 的默认超时时间为 `spawn_agents_on_csv` 任务。未设置时，工具将回退到每个 worker 1800 秒。
`agents.max_depth`	`number`	生成的代理线程允许的最大嵌套深度（根会话从深度 0 开始；默认：1）。
`agents.max_threads`	`number`	允许同时打开的代理线程最大数量。默认为 `6` 未设置时。
`allow_login_shell`	`boolean`	允许基于 shell 的工具使用登录 shell 语义。默认为 `true`；当 `false`, `login = true` 请求将被拒绝并忽略 `login` 默认为非登录 shell。
`analytics.enabled`	`boolean`	启用或禁用此机器/配置文件的分析功能。未设置时，将应用客户端默认值。
`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 = { ... } }` 来允许或自动拒绝特定提示类别，同时保持其他提示的交互性。 `on-failure` 已弃用；请使用 `on-request` for interactive runs or `never` for non-interactive runs.
`approval_policy.granular.mcp_elicitations`	`boolean`	当 `true`, MCP 启发提示将被允许显示，而不是被自动拒绝。
`approval_policy.granular.request_permissions`	`boolean`	当 `true`，来自 `request_permissions` 工具允许显示。
`approval_policy.granular.rules`	`boolean`	当 `true`，由 execpolicy 触发的审批 `prompt` 规则允许显示。
`approval_policy.granular.sandbox_approval`	`boolean`	当 `true`，允许弹出沙箱权限提升审批提示。
`approval_policy.granular.skill_approval`	`boolean`	当 `true`，允许弹出技能脚本审批提示。
`approvals_reviewer`	`user \| auto_review`	在以下模式下，谁负责审查符合条件的审批提示： `on-request` 或精细审批策略。默认为 `user`; `auto_review` 使用审查子代理。此设置不会更改沙箱机制，也不会影响沙箱内已允许的审查操作。
`apps._default.destructive_enabled`	`boolean`	应用工具的默认允许/拒绝设置，带有 `destructive_hint = true`.
`apps._default.enabled`	`boolean`	所有应用的默认启用状态，除非按应用单独覆盖。
`apps._default.open_world_enabled`	`boolean`	应用工具的默认允许/拒绝设置，带有 `open_world_hint = true`.
`apps.<id>.default_tools_approval_mode`	`auto \| prompt \| approve`	此应用中工具的默认批准行为，除非存在针对单个工具的覆盖设置。
`apps.<id>.default_tools_enabled`	`boolean`	此应用中工具的默认启用状态，除非存在针对单个工具的覆盖设置。
`apps.<id>.destructive_enabled`	`boolean`	允许或阻止此应用中声明为 `destructive_hint = true`.
`apps.<id>.enabled`	`boolean`	通过 id 启用或禁用特定应用/连接器（默认：true）。
`apps.<id>.open_world_enabled`	`boolean`	允许或阻止此应用中声明为 `open_world_hint = true`.
`apps.<id>.tools.<tool>.approval_mode`	`auto \| prompt \| approve`	针对单个应用工具的逐工具批准行为覆盖。
`apps.<id>.tools.<tool>.enabled`	`boolean`	应用工具的逐工具启用覆盖（例如 `repos/list`).
`auto_review.policy`	`string`	用于自动审查的本地 Markdown 策略指令。由 `guardian_policy_config` 优先。忽略空值。
`background_terminal_max_timeout`	`number`	空轮询的最大轮询窗口（毫秒） `write_stdin` （后台终端轮询）。默认值： `300000` （5 分钟）。取代较旧的 `background_terminal_timeout` key.
`chatgpt_base_url`	`string`	覆盖在 ChatGPT 登录流程中使用的基 URL。
`check_for_update_on_startup`	`boolean`	在启动时检查 Codex 更新（仅当更新由中央统一管理时才设置为 false）。
`cli_auth_credentials_store`	`file \| keyring \| auto`	控制 CLI 存储缓存凭据的位置（基于文件的 auth.json 还是操作系统密钥链）。
`commit_attribution`	`string`	Commit 联合作者 Trailer，用于在 `[features].codex_git_commit` 启用时生效。默认为 `Codex <[email protected]>`；设置 `""` to disable.
`compact_prompt`	`string`	对历史记录压缩提示的内联覆盖。
`default_permissions`	`string`	应用于沙盒工具调用的默认权限配置文件名称。内置选项为 `:read-only`, `:workspace`，且 `:danger-full-access`；自定义配置文件名称需要匹配 `[permissions.<name>]` 表。请勿与 `sandbox_mode` or `[sandbox_workspace_write]`.
`developer_instructions`	`string`	注入到会话中的附加开发者指令（可选）。
`disable_paste_burst`	`boolean`	禁用 TUI 中的突发粘贴检测。
`experimental_compact_prompt_file`	`string (path)`	从文件加载压缩提示覆盖（实验性）。
`experimental_use_unified_exec_tool`	`boolean`	启用统一执行 (unified exec) 的旧版名称；推荐使用 `[features].unified_exec` or `codex --enable unified_exec`.
`features.apps`	`boolean`	启用 ChatGPT Apps/连接器支持（实验性）。
`features.codex_git_commit`	`boolean`	启用 Codex 生成的 git 提交。启用后，Codex 会使用 `commit_attribution` to append a `Co-authored-by:` trailer 来生成提交消息。
`features.enable_request_compression`	`boolean`	在受支持的情况下，使用 zstd 压缩流式请求体（稳定版；默认开启）。
`features.fast_mode`	`boolean`	在 TUI 中启用模型目录服务层级选择，包括当活动模型播发快速层级 (Fast-tier) 命令时启用该命令（稳定版；默认开启）。
`features.hooks`	`boolean`	启用从以下位置加载的生命周期钩子 `hooks.json` or inline `[hooks]` config. `features.codex_hooks` 是一个已弃用的别名。
`features.memories`	`boolean`	启用记忆（默认关闭）。
`features.multi_agent`	`boolean`	启用多智能体协作工具（`spawn_agent`, `send_input`, `resume_agent`, `wait_agent`，且 `close_agent`）（稳定功能；默认开启）。
`features.network_proxy`	`boolean \| table`	启用沙盒网络。在设置网络策略选项（例如 `domains` （实验性功能；默认关闭）。
`features.network_proxy.allow_local_binding`	`boolean`	允许更广泛的本地/私有网络访问。默认为 `false`；确切的本地 IP 字面值或 `localhost` allow 规则仍可允许特定的本地目标。
`features.network_proxy.allow_upstream_proxy`	`boolean`	允许通过环境中的上游代理进行链式连接。默认为 `true`.
`features.network_proxy.dangerously_allow_all_unix_sockets`	`boolean`	允许任意 Unix socket 目标，而非仅限允许列表中的访问。默认为 `false`；仅在严格控制的环境中使用。
`features.network_proxy.dangerously_allow_non_loopback_proxy`	`boolean`	允许非回环监听器地址。默认为 `false`；启用此选项可能会将代理监听器暴露给 localhost 之外。
`features.network_proxy.domains`	`map<string, allow \| deny>`	沙盒网络的域策略。默认未设置，这意味着在您添加 `allow` 规则之前不允许任何外部目标。支持精确的主机名、 `.example.com` for subdomains only, `.example.com` 表示顶级域及其子域，以及全局的 `` allow 规则；优先使用限定范围的规则，因为 `*` 会完全开放公共出站访问。添加 `deny` 规则以阻止特定目标；发生冲突时以 `deny` 规则为准。
`features.network_proxy.enable_socks5`	`boolean`	暴露 SOCKS5 支持。默认为 `true`.
`features.network_proxy.enable_socks5_udp`	`boolean`	允许通过 SOCKS5 使用 UDP。默认为 `true`.
`features.network_proxy.enabled`	`boolean`	启用沙盒网络。默认为 `false`.
`features.network_proxy.proxy_url`	`string`	用于沙盒网络的 HTTP 监听器 URL。默认为 `"http://127.0.0.1:3128"`.
`features.network_proxy.socks_url`	`string`	SOCKS5 监听器 URL。默认为 `"http://127.0.0.1:8081"`.
`features.network_proxy.unix_sockets`	`map<string, allow \| deny>`	沙盒网络的 Unix socket 策略。默认未设置；为允许的 socket 添加 `allow` 条目。
`features.personality`	`boolean`	启用人格选择控制（稳定功能；默认开启）。
`features.prevent_idle_sleep`	`boolean`	在回合处于活动运行状态时防止机器休眠（实验性功能；默认关闭）。
`features.shell_snapshot`	`boolean`	快照 shell 环境以加速重复命令的执行（稳定功能；默认开启）。
`features.shell_tool`	`boolean`	启用默认设置 `shell` 用于运行命令的
`features.skill_mcp_dependency_install`	`boolean`	允许提示并安装技能缺失的 MCP 依赖项（稳定版；默认开启）。
`features.undo`	`boolean`	启用撤销支持（稳定版；默认关闭）。
`features.unified_exec`	`boolean`	使用统一的基于 PTY 的 exec 工具（稳定版；除 Windows 外默认开启）。
`features.web_search`	`boolean`	已弃用的旧版开关；请使用顶层 `web_search` setting.
`features.web_search_cached`	`boolean`	已弃用的旧版开关。当 `web_search` 未设置时，true 对应于 `web_search = "cached"`.
`features.web_search_request`	`boolean`	已弃用的旧版开关。当 `web_search` 未设置时，true 对应于 `web_search = "live"`.
`feedback.enabled`	`boolean`	启用通过 `/feedback` 在所有 Codex 界面提交反馈的功能（默认：true）。
`file_opener`	`vscode \| vscode-insiders \| windsurf \| cursor \| none`	用于打开 Codex 输出引用的 URI 方案（默认： `vscode`).
`forced_chatgpt_workspace_id`	`string (uuid)`	将 ChatGPT 登录限制为特定的工作区标识符。
`forced_login_method`	`chatgpt \| api`	将 Codex 限制为特定的身份验证方法。
`hide_agent_reasoning`	`boolean`	抑制推理事件,在 TUI 和 `codex exec` output.
`history.max_bytes`	`number`	如果设置,通过丢弃最旧的条目将历史文件大小限制在指定字节数内。
`history.persistence`	`save-all \| none`	控制 Codex 是否将会话记录保存到 history.jsonl。
`hooks`	`table`	内联配置在以下位置的生命周期钩子: `config.toml`。使用与以下相同的事件结构: `hooks.json`;有关示例和支持的事件,请参阅 Hooks 指南。
`hooks.<Event>`	`array<table>`	用于钩子事件的匹配器组,例如 `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, or `Stop`.
`hooks.<Event>[].hooks`	`array<table>`	匹配器组的钩子处理程序。目前支持命令钩子;提示和智能体钩子处理程序会被解析但跳过。
`hooks.<Event>[].hooks[].commandWindows`	`string`	仅适用于 Windows 的命令钩子命令覆盖。TOML 别名 `command_windows` is also accepted.
`instructions`	`string`	保留供未来使用;请优先使用 `model_instructions_file` or `AGENTS.md`.
`log_dir`	`string (path)`	Codex 写入日志文件的目录(例如 `codex-tui.log`); defaults to `$CODEX_HOME/log`.
`mcp_oauth_callback_port`	`integer`	MCP OAuth 登录期间使用的本地 HTTP 回调服务器的可选固定端口。未设置时,Codex 会绑定到由操作系统选择的临时端口。
`mcp_oauth_callback_url`	`string`	MCP OAuth 登录的可选重定向 URI 覆盖(例如 devbox 入口 URL)。 `mcp_oauth_callback_port` 仍然控制回调监听端口。
`mcp_oauth_credentials_store`	`auto \| file \| keyring`	存储 MCP OAuth 凭据的首选位置。
`mcp_servers.<id>.args`	`array<string>`	传递给 MCP stdio 服务器命令的参数。
`mcp_servers.<id>.bearer_token_env_var`	`string`	为 MCP HTTP 服务器提供 bearer 令牌的环境变量。
`mcp_servers.<id>.command`	`string`	MCP stdio 服务器的启动命令。
`mcp_servers.<id>.cwd`	`string`	MCP stdio 服务器进程的工作目录。
`mcp_servers.<id>.default_tools_approval_mode`	`auto \| prompt \| approve`	此服务器上 MCP 工具的默认审批行为，除非存在针对单个工具的覆盖配置。
`mcp_servers.<id>.disabled_tools`	`array<string>`	在以下内容之后应用的拒绝列表： `enabled_tools` for the MCP server.
`mcp_servers.<id>.enabled`	`boolean`	禁用 MCP 服务器而不移除其配置。
`mcp_servers.<id>.enabled_tools`	`array<string>`	MCP 服务器暴露的允许工具名称列表。
`mcp_servers.<id>.env`	`map<string,string>`	转发到 MCP stdio 服务器的环境变量。
`mcp_servers.<id>.env_http_headers`	`map<string,string>`	从环境变量填充的 MCP HTTP 服务器的 HTTP 请求头。
`mcp_servers.<id>.env_vars`	`array<string \| { name = string, source = "local" \| "remote" }>`	要加入 MCP stdio 服务器允许列表的附加环境变量。字符串条目默认为 `source = "local"`; 使用 `source = "remote"` 仅适用于由执行器支持的远程 stdio。
`mcp_servers.<id>.experimental_environment`	`local \| remote`	MCP 服务器的实验性部署位置。 `remote` 通过远程执行器环境启动 stdio 服务器；可流式传输的 HTTP 远程部署尚未实现。
`mcp_servers.<id>.http_headers`	`map<string,string>`	随每个 MCP HTTP 请求包含的静态 HTTP 请求头。
`mcp_servers.<id>.oauth_resource`	`string`	MCP 登录期间包含的可选 RFC 8707 OAuth 资源参数。
`mcp_servers.<id>.required`	`boolean`	为 true 时，如果此已启用的 MCP 服务器无法初始化，则启动/恢复失败。
`mcp_servers.<id>.scopes`	`array<string>`	向该 MCP 服务器进行身份验证时请求的 OAuth 范围。
`mcp_servers.<id>.startup_timeout_ms`	`number`	的别名 `startup_timeout_sec` in milliseconds.
`mcp_servers.<id>.startup_timeout_sec`	`number`	覆盖 MCP 服务器的默认 10 秒启动超时。
`mcp_servers.<id>.tool_timeout_sec`	`number`	覆盖 MCP 服务器的默认 60 秒单工具超时。
`mcp_servers.<id>.tools.<tool>.approval_mode`	`auto \| prompt \| approve`	此服务器上单个 MCP 工具的按工具审批行为覆盖配置。
`mcp_servers.<id>.url`	`string`	MCP 可流式传输 HTTP 服务器的端点。
`memories.consolidation_model`	`string`	用于全局记忆整合的可选模型覆盖。
`memories.disable_on_external_context`	`boolean`	当 `true`,使用外部上下文(如 MCP 工具调用、网络搜索或工具搜索)的线程不会纳入记忆生成。默认为 `false`. Legacy alias: `memories.no_memories_if_mcp_or_web_search`.
`memories.extract_model`	`string`	用于按线程记忆提取的可选模型覆盖。
`memories.generate_memories`	`boolean`	当 `false`,新创建的线程不会作为记忆生成的输入被存储。默认为 `true`.
`memories.max_raw_memories_for_consolidation`	`number`	为全局整合保留的最大近期原始记忆数量。默认为 `256` and is capped at `4096`.
`memories.max_rollout_age_days`	`number`	考虑用于记忆生成的线程最大期限。默认为 `30` and is clamped to `0`-`90`.
`memories.max_rollouts_per_startup`	`number`	每次启动阶段处理的最大推出候选数。默认为 `16` and is capped at `128`.
`memories.max_unused_days`	`number`	记忆在不符合整合条件之前未被使用的最大天数。默认为 `30` and is clamped to `0`-`365`.
`memories.min_rate_limit_remaining_percent`	`number`	在记忆生成开始前，Codex 速率限制窗口中要求的最小剩余百分比。默认为 `25` and is clamped to `0`-`100`.
`memories.min_rollout_idle_hours`	`number`	线程被考虑用于记忆生成前的最短空闲时间。默认为 `6` and is clamped to `1`-`48`.
`memories.use_memories`	`boolean`	当 `false`,Codex 会跳过将现有记忆注入未来会话。默认为 `true`.
`model`	`string`	要使用的模型（例如， `gpt-5.5`).
`model_auto_compact_token_limit`	`number`	触发自动历史记录压缩的 Token 阈值（未设置则使用模型默认值）。
`model_catalog_json`	`string (path)`	启动时加载的可选 JSON 模型目录路径。所选的 `$CODEX_HOME/profile-name.config.toml` 配置文件可以按配置文件覆盖此设置。
`model_context_window`	`number`	活动模型可用的上下文窗口 Token 数。
`model_instructions_file`	`string (path)`	内置指令的替代项，而不是 `AGENTS.md`.
`model_provider`	`string`	提供者 ID 来自 `model_providers` (默认： `openai`).
`model_providers.<id>`	`table`	自定义提供者定义。内置提供者 ID（`openai`, `ollama`，且 `lmstudio`）已被保留，无法被覆盖。
`model_providers.<id>.auth`	`table`	自定义提供者的命令支持的 Bearer 令牌配置。请勿与 `env_key`, `experimental_bearer_token`, or `requires_openai_auth`.
`model_providers.<id>.auth.args`	`array<string>`	传递给令牌命令的参数。
`model_providers.<id>.auth.command`	`string`	当 Codex 需要 Bearer 令牌时运行的命令。该命令必须将令牌打印到标准输出。
`model_providers.<id>.auth.cwd`	`string (path)`	令牌命令的工作目录。
`model_providers.<id>.auth.refresh_interval_ms`	`number`	Codex 主动刷新令牌的频率，以毫秒为单位（默认值：300000）。设置为 `0` 仅在进行身份验证重试后刷新。
`model_providers.<id>.auth.timeout_ms`	`number`	令牌命令的最大运行时间，以毫秒为单位（默认值：5000）。
`model_providers.<id>.base_url`	`string`	模型提供者的 API 基础 URL。
`model_providers.<id>.env_http_headers`	`map<string,string>`	存在时从环境变量填充的 HTTP 请求头。
`model_providers.<id>.env_key`	`string`	提供提供者 API 密钥的环境变量。
`model_providers.<id>.env_key_instructions`	`string`	提供者 API 密钥的可选设置指南。
`model_providers.<id>.experimental_bearer_token`	`string`	提供者的直接 Bearer 令牌（不建议使用；请使用 `env_key`).
`model_providers.<id>.http_headers`	`map<string,string>`	添加到提供者请求中的静态 HTTP 请求头。
`model_providers.<id>.name`	`string`	自定义模型提供者的显示名称。
`model_providers.<id>.query_params`	`map<string,string>`	附加到提供者请求的额外查询参数。
`model_providers.<id>.request_max_retries`	`number`	向提供者发起的 HTTP 请求的重试次数（默认值：4）。
`model_providers.<id>.requires_openai_auth`	`boolean`	该提供者使用 OpenAI 身份验证（默认值：false）。
`model_providers.<id>.stream_idle_timeout_ms`	`number`	SSE 流的空闲超时时间，以毫秒为单位（默认值：300000）。
`model_providers.<id>.stream_max_retries`	`number`	SSE 流中断的重试次数（默认值：5）。
`model_providers.<id>.supports_websockets`	`boolean`	该提供者是否支持 Responses API WebSocket 传输协议。
`model_providers.<id>.wire_api`	`responses`	提供者使用的协议。 `responses` 是唯一支持的值，在省略时为默认值。
`model_providers.amazon-bedrock.aws.profile`	`string`	内置的所使用的 AWS 配置文件名称 `amazon-bedrock` provider.
`model_providers.amazon-bedrock.aws.region`	`string`	内置的所使用的 AWS 区域 `amazon-bedrock` provider.
`model_reasoning_effort`	`minimal \| low \| medium \| high \| xhigh`	调整支持的模型的推理工作量（仅限 Responses API； `xhigh` 取决于具体模型）。
`model_reasoning_summary`	`auto \| concise \| detailed \| none`	选择推理摘要的详细程度或完全禁用摘要。
`model_supports_reasoning_summaries`	`boolean`	强制 Codex 发送或不发送推理元数据。
`model_verbosity`	`low \| medium \| high`	可选的 GPT-5 Responses API 冗余度覆盖；未设置时，将使用所选的模型/预设默认值。
`notice.hide_full_access_warning`	`boolean`	记录已确认完整访问警告提示。
`notice.hide_gpt-5.1-codex-max_migration_prompt`	`boolean`	记录已确认 gpt-5.1-codex-max 迁移提示。
`notice.hide_gpt5_1_migration_prompt`	`boolean`	记录已确认 GPT-5.1 迁移提示。
`notice.hide_rate_limit_model_nudge`	`boolean`	记录已选择退出速率限制模型切换提醒。
`notice.hide_world_writable_warning`	`boolean`	记录已确认 Windows 全局可写目录警告。
`notice.model_migrations`	`map<string,string>`	将已确认的模型迁移记录为 old->new 映射。
`notify`	`array<string>`	用于通知的调用命令；接收来自 Codex 的 JSON 负载。
`openai_base_url`	`string`	内置 `openai` 模型提供者的 Base URL 覆盖。
`oss_provider`	`lmstudio \| ollama`	使用以下参数运行时使用的默认本地提供者 `--oss` （如未设置，默认为提示用户选择）。
`otel.environment`	`string`	应用于发出的 OpenTelemetry 事件的环境标签（默认： `dev`).
`otel.exporter`	`none \| otlp-http \| otlp-grpc`	选择 OpenTelemetry 导出器并提供相关端点元数据。
`otel.exporter.<id>.endpoint`	`string`	OTEL 日志的导出器端点。
`otel.exporter.<id>.headers`	`map<string,string>`	包含在 OTEL 导出器请求中的静态请求头。
`otel.exporter.<id>.protocol`	`binary \| json`	OTLP/HTTP 导出器使用的协议。
`otel.exporter.<id>.tls.ca-certificate`	`string`	OTEL 导出器 TLS 的 CA 证书路径。
`otel.exporter.<id>.tls.client-certificate`	`string`	OTEL 导出器 TLS 的客户端证书路径。
`otel.exporter.<id>.tls.client-private-key`	`string`	OTEL 导出器 TLS 的客户端私钥路径。
`otel.log_user_prompt`	`boolean`	选择允许通过 OpenTelemetry 日志导出原始用户提示。
`otel.metrics_exporter`	`none \| statsig \| otlp-http \| otlp-grpc`	选择 OpenTelemetry 指标导出器（默认为 `statsig`).
`otel.trace_exporter`	`none \| otlp-http \| otlp-grpc`	选择 OpenTelemetry 链路追踪导出器并提供相关端点元数据。
`otel.trace_exporter.<id>.endpoint`	`string`	OTEL 日志的链路追踪导出器端点。
`otel.trace_exporter.<id>.headers`	`map<string,string>`	包含在 OTEL 链路追踪导出器请求中的静态请求头。
`otel.trace_exporter.<id>.protocol`	`binary \| json`	OTLP/HTTP 链路追踪导出器使用的协议。
`otel.trace_exporter.<id>.tls.ca-certificate`	`string`	OTEL 追踪导出器 TLS 的 CA 证书路径。
`otel.trace_exporter.<id>.tls.client-certificate`	`string`	OTEL 追踪导出器 TLS 的客户端证书路径。
`otel.trace_exporter.<id>.tls.client-private-key`	`string`	OTEL 追踪导出器 TLS 的客户端私钥路径。
`permissions.<name>.description`	`string`	此命名配置文件的可读描述。配置文件不会通过以下方式继承其父级的描述： `extends`.
`permissions.<name>.extends`	`string`	在此命名配置文件之前应用的可选父级配置文件。将其设置为另一个命名配置文件， `:read-only`, or `:workspace`; `:danger-full-access`,未定义的父级以及循环会被拒绝。
`permissions.<name>.filesystem`	`table`	命名的文件系统权限配置文件。每个键都是绝对路径或特殊令牌，例如 `:minimal` or `:workspace_roots`.
`permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob>`	`"read" \| "write" \| "deny"`	相对于每个有效工作区根目录的范围文件系统访问。使用 `"."` 用于根路径本身；glob 子路径，例如 `"*/.env"` 可以使用以下方式拒绝读取操作 `"deny"`.
`permissions.<name>.filesystem.<path-or-glob>`	`"read" \| "write" \| "deny" \| table`	授予对某一路径、glob 模式或特殊令牌的直接访问权限，或者在根路径下限定嵌套条目的作用域。使用 `"deny"` 来拒绝匹配路径的读取操作。
`permissions.<name>.filesystem.glob_scan_max_depth`	`number`	在沙箱启动前快照匹配项的平台上，用于展开 deny-read glob 模式的最大深度。设置时必须至少为 `1` 设置时。
`permissions.<name>.network.allow_local_binding`	`boolean`	允许通过沙箱网络进行更广泛的本地/私网访问。精确的本地 IP 字面量或 `localhost` allow 规则仍可允许特定的本地目标，前提是此选项保持 `false`.
`permissions.<name>.network.allow_upstream_proxy`	`boolean`	允许沙盒网络连接通过另一上游代理进行链式传输。
`permissions.<name>.network.dangerously_allow_all_unix_sockets`	`boolean`	允许任意 Unix 套接字目标，而非默认的受限集合。仅在严格控制的环境中使用。
`permissions.<name>.network.dangerously_allow_non_loopback_proxy`	`boolean`	允许沙盒网络监听器绑定到非回环地址。启用此选项可能会将监听器暴露在 localhost 之外。
`permissions.<name>.network.domains`	`table`	沙盒网络的域规则。支持精确匹配的主机， `.example.com` for subdomains only, `.example.com` 表示顶级域及其子域，以及全局的 `` 允许规则。 `deny` 规则为准。
`permissions.<name>.network.domains.<pattern>`	`allow \| deny`	允许或拒绝精确的主机或限定范围的通配符模式，例如 `.example.com` or `*.example.com`.
`permissions.<name>.network.enable_socks5`	`boolean`	当此权限配置文件启用沙盒网络时，暴露 SOCKS5 支持。
`permissions.<name>.network.enable_socks5_udp`	`boolean`	启用时允许通过 SOCKS5 监听器使用 UDP。
`permissions.<name>.network.enabled`	`boolean`	为此命名的权限配置文件启用网络访问。这会更改沙盒网络策略；其本身不会启动网络代理。
`permissions.<name>.network.mode`	`limited \| full`	用于子进程流量的网络代理模式。
`permissions.<name>.network.proxy_url`	`string`	当此权限配置文件启用沙盒网络时使用的 HTTP 监听器 URL。
`permissions.<name>.network.socks_url`	`string`	此权限配置文件使用的 SOCKS5 代理端点。
`permissions.<name>.network.unix_sockets`	`table`	沙盒网络的 Unix 套接字允许列表覆盖。使用套接字路径作为键； `allow` 添加路径，并且 `deny` 拒绝该路径。
`permissions.<name>.network.unix_sockets.<path>`	`allow \| deny`	将绝对 Unix 套接字路径添加到有效允许列表中，且 `allow`,或用以下方式拒绝它: `deny`。被拒绝的条目会从生效的允许列表中省略。
`permissions.<name>.workspace_roots`	`table`	与配置文件定义的工作区根目录一同接收 `:workspace_roots` 文件系统规则，同时包含会话的运行时工作区根目录。
`permissions.<name>.workspace_roots.<path>`	`boolean`	在以下情况时，将路径选择加入配置文件的工作区根目录集： `true`。已禁用的条目保持不活动状态。
`personality`	`none \| friendly \| pragmatic`	为声明了以下内容的模型设置默认通信风格： `supportsPersonality`;可以按线程/轮次覆盖,或通过 `/personality`.
`plan_mode_reasoning_effort`	`none \| minimal \| low \| medium \| high \| xhigh`	Plan 模式专属推理覆盖设置。未设置时，Plan 模式将使用其内置的预设默认值。
`plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode`	`auto \| prompt \| approve`	插件提供的 MCP 服务器上各工具的默认批准行为。
`plugins.<plugin>.mcp_servers.<server>.disabled_tools`	`array<string>`	在以下内容之后应用的拒绝列表： `enabled_tools` 用于插件提供的 MCP 服务器。
`plugins.<plugin>.mcp_servers.<server>.enabled`	`boolean`	无需更改插件清单，即可启用或禁用由已安装插件捆绑的 MCP 服务器。
`plugins.<plugin>.mcp_servers.<server>.enabled_tools`	`array<string>`	从插件提供的 MCP 服务器中暴露的工具允许列表。
`plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode`	`auto \| prompt \| approve`	针对插件提供的 MCP 工具的单工具批准行为覆盖设置。
`project_doc_fallback_filenames`	`array<string>`	在缺少 `AGENTS.md` 时尝试读取的额外文件名。
`project_doc_max_bytes`	`number`	从中读取的最大字节数为 `AGENTS.md` （在构建项目指令时）。
`project_root_markers`	`array<string>`	项目根目录标记文件名列表；在向上搜索父目录以查找项目根目录时使用。
`projects.<path>.trust_level`	`string`	将项目或工作区标记为受信任或不受信任 (`"trusted"` \| `"untrusted"`)。不受信任的项目将跳过项目范围的 `.codex/` 层，包括项目本地配置、钩子和规则。
`review_model`	`string`	使用的可选模型覆盖（ `/review` 默认为当前会话模型）。
`sandbox_mode`	`read-only \| workspace-write \| danger-full-access`	命令执行期间文件系统和网络访问的沙盒策略。
`sandbox_workspace_write.exclude_slash_tmp`	`boolean`	在工作区写入模式下，将 `/tmp` 从可写入根目录中排除。
`sandbox_workspace_write.exclude_tmpdir_env_var`	`boolean`	在工作区写入模式下，将 `$TMPDIR` 从可写入根目录中排除。
`sandbox_workspace_write.network_access`	`boolean`	允许工作区写入沙盒内的出站网络访问。
`sandbox_workspace_write.writable_roots`	`array<string>`	启用工作区写入模式时的额外可写入根目录。 `sandbox_mode = "workspace-write"`.
`service_tier`	`string`	新轮次的首选服务层级。内置值包括 `flex` and `fast`；传统 `fast` 配置映射到请求值 `priority`,目录提供的层级 ID 也可以被存储。
`shell_environment_policy.exclude`	`array<string>`	在应用默认值后用于移除环境变量的 Glob 模式。
`shell_environment_policy.experimental_use_profile`	`boolean`	在启动子进程时使用用户 Shell 配置文件。
`shell_environment_policy.ignore_default_excludes`	`boolean`	在其他过滤器运行之前，保留包含 KEY/SECRET/TOKEN 的变量。
`shell_environment_policy.include_only`	`array<string>`	白名单模式；设置后仅保留匹配的变量。
`shell_environment_policy.inherit`	`all \| core \| none`	派生子进程时的基线环境继承。
`shell_environment_policy.set`	`map<string,string>`	注入到每个子进程的显式环境覆盖。
`show_raw_agent_reasoning`	`boolean`	在活动模型输出原始推理内容时将其展示。
`skills.config`	`array<object>`	存储在 config.toml 中的按技能启用的覆盖设置。
`skills.config.<index>.enabled`	`boolean`	启用或禁用引用的技能。
`skills.config.<index>.path`	`string (path)`	包含以下内容的技能文件夹路径 `SKILL.md`.
`sqlite_home`	`string (path)`	Codex 存储 SQLite 支持的状态数据库的目录，该数据库用于代理任务和其他可恢复的运行时状态。
`suppress_unstable_features_warning`	`boolean`	抑制启用开发中功能标记时出现的警告。
`tool_output_token_limit`	`number`	用于在历史记录中存储单个工具/函数输出的 Token 预算。
`tool_suggest.disabled_tools`	`array<table>`	禁用对特定可发现连接器或插件的建议。每个条目使用 `type = "connector"` or `"plugin"` and an `id`.
`tool_suggest.discoverables`	`array<table>`	允许对额外可发现连接器或插件提供工具建议。每个条目使用 `type = "connector"` or `"plugin"` and an `id`.
`tools.view_image`	`boolean`	启用本地图像附件工具 `view_image`.
`tools.web_search`	`boolean \| { context_size = "low\|medium\|high", allowed_domains = [string], location = { country, region, city, timezone } }`	可选的网络搜索工具配置。仍接受旧版的布尔值格式，但对象格式允许您设置搜索上下文大小、允许的域以及用户的大致位置。
`tui`	`table`	特定于 TUI 的选项，例如启用内联桌面通知。
`tui.alternate_screen`	`auto \| always \| never`	控制 TUI 对备用屏幕的使用（默认值：auto；auto 模式下在 Zellij 中会跳过此设置以保留回滚历史）。
`tui.animations`	`boolean`	启用终端动画（欢迎屏幕、微光闪烁、加载动画）（默认值：true）。
`tui.keymap.<context>.<action>`	`string \| array<string>`	TUI 操作的键盘快捷键绑定。支持的上下文包括 `global`, `chat`, `composer`, `editor`, `pager`, `list`，且 `approval`;特定上下文的绑定会覆盖 `tui.keymap.global`.
`tui.keymap.<context>.<action> = []`	`empty array`	在该按键映射上下文中解除操作绑定。按键名称使用规范化字符串，例如 `ctrl-a`, `shift-enter`, `page-down`, or `minus`.
`tui.model_availability_nux.<model>`	`integer`	按键为模型别名的内部启动提示状态。
`tui.notification_condition`	`unfocused \| always`	控制 TUI 通知是仅在终端未聚焦时触发，还是无论聚焦状态如何均触发。默认值为 `unfocused`.
`tui.notification_method`	`auto \| osc9 \| bel`	终端通知的通知方式（默认值：auto）。
`tui.notifications`	`boolean \| array<string>`	启用 TUI 通知；可选择限制为特定事件类型。
`tui.raw_output_mode`	`boolean`	以原始回滚模式启动 TUI，以便在终端中进行易于复制的文本选择（默认值：false）。您可以通过以下方式切换： `/raw` or the default `alt-r` 按键绑定。
`tui.show_tooltips`	`boolean`	在 TUI 欢迎屏幕中显示新手提示（默认值：true）。
`tui.status_line`	`array<string> \| null`	TUI 底部状态栏项目标识符的有序列表。 `null` 禁用状态栏。
`tui.terminal_title`	`array<string> \| null`	终端窗口/标签页标题项标识符的有序列表。默认为 `["spinner", "project"]`; `null` 禁用标题更新。
`tui.theme`	`string`	语法高亮主题覆盖（使用 kebab-case 格式的主题名称）。
`tui.vim_mode_default`	`boolean`	在普通模式下启动 Vim 编辑器，而非插入模式（默认：false）。您仍然可以在每次会话中通过以下方式切换： `/vim`.
`web_search`	`disabled \| cached \| live`	网络搜索模式（默认： `"cached"`;cached 使用由 OpenAI 维护的索引,不会抓取实时页面;如果你使用 `--yolo` 或其他完全访问权限的沙盒设置，它默认为 `"live"`）。使用 `"live"` 从网络获取最新数据，或者 `"disabled"` to remove the tool.
`windows_wsl_setup_acknowledged`	`boolean`	跟踪 Windows 引导确认（仅限 Windows）。
`windows.sandbox`	`unelevated \| elevated`	在 Windows 上原生运行 Codex 时的专用原生沙盒模式。
`windows.sandbox_private_desktop`	`boolean`	在原生 Windows 上默认在私有桌面上运行最终受沙盒保护的子进程。设置 `false` 仅用于兼容较旧的 `Winsta0\\Default` behavior.

键

agents.<name>.config_file

类型 / 值

string (path)

详情

该角色的 TOML 配置层路径；相对路径将从声明该角色的配置文件开始解析。

键

agents.<name>.description

类型 / 值

string

详情

在选择和生成该代理类型时向 Codex 展示的角色指导。

键

agents.<name>.nickname_candidates

类型 / 值

array<string>

详情

该角色下已生成代理的可选显示昵称池。

键

agents.job_max_runtime_seconds

类型 / 值

number

详情

的每个 worker 的默认超时时间为 spawn_agents_on_csv 任务。未设置时，工具将回退到每个 worker 1800 秒。

键

agents.max_depth

类型 / 值

number

详情

生成的代理线程允许的最大嵌套深度（根会话从深度 0 开始；默认：1）。

键

agents.max_threads

类型 / 值

number

详情

允许同时打开的代理线程最大数量。默认为 6 未设置时。

键

allow_login_shell

类型 / 值

boolean

详情

允许基于 shell 的工具使用登录 shell 语义。默认为 true；当 false, login = true 请求将被拒绝并忽略 login 默认为非登录 shell。

键

analytics.enabled

类型 / 值

boolean

详情

启用或禁用此机器/配置文件的分析功能。未设置时，将应用客户端默认值。

键

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 = { ... } } 来允许或自动拒绝特定提示类别，同时保持其他提示的交互性。 on-failure 已弃用；请使用 on-request for interactive runs or never for non-interactive runs.

键

approval_policy.granular.mcp_elicitations

类型 / 值

boolean

详情

当 true, MCP 启发提示将被允许显示，而不是被自动拒绝。

键

approval_policy.granular.request_permissions

类型 / 值

boolean

详情

当 true，来自 request_permissions 工具允许显示。

键

approval_policy.granular.rules

类型 / 值

boolean

详情

当 true，由 execpolicy 触发的审批 prompt 规则允许显示。

键

approval_policy.granular.sandbox_approval

类型 / 值

boolean

详情

当 true，允许弹出沙箱权限提升审批提示。

键

approval_policy.granular.skill_approval

类型 / 值

boolean

详情

当 true，允许弹出技能脚本审批提示。

键

approvals_reviewer

类型 / 值

user | auto_review

详情

在以下模式下，谁负责审查符合条件的审批提示： on-request 或精细审批策略。默认为 user; auto_review 使用审查子代理。此设置不会更改沙箱机制，也不会影响沙箱内已允许的审查操作。

键

apps._default.destructive_enabled

类型 / 值

boolean

详情

应用工具的默认允许/拒绝设置，带有 destructive_hint = true.

键

apps._default.enabled

类型 / 值

boolean

详情

所有应用的默认启用状态，除非按应用单独覆盖。

键

apps._default.open_world_enabled

类型 / 值

boolean

详情

应用工具的默认允许/拒绝设置，带有 open_world_hint = true.

键

apps.<id>.default_tools_approval_mode

类型 / 值

auto | prompt | approve

详情

此应用中工具的默认批准行为，除非存在针对单个工具的覆盖设置。

键

apps.<id>.default_tools_enabled

类型 / 值

boolean

详情

此应用中工具的默认启用状态，除非存在针对单个工具的覆盖设置。

键

apps.<id>.destructive_enabled

类型 / 值

boolean

详情

允许或阻止此应用中声明为 destructive_hint = true.

键

apps.<id>.enabled

类型 / 值

boolean

详情

通过 id 启用或禁用特定应用/连接器（默认：true）。

键

apps.<id>.open_world_enabled

类型 / 值

boolean

详情

允许或阻止此应用中声明为 open_world_hint = true.

键

apps.<id>.tools.<tool>.approval_mode

类型 / 值

auto | prompt | approve

详情

针对单个应用工具的逐工具批准行为覆盖。

键

apps.<id>.tools.<tool>.enabled

类型 / 值

boolean

详情

应用工具的逐工具启用覆盖（例如 repos/list).

键

auto_review.policy

类型 / 值

string

详情

用于自动审查的本地 Markdown 策略指令。由 guardian_policy_config 优先。忽略空值。

键

background_terminal_max_timeout

类型 / 值

number

详情

空轮询的最大轮询窗口（毫秒） write_stdin （后台终端轮询）。默认值： 300000 （5 分钟）。取代较旧的 background_terminal_timeout key.

键

chatgpt_base_url

类型 / 值

string

详情

覆盖在 ChatGPT 登录流程中使用的基 URL。

键

check_for_update_on_startup

类型 / 值

boolean

详情

在启动时检查 Codex 更新（仅当更新由中央统一管理时才设置为 false）。

键

cli_auth_credentials_store

类型 / 值

file | keyring | auto

详情

控制 CLI 存储缓存凭据的位置（基于文件的 auth.json 还是操作系统密钥链）。

键

commit_attribution

类型 / 值

string

详情

Commit 联合作者 Trailer，用于在 [features].codex_git_commit 启用时生效。默认为 Codex <[email protected]>；设置 "" to disable.

键

compact_prompt

类型 / 值

string

详情

对历史记录压缩提示的内联覆盖。

键

default_permissions

类型 / 值

string

详情

应用于沙盒工具调用的默认权限配置文件名称。内置选项为 :read-only, :workspace，且 :danger-full-access；自定义配置文件名称需要匹配 [permissions.<name>] 表。请勿与 sandbox_mode or [sandbox_workspace_write].

键

developer_instructions

类型 / 值

string

详情

注入到会话中的附加开发者指令（可选）。

键

disable_paste_burst

类型 / 值

boolean

详情

禁用 TUI 中的突发粘贴检测。

键

experimental_compact_prompt_file

类型 / 值

string (path)

详情

从文件加载压缩提示覆盖（实验性）。

键

experimental_use_unified_exec_tool

类型 / 值

boolean

详情

启用统一执行 (unified exec) 的旧版名称；推荐使用 [features].unified_exec or codex --enable unified_exec.

键

features.apps

类型 / 值

boolean

详情

启用 ChatGPT Apps/连接器支持（实验性）。

键

features.codex_git_commit

类型 / 值

boolean

详情

启用 Codex 生成的 git 提交。启用后，Codex 会使用 commit_attribution to append a Co-authored-by: trailer 来生成提交消息。

键

features.enable_request_compression

类型 / 值

boolean

详情

在受支持的情况下，使用 zstd 压缩流式请求体（稳定版；默认开启）。

键

features.fast_mode

类型 / 值

boolean

详情

在 TUI 中启用模型目录服务层级选择，包括当活动模型播发快速层级 (Fast-tier) 命令时启用该命令（稳定版；默认开启）。

键

features.hooks

类型 / 值

boolean

详情

启用从以下位置加载的生命周期钩子 hooks.json or inline [hooks] config. features.codex_hooks 是一个已弃用的别名。

键

features.memories

类型 / 值

boolean

详情

启用记忆（默认关闭）。

键

features.multi_agent

类型 / 值

boolean

详情

启用多智能体协作工具（spawn_agent, send_input, resume_agent, wait_agent，且 close_agent）（稳定功能；默认开启）。

键

features.network_proxy

类型 / 值

boolean | table

详情

启用沙盒网络。在设置网络策略选项（例如 domains （实验性功能；默认关闭）。

键

features.network_proxy.allow_local_binding

类型 / 值

boolean

详情

允许更广泛的本地/私有网络访问。默认为 false；确切的本地 IP 字面值或 localhost allow 规则仍可允许特定的本地目标。

键

features.network_proxy.allow_upstream_proxy

类型 / 值

boolean

详情

允许通过环境中的上游代理进行链式连接。默认为 true.

键

features.network_proxy.dangerously_allow_all_unix_sockets

类型 / 值

boolean

详情

允许任意 Unix socket 目标，而非仅限允许列表中的访问。默认为 false；仅在严格控制的环境中使用。

键

features.network_proxy.dangerously_allow_non_loopback_proxy

类型 / 值

boolean

详情

允许非回环监听器地址。默认为 false；启用此选项可能会将代理监听器暴露给 localhost 之外。

键

features.network_proxy.domains

类型 / 值

map<string, allow | deny>

详情

沙盒网络的域策略。默认未设置，这意味着在您添加 allow 规则之前不允许任何外部目标。支持精确的主机名、 *.example.com for subdomains only, **.example.com 表示顶级域及其子域，以及全局的 * allow 规则；优先使用限定范围的规则，因为 * 会完全开放公共出站访问。添加 deny 规则以阻止特定目标；发生冲突时以 deny 规则为准。

键

features.network_proxy.enable_socks5

类型 / 值

boolean

详情

暴露 SOCKS5 支持。默认为 true.

键

features.network_proxy.enable_socks5_udp

类型 / 值

boolean

详情

允许通过 SOCKS5 使用 UDP。默认为 true.

键

features.network_proxy.enabled

类型 / 值

boolean

详情

启用沙盒网络。默认为 false.

键

features.network_proxy.proxy_url

类型 / 值

string

详情

用于沙盒网络的 HTTP 监听器 URL。默认为 "http://127.0.0.1:3128".

键

features.network_proxy.socks_url

类型 / 值

string

详情

SOCKS5 监听器 URL。默认为 "http://127.0.0.1:8081".

键

features.network_proxy.unix_sockets

类型 / 值

map<string, allow | deny>

详情

沙盒网络的 Unix socket 策略。默认未设置；为允许的 socket 添加 allow 条目。

键

features.personality

类型 / 值

boolean

详情

启用人格选择控制（稳定功能；默认开启）。

键

features.prevent_idle_sleep

类型 / 值

boolean

详情

在回合处于活动运行状态时防止机器休眠（实验性功能；默认关闭）。

键

features.shell_snapshot

类型 / 值

boolean

详情

快照 shell 环境以加速重复命令的执行（稳定功能；默认开启）。

键

features.shell_tool

类型 / 值

boolean

详情

启用默认设置 shell 用于运行命令的

键

features.skill_mcp_dependency_install

类型 / 值

boolean

详情

允许提示并安装技能缺失的 MCP 依赖项（稳定版；默认开启）。

键

features.undo

类型 / 值

boolean

详情

启用撤销支持（稳定版；默认关闭）。

键

features.unified_exec

类型 / 值

boolean

详情

使用统一的基于 PTY 的 exec 工具（稳定版；除 Windows 外默认开启）。

键

features.web_search

类型 / 值

boolean

详情

已弃用的旧版开关；请使用顶层 web_search setting.

键

features.web_search_cached

类型 / 值

boolean

详情

已弃用的旧版开关。当 web_search 未设置时，true 对应于 web_search = "cached".

键

features.web_search_request

类型 / 值

boolean

详情

已弃用的旧版开关。当 web_search 未设置时，true 对应于 web_search = "live".

键

feedback.enabled

类型 / 值

boolean

详情

启用通过 /feedback 在所有 Codex 界面提交反馈的功能（默认：true）。

键

file_opener

类型 / 值

vscode | vscode-insiders | windsurf | cursor | none

详情

用于打开 Codex 输出引用的 URI 方案（默认： vscode).

键

forced_chatgpt_workspace_id

类型 / 值

string (uuid)

详情

将 ChatGPT 登录限制为特定的工作区标识符。

键

forced_login_method

类型 / 值

chatgpt | api

详情

将 Codex 限制为特定的身份验证方法。

键

hide_agent_reasoning

类型 / 值

boolean

详情

抑制推理事件,在 TUI 和 codex exec output.

键

history.max_bytes

类型 / 值

number

详情

如果设置,通过丢弃最旧的条目将历史文件大小限制在指定字节数内。

键

history.persistence

类型 / 值

save-all | none

详情

控制 Codex 是否将会话记录保存到 history.jsonl。

键

hooks

类型 / 值

table

详情

内联配置在以下位置的生命周期钩子: config.toml。使用与以下相同的事件结构: hooks.json;有关示例和支持的事件,请参阅 Hooks 指南。

键

hooks.<Event>

类型 / 值

array<table>

详情

用于钩子事件的匹配器组,例如 PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SubagentStart, SubagentStop, UserPromptSubmit, or Stop.

键

hooks.<Event>[].hooks

类型 / 值

array<table>

详情

匹配器组的钩子处理程序。目前支持命令钩子;提示和智能体钩子处理程序会被解析但跳过。

键

hooks.<Event>[].hooks[].commandWindows

类型 / 值

string

详情

仅适用于 Windows 的命令钩子命令覆盖。TOML 别名 command_windows is also accepted.

键

instructions

类型 / 值

string

详情

保留供未来使用;请优先使用 model_instructions_file or AGENTS.md.

键

log_dir

类型 / 值

string (path)

详情

Codex 写入日志文件的目录(例如 codex-tui.log); defaults to $CODEX_HOME/log.

键

mcp_oauth_callback_port

类型 / 值

integer

详情

MCP OAuth 登录期间使用的本地 HTTP 回调服务器的可选固定端口。未设置时,Codex 会绑定到由操作系统选择的临时端口。

键

mcp_oauth_callback_url

类型 / 值

string

详情

MCP OAuth 登录的可选重定向 URI 覆盖(例如 devbox 入口 URL)。 mcp_oauth_callback_port 仍然控制回调监听端口。

键

mcp_oauth_credentials_store

类型 / 值

auto | file | keyring

详情

存储 MCP OAuth 凭据的首选位置。

键

mcp_servers.<id>.args

类型 / 值

array<string>

详情

传递给 MCP stdio 服务器命令的参数。

键

mcp_servers.<id>.bearer_token_env_var

类型 / 值

string

详情

为 MCP HTTP 服务器提供 bearer 令牌的环境变量。

键

mcp_servers.<id>.command

类型 / 值

string

详情

MCP stdio 服务器的启动命令。

键

mcp_servers.<id>.cwd

类型 / 值

string

详情

MCP stdio 服务器进程的工作目录。

键

mcp_servers.<id>.default_tools_approval_mode

类型 / 值

auto | prompt | approve

详情

此服务器上 MCP 工具的默认审批行为，除非存在针对单个工具的覆盖配置。

键

mcp_servers.<id>.disabled_tools

类型 / 值

array<string>

详情

在以下内容之后应用的拒绝列表： enabled_tools for the MCP server.

键

mcp_servers.<id>.enabled

类型 / 值

boolean

详情

禁用 MCP 服务器而不移除其配置。

键

mcp_servers.<id>.enabled_tools

类型 / 值

array<string>

详情

MCP 服务器暴露的允许工具名称列表。

键

mcp_servers.<id>.env

类型 / 值

map<string,string>

详情

转发到 MCP stdio 服务器的环境变量。

键

mcp_servers.<id>.env_http_headers

类型 / 值

map<string,string>

详情

从环境变量填充的 MCP HTTP 服务器的 HTTP 请求头。

键

mcp_servers.<id>.env_vars

类型 / 值

array<string | { name = string, source = "local" | "remote" }>

详情

要加入 MCP stdio 服务器允许列表的附加环境变量。字符串条目默认为 source = "local"; 使用 source = "remote" 仅适用于由执行器支持的远程 stdio。

键

mcp_servers.<id>.experimental_environment

类型 / 值

local | remote

详情

MCP 服务器的实验性部署位置。 remote 通过远程执行器环境启动 stdio 服务器；可流式传输的 HTTP 远程部署尚未实现。

键

mcp_servers.<id>.http_headers

类型 / 值

map<string,string>

详情

随每个 MCP HTTP 请求包含的静态 HTTP 请求头。

键

mcp_servers.<id>.oauth_resource

类型 / 值

string

详情

MCP 登录期间包含的可选 RFC 8707 OAuth 资源参数。

键

mcp_servers.<id>.required

类型 / 值

boolean

详情

为 true 时，如果此已启用的 MCP 服务器无法初始化，则启动/恢复失败。

键

mcp_servers.<id>.scopes

类型 / 值

array<string>

详情

向该 MCP 服务器进行身份验证时请求的 OAuth 范围。

键

mcp_servers.<id>.startup_timeout_ms

类型 / 值

number

详情

的别名 startup_timeout_sec in milliseconds.

键

mcp_servers.<id>.startup_timeout_sec

类型 / 值

number

详情

覆盖 MCP 服务器的默认 10 秒启动超时。

键

mcp_servers.<id>.tool_timeout_sec

类型 / 值

number

详情

覆盖 MCP 服务器的默认 60 秒单工具超时。

键

mcp_servers.<id>.tools.<tool>.approval_mode

类型 / 值

auto | prompt | approve

详情

此服务器上单个 MCP 工具的按工具审批行为覆盖配置。

键

mcp_servers.<id>.url

类型 / 值

string

详情

MCP 可流式传输 HTTP 服务器的端点。

键

memories.consolidation_model

类型 / 值

string

详情

用于全局记忆整合的可选模型覆盖。

键

memories.disable_on_external_context

类型 / 值

boolean

详情

当 true,使用外部上下文(如 MCP 工具调用、网络搜索或工具搜索)的线程不会纳入记忆生成。默认为 false. Legacy alias: memories.no_memories_if_mcp_or_web_search.

键

memories.extract_model

类型 / 值

string

详情

用于按线程记忆提取的可选模型覆盖。

键

memories.generate_memories

类型 / 值

boolean

详情

当 false,新创建的线程不会作为记忆生成的输入被存储。默认为 true.

键

memories.max_raw_memories_for_consolidation

类型 / 值

number

详情

为全局整合保留的最大近期原始记忆数量。默认为 256 and is capped at 4096.

键

memories.max_rollout_age_days

类型 / 值

number

详情

考虑用于记忆生成的线程最大期限。默认为 30 and is clamped to 0-90.

键

memories.max_rollouts_per_startup

类型 / 值

number

详情

每次启动阶段处理的最大推出候选数。默认为 16 and is capped at 128.

键

memories.max_unused_days

类型 / 值

number

详情

记忆在不符合整合条件之前未被使用的最大天数。默认为 30 and is clamped to 0-365.

键

memories.min_rate_limit_remaining_percent

类型 / 值

number

详情

在记忆生成开始前，Codex 速率限制窗口中要求的最小剩余百分比。默认为 25 and is clamped to 0-100.

键

memories.min_rollout_idle_hours

类型 / 值

number

详情

线程被考虑用于记忆生成前的最短空闲时间。默认为 6 and is clamped to 1-48.

键

memories.use_memories

类型 / 值

boolean

详情

当 false,Codex 会跳过将现有记忆注入未来会话。默认为 true.

键

model

类型 / 值

string

详情

要使用的模型（例如， gpt-5.5).

键

model_auto_compact_token_limit

类型 / 值

number

详情

触发自动历史记录压缩的 Token 阈值（未设置则使用模型默认值）。

键

model_catalog_json

类型 / 值

string (path)

详情

启动时加载的可选 JSON 模型目录路径。所选的 $CODEX_HOME/profile-name.config.toml 配置文件可以按配置文件覆盖此设置。

键

model_context_window

类型 / 值

number

详情

活动模型可用的上下文窗口 Token 数。

键

model_instructions_file

类型 / 值

string (path)

详情

内置指令的替代项，而不是 AGENTS.md.

键

model_provider

类型 / 值

string

详情

提供者 ID 来自 model_providers (默认： openai).

键

model_providers.<id>

类型 / 值

table

详情

自定义提供者定义。内置提供者 ID（openai, ollama，且 lmstudio）已被保留，无法被覆盖。

键

model_providers.<id>.auth

类型 / 值

table

详情

自定义提供者的命令支持的 Bearer 令牌配置。请勿与 env_key, experimental_bearer_token, or requires_openai_auth.

键

model_providers.<id>.auth.args

类型 / 值

array<string>

详情

传递给令牌命令的参数。

键

model_providers.<id>.auth.command

类型 / 值

string

详情

当 Codex 需要 Bearer 令牌时运行的命令。该命令必须将令牌打印到标准输出。

键

model_providers.<id>.auth.cwd

类型 / 值

string (path)

详情

令牌命令的工作目录。

键

model_providers.<id>.auth.refresh_interval_ms

类型 / 值

number

详情

Codex 主动刷新令牌的频率，以毫秒为单位（默认值：300000）。设置为 0 仅在进行身份验证重试后刷新。

键

model_providers.<id>.auth.timeout_ms

类型 / 值

number

详情

令牌命令的最大运行时间，以毫秒为单位（默认值：5000）。

键

model_providers.<id>.base_url

类型 / 值

string

详情

模型提供者的 API 基础 URL。

键

model_providers.<id>.env_http_headers

类型 / 值

map<string,string>

详情

存在时从环境变量填充的 HTTP 请求头。

键

model_providers.<id>.env_key

类型 / 值

string

详情

提供提供者 API 密钥的环境变量。

键

model_providers.<id>.env_key_instructions

类型 / 值

string

详情

提供者 API 密钥的可选设置指南。

键

model_providers.<id>.experimental_bearer_token

类型 / 值

string

详情

提供者的直接 Bearer 令牌（不建议使用；请使用 env_key).

键

model_providers.<id>.http_headers

类型 / 值

map<string,string>

详情

添加到提供者请求中的静态 HTTP 请求头。

键

model_providers.<id>.name

类型 / 值

string

详情

自定义模型提供者的显示名称。

键

model_providers.<id>.query_params

类型 / 值

map<string,string>

详情

附加到提供者请求的额外查询参数。

键

model_providers.<id>.request_max_retries

类型 / 值

number

详情

向提供者发起的 HTTP 请求的重试次数（默认值：4）。

键

model_providers.<id>.requires_openai_auth

类型 / 值

boolean

详情

该提供者使用 OpenAI 身份验证（默认值：false）。

键

model_providers.<id>.stream_idle_timeout_ms

类型 / 值

number

详情

SSE 流的空闲超时时间，以毫秒为单位（默认值：300000）。

键

model_providers.<id>.stream_max_retries

类型 / 值

number

详情

SSE 流中断的重试次数（默认值：5）。

键

model_providers.<id>.supports_websockets

类型 / 值

boolean

详情

该提供者是否支持 Responses API WebSocket 传输协议。

键

model_providers.<id>.wire_api

类型 / 值

responses

详情

提供者使用的协议。 responses 是唯一支持的值，在省略时为默认值。

键

model_providers.amazon-bedrock.aws.profile

类型 / 值

string

详情

内置的所使用的 AWS 配置文件名称 amazon-bedrock provider.

键

model_providers.amazon-bedrock.aws.region

类型 / 值

string

详情

内置的所使用的 AWS 区域 amazon-bedrock provider.

键

model_reasoning_effort

类型 / 值

minimal | low | medium | high | xhigh

详情

调整支持的模型的推理工作量（仅限 Responses API； xhigh 取决于具体模型）。

键

model_reasoning_summary

类型 / 值

auto | concise | detailed | none

详情

选择推理摘要的详细程度或完全禁用摘要。

键

model_supports_reasoning_summaries

类型 / 值

boolean

详情

强制 Codex 发送或不发送推理元数据。

键

model_verbosity

类型 / 值

low | medium | high

详情

可选的 GPT-5 Responses API 冗余度覆盖；未设置时，将使用所选的模型/预设默认值。

键

notice.hide_full_access_warning

类型 / 值

boolean

详情

记录已确认完整访问警告提示。

键

notice.hide_gpt-5.1-codex-max_migration_prompt

类型 / 值

boolean

详情

记录已确认 gpt-5.1-codex-max 迁移提示。

键

notice.hide_gpt5_1_migration_prompt

类型 / 值

boolean

详情

记录已确认 GPT-5.1 迁移提示。

键

notice.hide_rate_limit_model_nudge

类型 / 值

boolean

详情

记录已选择退出速率限制模型切换提醒。

键

notice.hide_world_writable_warning

类型 / 值

boolean

详情

记录已确认 Windows 全局可写目录警告。

键

notice.model_migrations

类型 / 值

map<string,string>

详情

将已确认的模型迁移记录为 old->new 映射。

键

notify

类型 / 值

array<string>

详情

用于通知的调用命令；接收来自 Codex 的 JSON 负载。

键

openai_base_url

类型 / 值

string

详情

内置 openai 模型提供者的 Base URL 覆盖。

键

oss_provider

类型 / 值

lmstudio | ollama

详情

使用以下参数运行时使用的默认本地提供者 --oss （如未设置，默认为提示用户选择）。

键

otel.environment

类型 / 值

string

详情

应用于发出的 OpenTelemetry 事件的环境标签（默认： dev).

键

otel.exporter

类型 / 值

none | otlp-http | otlp-grpc

详情

选择 OpenTelemetry 导出器并提供相关端点元数据。

键

otel.exporter.<id>.endpoint

类型 / 值

string

详情

OTEL 日志的导出器端点。

键

otel.exporter.<id>.headers

类型 / 值

map<string,string>

详情

包含在 OTEL 导出器请求中的静态请求头。

键

otel.exporter.<id>.protocol

类型 / 值

binary | json

详情

OTLP/HTTP 导出器使用的协议。

键

otel.exporter.<id>.tls.ca-certificate

类型 / 值

string

详情

OTEL 导出器 TLS 的 CA 证书路径。

键

otel.exporter.<id>.tls.client-certificate

类型 / 值

string

详情

OTEL 导出器 TLS 的客户端证书路径。

键

otel.exporter.<id>.tls.client-private-key

类型 / 值

string

详情

OTEL 导出器 TLS 的客户端私钥路径。

键

otel.log_user_prompt

类型 / 值

boolean

详情

选择允许通过 OpenTelemetry 日志导出原始用户提示。

键

otel.metrics_exporter

类型 / 值

none | statsig | otlp-http | otlp-grpc

详情

选择 OpenTelemetry 指标导出器（默认为 statsig).

键

otel.trace_exporter

类型 / 值

none | otlp-http | otlp-grpc

详情

选择 OpenTelemetry 链路追踪导出器并提供相关端点元数据。

键

otel.trace_exporter.<id>.endpoint

类型 / 值

string

详情

OTEL 日志的链路追踪导出器端点。

键

otel.trace_exporter.<id>.headers

类型 / 值

map<string,string>

详情

包含在 OTEL 链路追踪导出器请求中的静态请求头。

键

otel.trace_exporter.<id>.protocol

类型 / 值

binary | json

详情

OTLP/HTTP 链路追踪导出器使用的协议。

键

otel.trace_exporter.<id>.tls.ca-certificate

类型 / 值

string

详情

OTEL 追踪导出器 TLS 的 CA 证书路径。

键

otel.trace_exporter.<id>.tls.client-certificate

类型 / 值

string

详情

OTEL 追踪导出器 TLS 的客户端证书路径。

键

otel.trace_exporter.<id>.tls.client-private-key

类型 / 值

string

详情

OTEL 追踪导出器 TLS 的客户端私钥路径。

键

permissions.<name>.description

类型 / 值

string

详情

此命名配置文件的可读描述。配置文件不会通过以下方式继承其父级的描述： extends.

键

permissions.<name>.extends

类型 / 值

string

详情

在此命名配置文件之前应用的可选父级配置文件。将其设置为另一个命名配置文件， :read-only, or :workspace; :danger-full-access,未定义的父级以及循环会被拒绝。

键

permissions.<name>.filesystem

类型 / 值

table

详情

命名的文件系统权限配置文件。每个键都是绝对路径或特殊令牌，例如 :minimal or :workspace_roots.

键

permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob>

类型 / 值

"read" | "write" | "deny"

详情

相对于每个有效工作区根目录的范围文件系统访问。使用 "." 用于根路径本身；glob 子路径，例如 "**/*.env" 可以使用以下方式拒绝读取操作 "deny".

键

permissions.<name>.filesystem.<path-or-glob>

类型 / 值

"read" | "write" | "deny" | table

详情

授予对某一路径、glob 模式或特殊令牌的直接访问权限，或者在根路径下限定嵌套条目的作用域。使用 "deny" 来拒绝匹配路径的读取操作。

键

permissions.<name>.filesystem.glob_scan_max_depth

类型 / 值

number

详情

在沙箱启动前快照匹配项的平台上，用于展开 deny-read glob 模式的最大深度。设置时必须至少为 1 设置时。

键

permissions.<name>.network.allow_local_binding

类型 / 值

boolean

详情

允许通过沙箱网络进行更广泛的本地/私网访问。精确的本地 IP 字面量或 localhost allow 规则仍可允许特定的本地目标，前提是此选项保持 false.

键

permissions.<name>.network.allow_upstream_proxy

类型 / 值

boolean

详情

允许沙盒网络连接通过另一上游代理进行链式传输。

键

permissions.<name>.network.dangerously_allow_all_unix_sockets

类型 / 值

boolean

详情

允许任意 Unix 套接字目标，而非默认的受限集合。仅在严格控制的环境中使用。

键

permissions.<name>.network.dangerously_allow_non_loopback_proxy

类型 / 值

boolean

详情

允许沙盒网络监听器绑定到非回环地址。启用此选项可能会将监听器暴露在 localhost 之外。

键

permissions.<name>.network.domains

类型 / 值

table

详情

沙盒网络的域规则。支持精确匹配的主机， *.example.com for subdomains only, **.example.com 表示顶级域及其子域，以及全局的 * 允许规则。 deny 规则为准。

键

permissions.<name>.network.domains.<pattern>

类型 / 值

allow | deny

详情

允许或拒绝精确的主机或限定范围的通配符模式，例如 *.example.com or **.example.com.

键

permissions.<name>.network.enable_socks5

类型 / 值

boolean

详情

当此权限配置文件启用沙盒网络时，暴露 SOCKS5 支持。

键

permissions.<name>.network.enable_socks5_udp

类型 / 值

boolean

详情

启用时允许通过 SOCKS5 监听器使用 UDP。

键

permissions.<name>.network.enabled

类型 / 值

boolean

详情

为此命名的权限配置文件启用网络访问。这会更改沙盒网络策略；其本身不会启动网络代理。

键

permissions.<name>.network.mode

类型 / 值

limited | full

详情

用于子进程流量的网络代理模式。

键

permissions.<name>.network.proxy_url

类型 / 值

string

详情

当此权限配置文件启用沙盒网络时使用的 HTTP 监听器 URL。

键

permissions.<name>.network.socks_url

类型 / 值

string

详情

此权限配置文件使用的 SOCKS5 代理端点。

键

permissions.<name>.network.unix_sockets

类型 / 值

table

详情

沙盒网络的 Unix 套接字允许列表覆盖。使用套接字路径作为键； allow 添加路径，并且 deny 拒绝该路径。

键

permissions.<name>.network.unix_sockets.<path>

类型 / 值

allow | deny

详情

将绝对 Unix 套接字路径添加到有效允许列表中，且 allow,或用以下方式拒绝它: deny。被拒绝的条目会从生效的允许列表中省略。

键

permissions.<name>.workspace_roots

类型 / 值

table

详情

与配置文件定义的工作区根目录一同接收 :workspace_roots 文件系统规则，同时包含会话的运行时工作区根目录。

键

permissions.<name>.workspace_roots.<path>

类型 / 值

boolean

详情

在以下情况时，将路径选择加入配置文件的工作区根目录集： true。已禁用的条目保持不活动状态。

键

personality

类型 / 值

none | friendly | pragmatic

详情

为声明了以下内容的模型设置默认通信风格： supportsPersonality;可以按线程/轮次覆盖,或通过 /personality.

键

plan_mode_reasoning_effort

类型 / 值

详情

Plan 模式专属推理覆盖设置。未设置时，Plan 模式将使用其内置的预设默认值。

键

plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode

类型 / 值

auto | prompt | approve

详情

插件提供的 MCP 服务器上各工具的默认批准行为。

键

plugins.<plugin>.mcp_servers.<server>.disabled_tools

类型 / 值

array<string>

详情

在以下内容之后应用的拒绝列表： enabled_tools 用于插件提供的 MCP 服务器。

键

plugins.<plugin>.mcp_servers.<server>.enabled

类型 / 值

boolean

详情

无需更改插件清单，即可启用或禁用由已安装插件捆绑的 MCP 服务器。

键

plugins.<plugin>.mcp_servers.<server>.enabled_tools

类型 / 值

array<string>

详情

从插件提供的 MCP 服务器中暴露的工具允许列表。

键

plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode

类型 / 值

auto | prompt | approve

详情

针对插件提供的 MCP 工具的单工具批准行为覆盖设置。

键

project_doc_fallback_filenames

类型 / 值

array<string>

详情

在缺少 AGENTS.md 时尝试读取的额外文件名。

键

project_doc_max_bytes

类型 / 值

number

详情

从中读取的最大字节数为 AGENTS.md （在构建项目指令时）。

键

project_root_markers

类型 / 值

array<string>

详情

项目根目录标记文件名列表；在向上搜索父目录以查找项目根目录时使用。

键

projects.<path>.trust_level

类型 / 值

string

详情

将项目或工作区标记为受信任或不受信任 ("trusted" | "untrusted")。不受信任的项目将跳过项目范围的 .codex/ 层，包括项目本地配置、钩子和规则。

键

review_model

类型 / 值

string

详情

使用的可选模型覆盖（ /review 默认为当前会话模型）。

键

sandbox_mode

类型 / 值

read-only | workspace-write | danger-full-access

详情

命令执行期间文件系统和网络访问的沙盒策略。

键

sandbox_workspace_write.exclude_slash_tmp

类型 / 值

boolean

详情

在工作区写入模式下，将 /tmp 从可写入根目录中排除。

键

sandbox_workspace_write.exclude_tmpdir_env_var

类型 / 值

boolean

详情

在工作区写入模式下，将 $TMPDIR 从可写入根目录中排除。

键

sandbox_workspace_write.network_access

类型 / 值

boolean

详情

允许工作区写入沙盒内的出站网络访问。

键

sandbox_workspace_write.writable_roots

类型 / 值

array<string>

详情

启用工作区写入模式时的额外可写入根目录。 sandbox_mode = "workspace-write".

键

service_tier

类型 / 值

string

详情

新轮次的首选服务层级。内置值包括 flex and fast；传统 fast 配置映射到请求值 priority,目录提供的层级 ID 也可以被存储。

键

shell_environment_policy.exclude

类型 / 值

array<string>

详情

在应用默认值后用于移除环境变量的 Glob 模式。

键

shell_environment_policy.experimental_use_profile

类型 / 值

boolean

详情

在启动子进程时使用用户 Shell 配置文件。

键

shell_environment_policy.ignore_default_excludes

类型 / 值

boolean

详情

在其他过滤器运行之前，保留包含 KEY/SECRET/TOKEN 的变量。

键

shell_environment_policy.include_only

类型 / 值

array<string>

详情

白名单模式；设置后仅保留匹配的变量。

键

shell_environment_policy.inherit

类型 / 值

all | core | none

详情

派生子进程时的基线环境继承。

键

shell_environment_policy.set

类型 / 值

map<string,string>

详情

注入到每个子进程的显式环境覆盖。

键

show_raw_agent_reasoning

类型 / 值

boolean

详情

在活动模型输出原始推理内容时将其展示。

键

skills.config

类型 / 值

array<object>

详情

存储在 config.toml 中的按技能启用的覆盖设置。

键

skills.config.<index>.enabled

类型 / 值

boolean

详情

启用或禁用引用的技能。

键

skills.config.<index>.path

类型 / 值

string (path)

详情

包含以下内容的技能文件夹路径 SKILL.md.

键

sqlite_home

类型 / 值

string (path)

详情

Codex 存储 SQLite 支持的状态数据库的目录，该数据库用于代理任务和其他可恢复的运行时状态。

键

suppress_unstable_features_warning

类型 / 值

boolean

详情

抑制启用开发中功能标记时出现的警告。

键

tool_output_token_limit

类型 / 值

number

详情

用于在历史记录中存储单个工具/函数输出的 Token 预算。

键

tool_suggest.disabled_tools

类型 / 值

array<table>

详情

禁用对特定可发现连接器或插件的建议。每个条目使用 type = "connector" or "plugin" and an id.

键

tool_suggest.discoverables

类型 / 值

array<table>

详情

允许对额外可发现连接器或插件提供工具建议。每个条目使用 type = "connector" or "plugin" and an id.

键

tools.view_image

类型 / 值

boolean

详情

启用本地图像附件工具 view_image.

键

tools.web_search

类型 / 值

boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }

详情

可选的网络搜索工具配置。仍接受旧版的布尔值格式，但对象格式允许您设置搜索上下文大小、允许的域以及用户的大致位置。

键

tui

类型 / 值

table

详情

特定于 TUI 的选项，例如启用内联桌面通知。

键

tui.alternate_screen

类型 / 值

auto | always | never

详情

控制 TUI 对备用屏幕的使用（默认值：auto；auto 模式下在 Zellij 中会跳过此设置以保留回滚历史）。

键

tui.animations

类型 / 值

boolean

详情

启用终端动画（欢迎屏幕、微光闪烁、加载动画）（默认值：true）。

键

tui.keymap.<context>.<action>

类型 / 值

string | array<string>

详情

TUI 操作的键盘快捷键绑定。支持的上下文包括 global, chat, composer, editor, pager, list，且 approval;特定上下文的绑定会覆盖 tui.keymap.global.

键

tui.keymap.<context>.<action> = []

类型 / 值

empty array

详情

在该按键映射上下文中解除操作绑定。按键名称使用规范化字符串，例如 ctrl-a, shift-enter, page-down, or minus.

键

tui.model_availability_nux.<model>

类型 / 值

integer

详情

按键为模型别名的内部启动提示状态。

键

tui.notification_condition

类型 / 值

unfocused | always

详情

控制 TUI 通知是仅在终端未聚焦时触发，还是无论聚焦状态如何均触发。默认值为 unfocused.

键

tui.notification_method

类型 / 值

auto | osc9 | bel

详情

终端通知的通知方式（默认值：auto）。

键

tui.notifications

类型 / 值

boolean | array<string>

详情

启用 TUI 通知；可选择限制为特定事件类型。

键

tui.raw_output_mode

类型 / 值

boolean

详情

以原始回滚模式启动 TUI，以便在终端中进行易于复制的文本选择（默认值：false）。您可以通过以下方式切换： /raw or the default alt-r 按键绑定。

键

tui.show_tooltips

类型 / 值

boolean

详情

在 TUI 欢迎屏幕中显示新手提示（默认值：true）。

键

tui.status_line

类型 / 值

array<string> | null

详情

TUI 底部状态栏项目标识符的有序列表。 null 禁用状态栏。

键

tui.terminal_title

类型 / 值

array<string> | null

详情

终端窗口/标签页标题项标识符的有序列表。默认为 ["spinner", "project"]; null 禁用标题更新。

键

tui.theme

类型 / 值

string

详情

语法高亮主题覆盖（使用 kebab-case 格式的主题名称）。

键

tui.vim_mode_default

类型 / 值

boolean

详情

在普通模式下启动 Vim 编辑器，而非插入模式（默认：false）。您仍然可以在每次会话中通过以下方式切换： /vim.

键

web_search

类型 / 值

disabled | cached | live

详情

网络搜索模式（默认： "cached";cached 使用由 OpenAI 维护的索引,不会抓取实时页面;如果你使用 --yolo 或其他完全访问权限的沙盒设置，它默认为 "live"）。使用 "live" 从网络获取最新数据，或者 "disabled" to remove the tool.

键

windows_wsl_setup_acknowledged

类型 / 值

boolean

详情

跟踪 Windows 引导确认（仅限 Windows）。

键

windows.sandbox

类型 / 值

unelevated | elevated

详情

在 Windows 上原生运行 Codex 时的专用原生沙盒模式。

键

windows.sandbox_private_desktop

类型 / 值

boolean

详情

在原生 Windows 上默认在私有桌面上运行最终受沙盒保护的子进程。设置 false 仅用于兼容较旧的 Winsta0\\Default behavior.

您可以在以下位置找到最新的 JSON schema config.toml 此处.

要在 VS Code 或 Cursor 中编辑 config.toml 时获得自动补全和诊断功能，您可以安装 Even Better TOML 扩展，并将以下行添加到您的 config.toml:

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

文件的顶部。注意：重命名 experimental_instructions_file to model_instructions_file。Codex 会弃用旧键;请将现有配置更新为新名称。

`requirements.toml`

requirements.toml 是由管理员强制执行的配置文件，用于限制用户无法覆盖的安全敏感设置。有关详细信息、文件位置和示例，请参阅管理员强制要求.

对于 ChatGPT Business 和 Enterprise 用户，Codex 还可以应用云端获取的需求。有关优先级的详细信息，请参阅安全页面。

使用 [features] in requirements.toml 用于固定特性标志，它使用与 config.toml 相同的规范键。省略的键将不受限制。

键	类型 / 值	详情
`allow_managed_hooks_only`	`boolean`	当 `true`,Codex 会跳过用户、项目、会话和插件钩子,同时仍允许来自以下来源的受管钩子: `requirements.toml` 和其他托管配置层。
`allowed_approval_policies`	`array<string>`	的允许值 `approval_policy` （当存在时）是由计量划分的多存储桶视图（例如 `untrusted`, `on-request`, `never`，且 `granular`).
`allowed_approvals_reviewers`	`array<string>`	的允许值 `approvals_reviewer`，例如 `user` and `auto_review`.
`allowed_sandbox_modes`	`array<string>`	的允许值 `sandbox_mode`.
`allowed_web_search_modes`	`array<string>`	的允许值 `web_search` (`disabled`, `cached`, `live`). `disabled` 始终被允许；空列表实际上仅允许 `disabled`.
`experimental_network`	`table`	从以下位置强制执行的网络访问要求 `requirements.toml`。这些约束独立于 `features.network_proxy` 并且无需用户特性标志即可配置受沙盒保护的网络。
`experimental_network.allow_local_binding`	`boolean`	允许受沙盒保护的网络访问更广泛的本地/专用网络。确切的本地 IP 字面量或 `localhost` allow 规则仍可允许特定的本地目标，前提是此选项保持 `false`.
`experimental_network.allow_upstream_proxy`	`boolean`	允许受沙盒保护的网络通过环境中的上游代理进行链式连接。
`experimental_network.allowed_domains`	`array<string>`	用于受沙盒保护的网络连接的列表形式管理员允许规则。请勿将此与 `experimental_network.domains`.
`experimental_network.dangerously_allow_all_unix_sockets`	`boolean`	允许任意 Unix 套接字目标，而不仅仅是仅限允许列表的访问。仅在严格控制的环境中使用。
`experimental_network.dangerously_allow_non_loopback_proxy`	`boolean`	允许非环回侦听器地址用于 `[experimental_network]` 需求。启用此选项可能会将侦听器暴露在 localhost 之外。
`experimental_network.denied_domains`	`array<string>`	沙盒网络的列表形式管理员拒绝规则。请勿与此选项结合使用： `experimental_network.domains`.
`experimental_network.domains`	`map<string, allow \| deny>`	沙盒网络的映射形式管理员域策略。支持精确的主机名， `.example.com` for subdomains only, `.example.com` 表示顶级域及其子域，以及全局的 `` allow 规则；优先使用限定范围的规则，因为 `*` 广泛开放公共出站访问。 `deny` 在发生冲突时优先。请勿与此选项结合使用： `experimental_network.allowed_domains` or `experimental_network.denied_domains`.
`experimental_network.enabled`	`boolean`	启用沙盒网络需求。当活跃沙盒保持命令网络关闭时，这并不会授予网络访问权限。
`experimental_network.http_port`	`integer`	要使用的环回 HTTP 侦听器端口，用于 `[experimental_network]` requirements.
`experimental_network.managed_allowed_domains_only`	`boolean`	当 `true`,当沙箱网络要求处于激活状态时,只有管理员管理的允许规则保持有效;用户添加的允许列表项会被忽略。没有受管允许规则时,用户添加的域名允许规则不会保持有效。
`experimental_network.socks_port`	`integer`	要使用的环回 SOCKS5 侦听器端口，用于 `[experimental_network]` requirements.
`experimental_network.unix_sockets`	`map<string, allow \| deny>`	管理员管理的沙盒网络 Unix 套接字策略。
`features`	`table`	通过以下项的规范名称作为键来锁定的功能值： `config.toml`'s `[features]` table.
`features.<name>`	`boolean`	要求特定的规范功能键保持启用或禁用状态。
`features.browser_use`	`boolean`	设置为 `false` in `requirements.toml` 以禁用浏览器使用和浏览器代理可用性。
`features.computer_use`	`boolean`	设置为 `false` in `requirements.toml` 以禁用计算机使用可用性及相关安装或启用流程。
`features.in_app_browser`	`boolean`	设置为 `false` in `requirements.toml` 以禁用应用内浏览器窗格。
`guardian_policy_config`	`string`	用于自动审查的受管 Markdown 策略指令。此设置优先于本地 `[auto_review].policy`。空值会被忽略。
`hooks`	`table`	管理员强制执行的受管生命周期钩子。需要受管钩子目录，并使用与内联相同的事件 schema `[hooks]` in `config.toml`.
`hooks.<Event>`	`array<table>`	钩子事件的匹配器组，例如 `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `SessionStart`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, or `Stop`.
`hooks.<Event>[].hooks`	`array<table>`	匹配器组的钩子处理程序。目前支持命令钩子;提示和智能体钩子处理程序会被解析但跳过。
`hooks.<Event>[].hooks[].commandWindows`	`string`	仅适用于 Windows 的命令钩子命令覆盖。TOML 别名 `command_windows` is also accepted.
`hooks.managed_dir`	`string (absolute path)`	在 macOS 和 Linux 上包含受管钩子脚本的目录。Codex 会在加载受管钩子之前验证该路径是否为绝对路径且确实存在。
`hooks.windows_managed_dir`	`string (absolute path)`	在 Windows 上包含受管钩子脚本的目录。Codex 会在加载受管钩子之前验证该路径是否为绝对路径且确实存在。
`mcp_servers`	`table`	允许启用的 MCP 服务器的白名单。服务器名称（`<id>`）及其身份必须均匹配，MCP 服务器才能被启用。任何未包含在白名单中（或身份不匹配）的已配置 MCP 服务器都将被禁用。
`mcp_servers.<id>.identity`	`table`	单个 MCP 服务器的身份验证规则。请设置 `command` (stdio) 或 `url` (streamable HTTP)。
`mcp_servers.<id>.identity.command`	`string`	当 MCP stdio 服务器的 `mcp_servers.<id>.command` 与此命令匹配时予以允许。
`mcp_servers.<id>.identity.url`	`string`	当 MCP streamable HTTP 服务器的 `mcp_servers.<id>.url` 与此 URL 匹配时予以允许。
`permissions.filesystem.deny_read`	`array<string>`	管理员强制执行的文件系统读取拒绝规则。条目可以是路径或 glob 模式，用户无法通过本地配置削弱此规则。
`plugin_sharing`	`boolean`	设置为 `false` in cloud-managed `requirements.toml` 以禁用本地构建插件的共享工作区功能。
`remote_sandbox_config`	`array<table>`	特定于主机的沙盒要求。第一个 `hostname_patterns` 与已解析的主机名匹配的条目将覆盖顶级 `allowed_sandbox_modes` 针对该要求源的设置。特定于主机的条目目前仅覆盖沙盒模式。
`remote_sandbox_config[].allowed_sandbox_modes`	`array<string>`	当此特定于主机的条目匹配时允许应用的沙盒模式。
`remote_sandbox_config[].hostname_patterns`	`array<string>`	不区分大小写的主机名模式。支持 `*` 匹配任意字符序列，以及 `?` for one character.
`rules`	`table`	管理员强制执行的命令规则与 `.rules` 文件合并。要求规则必须是限制性的。
`rules.prefix_rules`	`array<table>`	强制执行的前缀规则列表。每条规则必须包含 `pattern` and `decision`.
`rules.prefix_rules[].decision`	`prompt \| forbidden`	必填。要求规则只能提示或禁止（不允许）。
`rules.prefix_rules[].justification`	`string`	在批准提示或拒绝消息中显示的可选非空原因说明。
`rules.prefix_rules[].pattern`	`array<table>`	以模式标记表示的命令前缀。每个标记设置 `token` or `any_of`.
`rules.prefix_rules[].pattern[].any_of`	`array<string>`	在此位置允许的备用标记列表。
`rules.prefix_rules[].pattern[].token`	`string`	在此位置的单个字面标记。

键

allow_managed_hooks_only

类型 / 值

boolean

详情

当 true,Codex 会跳过用户、项目、会话和插件钩子,同时仍允许来自以下来源的受管钩子: requirements.toml 和其他托管配置层。

键

allowed_approval_policies

类型 / 值

array<string>

详情

的允许值 approval_policy （当存在时）是由计量划分的多存储桶视图（例如 untrusted, on-request, never，且 granular).

键

allowed_approvals_reviewers

类型 / 值

array<string>

详情

的允许值 approvals_reviewer，例如 user and auto_review.

键

allowed_sandbox_modes

类型 / 值

array<string>

详情

的允许值 sandbox_mode.

键

allowed_web_search_modes

类型 / 值

array<string>

详情

的允许值 web_search (disabled, cached, live). disabled 始终被允许；空列表实际上仅允许 disabled.

键

experimental_network

类型 / 值

table

详情

从以下位置强制执行的网络访问要求 requirements.toml。这些约束独立于 features.network_proxy 并且无需用户特性标志即可配置受沙盒保护的网络。

键

experimental_network.allow_local_binding

类型 / 值

boolean

详情

允许受沙盒保护的网络访问更广泛的本地/专用网络。确切的本地 IP 字面量或 localhost allow 规则仍可允许特定的本地目标，前提是此选项保持 false.

键

experimental_network.allow_upstream_proxy

类型 / 值

boolean

详情

允许受沙盒保护的网络通过环境中的上游代理进行链式连接。

键

experimental_network.allowed_domains

类型 / 值

array<string>

详情

用于受沙盒保护的网络连接的列表形式管理员允许规则。请勿将此与 experimental_network.domains.

键

experimental_network.dangerously_allow_all_unix_sockets

类型 / 值

boolean

详情

允许任意 Unix 套接字目标，而不仅仅是仅限允许列表的访问。仅在严格控制的环境中使用。

键

experimental_network.dangerously_allow_non_loopback_proxy

类型 / 值

boolean

详情

允许非环回侦听器地址用于 [experimental_network] 需求。启用此选项可能会将侦听器暴露在 localhost 之外。

键

experimental_network.denied_domains

类型 / 值

array<string>

详情

沙盒网络的列表形式管理员拒绝规则。请勿与此选项结合使用： experimental_network.domains.

键

experimental_network.domains

类型 / 值

map<string, allow | deny>

详情

沙盒网络的映射形式管理员域策略。支持精确的主机名， *.example.com for subdomains only, **.example.com 表示顶级域及其子域，以及全局的 * allow 规则；优先使用限定范围的规则，因为 * 广泛开放公共出站访问。 deny 在发生冲突时优先。请勿与此选项结合使用： experimental_network.allowed_domains or experimental_network.denied_domains.

键

experimental_network.enabled

类型 / 值

boolean

详情

启用沙盒网络需求。当活跃沙盒保持命令网络关闭时，这并不会授予网络访问权限。

键

experimental_network.http_port

类型 / 值

integer

详情

要使用的环回 HTTP 侦听器端口，用于 [experimental_network] requirements.

键

experimental_network.managed_allowed_domains_only

类型 / 值

boolean

详情

当 true,当沙箱网络要求处于激活状态时,只有管理员管理的允许规则保持有效;用户添加的允许列表项会被忽略。没有受管允许规则时,用户添加的域名允许规则不会保持有效。

键

experimental_network.socks_port

类型 / 值

integer

详情

要使用的环回 SOCKS5 侦听器端口，用于 [experimental_network] requirements.

键

experimental_network.unix_sockets

类型 / 值

map<string, allow | deny>

详情

管理员管理的沙盒网络 Unix 套接字策略。

键

features

类型 / 值

table

详情

通过以下项的规范名称作为键来锁定的功能值： config.toml's [features] table.

键

features.<name>

类型 / 值

boolean

详情

要求特定的规范功能键保持启用或禁用状态。

键

features.browser_use

类型 / 值

boolean

详情

设置为 false in requirements.toml 以禁用浏览器使用和浏览器代理可用性。

键

features.computer_use

类型 / 值

boolean

详情

设置为 false in requirements.toml 以禁用计算机使用可用性及相关安装或启用流程。

键

features.in_app_browser

类型 / 值

boolean

详情

设置为 false in requirements.toml 以禁用应用内浏览器窗格。

键

guardian_policy_config

类型 / 值

string

详情

用于自动审查的受管 Markdown 策略指令。此设置优先于本地 [auto_review].policy。空值会被忽略。

键

hooks

类型 / 值

table

详情

管理员强制执行的受管生命周期钩子。需要受管钩子目录，并使用与内联相同的事件 schema [hooks] in config.toml.

键

hooks.<Event>

类型 / 值

array<table>

详情

钩子事件的匹配器组，例如 PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, SubagentStart, SubagentStop, UserPromptSubmit, or Stop.

键

hooks.<Event>[].hooks

类型 / 值

array<table>

详情

匹配器组的钩子处理程序。目前支持命令钩子;提示和智能体钩子处理程序会被解析但跳过。

键

hooks.<Event>[].hooks[].commandWindows

类型 / 值

string

详情

仅适用于 Windows 的命令钩子命令覆盖。TOML 别名 command_windows is also accepted.

键

hooks.managed_dir

类型 / 值

string (absolute path)

详情

在 macOS 和 Linux 上包含受管钩子脚本的目录。Codex 会在加载受管钩子之前验证该路径是否为绝对路径且确实存在。

键

hooks.windows_managed_dir

类型 / 值

string (absolute path)

详情

在 Windows 上包含受管钩子脚本的目录。Codex 会在加载受管钩子之前验证该路径是否为绝对路径且确实存在。

键

mcp_servers

类型 / 值

table

详情

允许启用的 MCP 服务器的白名单。服务器名称（<id>）及其身份必须均匹配，MCP 服务器才能被启用。任何未包含在白名单中（或身份不匹配）的已配置 MCP 服务器都将被禁用。

键

mcp_servers.<id>.identity

类型 / 值

table

详情

单个 MCP 服务器的身份验证规则。请设置 command (stdio) 或 url (streamable HTTP)。

键

mcp_servers.<id>.identity.command

类型 / 值

string

详情

当 MCP stdio 服务器的 mcp_servers.<id>.command 与此命令匹配时予以允许。

键

mcp_servers.<id>.identity.url

类型 / 值

string

详情

当 MCP streamable HTTP 服务器的 mcp_servers.<id>.url 与此 URL 匹配时予以允许。

键

permissions.filesystem.deny_read

类型 / 值

array<string>

详情

管理员强制执行的文件系统读取拒绝规则。条目可以是路径或 glob 模式，用户无法通过本地配置削弱此规则。

键

plugin_sharing

类型 / 值

boolean

详情

设置为 false in cloud-managed requirements.toml 以禁用本地构建插件的共享工作区功能。

键

remote_sandbox_config

类型 / 值

array<table>

详情

特定于主机的沙盒要求。第一个 hostname_patterns 与已解析的主机名匹配的条目将覆盖顶级 allowed_sandbox_modes 针对该要求源的设置。特定于主机的条目目前仅覆盖沙盒模式。

键

remote_sandbox_config[].allowed_sandbox_modes

类型 / 值

array<string>

详情

当此特定于主机的条目匹配时允许应用的沙盒模式。

键

remote_sandbox_config[].hostname_patterns

类型 / 值

array<string>

详情

不区分大小写的主机名模式。支持 * 匹配任意字符序列，以及 ? for one character.

键

rules

类型 / 值

table

详情

管理员强制执行的命令规则与 .rules 文件合并。要求规则必须是限制性的。

键

rules.prefix_rules

类型 / 值

array<table>

详情

强制执行的前缀规则列表。每条规则必须包含 pattern and decision.

键

rules.prefix_rules[].decision

类型 / 值

prompt | forbidden

详情

必填。要求规则只能提示或禁止（不允许）。

键

rules.prefix_rules[].justification

类型 / 值

string

详情

在批准提示或拒绝消息中显示的可选非空原因说明。

键

rules.prefix_rules[].pattern

类型 / 值

array<table>

详情

以模式标记表示的命令前缀。每个标记设置 token or any_of.

键

rules.prefix_rules[].pattern[].any_of

类型 / 值

array<string>

详情

在此位置允许的备用标记列表。

键

rules.prefix_rules[].pattern[].token

类型 / 值

string

详情

在此位置的单个字面标记。

推荐

入门

核心概念

Apps SDK

工具

运行与扩展

评估

实时与音频

模型优化

专业模型

正式上线

旧版 API

资源

入门指南

使用 Codex

配置

管理

自动化

学习

发布

核心概念

规划

构建

部署

转化应用

指南

资源

指南

文件上传

API

衡量

广告主 API

API 参考

最新

主题

主题

贡献

分类

主题

项目

活动

config.toml

requirements.toml

`config.toml`

`requirements.toml`