配置参考资料 | ChatGPT Learn

本页提供可搜索的 Codex 配置文件参考资料。如需了解相关概念和示例，请先阅读基础配置和高级配置。

`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/config.toml 中，Codex 会忽略这些设置；请改为在用户级配置中设置提供商、通知和遥测配置键。配置方案文件与 config.toml 位于同一目录，路径为 $CODEX_HOME/profile-name.config.toml；使用 --profile profile-name 选择配置方案。

对于沙盒和审批配置键（approval_policy、sandbox_mode 和 sandbox_workspace_write.*），请结合沙盒与审批、可写根目录中的受保护路径以及网络访问阅读本参考资料。有关测试版权限配置方案，请参阅权限。

Key	Type / Values	Details
`agents`	`table`	多智能体设置和自定义角色声明。标量设置名称已被保留，不能用作自定义角色名称。
`agents.<name>.config_file`	`string (path)`	该角色对应的 TOML 配置层路径；相对路径以声明该角色的配置文件所在目录为基准解析。
`agents.<name>.description`	`string`	Codex 在选择并创建此类型的智能体时看到的角色指引。
`agents.default_subagent_model`	`string`	创建智能体时使用的默认模型。创建时显式指定的模型优先。
`agents.default_subagent_reasoning_effort`	`string`	创建智能体时使用的默认推理强度。创建时显式指定的推理强度优先。
`agents.enabled`	`boolean`	启用或禁用多智能体工具（默认值：true）。
`agents.interrupt_message`	`boolean`	智能体轮次中断时，记录一条对模型可见的消息（默认值：true）。
`agents.max_concurrent_threads_per_session`	`number`	可同时保持打开状态的已创建智能体线程数上限，不包括主线程。未设置时，由 Codex 选择默认值。
`agents.max_threads`	`number`	`agents.max_concurrent_threads_per_session` 的旧版别名。
`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`，非交互式运行请使用 `never`。
`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.approvals_reviewer`	`user \| auto_review`	应用工具审批提示的默认审查者；各应用可单独覆盖此设置。省略时，应用会继承顶层 `approvals_reviewer` 的值。
`apps._default.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	未设置按应用或按工具覆盖项时，应用工具的默认审批行为。
`apps._default.destructive_enabled`	`boolean`	对设置了 `destructive_hint = true` 的应用工具的默认允许或拒绝设置。
`apps._default.enabled`	`boolean`	所有应用的默认启用状态；各应用可单独覆盖此设置。
`apps._default.open_world_enabled`	`boolean`	对设置了 `open_world_hint = true` 的应用工具的默认允许或拒绝设置。
`apps.<id>.approvals_reviewer`	`user \| auto_review`	此应用工具审批提示的审查者。覆盖 `apps._default.approvals_reviewer`。
`apps.<id>.default_tools_approval_mode`	`auto \| prompt \| writes \| 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 \| writes \| 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` 键。
`chatgpt_base_url`	`string`	覆盖 ChatGPT 登录流程中使用的基础 URL。
`check_for_update_on_startup`	`boolean`	启动时检查 Codex 更新（仅当更新由集中管理时，才设为 false）。
`cli_auth_credentials_store`	`file \| keyring \| auto`	控制 CLI 缓存凭据的存储位置（auth.json 文件或操作系统密钥链）。
`compact_prompt`	`string`	历史记录压缩提示的内联覆盖项。
`computer_use.windows.always_allowed_app_ids`	`array<string>`	“计算机使用”无需提示即可打开的 Windows 应用的标识符。不在列表中的应用需要审批；请在 ChatGPT 桌面应用的“计算机使用”设置中移除已保存的条目。
`default_permissions`	`string`	应用于沙盒内工具调用的默认权限配置方案名称。内置配置方案为 `:read-only`、`:workspace` 和 `:danger-full-access`；自定义配置方案名称必须有相应的 `[permissions.<name>]` 表。请勿与 `sandbox_mode` 或 `[sandbox_workspace_write]` 同时使用。
`desktop.custom_file_handlers.<id>`	`table`	仅限用户级配置。为 ChatGPT 桌面应用定义额外的打开方式目标。有关示例和处理程序 ID 限制，请参阅添加自定义文件处理程序。
`desktop.custom_file_handlers.<id>.args`	`array<string>`	插入到命令与文件输入之间的参数（默认：`[]`）。
`desktop.custom_file_handlers.<id>.command`	`string`	要检测并启动的可执行文件路径或命令名称。必填。
`desktop.custom_file_handlers.<id>.icon`	`string`	处理程序图标的内置资源路径、采用 Base64 编码的 `data:image/...` URL、文件 URI 或本地绝对路径。必填；如果图标来源不受支持，则使用默认的 VS Code 图标。
`desktop.custom_file_handlers.<id>.input`	`path \| json_argument \| json_stdin`	应用向处理程序发送文件输入的方式（默认：`path`）。
`desktop.custom_file_handlers.<id>.label`	`string`	在打开方式菜单中显示的名称。必填。
`desktop.custom_file_handlers.<id>.supports_ssh`	`boolean`	为 SSH 工作空间中的文件提供该处理程序（默认：`false`）。
`developer_instructions`	`string`	注入会话的额外开发者指令（可选）。
`disable_paste_burst`	`boolean`	禁用 TUI 中的突发粘贴检测。
`experimental_compact_prompt_file`	`string (path)`	从文件加载压缩提示的覆盖内容（实验性）。
`experimental_use_unified_exec_tool`	`boolean`	用于启用统一执行的旧名称；请优先使用 `[features].unified_exec` 或 `codex --enable unified_exec`。
`features.apps`	`boolean`	启用应用（连接器）集成（稳定；默认启用）。应用和连接器的流量不受沙盒命令网络代理或其域名允许列表控制。
`features.code_mode.direct_only_tool_namespaces`	`array<string>`	代码模式中仅可通过直接工具调用使用的工具命名空间。
`features.code_mode.enabled`	`boolean`	启用代码模式功能配置。此功能仍在开发中，默认关闭。
`features.code_mode.excluded_tool_namespaces`	`array<string>`	代码模式在嵌套代码模式工具指引中排除、且不向执行器公开的工具命名空间。
`features.enable_request_compression`	`boolean`	在支持的情况下，使用 zstd 压缩流式请求体（稳定功能；默认开启）。
`features.fast_mode`	`boolean`	在 TUI 中启用模型目录中的服务层级选择功能，包括在当前模型声明支持时启用快速层级命令（稳定功能；默认开启）。
`features.goals`	`boolean`	启用目标持久化和自动继续功能（稳定功能；默认开启）。
`features.hooks`	`boolean`	启用从 `hooks.json` 或内联 `[hooks]` 配置加载的生命周期钩子。`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`	启动沙盒命令的网络代理（实验性功能；默认关闭）。要强制执行权限配置方案中的域名规则，必须启用此功能，除非通过已启用的管理员托管 `experimental_network` 要求启动代理。设置 `domains` 等功能级策略选项时，请使用表形式。该代理不会过滤网页搜索、应用、MCP 或其他托管工具。
`features.network_proxy.allow_local_binding`	`boolean`	允许更广泛地访问本地网络或私有网络。默认值为 `false`；精确匹配本地 IP 字面量或 `localhost` 的允许规则仍可放行特定本地目标。
`features.network_proxy.allow_upstream_proxy`	`boolean`	允许通过环境中指定的上游代理进行链式转发。默认值为 `true`。
`features.network_proxy.dangerously_allow_all_unix_sockets`	`boolean`	允许访问任意 Unix 套接字目标，而不是仅限允许列表中的目标。默认值为 `false`；请仅在严格受控的环境中使用。
`features.network_proxy.dangerously_allow_non_loopback_proxy`	`boolean`	允许使用非环回监听地址。默认值为 `false`；启用后，代理监听器可能会向 localhost 以外开放。
`features.network_proxy.domains`	`map<string, allow \| deny>`	沙盒网络的域名策略。默认未设置，这意味着在添加 `allow` 规则之前，不允许访问任何外部目标。支持精确主机匹配、仅匹配子域名的 `.example.com`、匹配根域名及其子域名的 `.example.com`，以及全局 `` 允许规则；建议优先使用限定范围的规则，因为 `*` 会广泛开放公网出站访问。添加 `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 套接字策略。默认未设置；请为允许使用的套接字添加 `allow` 条目。
`features.personality`	`boolean`	启用个性选择控件（稳定功能；默认开启）。
`features.prevent_idle_sleep`	`boolean`	在轮次运行期间阻止计算机进入睡眠状态（实验性功能；默认关闭）。
`features.remote_plugin`	`boolean`	启用远程插件目录（稳定功能；默认开启）。
`features.rollout_budget.enabled`	`boolean`	启用推演预算跟踪。此功能仍在开发中，默认关闭。启用后必须设置 `features.rollout_budget.limit_tokens`。
`features.rollout_budget.limit_tokens`	`integer`	用于推演预算跟踪的 Token 上限，必须为正数。启用推演预算时必填。
`features.rollout_budget.prefill_token_weight`	`number`	推演预算核算中预填充 Token 的乘数，必须为有限非负数。默认为 `1.0`。
`features.rollout_budget.reminder_interval_tokens`	`integer`	推演预算提醒之间的 Token 间隔，必须为正数。默认为 `limit_tokens` 的 10%，且至少为 1 个 Token。
`features.rollout_budget.sampling_token_weight`	`number`	推演预算核算中采样 Token 的乘数，必须为有限非负数。默认为 `1.0`。
`features.shell_snapshot`	`boolean`	创建 shell 环境快照，以加快重复命令的执行（稳定；默认启用）。
`features.shell_tool`	`boolean`	启用用于运行命令的默认 `shell` 工具（稳定功能；默认开启）。
`features.skill_mcp_dependency_install`	`boolean`	允许在技能缺少 MCP 依赖项时发出提示并安装这些依赖项（稳定功能；默认开启）。
`features.unified_exec`	`boolean`	使用基于 PTY 的统一 exec 工具（稳定；除 Windows 外默认启用）。
`features.web_search`	`boolean`	已弃用的旧版开关；请优先使用顶层 `web_search` 设置。
`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` 提交反馈（默认值：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` 输出中隐藏推理事件。
`history.max_bytes`	`number`	设置后，通过删除最早的条目，将历史记录文件大小限制在指定字节数以内。
`history.persistence`	`save-all \| none`	控制 Codex 是否将会话记录保存到 history.jsonl。
`hooks`	`table`	在 `config.toml` 中内联配置的生命周期钩子。采用与 `hooks.json` 相同的事件模式；示例和支持的事件请参阅钩子指南。
`hooks.<Event>`	`array<table>`	用于 `PreToolUse`、`PermissionRequest`、`PostToolUse`、`PreCompact`、`PostCompact`、`SessionStart`、`SessionEnd`、`SubagentStart`、`SubagentStop`、`UserPromptSubmit` 或 `Stop` 等钩子事件的匹配器组。
`hooks.<Event>[].hooks`	`array<table>`	匹配器组的钩子处理程序。支持命令钩子和 MCP 工具钩子；提示钩子和智能体钩子处理程序虽会被解析，但会跳过执行。
`hooks.<Event>[].hooks[].additionalContextLimit`	`integer`	每个处理程序用于判定 `additionalContext` 过大的近似 Token 阈值。超过该阈值时，会将其保存到磁盘，并向模型显示较短的预览。默认为 `2500`；`0` 会将完整上下文直接传递给模型。请参阅大型钩子输出。
`hooks.<Event>[].hooks[].async`	`boolean`	在后台运行命令钩子，不延迟触发该钩子的操作。默认为 `false`；`SessionEnd` 始终同步运行。请参阅在后台运行钩子。
`hooks.<Event>[].hooks[].commandWindows`	`string`	命令钩子的 Windows 专用命令覆盖设置。也接受 TOML 别名 `command_windows`。
`instructions`	`string`	预留供将来使用；优先使用 `model_instructions_file` 或 `AGENTS.md`。
`log_dir`	`string (path)`	Codex 写入日志文件的目录；默认为 `$CODEX_HOME/log`。显式设置此项还会在该目录中启用需主动开启的纯文本 TUI 日志 `codex-tui.log`。
`mcp_oauth_callback_port`	`integer`	MCP OAuth 登录期间所用本地 HTTP 回调服务器的可选全局固定端口。特定服务器的 `oauth.callback_port` 优先。两者均未设置时，Codex 会绑定到操作系统选择的临时端口。
`mcp_oauth_callback_url`	`string`	MCP OAuth 登录的可选基础回调 URL，例如 devbox 入口 URL。如果授权服务器支持颁发者识别，新添加的预注册客户端会原样使用此 URL；未保存回调的现有客户端会附加特定于服务器的回调 ID。如果不支持颁发者识别，任何预注册的 MCP 服务器只要其配置的回调缺少所需 ID，就会回退为使用附加了该 ID 的此 URL。回调 URL 中的端口不会决定监听端口。
`mcp_oauth_credentials_store`	`auto \| file \| keyring`	MCP OAuth 凭据的首选存储位置。
`mcp_servers.<id>.args`	`array<string>`	传递给 MCP stdio 服务器命令的参数。
`mcp_servers.<id>.auth`	`oauth \| chatgpt`	MCP HTTP 服务器的身份验证回退方式，优先级低于已配置的 Bearer Token 和授权标头。`oauth`（默认值）会在可用时使用已存储的 MCP OAuth 凭据。`chatgpt` 会针对受信任的第一方 ChatGPT 源站使用当前 ChatGPT 会话，然后回退到已存储的 OAuth 凭据。若无法从任何来源获取凭据，这两种模式都可在不进行身份验证的情况下连接。
`mcp_servers.<id>.bearer_token_env_var`	`string`	为 MCP HTTP 服务器提供 Bearer Token 的环境变量。
`mcp_servers.<id>.command`	`string`	用于启动 MCP stdio 服务器的命令。
`mcp_servers.<id>.cwd`	`string`	MCP stdio 服务器进程的工作目录。
`mcp_servers.<id>.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	此服务器上 MCP 工具的默认审批行为；如果存在针对单个工具的覆盖设置，则以该设置为准。
`mcp_servers.<id>.disabled_tools`	`array<string>`	在 `enabled_tools` 之后应用于 MCP 服务器的拒绝列表。
`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 服务器；尚未实现 streamable 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>.oauth.callback_port`	`integer`	此 MCP 服务器的固定 OAuth 回调监听端口。覆盖 `mcp_oauth_callback_port`。对于 URL 中明确指定了端口的直接回环回调，请将监听端口设为相同的端口。
`mcp_servers.<id>.oauth.callback_url`	`string`	此服务器专用的 OAuth 回调地址。预先注册的客户端在支持签发者标识，或 URL 已以此服务器专用的回调 ID 结尾时，会复用该地址。否则，Codex 会使用全局或默认回调地址，并在末尾附加该 ID。没有预先注册 ID 的客户端会在客户端注册时使用此回调地址。
`mcp_servers.<id>.oauth.client_id`	`string`	预先注册的 OAuth 客户端 ID，用于与此 MCP 服务器进行授权和 Token 交换。
`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` 别名。
`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 \| writes \| approve`	此服务器上单个 MCP 工具的审批行为覆盖设置。
`mcp_servers.<id>.url`	`string`	MCP streamable HTTP 服务器的端点。
`memories.consolidation_model`	`string`	用于全局记忆整合的可选模型覆盖设置。
`memories.disable_on_external_context`	`boolean`	设为 `true` 时，使用 MCP 工具调用、网页搜索或工具搜索等外部上下文的线程不会用于生成记忆。默认为 `false`。旧版别名：`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`，上限为 `4096`。
`memories.max_rollout_age_days`	`number`	用于生成记忆的线程距创建时间的最大时长。默认为 `30`，取值会被限制在 `0` 至 `90` 之间。
`memories.max_rollouts_per_startup`	`number`	每轮启动处理的推演候选项数量上限。默认为 `16`，上限为 `128`。
`memories.max_unused_days`	`number`	记忆自上次使用后仍可参与整合的最长天数。默认为 `30`，取值会被限制在 `0` 至 `365` 之间。
`memories.min_rate_limit_remaining_percent`	`number`	开始生成记忆前，Codex 速率限制窗口中所需的最低剩余百分比。默认为 `25`，取值会被限制在 `0` 至 `100` 之间。
`memories.min_rollout_idle_hours`	`number`	线程纳入记忆生成范围前所需的最短空闲时间。默认为 `6`，取值会被限制在 `1` 至 `48` 之间。
`memories.use_memories`	`boolean`	设为 `false` 时，Codex 不会将现有记忆注入后续会话。默认为 `true`。
`model`	`string`	要使用的模型（例如 `gpt-5.5`）。
`model_auto_compact_token_limit`	`number`	触发历史记录自动压缩的 Token 阈值（未设置时使用模型默认值）。
`model_auto_compact_token_limit_scope`	`total \| body_after_prefix`	控制自动压缩阈值是按完整的当前上下文计算（`total`，默认值），还是仅按沿用的压缩窗口前缀之后的增长量计算（`body_after_prefix`）。
`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`	来自 `model_providers` 的提供商 ID（默认值：`openai`）。
`model_providers.<id>`	`table`	自定义提供商的定义。内置提供商 ID（`openai`、`ollama` 和 `lmstudio`）为保留项，不能覆盖。
`model_providers.<id>.auth`	`table`	自定义提供商通过命令获取 Bearer Token 的配置。请勿与 `env_key`、`experimental_bearer_token` 或 `requires_openai_auth` 结合使用。
`model_providers.<id>.auth.args`	`array<string>`	传递给 Token 获取命令的参数。
`model_providers.<id>.auth.command`	`string`	Codex 需要 Bearer Token 时要运行的命令。该命令必须将 Token 输出到 stdout。
`model_providers.<id>.auth.cwd`	`string (path)`	Token 获取命令的工作目录。
`model_providers.<id>.auth.refresh_interval_ms`	`number`	Codex 主动刷新 Token 的间隔，单位为毫秒（默认值：300000）。设置为 `0` 后，仅在身份验证重试后刷新。
`model_providers.<id>.auth.timeout_ms`	`number`	Token 获取命令的最长运行时间，单位为毫秒（默认值：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 Token（不建议使用；请改用 `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_standalone_web_search`	`boolean`	声明支持兼容的独立网页搜索端点（默认值：false）。独立搜索仍在开发中，默认关闭；即使提供商兼容，也不会自动启用该功能。
`model_providers.<id>.supports_websockets`	`boolean`	该提供商是否支持 Responses API 的 WebSocket 传输方式。
`model_providers.<id>.wire_api`	`responses`	提供商使用的协议。`responses` 是唯一受支持的值，省略时也默认使用该值。
`model_providers.amazon-bedrock.aws.profile`	`string`	内置 `amazon-bedrock` 提供商使用的 AWS 配置方案名称。
`model_providers.amazon-bedrock.aws.region`	`string`	内置 `amazon-bedrock` 提供商使用的 AWS 区域。
`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` 模型提供商的基础 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` 或 `:workspace`；不允许使用 `:danger-full-access`、未定义的父配置方案或循环继承。
`permissions.<name>.filesystem`	`table`	命名的文件系统权限配置方案。每个键都是绝对路径或特殊 Token，例如 `:minimal` 或 `:workspace_roots`。
`permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob>`	`"read" \| "write" \| "deny"`	相对于每个生效的工作空间根目录设置的文件系统访问权限。使用 `"."` 表示根目录本身；对于 `"*/.env"` 等 glob 子路径，可使用 `"deny"` 拒绝读取。
`permissions.<name>.filesystem.<path-or-glob>`	`"read" \| "write" \| "deny" \| table`	为路径、glob 模式或特殊 Token 授予直接访问权限，或将嵌套条目的作用域限定在该根路径下。使用 `"deny"` 拒绝读取匹配的路径。
`permissions.<name>.filesystem.glob_scan_max_depth`	`number`	在沙盒启动前对匹配结果生成快照的平台上，展开拒绝读取的 glob 模式时所用的最大深度。如果设置此项，其值必须至少为 `1`。
`permissions.<name>.network.allow_local_binding`	`boolean`	允许沙盒网络更广泛地访问本地网络或私有网络。即使此项保持为 `false`，针对精确本地 IP 字面值或 `localhost` 的允许规则仍可允许访问特定本地目标。
`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`	沙盒命令的域名规则。仅当 `features.network_proxy` 或已启用的管理员管理的网络要求激活代理时，才会强制执行。支持精确匹配的主机、`.example.com`、`.example.com` 和全局 `` 允许规则；`deny` 优先。不限制网页搜索、应用或 MCP 服务器。
`permissions.<name>.network.domains.<pattern>`	`allow \| deny`	允许或拒绝精确匹配的主机，或 `.example.com`、`*.example.com` 等限定范围的通配符模式。
`permissions.<name>.network.enable_socks5`	`boolean`	此权限配置方案启用沙盒网络时提供 SOCKS5 支持。
`permissions.<name>.network.enable_socks5_udp`	`boolean`	启用后，允许通过 SOCKS5 监听器传输 UDP。
`permissions.<name>.network.enabled`	`boolean`	为此权限配置方案中的命令启用网络访问。此设置不会启动网络代理。如果既未启用 `features.network_proxy`，也未启用管理员管理的网络要求，命令将直接访问网络，且不会强制执行配置方案的域名规则。
`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`	使用 `allow` 将 Unix 套接字绝对路径添加到生效的允许列表，或使用 `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`	计划模式专用的推理强度覆盖值。未设置时，计划模式使用其内置预设的默认值。
`plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode`	`auto \| prompt \| writes \| approve`	插件提供的 MCP 服务器上各工具的默认审批行为。
`plugins.<plugin>.mcp_servers.<server>.disabled_tools`	`array<string>`	插件提供的 MCP 服务器的拒绝列表，在 `enabled_tools` 之后应用。
`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 \| writes \| 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`	在 workspace-write 模式下，将 `/tmp` 排除在可写根目录之外。
`sandbox_workspace_write.exclude_tmpdir_env_var`	`boolean`	在 workspace-write 模式下，将 `$TMPDIR` 排除在可写根目录之外。
`sandbox_workspace_write.network_access`	`boolean`	允许在 workspace-write 沙盒内进行出站网络访问。
`sandbox_workspace_write.writable_roots`	`array<string>`	当 `sandbox_mode = "workspace-write"` 时的额外可写根目录。
`service_tier`	`string`	新轮次的首选服务层级。请使用 `fast` 或当前模型声明支持的其他层级；`fast` 映射到请求值 `priority`。
`shell_environment_policy.exclude`	`array<string>`	旧版环境变量排除模式。新配置请使用 `shell_environment_policy.filters`；请勿在同一配置层中同时使用这两种形式。
`shell_environment_policy.experimental_use_profile`	`boolean`	启动子进程时使用用户的 shell 配置文件。
`shell_environment_policy.filters`	`map<string, include \| exclude>`	标准的环境变量模式筛选器，不区分大小写。包含规则会创建允许列表，但无法恢复已排除的值。显式指定的 `set` 值在排除操作后应用。请勿在同一配置层中将这些筛选器与旧版 `exclude` 或 `include_only` 数组混用。
`shell_environment_policy.ignore_default_excludes`	`boolean`	在其他筛选器运行前，保留名称中包含 KEY、SECRET 或 TOKEN 的变量（默认值：true）。设置为 false 后，会自动排除名称表明其包含机密信息的变量。
`shell_environment_policy.include_only`	`array<string>`	旧版环境变量模式允许列表。新配置请使用 `shell_environment_policy.filters`；请勿在同一配置层中同时使用这两种形式。
`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"` 或 `"plugin"`，并包含一个 `id`。
`tool_suggest.discoverables`	`array<table>`	允许针对其他可发现的连接器或插件提供工具建议。每个条目使用 `type = "connector"` 或 `"plugin"`，并包含一个 `id`。
`tools.view_image`	`boolean`	启用本地图像附件工具 `view_image`。
`tools.web_search`	`boolean \| { context_size = "low\|medium\|high", allowed_domains = [string], location = { country, region, city, timezone } }`	可选的网页搜索工具配置。对象形式可以设置搜索上下文大小、允许搜索的域名以及用户的大致位置。这些搜索域名过滤器与沙盒命令的网络域名规则彼此独立，也不会限制连接器或 MCP 服务器。
`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`、`vim_normal`、`vim_operator`、`vim_text_object`、`pager`、`list` 和 `approval`。部分编辑器操作会回退到匹配的 `tui.keymap.global` 绑定；如果支持特定上下文的绑定，则优先使用这些绑定。
`tui.keymap.<context>.<action> = []`	`empty array`	取消该操作在相应键位映射上下文中的绑定。按键名称使用规范化字符串，例如 `ctrl-a`、`shift-enter`、`page-down` 或 `minus`。
`tui.model_availability_nux.<model>`	`integer`	以模型 Slug 为键的内部启动提示状态。
`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` 或默认的 `alt-r` 按键绑定切换该模式。
`tui.resume_cwd`	`current \| session`	恢复或派生会话时使用的工作目录。未设置时，如果您当前的目录与会话中保存的目录不同，Codex 会提示您选择。
`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 \| indexed \| live`	网页搜索模式（默认：`"cached"`；cached 使用 OpenAI 维护的索引，不访问外部网页；indexed 仅在搜索索引允许的情况下进行外部访问；如果您使用 `--yolo` 或其他完全访问权限沙盒设置，则默认为 `"live"`）。使用 `"live"` 可进行不受限制的实时检索，使用 `"disabled"` 可移除该工具。
`windows_wsl_setup_acknowledged`	`boolean`	记录 Windows 新用户引导的确认状态（仅限 Windows）。
`windows.sandbox`	`unelevated \| elevated`	Codex 在 Windows 上原生运行时使用的 Windows 专用原生沙盒模式。
`windows.sandbox_private_desktop`	`boolean`	在原生 Windows 上，默认让最终的沙盒子进程在专用桌面上运行。仅当需要兼容旧版 `Winsta0\\Default` 行为时，才设为 `false`。

Key

agents

Type / Values

table

Details

多智能体设置和自定义角色声明。标量设置名称已被保留，不能用作自定义角色名称。

Key

agents.<name>.config_file

Type / Values

string (path)

Details

该角色对应的 TOML 配置层路径；相对路径以声明该角色的配置文件所在目录为基准解析。

Key

agents.<name>.description

Type / Values

string

Details

Codex 在选择并创建此类型的智能体时看到的角色指引。

Key

agents.default_subagent_model

Type / Values

string

Details

创建智能体时使用的默认模型。创建时显式指定的模型优先。

Key

agents.default_subagent_reasoning_effort

Type / Values

string

Details

创建智能体时使用的默认推理强度。创建时显式指定的推理强度优先。

Key

agents.enabled

Type / Values

boolean

Details

启用或禁用多智能体工具（默认值：true）。

Key

agents.interrupt_message

Type / Values

boolean

Details

智能体轮次中断时，记录一条对模型可见的消息（默认值：true）。

Key

agents.max_concurrent_threads_per_session

Type / Values

number

Details

可同时保持打开状态的已创建智能体线程数上限，不包括主线程。未设置时，由 Codex 选择默认值。

Key

agents.max_threads

Type / Values

number

Details

agents.max_concurrent_threads_per_session 的旧版别名。

Key

allow_login_shell

Type / Values

boolean

Details

允许基于 Shell 的工具采用登录 Shell 语义。默认为 true；设为 false 时，login = true 请求会被拒绝，省略 login 时则默认使用非登录 Shell。

Key

analytics.enabled

Type / Values

boolean

Details

启用或禁用此计算机或配置方案的分析功能。未设置时，采用客户端默认值。

Key

approval_policy

Type / Values

untrusted | on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } }

Details

控制 Codex 在执行命令前暂停并请求审批的时机。您还可以使用 approval_policy = { granular = { ... } }，允许显示或自动拒绝特定类别的提示，同时保留其他提示的交互方式。on-failure 已弃用；交互式运行请使用 on-request，非交互式运行请使用 never。

Key

approval_policy.granular.mcp_elicitations

Type / Values

boolean

Details

设为 true 时，允许显示 MCP 引导式提取提示，而不是自动拒绝。

Key

approval_policy.granular.request_permissions

Type / Values

boolean

Details

设为 true 时，允许显示来自 request_permissions 工具的提示。

Key

approval_policy.granular.rules

Type / Values

boolean

Details

设为 true 时，允许显示由 execpolicy 的 prompt 规则触发的审批提示。

Key

approval_policy.granular.sandbox_approval

Type / Values

boolean

Details

设为 true 时，允许显示沙盒权限提升审批提示。

Key

approval_policy.granular.skill_approval

Type / Values

boolean

Details

设为 true 时，允许显示技能脚本审批提示。

Key

approvals_reviewer

Type / Values

user | auto_review

Details

指定由谁审查 on-request 或细粒度审批策略下符合条件的审批提示。默认为 user；auto_review 使用审查子智能体。此设置不会改变沙盒机制，也不会审查沙盒内已获允许的操作。

Key

apps._default.approvals_reviewer

Type / Values

user | auto_review

Details

应用工具审批提示的默认审查者；各应用可单独覆盖此设置。省略时，应用会继承顶层 approvals_reviewer 的值。

Key

apps._default.default_tools_approval_mode

Type / Values

auto | prompt | writes | approve

Details

未设置按应用或按工具覆盖项时，应用工具的默认审批行为。

Key

apps._default.destructive_enabled

Type / Values

boolean

Details

对设置了 destructive_hint = true 的应用工具的默认允许或拒绝设置。

Key

apps._default.enabled

Type / Values

boolean

Details

所有应用的默认启用状态；各应用可单独覆盖此设置。

Key

apps._default.open_world_enabled

Type / Values

boolean

Details

对设置了 open_world_hint = true 的应用工具的默认允许或拒绝设置。

Key

apps.<id>.approvals_reviewer

Type / Values

user | auto_review

Details

此应用工具审批提示的审查者。覆盖 apps._default.approvals_reviewer。

Key

apps.<id>.default_tools_approval_mode

Type / Values

auto | prompt | writes | approve

Details

此应用中工具的默认审批行为；单个工具的覆盖设置优先。

Key

apps.<id>.default_tools_enabled

Type / Values

boolean

Details

此应用中工具的默认启用状态；单个工具的覆盖设置优先。

Key

apps.<id>.destructive_enabled

Type / Values

boolean

Details

允许或阻止此应用中声明 destructive_hint = true 的工具。

Key

apps.<id>.enabled

Type / Values

boolean

Details

按 ID 启用或禁用特定应用或连接器（默认值：true）。

Key

apps.<id>.open_world_enabled

Type / Values

boolean

Details

允许或阻止此应用中声明 open_world_hint = true 的工具。

Key

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

Type / Values

auto | prompt | writes | approve

Details

针对单个应用工具的审批行为覆盖项。

Key

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

Type / Values

boolean

Details

针对单个应用工具的启用状态覆盖项（例如 repos/list）。

Key

auto_review.policy

Type / Values

string

Details

自动审查所用的本地 Markdown 策略指令。受管理的 guardian_policy_config 优先级更高。空值会被忽略。

Key

background_terminal_max_timeout

Type / Values

number

Details

空 write_stdin 轮询（后台终端轮询）的最长等待时间，以毫秒为单位。默认值为 300000（5 分钟）。取代旧的 background_terminal_timeout 键。

Key

chatgpt_base_url

Type / Values

string

Details

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

Key

check_for_update_on_startup

Type / Values

boolean

Details

启动时检查 Codex 更新（仅当更新由集中管理时，才设为 false）。

Key

cli_auth_credentials_store

Type / Values

file | keyring | auto

Details

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

Key

compact_prompt

Type / Values

string

Details

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

Key

computer_use.windows.always_allowed_app_ids

Type / Values

array<string>

Details

“计算机使用”无需提示即可打开的 Windows 应用的标识符。不在列表中的应用需要审批；请在 ChatGPT 桌面应用的“计算机使用”设置中移除已保存的条目。

Key

default_permissions

Type / Values

string

Details

应用于沙盒内工具调用的默认权限配置方案名称。内置配置方案为 :read-only、:workspace 和 :danger-full-access；自定义配置方案名称必须有相应的 [permissions.<name>] 表。请勿与 sandbox_mode 或 [sandbox_workspace_write] 同时使用。

Key

desktop.custom_file_handlers.<id>

Type / Values

table

Details

仅限用户级配置。为 ChatGPT 桌面应用定义额外的打开方式目标。有关示例和处理程序 ID 限制，请参阅添加自定义文件处理程序。

Key

desktop.custom_file_handlers.<id>.args

Type / Values

array<string>

Details

插入到命令与文件输入之间的参数（默认：[]）。

Key

desktop.custom_file_handlers.<id>.command

Type / Values

string

Details

要检测并启动的可执行文件路径或命令名称。必填。

Key

desktop.custom_file_handlers.<id>.icon

Type / Values

string

Details

处理程序图标的内置资源路径、采用 Base64 编码的 data:image/... URL、文件 URI 或本地绝对路径。必填；如果图标来源不受支持，则使用默认的 VS Code 图标。

Key

desktop.custom_file_handlers.<id>.input

Type / Values

path | json_argument | json_stdin

Details

应用向处理程序发送文件输入的方式（默认：path）。

Key

desktop.custom_file_handlers.<id>.label

Type / Values

string

Details

在打开方式菜单中显示的名称。必填。

Key

desktop.custom_file_handlers.<id>.supports_ssh

Type / Values

boolean

Details

为 SSH 工作空间中的文件提供该处理程序（默认：false）。

Key

developer_instructions

Type / Values

string

Details

注入会话的额外开发者指令（可选）。

Key

disable_paste_burst

Type / Values

boolean

Details

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

Key

experimental_compact_prompt_file

Type / Values

string (path)

Details

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

Key

experimental_use_unified_exec_tool

Type / Values

boolean

Details

用于启用统一执行的旧名称；请优先使用 [features].unified_exec 或 codex --enable unified_exec。

Key

features.apps

Type / Values

boolean

Details

启用应用（连接器）集成（稳定；默认启用）。应用和连接器的流量不受沙盒命令网络代理或其域名允许列表控制。

Key

features.code_mode.direct_only_tool_namespaces

Type / Values

array<string>

Details

代码模式中仅可通过直接工具调用使用的工具命名空间。

Key

features.code_mode.enabled

Type / Values

boolean

Details

启用代码模式功能配置。此功能仍在开发中，默认关闭。

Key

features.code_mode.excluded_tool_namespaces

Type / Values

array<string>

Details

代码模式在嵌套代码模式工具指引中排除、且不向执行器公开的工具命名空间。

Key

features.enable_request_compression

Type / Values

boolean

Details

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

Key

features.fast_mode

Type / Values

boolean

Details

在 TUI 中启用模型目录中的服务层级选择功能，包括在当前模型声明支持时启用快速层级命令（稳定功能；默认开启）。

Key

features.goals

Type / Values

boolean

Details

启用目标持久化和自动继续功能（稳定功能；默认开启）。

Key

features.hooks

Type / Values

boolean

Details

启用从 hooks.json 或内联 [hooks] 配置加载的生命周期钩子。features.codex_hooks 是已弃用的别名。

Key

features.memories

Type / Values

boolean

Details

启用记忆（默认关闭）。

Key

features.multi_agent

Type / Values

boolean

Details

启用多智能体协作工具（spawn_agent、send_input、resume_agent、wait_agent 和 close_agent）（稳定；默认启用）。

Key

features.network_proxy

Type / Values

boolean | table

Details

启动沙盒命令的网络代理（实验性功能；默认关闭）。要强制执行权限配置方案中的域名规则，必须启用此功能，除非通过已启用的管理员托管 experimental_network 要求启动代理。设置 domains 等功能级策略选项时，请使用表形式。该代理不会过滤网页搜索、应用、MCP 或其他托管工具。

Key

features.network_proxy.allow_local_binding

Type / Values

boolean

Details

允许更广泛地访问本地网络或私有网络。默认值为 false；精确匹配本地 IP 字面量或 localhost 的允许规则仍可放行特定本地目标。

Key

features.network_proxy.allow_upstream_proxy

Type / Values

boolean

Details

允许通过环境中指定的上游代理进行链式转发。默认值为 true。

Key

features.network_proxy.dangerously_allow_all_unix_sockets

Type / Values

boolean

Details

允许访问任意 Unix 套接字目标，而不是仅限允许列表中的目标。默认值为 false；请仅在严格受控的环境中使用。

Key

features.network_proxy.dangerously_allow_non_loopback_proxy

Type / Values

boolean

Details

允许使用非环回监听地址。默认值为 false；启用后，代理监听器可能会向 localhost 以外开放。

Key

features.network_proxy.domains

Type / Values

map<string, allow | deny>

Details

沙盒网络的域名策略。默认未设置，这意味着在添加 allow 规则之前，不允许访问任何外部目标。支持精确主机匹配、仅匹配子域名的 *.example.com、匹配根域名及其子域名的 **.example.com，以及全局 * 允许规则；建议优先使用限定范围的规则，因为 * 会广泛开放公网出站访问。添加 deny 规则可阻止访问相应目标；发生冲突时以 deny 为准。

Key

features.network_proxy.enable_socks5

Type / Values

boolean

Details

提供 SOCKS5 支持。默认值为 true。

Key

features.network_proxy.enable_socks5_udp

Type / Values

boolean

Details

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

Key

features.network_proxy.enabled

Type / Values

boolean

Details

在启用命令网络访问时，启动沙盒命令的网络代理。默认值为 false；代理关闭时，不会强制执行权限配置方案中的域名规则。

Key

features.network_proxy.proxy_url

Type / Values

string

Details

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

Key

features.network_proxy.socks_url

Type / Values

string

Details

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

Key

features.network_proxy.unix_sockets

Type / Values

map<string, allow | deny>

Details

沙盒网络的 Unix 套接字策略。默认未设置；请为允许使用的套接字添加 allow 条目。

Key

features.personality

Type / Values

boolean

Details

启用个性选择控件（稳定功能；默认开启）。

Key

features.prevent_idle_sleep

Type / Values

boolean

Details

在轮次运行期间阻止计算机进入睡眠状态（实验性功能；默认关闭）。

Key

features.remote_plugin

Type / Values

boolean

Details

启用远程插件目录（稳定功能；默认开启）。

Key

features.rollout_budget.enabled

Type / Values

boolean

Details

启用推演预算跟踪。此功能仍在开发中，默认关闭。启用后必须设置 features.rollout_budget.limit_tokens。

Key

features.rollout_budget.limit_tokens

Type / Values

integer

Details

用于推演预算跟踪的 Token 上限，必须为正数。启用推演预算时必填。

Key

features.rollout_budget.prefill_token_weight

Type / Values

number

Details

推演预算核算中预填充 Token 的乘数，必须为有限非负数。默认为 1.0。

Key

features.rollout_budget.reminder_interval_tokens

Type / Values

integer

Details

推演预算提醒之间的 Token 间隔，必须为正数。默认为 limit_tokens 的 10%，且至少为 1 个 Token。

Key

features.rollout_budget.sampling_token_weight

Type / Values

number

Details

推演预算核算中采样 Token 的乘数，必须为有限非负数。默认为 1.0。

Key

features.shell_snapshot

Type / Values

boolean

Details

创建 shell 环境快照，以加快重复命令的执行（稳定；默认启用）。

Key

features.shell_tool

Type / Values

boolean

Details

启用用于运行命令的默认 shell 工具（稳定功能；默认开启）。

Key

features.skill_mcp_dependency_install

Type / Values

boolean

Details

允许在技能缺少 MCP 依赖项时发出提示并安装这些依赖项（稳定功能；默认开启）。

Key

features.unified_exec

Type / Values

boolean

Details

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

Key

features.web_search

Type / Values

boolean

Details

已弃用的旧版开关；请优先使用顶层 web_search 设置。

Key

features.web_search_cached

Type / Values

boolean

Details

已弃用的旧版开关。未设置 web_search 时，true 会映射为 web_search = "cached"。

Key

features.web_search_request

Type / Values

boolean

Details

已弃用的旧版开关。未设置 web_search 时，true 会映射为 web_search = "live"。

Key

feedback.enabled

Type / Values

boolean

Details

允许在所有本地客户端中通过 /feedback 提交反馈（默认值：true）。

Key

file_opener

Type / Values

vscode | vscode-insiders | windsurf | cursor | none

Details

用于打开 Codex 输出中引用内容的 URI 方案（默认：vscode）。

Key

forced_chatgpt_workspace_id

Type / Values

string (uuid)

Details

将 ChatGPT 登录限制在指定标识符所对应的工作空间内。

Key

forced_login_method

Type / Values

chatgpt | api

Details

将 Codex 限制为只能使用特定的身份验证方式。

Key

hide_agent_reasoning

Type / Values

boolean

Details

在 TUI 和 codex exec 输出中隐藏推理事件。

Key

history.max_bytes

Type / Values

number

Details

设置后，通过删除最早的条目，将历史记录文件大小限制在指定字节数以内。

Key

history.persistence

Type / Values

save-all | none

Details

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

Key

hooks

Type / Values

table

Details

在 config.toml 中内联配置的生命周期钩子。采用与 hooks.json 相同的事件模式；示例和支持的事件请参阅钩子指南。

Key

hooks.<Event>

Type / Values

array<table>

Details

用于 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SessionEnd、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop 等钩子事件的匹配器组。

Key

hooks.<Event>[].hooks

Type / Values

array<table>

Details

匹配器组的钩子处理程序。支持命令钩子和 MCP 工具钩子；提示钩子和智能体钩子处理程序虽会被解析，但会跳过执行。

Key

hooks.<Event>[].hooks[].additionalContextLimit

Type / Values

integer

Details

每个处理程序用于判定 additionalContext 过大的近似 Token 阈值。超过该阈值时，会将其保存到磁盘，并向模型显示较短的预览。默认为 2500；0 会将完整上下文直接传递给模型。请参阅大型钩子输出。

Key

hooks.<Event>[].hooks[].async

Type / Values

boolean

Details

在后台运行命令钩子，不延迟触发该钩子的操作。默认为 false；SessionEnd 始终同步运行。请参阅在后台运行钩子。

Key

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

Type / Values

string

Details

命令钩子的 Windows 专用命令覆盖设置。也接受 TOML 别名 command_windows。

Key

instructions

Type / Values

string

Details

预留供将来使用；优先使用 model_instructions_file 或 AGENTS.md。

Key

log_dir

Type / Values

string (path)

Details

Codex 写入日志文件的目录；默认为 $CODEX_HOME/log。显式设置此项还会在该目录中启用需主动开启的纯文本 TUI 日志 codex-tui.log。

Key

mcp_oauth_callback_port

Type / Values

integer

Details

MCP OAuth 登录期间所用本地 HTTP 回调服务器的可选全局固定端口。特定服务器的 oauth.callback_port 优先。两者均未设置时，Codex 会绑定到操作系统选择的临时端口。

Key

mcp_oauth_callback_url

Type / Values

string

Details

MCP OAuth 登录的可选基础回调 URL，例如 devbox 入口 URL。如果授权服务器支持颁发者识别，新添加的预注册客户端会原样使用此 URL；未保存回调的现有客户端会附加特定于服务器的回调 ID。如果不支持颁发者识别，任何预注册的 MCP 服务器只要其配置的回调缺少所需 ID，就会回退为使用附加了该 ID 的此 URL。回调 URL 中的端口不会决定监听端口。

Key

mcp_oauth_credentials_store

Type / Values

auto | file | keyring

Details

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

Key

mcp_servers.<id>.args

Type / Values

array<string>

Details

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

Key

mcp_servers.<id>.auth

Type / Values

oauth | chatgpt

Details

MCP HTTP 服务器的身份验证回退方式，优先级低于已配置的 Bearer Token 和授权标头。oauth（默认值）会在可用时使用已存储的 MCP OAuth 凭据。chatgpt 会针对受信任的第一方 ChatGPT 源站使用当前 ChatGPT 会话，然后回退到已存储的 OAuth 凭据。若无法从任何来源获取凭据，这两种模式都可在不进行身份验证的情况下连接。

Key

mcp_servers.<id>.bearer_token_env_var

Type / Values

string

Details

为 MCP HTTP 服务器提供 Bearer Token 的环境变量。

Key

mcp_servers.<id>.command

Type / Values

string

Details

用于启动 MCP stdio 服务器的命令。

Key

mcp_servers.<id>.cwd

Type / Values

string

Details

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

Key

mcp_servers.<id>.default_tools_approval_mode

Type / Values

auto | prompt | writes | approve

Details

此服务器上 MCP 工具的默认审批行为；如果存在针对单个工具的覆盖设置，则以该设置为准。

Key

mcp_servers.<id>.disabled_tools

Type / Values

array<string>

Details

在 enabled_tools 之后应用于 MCP 服务器的拒绝列表。

Key

mcp_servers.<id>.enabled

Type / Values

boolean

Details

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

Key

mcp_servers.<id>.enabled_tools

Type / Values

array<string>

Details

MCP 服务器所公开工具名称的允许列表。

Key

mcp_servers.<id>.env

Type / Values

map<string,string>

Details

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

Key

mcp_servers.<id>.env_http_headers

Type / Values

map<string,string>

Details

为 MCP HTTP 服务器从环境变量填充的 HTTP 标头。

Key

mcp_servers.<id>.env_vars

Type / Values

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

Details

要加入 MCP stdio 服务器允许列表的额外环境变量。字符串条目默认为 source = "local"；source = "remote" 仅用于通过执行器运行的远程 stdio。

Key

mcp_servers.<id>.experimental_environment

Type / Values

local | remote

Details

MCP 服务器的实验性运行位置设置。remote 会通过远程执行器环境启动 stdio 服务器；尚未实现 streamable HTTP 的远程运行。

Key

mcp_servers.<id>.http_headers

Type / Values

map<string,string>

Details

随每个 MCP HTTP 请求发送的静态 HTTP 标头。

Key

mcp_servers.<id>.oauth_resource

Type / Values

string

Details

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

Key

mcp_servers.<id>.oauth.callback_port

Type / Values

integer

Details

此 MCP 服务器的固定 OAuth 回调监听端口。覆盖 mcp_oauth_callback_port。对于 URL 中明确指定了端口的直接回环回调，请将监听端口设为相同的端口。

Key

mcp_servers.<id>.oauth.callback_url

Type / Values

string

Details

此服务器专用的 OAuth 回调地址。预先注册的客户端在支持签发者标识，或 URL 已以此服务器专用的回调 ID 结尾时，会复用该地址。否则，Codex 会使用全局或默认回调地址，并在末尾附加该 ID。没有预先注册 ID 的客户端会在客户端注册时使用此回调地址。

Key

mcp_servers.<id>.oauth.client_id

Type / Values

string

Details

预先注册的 OAuth 客户端 ID，用于与此 MCP 服务器进行授权和 Token 交换。

Key

mcp_servers.<id>.required

Type / Values

boolean

Details

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

Key

mcp_servers.<id>.scopes

Type / Values

array<string>

Details

对该 MCP 服务器进行身份验证时请求的 OAuth 作用域。

Key

mcp_servers.<id>.startup_timeout_ms

Type / Values

number

Details

以毫秒为单位的 startup_timeout_sec 别名。

Key

mcp_servers.<id>.startup_timeout_sec

Type / Values

number

Details

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

Key

mcp_servers.<id>.tool_timeout_sec

Type / Values

number

Details

覆盖 MCP 服务器中每个工具默认的 60 秒超时时间。

Key

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

Type / Values

auto | prompt | writes | approve

Details

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

Key

mcp_servers.<id>.url

Type / Values

string

Details

MCP streamable HTTP 服务器的端点。

Key

memories.consolidation_model

Type / Values

string

Details

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

Key

memories.disable_on_external_context

Type / Values

boolean

Details

设为 true 时，使用 MCP 工具调用、网页搜索或工具搜索等外部上下文的线程不会用于生成记忆。默认为 false。旧版别名：memories.no_memories_if_mcp_or_web_search。

Key

memories.extract_model

Type / Values

string

Details

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

Key

memories.generate_memories

Type / Values

boolean

Details

设为 false 时，新创建的线程不会被存储为记忆生成的输入。默认为 true。

Key

memories.max_raw_memories_for_consolidation

Type / Values

number

Details

为全局整合保留的近期原始记忆数量上限。默认为 256，上限为 4096。

Key

memories.max_rollout_age_days

Type / Values

number

Details

用于生成记忆的线程距创建时间的最大时长。默认为 30，取值会被限制在 0 至 90 之间。

Key

memories.max_rollouts_per_startup

Type / Values

number

Details

每轮启动处理的推演候选项数量上限。默认为 16，上限为 128。

Key

memories.max_unused_days

Type / Values

number

Details

记忆自上次使用后仍可参与整合的最长天数。默认为 30，取值会被限制在 0 至 365 之间。

Key

memories.min_rate_limit_remaining_percent

Type / Values

number

Details

开始生成记忆前，Codex 速率限制窗口中所需的最低剩余百分比。默认为 25，取值会被限制在 0 至 100 之间。

Key

memories.min_rollout_idle_hours

Type / Values

number

Details

线程纳入记忆生成范围前所需的最短空闲时间。默认为 6，取值会被限制在 1 至 48 之间。

Key

memories.use_memories

Type / Values

boolean

Details

设为 false 时，Codex 不会将现有记忆注入后续会话。默认为 true。

Key

model

Type / Values

string

Details

要使用的模型（例如 gpt-5.5）。

Key

model_auto_compact_token_limit

Type / Values

number

Details

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

Key

model_auto_compact_token_limit_scope

Type / Values

total | body_after_prefix

Details

控制自动压缩阈值是按完整的当前上下文计算（total，默认值），还是仅按沿用的压缩窗口前缀之后的增长量计算（body_after_prefix）。

Key

model_catalog_json

Type / Values

string (path)

Details

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

Key

model_context_window

Type / Values

number

Details

当前模型可用的上下文窗口 Token 数。

Key

model_instructions_file

Type / Values

string (path)

Details

用于替换内置指令，而非 AGENTS.md。

Key

model_provider

Type / Values

string

Details

来自 model_providers 的提供商 ID（默认值：openai）。

Key

model_providers.<id>

Type / Values

table

Details

自定义提供商的定义。内置提供商 ID（openai、ollama 和 lmstudio）为保留项，不能覆盖。

Key

model_providers.<id>.auth

Type / Values

table

Details

自定义提供商通过命令获取 Bearer Token 的配置。请勿与 env_key、experimental_bearer_token 或 requires_openai_auth 结合使用。

Key

model_providers.<id>.auth.args

Type / Values

array<string>

Details

传递给 Token 获取命令的参数。

Key

model_providers.<id>.auth.command

Type / Values

string

Details

Codex 需要 Bearer Token 时要运行的命令。该命令必须将 Token 输出到 stdout。

Key

model_providers.<id>.auth.cwd

Type / Values

string (path)

Details

Token 获取命令的工作目录。

Key

model_providers.<id>.auth.refresh_interval_ms

Type / Values

number

Details

Codex 主动刷新 Token 的间隔，单位为毫秒（默认值：300000）。设置为 0 后，仅在身份验证重试后刷新。

Key

model_providers.<id>.auth.timeout_ms

Type / Values

number

Details

Token 获取命令的最长运行时间，单位为毫秒（默认值：5000）。

Key

model_providers.<id>.base_url

Type / Values

string

Details

模型提供商的 API 基础 URL。

Key

model_providers.<id>.env_http_headers

Type / Values

map<string,string>

Details

存在相应环境变量时，使用其值填充的 HTTP 标头。

Key

model_providers.<id>.env_key

Type / Values

string

Details

提供商 API 密钥所在的环境变量。

Key

model_providers.<id>.env_key_instructions

Type / Values

string

Details

提供商 API 密钥的可选设置说明。

Key

model_providers.<id>.experimental_bearer_token

Type / Values

string

Details

直接指定的提供商 Bearer Token（不建议使用；请改用 env_key）。

Key

model_providers.<id>.http_headers

Type / Values

map<string,string>

Details

添加到提供商请求的静态 HTTP 标头。

Key

model_providers.<id>.name

Type / Values

string

Details

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

Key

model_providers.<id>.query_params

Type / Values

map<string,string>

Details

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

Key

model_providers.<id>.request_max_retries

Type / Values

number

Details

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

Key

model_providers.<id>.requires_openai_auth

Type / Values

boolean

Details

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

Key

model_providers.<id>.stream_idle_timeout_ms

Type / Values

number

Details

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

Key

model_providers.<id>.stream_max_retries

Type / Values

number

Details

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

Key

model_providers.<id>.supports_standalone_web_search

Type / Values

boolean

Details

声明支持兼容的独立网页搜索端点（默认值：false）。独立搜索仍在开发中，默认关闭；即使提供商兼容，也不会自动启用该功能。

Key

model_providers.<id>.supports_websockets

Type / Values

boolean

Details

该提供商是否支持 Responses API 的 WebSocket 传输方式。

Key

model_providers.<id>.wire_api

Type / Values

responses

Details

提供商使用的协议。responses 是唯一受支持的值，省略时也默认使用该值。

Key

model_providers.amazon-bedrock.aws.profile

Type / Values

string

Details

内置 amazon-bedrock 提供商使用的 AWS 配置方案名称。

Key

model_providers.amazon-bedrock.aws.region

Type / Values

string

Details

内置 amazon-bedrock 提供商使用的 AWS 区域。

Key

model_reasoning_effort

Type / Values

minimal | low | medium | high | xhigh

Details

调整受支持模型的推理强度（仅限 Responses API；xhigh 是否可用取决于模型）。

Key

model_reasoning_summary

Type / Values

auto | concise | detailed | none

Details

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

Key

model_supports_reasoning_summaries

Type / Values

boolean

Details

强制指定 Codex 是否发送推理元数据。

Key

model_verbosity

Type / Values

low | medium | high

Details

可选的 GPT-5 Responses API 输出详细程度覆盖值；未设置时，使用选定模型或预设的默认值。

Key

notice.hide_full_access_warning

Type / Values

boolean

Details

记录是否已确认完全访问权限警告提示。

Key

notice.hide_gpt-5.1-codex-max_migration_prompt

Type / Values

boolean

Details

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

Key

notice.hide_gpt5_1_migration_prompt

Type / Values

boolean

Details

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

Key

notice.hide_rate_limit_model_nudge

Type / Values

boolean

Details

记录是否已选择不再显示速率限制下的模型切换提醒。

Key

notice.hide_world_writable_warning

Type / Values

boolean

Details

记录是否已确认有关 Windows 目录对所有用户可写的警告。

Key

notice.model_migrations

Type / Values

map<string,string>

Details

以 old->new 映射的形式记录已确认的模型迁移。

Key

notify

Type / Values

array<string>

Details

发送通知时调用的命令；该命令接收来自 Codex 的 JSON 负载。

Key

openai_base_url

Type / Values

string

Details

内置 openai 模型提供商的基础 URL 覆盖项。

Key

oss_provider

Type / Values

lmstudio | ollama

Details

使用 --oss 运行时采用的默认本地提供商（未设置时，默认提示您选择）。

Key

otel.environment

Type / Values

string

Details

添加到所发出 OpenTelemetry 事件上的环境标签（默认：dev）。

Key

otel.exporter

Type / Values

none | otlp-http | otlp-grpc

Details

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

Key

otel.exporter.<id>.endpoint

Type / Values

string

Details

OTEL 日志的导出器端点。

Key

otel.exporter.<id>.headers

Type / Values

map<string,string>

Details

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

Key

otel.exporter.<id>.protocol

Type / Values

binary | json

Details

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

Key

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

Type / Values

string

Details

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

Key

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

Type / Values

string

Details

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

Key

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

Type / Values

string

Details

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

Key

otel.log_user_prompt

Type / Values

boolean

Details

选择将原始用户提示随 OpenTelemetry 日志一同导出。

Key

otel.metrics_exporter

Type / Values

none | statsig | otlp-http | otlp-grpc

Details

选择 OpenTelemetry 指标导出器（默认为 statsig）。

Key

otel.trace_exporter

Type / Values

none | otlp-http | otlp-grpc

Details

选择 OpenTelemetry 跟踪导出器并提供端点元数据。

Key

otel.trace_exporter.<id>.endpoint

Type / Values

string

Details

OTEL 日志的跟踪导出器端点。

Key

otel.trace_exporter.<id>.headers

Type / Values

map<string,string>

Details

OTEL 跟踪导出器请求中包含的静态标头。

Key

otel.trace_exporter.<id>.protocol

Type / Values

binary | json

Details

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

Key

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

Type / Values

string

Details

OTEL 跟踪导出器 TLS 使用的 CA 证书路径。

Key

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

Type / Values

string

Details

OTEL 跟踪导出器 TLS 使用的客户端证书路径。

Key

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

Type / Values

string

Details

OTEL 跟踪导出器 TLS 使用的客户端私钥路径。

Key

permissions.<name>.description

Type / Values

string

Details

此命名配置方案的文字说明。配置方案不会通过 extends 继承其父配置方案的说明。

Key

permissions.<name>.extends

Type / Values

string

Details

可选的父配置方案，在此命名配置方案之前应用。可将其设为另一个命名配置方案、:read-only 或 :workspace；不允许使用 :danger-full-access、未定义的父配置方案或循环继承。

Key

permissions.<name>.filesystem

Type / Values

table

Details

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

Key

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

Type / Values

"read" | "write" | "deny"

Details

相对于每个生效的工作空间根目录设置的文件系统访问权限。使用 "." 表示根目录本身；对于 "**/*.env" 等 glob 子路径，可使用 "deny" 拒绝读取。

Key

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

Type / Values

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

Details

为路径、glob 模式或特殊 Token 授予直接访问权限，或将嵌套条目的作用域限定在该根路径下。使用 "deny" 拒绝读取匹配的路径。

Key

permissions.<name>.filesystem.glob_scan_max_depth

Type / Values

number

Details

在沙盒启动前对匹配结果生成快照的平台上，展开拒绝读取的 glob 模式时所用的最大深度。如果设置此项，其值必须至少为 1。

Key

permissions.<name>.network.allow_local_binding

Type / Values

boolean

Details

允许沙盒网络更广泛地访问本地网络或私有网络。即使此项保持为 false，针对精确本地 IP 字面值或 localhost 的允许规则仍可允许访问特定本地目标。

Key

permissions.<name>.network.allow_upstream_proxy

Type / Values

boolean

Details

允许沙盒网络通过另一个上游代理进行链式转发。

Key

permissions.<name>.network.dangerously_allow_all_unix_sockets

Type / Values

boolean

Details

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

Key

permissions.<name>.network.dangerously_allow_non_loopback_proxy

Type / Values

boolean

Details

允许沙盒网络监听器绑定非环回地址。启用后，localhost 以外的主机可能也能访问这些监听器。

Key

permissions.<name>.network.domains

Type / Values

table

Details

沙盒命令的域名规则。仅当 features.network_proxy 或已启用的管理员管理的网络要求激活代理时，才会强制执行。支持精确匹配的主机、*.example.com、**.example.com 和全局 * 允许规则；deny 优先。不限制网页搜索、应用或 MCP 服务器。

Key

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

Type / Values

allow | deny

Details

允许或拒绝精确匹配的主机，或 *.example.com、**.example.com 等限定范围的通配符模式。

Key

permissions.<name>.network.enable_socks5

Type / Values

boolean

Details

此权限配置方案启用沙盒网络时提供 SOCKS5 支持。

Key

permissions.<name>.network.enable_socks5_udp

Type / Values

boolean

Details

启用后，允许通过 SOCKS5 监听器传输 UDP。

Key

permissions.<name>.network.enabled

Type / Values

boolean

Details

为此权限配置方案中的命令启用网络访问。此设置不会启动网络代理。如果既未启用 features.network_proxy，也未启用管理员管理的网络要求，命令将直接访问网络，且不会强制执行配置方案的域名规则。

Key

permissions.<name>.network.mode

Type / Values

limited | full

Details

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

Key

permissions.<name>.network.proxy_url

Type / Values

string

Details

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

Key

permissions.<name>.network.socks_url

Type / Values

string

Details

此权限配置方案使用的 SOCKS5 代理端点。

Key

permissions.<name>.network.unix_sockets

Type / Values

table

Details

沙盒网络的 Unix 套接字允许列表覆盖项。以套接字路径为键；allow 添加路径，deny 拒绝路径。

Key

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

Type / Values

allow | deny

Details

使用 allow 将 Unix 套接字绝对路径添加到生效的允许列表，或使用 deny 拒绝该路径。被拒绝的条目不会纳入生效的允许列表。

Key

permissions.<name>.workspace_roots

Type / Values

table

Details

配置方案定义的工作空间根目录。这些目录与会话的运行时工作空间根目录都适用 :workspace_roots 文件系统规则。

Key

permissions.<name>.workspace_roots.<path>

Type / Values

boolean

Details

为 true 时，将路径纳入该配置方案的工作空间根目录集合。已禁用的条目仍不生效。

Key

personality

Type / Values

none | friendly | pragmatic

Details

声明支持 supportsPersonality 的模型所使用的默认沟通风格；可按线程或轮次覆盖，也可通过 /personality 覆盖。

Key

plan_mode_reasoning_effort

Type / Values

Details

计划模式专用的推理强度覆盖值。未设置时，计划模式使用其内置预设的默认值。

Key

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

Type / Values

auto | prompt | writes | approve

Details

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

Key

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

Type / Values

array<string>

Details

插件提供的 MCP 服务器的拒绝列表，在 enabled_tools 之后应用。

Key

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

Type / Values

boolean

Details

在不更改插件清单的情况下，启用或禁用已安装插件附带的 MCP 服务器。

Key

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

Type / Values

array<string>

Details

插件提供的 MCP 服务器所公开工具的允许列表。

Key

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

Type / Values

auto | prompt | writes | approve

Details

插件提供的单个 MCP 工具的审批行为覆盖设置。

Key

project_doc_fallback_filenames

Type / Values

array<string>

Details

缺少 AGENTS.md 时要尝试的其他文件名。

Key

project_doc_max_bytes

Type / Values

number

Details

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

Key

project_root_markers

Type / Values

array<string>

Details

项目根目录标记文件名列表；在父目录中查找项目根目录时使用。

Key

projects.<path>.trust_level

Type / Values

string

Details

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

Key

review_model

Type / Values

string

Details

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

Key

sandbox_mode

Type / Values

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

Details

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

Key

sandbox_workspace_write.exclude_slash_tmp

Type / Values

boolean

Details

在 workspace-write 模式下，将 /tmp 排除在可写根目录之外。

Key

sandbox_workspace_write.exclude_tmpdir_env_var

Type / Values

boolean

Details

在 workspace-write 模式下，将 $TMPDIR 排除在可写根目录之外。

Key

sandbox_workspace_write.network_access

Type / Values

boolean

Details

允许在 workspace-write 沙盒内进行出站网络访问。

Key

sandbox_workspace_write.writable_roots

Type / Values

array<string>

Details

当 sandbox_mode = "workspace-write" 时的额外可写根目录。

Key

service_tier

Type / Values

string

Details

新轮次的首选服务层级。请使用 fast 或当前模型声明支持的其他层级；fast 映射到请求值 priority。

Key

shell_environment_policy.exclude

Type / Values

array<string>

Details

旧版环境变量排除模式。新配置请使用 shell_environment_policy.filters；请勿在同一配置层中同时使用这两种形式。

Key

shell_environment_policy.experimental_use_profile

Type / Values

boolean

Details

启动子进程时使用用户的 shell 配置文件。

Key

shell_environment_policy.filters

Type / Values

map<string, include | exclude>

Details

标准的环境变量模式筛选器，不区分大小写。包含规则会创建允许列表，但无法恢复已排除的值。显式指定的 set 值在排除操作后应用。请勿在同一配置层中将这些筛选器与旧版 exclude 或 include_only 数组混用。

Key

shell_environment_policy.ignore_default_excludes

Type / Values

boolean

Details

在其他筛选器运行前，保留名称中包含 KEY、SECRET 或 TOKEN 的变量（默认值：true）。设置为 false 后，会自动排除名称表明其包含机密信息的变量。

Key

shell_environment_policy.include_only

Type / Values

array<string>

Details

旧版环境变量模式允许列表。新配置请使用 shell_environment_policy.filters；请勿在同一配置层中同时使用这两种形式。

Key

shell_environment_policy.inherit

Type / Values

all | core | none

Details

启动子进程时的基础环境继承设置。

Key

shell_environment_policy.set

Type / Values

map<string,string>

Details

排除操作后显式注入的环境变量值；包含筛选器仍可移除这些值。

Key

show_raw_agent_reasoning

Type / Values

boolean

Details

当前模型输出原始推理内容时，将其显示出来。

Key

skills.config

Type / Values

array<object>

Details

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

Key

skills.config.<index>.enabled

Type / Values

boolean

Details

启用或禁用引用的技能。

Key

skills.config.<index>.path

Type / Values

string (path)

Details

包含 SKILL.md 的技能文件夹路径。

Key

sqlite_home

Type / Values

string (path)

Details

Codex 存储基于 SQLite 的状态数据库的目录；该数据库用于智能体作业及其他可恢复的运行时状态。

Key

suppress_unstable_features_warning

Type / Values

boolean

Details

不显示启用开发中功能标志时出现的警告。

Key

tool_output_token_limit

Type / Values

number

Details

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

Key

tool_suggest.disabled_tools

Type / Values

array<table>

Details

禁用针对特定可发现连接器或插件的建议。每个条目使用 type = "connector" 或 "plugin"，并包含一个 id。

Key

tool_suggest.discoverables

Type / Values

array<table>

Details

允许针对其他可发现的连接器或插件提供工具建议。每个条目使用 type = "connector" 或 "plugin"，并包含一个 id。

Key

tools.view_image

Type / Values

boolean

Details

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

Key

tools.web_search

Type / Values

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

Details

可选的网页搜索工具配置。对象形式可以设置搜索上下文大小、允许搜索的域名以及用户的大致位置。这些搜索域名过滤器与沙盒命令的网络域名规则彼此独立，也不会限制连接器或 MCP 服务器。

Key

tui

Type / Values

table

Details

TUI 专用选项，例如启用内嵌桌面通知。

Key

tui.alternate_screen

Type / Values

auto | always | never

Details

控制 TUI 是否使用备用屏幕（默认：auto；为保留滚动回溯记录，auto 在 Zellij 中不会使用备用屏幕）。

Key

tui.animations

Type / Values

boolean

Details

启用终端动画（欢迎屏幕、微光效果、旋转指示器）（默认：true）。

Key

tui.keymap.<context>.<action>

Type / Values

string | array<string>

Details

TUI 操作的键盘快捷键绑定。支持的上下文包括 global、chat、composer、editor、vim_normal、vim_operator、vim_text_object、pager、list 和 approval。部分编辑器操作会回退到匹配的 tui.keymap.global 绑定；如果支持特定上下文的绑定，则优先使用这些绑定。

Key

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

Type / Values

empty array

Details

取消该操作在相应键位映射上下文中的绑定。按键名称使用规范化字符串，例如 ctrl-a、shift-enter、page-down 或 minus。

Key

tui.model_availability_nux.<model>

Type / Values

integer

Details

以模型 Slug 为键的内部启动提示状态。

Key

tui.notification_condition

Type / Values

unfocused | always

Details

控制 TUI 通知是仅在终端失去焦点时触发，还是无论焦点状态如何都触发。默认为 unfocused。

Key

tui.notification_method

Type / Values

auto | osc9 | bel

Details

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

Key

tui.notifications

Type / Values

boolean | array<string>

Details

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

Key

tui.raw_output_mode

Type / Values

boolean

Details

以原始滚动回溯模式启动 TUI，便于在终端中选择并复制文本（默认：false）。您可以使用 /raw 或默认的 alt-r 按键绑定切换该模式。

Key

tui.resume_cwd

Type / Values

current | session

Details

恢复或派生会话时使用的工作目录。未设置时，如果您当前的目录与会话中保存的目录不同，Codex 会提示您选择。

Key

tui.show_tooltips

Type / Values

boolean

Details

在 TUI 欢迎屏幕中显示新用户引导提示（默认：true）。

Key

tui.status_line

Type / Values

array<string> | null

Details

TUI 底部状态行中各项标识符的有序列表。null 会禁用状态行。

Key

tui.terminal_title

Type / Values

array<string> | null

Details

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

Key

tui.theme

Type / Values

string

Details

语法高亮主题覆盖设置（主题名称采用 kebab-case 格式）。

Key

tui.vim_mode_default

Type / Values

boolean

Details

让编辑器启动时进入 Vim 普通模式，而不是插入模式（默认：false）。您仍可在各个会话中使用 /vim 切换。

Key

web_search

Type / Values

disabled | cached | indexed | live

Details

网页搜索模式（默认："cached"；cached 使用 OpenAI 维护的索引，不访问外部网页；indexed 仅在搜索索引允许的情况下进行外部访问；如果您使用 --yolo 或其他完全访问权限沙盒设置，则默认为 "live"）。使用 "live" 可进行不受限制的实时检索，使用 "disabled" 可移除该工具。

Key

windows_wsl_setup_acknowledged

Type / Values

boolean

Details

记录 Windows 新用户引导的确认状态（仅限 Windows）。

Key

windows.sandbox

Type / Values

unelevated | elevated

Details

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

Key

windows.sandbox_private_desktop

Type / Values

boolean

Details

在原生 Windows 上，默认让最终的沙盒子进程在专用桌面上运行。仅当需要兼容旧版 Winsta0\\Default 行为时，才设为 false。

您可以在此处找到 config.toml 的最新 JSON 模式。

在 VS Code 或 Cursor 中编辑 config.toml 时，如需使用自动补全和诊断功能，您可以安装 Even Better TOML 扩展程序，并在 config.toml 顶部添加下面这一行：

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

注意：请将 experimental_instructions_file 重命名为 model_instructions_file。Codex 已弃用旧键；请在现有配置中改用新名称。

`requirements.toml`

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

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

在 requirements.toml 中使用 [features]，通过与 config.toml 相同的规范键名固定运行时功能标志。要求中也可以包含文档列明的应用专用键，这些键不属于 config.toml。未指定的键仍不受约束。

部分托管要求会强制使用确切的配置值，而不是允许列表。用户无法覆盖强制指定的路径、更新偏好设置、登录 Shell 策略、反馈设置或 Windows 私有桌面设置。

托管权限配置方案允许列表需要 Codex 0.138.0 或更高版本。 Codex 0.137.0 及更早版本会忽略 allowed_permission_profiles 和托管的 default_permissions。

请将 allowed_sandbox_modes 与 sandbox_mode 配合使用。对于使用权限配置方案的部署，请将 allowed_permission_profiles 与托管的 default_permissions 配合使用。

[models.new_thread] 表提供托管默认值，而非强制设置。通过专用 CLI 标志或 --config 覆盖项显式指定的启动选项具有更高优先级。显式指定模型或推理强度覆盖项时，会跳过两个托管模型字段； service_tier 独立于这些字段。

Key	Type / Values	Details
`allow_appshots`	`boolean`	设为 `false` 可为受管理用户禁用应用快照。如果省略，应用快照不受要求配置限制，并遵循产品正常的可用性规则。
`allow_login_shell`	`boolean`	强制规定 Shell 工具是否可以启动登录 Shell。
`allow_managed_hooks_only`	`boolean`	设为 `true` 时，Codex 会跳过用户、项目、会话和插件钩子，但仍允许来自 `requirements.toml` 和其他托管配置层的托管钩子。
`allow_remote_control`	`boolean`	设为 `false` 可为受管理用户禁用设备远程控制。如果省略，设备远程控制不受要求配置限制，并遵循产品正常的可用性规则。
`allowed_approval_policies`	`array<string>`	`approval_policy` 的允许值（例如 `untrusted`、`on-request`、`never` 和 `granular`）。
`allowed_approvals_reviewers`	`array<string>`	`approvals_reviewer` 的允许值，例如 `user` 和 `auto_review`。
`allowed_permission_profiles`	`table<boolean>`	允许使用的权限配置方案的完整列表。设置为 `true` 的配置方案允许使用。未列出或设置为 `false` 的配置方案均禁止使用，包括未来版本中新增的配置方案。合并多个要求来源时，各条目按配置方案名称匹配。
`allowed_permission_profiles.<name>`	`boolean`	允许或拒绝已加载的配置或要求来源中定义的内置或自定义权限配置方案。较晚应用且优先级更高的要求来源可以使用 `false` 禁用较早且优先级较低的来源所允许的配置方案。
`allowed_sandbox_modes`	`array<string>`	`sandbox_mode` 的允许值。
`allowed_web_search_modes`	`array<string>`	`web_search` 的允许值（`disabled`、`cached`、`indexed`、`live`）。始终允许 `disabled`；空列表实际上只允许 `disabled`。
`apps`	`table`	以应用标识符为键的托管应用要求。这些要求可以禁用应用，也可以约束单个工具的审批行为。
`apps.<id>.enabled`	`boolean`	设为 `false` 可禁用应用。合并多个要求来源时，仍会保留禁用应用的限制。
`apps.<id>.tools.<tool>.approval_mode`	`auto \| prompt \| writes \| approve`	设置某个应用工具的托管审批模式。
`check_for_update_on_startup`	`boolean`	强制规定 Codex 启动时是否检查更新。
`computer_use`	`table`	由 `requirements.toml` 强制执行的计算机使用要求。
`computer_use.allow_locked_computer_use`	`boolean`	设为 `false` 可阻止计算机使用功能在受管理的 macOS 设备锁定后运行。如果省略，锁定后使用功能不受要求配置限制。
`default_permissions`	`string`	托管的默认权限配置方案。该配置方案必须在 `allowed_permission_profiles` 中获准使用。为确保行为可预测，请显式设置此项；如果省略此项，只有在 `:workspace` 和 `:read-only` 均被显式允许时，Codex 才会默认使用 `:workspace`。
`enforce_residency`	`string`	要求 Codex 服务流量使用受支持的数据驻留区域。目前接受 `us`。
`experimental_network`	`table`	适用于沙盒内本地命令的管理员托管网络要求，通过 `requirements.toml` 强制执行。启用后，这些要求可在未启用 `features.network_proxy` 的情况下启动命令网络代理。这些要求不控制网页搜索、应用、MCP 服务器、浏览器或 Codex 云端的网络访问。
`experimental_network.allow_local_binding`	`boolean`	允许沙盒网络更广泛地访问本地网络或私有网络。当此设置保持为 `false` 时，精确匹配本地 IP 字面量或 `localhost` 的允许规则仍可允许访问特定本地目标。
`experimental_network.allow_upstream_proxy`	`boolean`	允许沙盒网络串联使用环境中的上游代理。
`experimental_network.allowed_domains`	`array<string>`	托管网络代理启用期间，适用于沙盒命令联网的管理员允许规则。这些规则不适用于网页搜索、应用或 MCP 服务器。请勿与 `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`、同时匹配根域名及其子域名的 `.example.com`，以及全局 `` 允许规则；由于 `*` 会广泛开放公网出站访问，建议优先使用限定范围的规则。发生冲突时，`deny` 优先。请勿与 `experimental_network.allowed_domains` 或 `experimental_network.denied_domains` 一起使用。
`experimental_network.enabled`	`boolean`	启用沙盒网络要求。如果当前沙盒仍禁止命令联网，此设置不会授予网络访问权限。
`experimental_network.http_port`	`integer`	用于 `[experimental_network]` 要求的回环 HTTP 监听器端口。
`experimental_network.managed_allowed_domains_only`	`boolean`	设为 `true` 时，在沙盒网络要求生效期间，仅管理员托管的允许规则保持有效；用户添加的允许列表条目会被忽略。即使没有托管的允许规则，用户添加的域名允许规则也不会继续生效。
`experimental_network.socks_port`	`integer`	用于 `[experimental_network]` 要求的回环 SOCKS5 监听器端口。
`experimental_network.unix_sockets`	`map<string, allow \| deny>`	由管理员托管的沙盒网络 Unix 套接字策略。
`features`	`table`	固定的功能配置值。运行时功能应使用 `config.toml` 中的规范名称；此处也支持文档中列出的应用专属要求配置键。
`features.<name>`	`boolean`	要求文档中列出的运行时功能或应用功能保持启用或禁用状态。
`features.apps`	`boolean`	将受管理用户的应用集成功能固定为启用或禁用状态。
`features.browser_use`	`boolean`	在 `requirements.toml` 中设为 `false` 可禁用浏览器中的计算机使用功能，并使浏览器 Agent 不可用。
`features.browser_use_external`	`boolean`	在 `requirements.toml` 中设为 `false` 可禁用外部浏览器中的计算机使用功能。
`features.browser_use_full_cdp_access`	`boolean`	在 `requirements.toml` 中设为 `false` 可禁用本地运行时对 Chrome DevTools Protocol 的完整访问，包括浏览器开发者模式，并阻止 ChatGPT 桌面应用启用对应设置。如果省略，则遵循产品正常的可用性规则。
`features.computer_use`	`boolean`	在 `requirements.toml` 中设为 `false` 可禁用计算机使用、录制与重放以及相关的安装或启用流程。
`features.fast_mode`	`boolean`	对受管理用户，将规范名称为 `fast_mode` 的功能固定为启用或禁用状态。
`features.guardian_approval`	`boolean`	将受管理用户的 Guardian 审批功能固定为启用或禁用状态。
`features.in_app_browser`	`boolean`	在 `requirements.toml` 中设为 `false` 可禁用内置浏览器窗格。
`features.in_app_updates`	`boolean`	在 `requirements.toml` 中设为 `false` 可禁用应用内更新。如果省略此要求，更新默认保持启用。
`features.memories`	`boolean`	将受管理用户的记忆功能固定为启用或禁用状态。
`features.multi_agent`	`boolean`	将受管理用户的多智能体功能固定为启用或禁用状态。
`features.plugin_sharing`	`boolean`	在云端托管的 `requirements.toml` 中设为 `false`，可禁用在工作空间内共享本地构建插件的功能。
`features.plugins`	`boolean`	将受管理用户的插件功能固定为启用或禁用状态。
`features.remote_plugin`	`boolean`	将受管理用户的远程插件目录固定为启用或禁用状态。
`features.workspace_dependencies`	`boolean`	对受管理用户，将随附的工作空间依赖项运行时固定为启用或禁用状态。
`feedback`	`table`	托管反馈设置。
`feedback.enabled`	`boolean`	强制规定用户能否在各 Codex 客户端中提交反馈。
`guardian_policy_config`	`string`	用于自动审查的托管 Markdown 策略指令。其优先级高于本地的 `[auto_review].policy`。空白值将被忽略。
`hooks`	`table`	由管理员强制执行的托管生命周期钩子。需要托管钩子目录，并使用与 `config.toml` 中内联 `[hooks]` 相同的事件模式。
`hooks.<Event>`	`array<table>`	用于 `PreToolUse`、`PermissionRequest`、`PostToolUse`、`PreCompact`、`PostCompact`、`SessionStart`、`SessionEnd`、`SubagentStart`、`SubagentStop`、`UserPromptSubmit` 或 `Stop` 等钩子事件的匹配器组。
`hooks.<Event>[].hooks`	`array<table>`	匹配器组的钩子处理程序。支持命令钩子和 MCP 工具钩子；提示钩子和智能体钩子的处理程序会被解析，但会跳过执行。
`hooks.<Event>[].hooks[].additionalContextLimit`	`integer`	每个处理程序的近似 Token 阈值：当 `additionalContext` 超过此阈值时，会将其保存到磁盘，并向模型显示较短的预览。默认值为 `2500`；`0` 会将完整上下文直接传递给模型。请参阅较大的钩子输出。
`hooks.<Event>[].hooks[].async`	`boolean`	在后台运行命令钩子，不会延迟触发该钩子的操作。默认值为 `false`；`SessionEnd` 始终同步运行。请参阅在后台运行钩子。
`hooks.<Event>[].hooks[].commandWindows`	`string`	命令钩子的 Windows 专用命令覆盖项。也接受 TOML 别名 `command_windows`。
`hooks.managed_dir`	`string (absolute path)`	macOS 和 Linux 上包含托管钩子脚本的目录。Codex 会在加载托管钩子前验证目录路径是否为绝对路径，以及目录是否存在。
`hooks.windows_managed_dir`	`string (absolute path)`	Windows 上包含托管钩子脚本的目录。Codex 会在加载托管钩子前验证目录路径是否为绝对路径，以及目录是否存在。
`log_dir`	`string (path)`	强制指定 Codex 写入本地日志文件的目录。
`marketplaces`	`table`	针对插件市场来源的管理员要求。规则在 `restrict_to_allowed_sources` 为 `true` 时生效。
`marketplaces.allowed_sources`	`table`	允许的市场来源以管理员选定的规则名称为键。不同名称的规则会跨要求配置层累积；同名规则下的字段遵循常规的配置层优先级。
`marketplaces.allowed_sources.<name>`	`table`	一条允许来源的规则。要求配置合并后的最终 `source` 值决定 Codex 解读哪些同级字段。
`marketplaces.allowed_sources.<name>.host_pattern`	`string`	当 `source = "host_pattern"` 时必需的正则表达式。Codex 将其与从 HTTPS、SSH 或 SCP 样式的 Git 来源中解析出的小写主机名进行匹配。使用 `^` 和 `$` 可要求匹配完整的主机名。
`marketplaces.allowed_sources.<name>.path`	`string (absolute path)`	当 `source = "local"` 时必需的本地市场目录。Codex 要求使用绝对路径，并在规范化后比较路径。
`marketplaces.allowed_sources.<name>.ref`	`string`	`git` 规则中可选的精确 Git 引用。省略时，该规则允许所匹配代码仓库中的任意引用。
`marketplaces.allowed_sources.<name>.source`	`git \| host_pattern \| local`	市场来源匹配器的类型。使用 `git` 匹配单个代码仓库，使用 `host_pattern` 通过正则表达式匹配 Git 主机，或使用 `local` 匹配单个目录。
`marketplaces.allowed_sources.<name>.url`	`string`	当 `source = "git"` 时必需的 Git 代码仓库 URL。Codex 会先规范化已配置的 URL 和允许的 URL，然后要求代码仓库精确匹配。
`marketplaces.restrict_to_allowed_sources`	`boolean`	当值为 `true` 时，添加市场、安装插件以及刷新已配置的 Git 市场均要求用户配置的市场来源与 `allowed_sources` 匹配。由 Codex 管理的 OpenAI 市场在其保留来源和名称匹配时仍在允许范围内。此设置不会在运行时筛选已配置的用户市场。
`mcp_servers`	`table`	可启用的 MCP 服务器允许列表。只有服务器名称（`<id>`）和身份均匹配时，才能启用该 MCP 服务器。任何不在允许列表中的已配置 MCP 服务器，或身份不匹配的服务器，都会被禁用。
`mcp_servers.<id>.identity`	`table`	单个 MCP 服务器的身份规则。设置 `command`（stdio）或 `url`（streamable HTTP）其中之一。
`mcp_servers.<id>.identity.command`	`string \| table`	通过精确匹配命令字符串来允许 MCP stdio 服务器，或使用匹配器表，要求可执行文件完全匹配且参数按顺序匹配。字符串形式不会检查参数、`cwd`、`env` 或 `env_vars`。
`mcp_servers.<id>.identity.command.args`	`array<table>`	stdio 服务器的有序参数匹配器。配置的参数列表必须与匹配器列表长度相同，且每个位置都必须匹配。命令匹配器不会检查 `cwd`、`env` 或 `env_vars`。
`mcp_servers.<id>.identity.command.args[].expression`	`string`	`regex` 参数匹配器使用的正则表达式。表达式必须有效，并与完整的参数值匹配。
`mcp_servers.<id>.identity.command.args[].match`	`exact \| prefix \| regex`	此参数位置所用的匹配操作。
`mcp_servers.<id>.identity.command.args[].value`	`string`	`exact` 或 `prefix` 参数匹配器使用的值。
`mcp_servers.<id>.identity.command.executable`	`string`	stdio 服务器配置的 `command` 必须完全匹配的可执行文件。
`mcp_servers.<id>.identity.url`	`string \| table`	通过精确匹配 URL 字符串来允许 MCP streamable HTTP 服务器，或使用 `exact`、`prefix` 或 `regex` 值匹配器表。
`mcp_servers.<id>.identity.url.expression`	`string`	`regex` URL 匹配器使用的正则表达式。表达式必须有效，并与完整的 URL 值匹配。
`mcp_servers.<id>.identity.url.match`	`exact \| prefix \| regex`	已配置的 MCP 服务器 URL 所用的匹配操作。
`mcp_servers.<id>.identity.url.value`	`string`	`exact` 或 `prefix` URL 匹配器使用的值。
`model_catalog_json`	`string (path)`	强制指定 Codex 启动时使用的 JSON 模型目录。
`models`	`table`	新线程的托管模型默认值。这些值的优先级高于用户默认值和项目默认值，但为新线程显式选择的值可以覆盖它们。
`models.new_thread`	`table`	启动新的本地线程时应用的默认值。各项模型设置均为可选。
`models.new_thread.model`	`string`	新线程的默认模型。显式指定的 `--model` 或通过 `--config` 设置的模型或推理覆盖项具有更高优先级。
`models.new_thread.model_reasoning_effort`	`string`	新线程的默认推理强度。显式指定模型或推理强度覆盖项时，会跳过两个托管模型字段。
`models.new_thread.service_tier`	`string`	新线程的默认服务层级。显式指定的服务层级覆盖项具有更高优先级，且不受模型字段影响。
`permissions`	`table`	由管理员定义、以配置方案名称为键的权限配置方案。使用与 `config.toml` 相同的配置方案字段。
`permissions.<name>`	`table`	由管理员定义的权限配置方案。名称不能以 `:` 开头，不能使用保留名称 `filesystem`，也不能与已加载配置中的任何配置方案重名。使用与 `config.toml` 相同的配置方案字段；有关配置方案的完整模式，请参阅权限指南。
`permissions.filesystem.deny_read`	`array<string>`	由管理员强制执行的文件系统读取拒绝规则。条目可以是路径或 glob 模式，用户无法通过本地配置放宽这些规则。
`plugins`	`table`	以插件标识符为键的插件专属 MCP 服务器允许列表。存在此表时，如果缺少匹配的插件条目或服务器条目，插件随附的服务器就会被禁用。
`plugins.<plugin>.mcp_servers`	`table`	单个插件随附的 MCP 服务器允许列表。插件服务器要求采用与顶层 `mcp_servers` 要求相同的精确身份规则和匹配器形式。
`plugins.<plugin>.mcp_servers.<server>.identity`	`table`	插件随附的单个 MCP 服务器的身份规则。设置 `command`（stdio）或 `url`（streamable HTTP）其中之一。
`plugins.<plugin>.mcp_servers.<server>.identity.command`	`string \| table`	通过精确匹配命令字符串来允许插件的 stdio MCP 服务器，或使用匹配器表来要求可执行文件精确匹配，并按顺序应用参数匹配器。
`plugins.<plugin>.mcp_servers.<server>.identity.command.args`	`array<table>`	插件随附的 stdio 服务器的有序参数匹配器。配置的参数列表必须与匹配器列表长度相同，且每个位置都必须匹配。
`plugins.<plugin>.mcp_servers.<server>.identity.command.args[].expression`	`string`	`regex` 参数匹配器使用的正则表达式。该表达式必须匹配完整的参数值。
`plugins.<plugin>.mcp_servers.<server>.identity.command.args[].match`	`exact \| prefix \| regex`	此参数位置的匹配操作。
`plugins.<plugin>.mcp_servers.<server>.identity.command.args[].value`	`string`	`exact` 或 `prefix` 参数匹配器使用的值。
`plugins.<plugin>.mcp_servers.<server>.identity.command.executable`	`string`	插件随附的 stdio 服务器所配置的命令必须与此可执行文件精确匹配。
`plugins.<plugin>.mcp_servers.<server>.identity.url`	`string \| table`	通过精确匹配 URL 字符串来允许插件的流式 HTTP MCP 服务器，或使用 `exact`、`prefix` 或 `regex` 值匹配器表。
`plugins.<plugin>.mcp_servers.<server>.identity.url.expression`	`string`	`regex` URL 匹配器使用的正则表达式。该表达式必须匹配完整的 URL 值。
`plugins.<plugin>.mcp_servers.<server>.identity.url.match`	`exact \| prefix \| regex`	插件随附的 MCP 服务器 URL 的匹配操作。
`plugins.<plugin>.mcp_servers.<server>.identity.url.value`	`string`	`exact` 或 `prefix` URL 匹配器使用的值。
`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>`	不区分大小写的主机名模式。支持用 `*` 匹配任意字符序列，用 `?` 匹配单个字符。
`rules`	`table`	由管理员强制执行并与 `.rules` 文件合并的命令规则。要求配置中的规则必须具有限制性。
`rules.prefix_rules`	`array<table>`	强制执行的前缀规则列表。每条规则都必须包含 `pattern` 和 `decision`。
`rules.prefix_rules[].decision`	`prompt \| forbidden`	必填。要求配置中的规则只能请求审批或禁止操作，不能允许操作。
`rules.prefix_rules[].justification`	`string`	可选的非空理由，会显示在审批提示或拒绝消息中。
`rules.prefix_rules[].pattern`	`array<table>`	以模式 Token 表示的命令前缀。每个 Token 须设置 `token` 或 `any_of` 之一。
`rules.prefix_rules[].pattern[].any_of`	`array<string>`	此位置允许的备选 Token 列表。
`rules.prefix_rules[].pattern[].token`	`string`	此位置的单个字面量 Token。
`sqlite_home`	`string (path)`	强制指定 Codex 存储基于 SQLite 的运行时状态的目录。
`windows`	`table`	Windows 原生沙盒要求。
`windows.allowed_sandbox_implementations`	`array<string>`	允许用于 `windows.sandbox` 的 Windows 原生沙盒实现（`elevated` 和 `unelevated`）。列表不能为空。同时允许两者且未选择模式时，Codex 优先使用 `elevated`。
`windows.sandbox_private_desktop`	`boolean`	强制设定原生 Windows 沙盒是否在私有桌面上启动其子进程。

Key

allow_appshots

Type / Values

boolean

Details

设为 false 可为受管理用户禁用应用快照。如果省略，应用快照不受要求配置限制，并遵循产品正常的可用性规则。

Key

allow_login_shell

Type / Values

boolean

Details

强制规定 Shell 工具是否可以启动登录 Shell。

Key

allow_managed_hooks_only

Type / Values

boolean

Details

设为 true 时，Codex 会跳过用户、项目、会话和插件钩子，但仍允许来自 requirements.toml 和其他托管配置层的托管钩子。

Key

allow_remote_control

Type / Values

boolean

Details

设为 false 可为受管理用户禁用设备远程控制。如果省略，设备远程控制不受要求配置限制，并遵循产品正常的可用性规则。

Key

allowed_approval_policies

Type / Values

array<string>

Details

approval_policy 的允许值（例如 untrusted、on-request、never 和 granular）。

Key

allowed_approvals_reviewers

Type / Values

array<string>

Details

approvals_reviewer 的允许值，例如 user 和 auto_review。

Key

allowed_permission_profiles

Type / Values

table<boolean>

Details

允许使用的权限配置方案的完整列表。设置为 true 的配置方案允许使用。未列出或设置为 false 的配置方案均禁止使用，包括未来版本中新增的配置方案。合并多个要求来源时，各条目按配置方案名称匹配。

Key

allowed_permission_profiles.<name>

Type / Values

boolean

Details

允许或拒绝已加载的配置或要求来源中定义的内置或自定义权限配置方案。较晚应用且优先级更高的要求来源可以使用 false 禁用较早且优先级较低的来源所允许的配置方案。

Key

allowed_sandbox_modes

Type / Values

array<string>

Details

sandbox_mode 的允许值。

Key

allowed_web_search_modes

Type / Values

array<string>

Details

web_search 的允许值（disabled、cached、indexed、live）。始终允许 disabled；空列表实际上只允许 disabled。

Key

apps

Type / Values

table

Details

以应用标识符为键的托管应用要求。这些要求可以禁用应用，也可以约束单个工具的审批行为。

Key

apps.<id>.enabled

Type / Values

boolean

Details

设为 false 可禁用应用。合并多个要求来源时，仍会保留禁用应用的限制。

Key

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

Type / Values

auto | prompt | writes | approve

Details

设置某个应用工具的托管审批模式。

Key

check_for_update_on_startup

Type / Values

boolean

Details

强制规定 Codex 启动时是否检查更新。

Key

computer_use

Type / Values

table

Details

由 requirements.toml 强制执行的计算机使用要求。

Key

computer_use.allow_locked_computer_use

Type / Values

boolean

Details

设为 false 可阻止计算机使用功能在受管理的 macOS 设备锁定后运行。如果省略，锁定后使用功能不受要求配置限制。

Key

default_permissions

Type / Values

string

Details

托管的默认权限配置方案。该配置方案必须在 allowed_permission_profiles 中获准使用。为确保行为可预测，请显式设置此项；如果省略此项，只有在 :workspace 和 :read-only 均被显式允许时，Codex 才会默认使用 :workspace。

Key

enforce_residency

Type / Values

string

Details

要求 Codex 服务流量使用受支持的数据驻留区域。目前接受 us。

Key

experimental_network

Type / Values

table

Details

适用于沙盒内本地命令的管理员托管网络要求，通过 requirements.toml 强制执行。启用后，这些要求可在未启用 features.network_proxy 的情况下启动命令网络代理。这些要求不控制网页搜索、应用、MCP 服务器、浏览器或 Codex 云端的网络访问。

Key

experimental_network.allow_local_binding

Type / Values

boolean

Details

允许沙盒网络更广泛地访问本地网络或私有网络。当此设置保持为 false 时，精确匹配本地 IP 字面量或 localhost 的允许规则仍可允许访问特定本地目标。

Key

experimental_network.allow_upstream_proxy

Type / Values

boolean

Details

允许沙盒网络串联使用环境中的上游代理。

Key

experimental_network.allowed_domains

Type / Values

array<string>

Details

托管网络代理启用期间，适用于沙盒命令联网的管理员允许规则。这些规则不适用于网页搜索、应用或 MCP 服务器。请勿与 experimental_network.domains 一起使用。

Key

experimental_network.dangerously_allow_all_unix_sockets

Type / Values

boolean

Details

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

Key

experimental_network.dangerously_allow_non_loopback_proxy

Type / Values

boolean

Details

允许 [experimental_network] 要求使用非回环监听地址。启用后，可能会将监听器暴露到 localhost 之外。

Key

experimental_network.denied_domains

Type / Values

array<string>

Details

沙盒网络的管理员拒绝规则，采用列表形式。请勿与 experimental_network.domains 一起使用。

Key

experimental_network.domains

Type / Values

map<string, allow | deny>

Details

沙盒网络的管理员域名策略，采用映射形式。支持精确匹配主机、仅匹配子域名的 *.example.com、同时匹配根域名及其子域名的 **.example.com，以及全局 * 允许规则；由于 * 会广泛开放公网出站访问，建议优先使用限定范围的规则。发生冲突时，deny 优先。请勿与 experimental_network.allowed_domains 或 experimental_network.denied_domains 一起使用。

Key

experimental_network.enabled

Type / Values

boolean

Details

启用沙盒网络要求。如果当前沙盒仍禁止命令联网，此设置不会授予网络访问权限。

Key

experimental_network.http_port

Type / Values

integer

Details

用于 [experimental_network] 要求的回环 HTTP 监听器端口。

Key

experimental_network.managed_allowed_domains_only

Type / Values

boolean

Details

设为 true 时，在沙盒网络要求生效期间，仅管理员托管的允许规则保持有效；用户添加的允许列表条目会被忽略。即使没有托管的允许规则，用户添加的域名允许规则也不会继续生效。

Key

experimental_network.socks_port

Type / Values

integer

Details

用于 [experimental_network] 要求的回环 SOCKS5 监听器端口。

Key

experimental_network.unix_sockets

Type / Values

map<string, allow | deny>

Details

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

Key

features

Type / Values

table

Details

固定的功能配置值。运行时功能应使用 config.toml 中的规范名称；此处也支持文档中列出的应用专属要求配置键。

Key

features.<name>

Type / Values

boolean

Details

要求文档中列出的运行时功能或应用功能保持启用或禁用状态。

Key

features.apps

Type / Values

boolean

Details

将受管理用户的应用集成功能固定为启用或禁用状态。

Key

features.browser_use

Type / Values

boolean

Details

在 requirements.toml 中设为 false 可禁用浏览器中的计算机使用功能，并使浏览器 Agent 不可用。

Key

features.browser_use_external

Type / Values

boolean

Details

在 requirements.toml 中设为 false 可禁用外部浏览器中的计算机使用功能。

Key

features.browser_use_full_cdp_access

Type / Values

boolean

Details

在 requirements.toml 中设为 false 可禁用本地运行时对 Chrome DevTools Protocol 的完整访问，包括浏览器开发者模式，并阻止 ChatGPT 桌面应用启用对应设置。如果省略，则遵循产品正常的可用性规则。

Key

features.computer_use

Type / Values

boolean

Details

在 requirements.toml 中设为 false 可禁用计算机使用、录制与重放以及相关的安装或启用流程。

Key

features.fast_mode

Type / Values

boolean

Details

对受管理用户，将规范名称为 fast_mode 的功能固定为启用或禁用状态。

Key

features.guardian_approval

Type / Values

boolean

Details

将受管理用户的 Guardian 审批功能固定为启用或禁用状态。

Key

features.in_app_browser

Type / Values

boolean

Details

在 requirements.toml 中设为 false 可禁用内置浏览器窗格。

Key

features.in_app_updates

Type / Values

boolean

Details

在 requirements.toml 中设为 false 可禁用应用内更新。如果省略此要求，更新默认保持启用。

Key

features.memories

Type / Values

boolean

Details

将受管理用户的记忆功能固定为启用或禁用状态。

Key

features.multi_agent

Type / Values

boolean

Details

将受管理用户的多智能体功能固定为启用或禁用状态。

Key

features.plugin_sharing

Type / Values

boolean

Details

在云端托管的 requirements.toml 中设为 false，可禁用在工作空间内共享本地构建插件的功能。

Key

features.plugins

Type / Values

boolean

Details

将受管理用户的插件功能固定为启用或禁用状态。

Key

features.remote_plugin

Type / Values

boolean

Details

将受管理用户的远程插件目录固定为启用或禁用状态。

Key

features.workspace_dependencies

Type / Values

boolean

Details

对受管理用户，将随附的工作空间依赖项运行时固定为启用或禁用状态。

Key

feedback

Type / Values

table

Details

托管反馈设置。

Key

feedback.enabled

Type / Values

boolean

Details

强制规定用户能否在各 Codex 客户端中提交反馈。

Key

guardian_policy_config

Type / Values

string

Details

用于自动审查的托管 Markdown 策略指令。其优先级高于本地的 [auto_review].policy。空白值将被忽略。

Key

hooks

Type / Values

table

Details

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

Key

hooks.<Event>

Type / Values

array<table>

Details

Key

hooks.<Event>[].hooks

Type / Values

array<table>

Details

匹配器组的钩子处理程序。支持命令钩子和 MCP 工具钩子；提示钩子和智能体钩子的处理程序会被解析，但会跳过执行。

Key

hooks.<Event>[].hooks[].additionalContextLimit

Type / Values

integer

Details

每个处理程序的近似 Token 阈值：当 additionalContext 超过此阈值时，会将其保存到磁盘，并向模型显示较短的预览。默认值为 2500；0 会将完整上下文直接传递给模型。请参阅较大的钩子输出。

Key

hooks.<Event>[].hooks[].async

Type / Values

boolean

Details

在后台运行命令钩子，不会延迟触发该钩子的操作。默认值为 false；SessionEnd 始终同步运行。请参阅在后台运行钩子。

Key

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

Type / Values

string

Details

命令钩子的 Windows 专用命令覆盖项。也接受 TOML 别名 command_windows。

Key

hooks.managed_dir

Type / Values

string (absolute path)

Details

macOS 和 Linux 上包含托管钩子脚本的目录。Codex 会在加载托管钩子前验证目录路径是否为绝对路径，以及目录是否存在。

Key

hooks.windows_managed_dir

Type / Values

string (absolute path)

Details

Windows 上包含托管钩子脚本的目录。Codex 会在加载托管钩子前验证目录路径是否为绝对路径，以及目录是否存在。

Key

log_dir

Type / Values

string (path)

Details

强制指定 Codex 写入本地日志文件的目录。

Key

marketplaces

Type / Values

table

Details

针对插件市场来源的管理员要求。规则在 restrict_to_allowed_sources 为 true 时生效。

Key

marketplaces.allowed_sources

Type / Values

table

Details

允许的市场来源以管理员选定的规则名称为键。不同名称的规则会跨要求配置层累积；同名规则下的字段遵循常规的配置层优先级。

Key

marketplaces.allowed_sources.<name>

Type / Values

table

Details

一条允许来源的规则。要求配置合并后的最终 source 值决定 Codex 解读哪些同级字段。

Key

marketplaces.allowed_sources.<name>.host_pattern

Type / Values

string

Details

当 source = "host_pattern" 时必需的正则表达式。Codex 将其与从 HTTPS、SSH 或 SCP 样式的 Git 来源中解析出的小写主机名进行匹配。使用 ^ 和 $ 可要求匹配完整的主机名。

Key

marketplaces.allowed_sources.<name>.path

Type / Values

string (absolute path)

Details

当 source = "local" 时必需的本地市场目录。Codex 要求使用绝对路径，并在规范化后比较路径。

Key

marketplaces.allowed_sources.<name>.ref

Type / Values

string

Details

git 规则中可选的精确 Git 引用。省略时，该规则允许所匹配代码仓库中的任意引用。

Key

marketplaces.allowed_sources.<name>.source

Type / Values

git | host_pattern | local

Details

市场来源匹配器的类型。使用 git 匹配单个代码仓库，使用 host_pattern 通过正则表达式匹配 Git 主机，或使用 local 匹配单个目录。

Key

marketplaces.allowed_sources.<name>.url

Type / Values

string

Details

当 source = "git" 时必需的 Git 代码仓库 URL。Codex 会先规范化已配置的 URL 和允许的 URL，然后要求代码仓库精确匹配。

Key

marketplaces.restrict_to_allowed_sources

Type / Values

boolean

Details

当值为 true 时，添加市场、安装插件以及刷新已配置的 Git 市场均要求用户配置的市场来源与 allowed_sources 匹配。由 Codex 管理的 OpenAI 市场在其保留来源和名称匹配时仍在允许范围内。此设置不会在运行时筛选已配置的用户市场。

Key

mcp_servers

Type / Values

table

Details

可启用的 MCP 服务器允许列表。只有服务器名称（<id>）和身份均匹配时，才能启用该 MCP 服务器。任何不在允许列表中的已配置 MCP 服务器，或身份不匹配的服务器，都会被禁用。

Key

mcp_servers.<id>.identity

Type / Values

table

Details

单个 MCP 服务器的身份规则。设置 command（stdio）或 url（streamable HTTP）其中之一。

Key

mcp_servers.<id>.identity.command

Type / Values

string | table

Details

通过精确匹配命令字符串来允许 MCP stdio 服务器，或使用匹配器表，要求可执行文件完全匹配且参数按顺序匹配。字符串形式不会检查参数、cwd、env 或 env_vars。

Key

mcp_servers.<id>.identity.command.args

Type / Values

array<table>

Details

stdio 服务器的有序参数匹配器。配置的参数列表必须与匹配器列表长度相同，且每个位置都必须匹配。命令匹配器不会检查 cwd、env 或 env_vars。

Key

mcp_servers.<id>.identity.command.args[].expression

Type / Values

string

Details

regex 参数匹配器使用的正则表达式。表达式必须有效，并与完整的参数值匹配。

Key

mcp_servers.<id>.identity.command.args[].match

Type / Values

exact | prefix | regex

Details

此参数位置所用的匹配操作。

Key

mcp_servers.<id>.identity.command.args[].value

Type / Values

string

Details

exact 或 prefix 参数匹配器使用的值。

Key

mcp_servers.<id>.identity.command.executable

Type / Values

string

Details

stdio 服务器配置的 command 必须完全匹配的可执行文件。

Key

mcp_servers.<id>.identity.url

Type / Values

string | table

Details

通过精确匹配 URL 字符串来允许 MCP streamable HTTP 服务器，或使用 exact、prefix 或 regex 值匹配器表。

Key

mcp_servers.<id>.identity.url.expression

Type / Values

string

Details

regex URL 匹配器使用的正则表达式。表达式必须有效，并与完整的 URL 值匹配。

Key

mcp_servers.<id>.identity.url.match

Type / Values

exact | prefix | regex

Details

已配置的 MCP 服务器 URL 所用的匹配操作。

Key

mcp_servers.<id>.identity.url.value

Type / Values

string

Details

exact 或 prefix URL 匹配器使用的值。

Key

model_catalog_json

Type / Values

string (path)

Details

强制指定 Codex 启动时使用的 JSON 模型目录。

Key

models

Type / Values

table

Details

新线程的托管模型默认值。这些值的优先级高于用户默认值和项目默认值，但为新线程显式选择的值可以覆盖它们。

Key

models.new_thread

Type / Values

table

Details

启动新的本地线程时应用的默认值。各项模型设置均为可选。

Key

models.new_thread.model

Type / Values

string

Details

新线程的默认模型。显式指定的 --model 或通过 --config 设置的模型或推理覆盖项具有更高优先级。

Key

models.new_thread.model_reasoning_effort

Type / Values

string

Details

新线程的默认推理强度。显式指定模型或推理强度覆盖项时，会跳过两个托管模型字段。

Key

models.new_thread.service_tier

Type / Values

string

Details

新线程的默认服务层级。显式指定的服务层级覆盖项具有更高优先级，且不受模型字段影响。

Key

permissions

Type / Values

table

Details

由管理员定义、以配置方案名称为键的权限配置方案。使用与 config.toml 相同的配置方案字段。

Key

permissions.<name>

Type / Values

table

Details

由管理员定义的权限配置方案。名称不能以 : 开头，不能使用保留名称 filesystem，也不能与已加载配置中的任何配置方案重名。使用与 config.toml 相同的配置方案字段；有关配置方案的完整模式，请参阅权限指南。

Key

permissions.filesystem.deny_read

Type / Values

array<string>

Details

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

Key

plugins

Type / Values

table

Details

以插件标识符为键的插件专属 MCP 服务器允许列表。存在此表时，如果缺少匹配的插件条目或服务器条目，插件随附的服务器就会被禁用。

Key

plugins.<plugin>.mcp_servers

Type / Values

table

Details

单个插件随附的 MCP 服务器允许列表。插件服务器要求采用与顶层 mcp_servers 要求相同的精确身份规则和匹配器形式。

Key

plugins.<plugin>.mcp_servers.<server>.identity

Type / Values

table

Details

插件随附的单个 MCP 服务器的身份规则。设置 command（stdio）或 url（streamable HTTP）其中之一。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command

Type / Values

string | table

Details

通过精确匹配命令字符串来允许插件的 stdio MCP 服务器，或使用匹配器表来要求可执行文件精确匹配，并按顺序应用参数匹配器。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.args

Type / Values

array<table>

Details

插件随附的 stdio 服务器的有序参数匹配器。配置的参数列表必须与匹配器列表长度相同，且每个位置都必须匹配。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.args[].expression

Type / Values

string

Details

regex 参数匹配器使用的正则表达式。该表达式必须匹配完整的参数值。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.args[].match

Type / Values

exact | prefix | regex

Details

此参数位置的匹配操作。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.args[].value

Type / Values

string

Details

exact 或 prefix 参数匹配器使用的值。

Key

plugins.<plugin>.mcp_servers.<server>.identity.command.executable

Type / Values

string

Details

插件随附的 stdio 服务器所配置的命令必须与此可执行文件精确匹配。

Key

plugins.<plugin>.mcp_servers.<server>.identity.url

Type / Values

string | table

Details

通过精确匹配 URL 字符串来允许插件的流式 HTTP MCP 服务器，或使用 exact、prefix 或 regex 值匹配器表。

Key

plugins.<plugin>.mcp_servers.<server>.identity.url.expression

Type / Values

string

Details

regex URL 匹配器使用的正则表达式。该表达式必须匹配完整的 URL 值。

Key

plugins.<plugin>.mcp_servers.<server>.identity.url.match

Type / Values

exact | prefix | regex

Details

插件随附的 MCP 服务器 URL 的匹配操作。

Key

plugins.<plugin>.mcp_servers.<server>.identity.url.value

Type / Values

string

Details

exact 或 prefix URL 匹配器使用的值。

Key

remote_sandbox_config

Type / Values

array<table>

Details

主机专属沙盒要求。hostname_patterns 与解析得到的主机名匹配的第一个条目，会覆盖该要求配置来源中的顶层 allowed_sandbox_modes。主机专属条目目前仅覆盖沙盒模式。

Key

remote_sandbox_config[].allowed_sandbox_modes

Type / Values

array<string>

Details

此主机专属条目匹配时允许使用的沙盒模式。

Key

remote_sandbox_config[].hostname_patterns

Type / Values

array<string>

Details

不区分大小写的主机名模式。支持用 * 匹配任意字符序列，用 ? 匹配单个字符。

Key

rules

Type / Values

table

Details

由管理员强制执行并与 .rules 文件合并的命令规则。要求配置中的规则必须具有限制性。

Key

rules.prefix_rules

Type / Values

array<table>

Details

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

Key

rules.prefix_rules[].decision

Type / Values

prompt | forbidden

Details

必填。要求配置中的规则只能请求审批或禁止操作，不能允许操作。

Key

rules.prefix_rules[].justification

Type / Values

string

Details

可选的非空理由，会显示在审批提示或拒绝消息中。

Key

rules.prefix_rules[].pattern

Type / Values

array<table>

Details

以模式 Token 表示的命令前缀。每个 Token 须设置 token 或 any_of 之一。

Key

rules.prefix_rules[].pattern[].any_of

Type / Values

array<string>

Details

此位置允许的备选 Token 列表。

Key

rules.prefix_rules[].pattern[].token

Type / Values

string

Details

此位置的单个字面量 Token。

Key

sqlite_home

Type / Values

string (path)

Details

强制指定 Codex 存储基于 SQLite 的运行时状态的目录。

Key

windows

Type / Values

table

Details

Windows 原生沙盒要求。

Key

windows.allowed_sandbox_implementations

Type / Values

array<string>

Details

允许用于 windows.sandbox 的 Windows 原生沙盒实现（elevated 和 unelevated）。列表不能为空。同时允许两者且未选择模式时，Codex 优先使用 elevated。

Key

windows.sandbox_private_desktop

Type / Values

boolean

Details

强制设定原生 Windows 沙盒是否在私有桌面上启动其子进程。

建议

开始使用

Core concepts

SDKs and CLI

资源

Legacy APIs

Choose a model

Text and code

提示词

Reasoning

Images and video

Realtime and audio

Specialized models

Agents SDK

ChatKit

Search and retrieval

Connect tools and data

Build tool workflows

Computer and code

Media

开始使用

Audio

Connection methods

Sessions and operations

Go live

Performance and quality

Cost and throughput

Safety and governance

Infrastructure and access

运营

Core concepts

Plan

Build

Test and publish

Conversion specs

指南

资源

开始使用

指南

File Upload

API

Measurement

Advertiser API

API 参考

开始使用

基础

探索

可用平台

发布

工作流

能力

参考资料

自定义

配置文件

智能体配置

扩展 ChatGPT 和 Codex 的功能

Linux

Windows

开发工作流

扩展并实现自动化

环境

使用 Codex 构建

第三方集成

参考资料

权限

Codex Security

网络安全

入门

身份与身份验证

工作空间访问权限、策略和模型

插件和连接器控制

使用情况、治理与合规

部署和模型提供商

社区

博客

社区

博客

最近搜索

Topics

Topics

`config.toml`

`requirements.toml`