配置参考
Codex config.toml 和 requirements.toml 的完整参考
将此页面用作 Codex 配置文件的可搜索参考。如需概念指导和示例，请先参阅配置基础和高级配置。
通过 Work Cloud 访问本地计算机的设置
启用通过 Work Cloud 访问本地计算机的功能后，OpenAI 云端负责协调任务，受支持的工具则在云端或所连接的计算机上运行。要求用于设定限制；配置值用于提供默认值。
使用策略 API 管理 Global 设置。要管理 Local 或 Codex Cloud 设置，请使用 Agent Security 界面。迁移后，现有的 Global API 工作流仍然可用。请测试你的脚本和 Terraform 集成，并确认策略分配及排序保持不变。支持某个 requirements.toml 字段本身并不能证明 API 兼容性。
| 设置或设置类别 | 通过 Work Cloud 访问本地计算机时的作用域 | 指南 |
|---|---|---|
| 审批策略和评审要求 | 启用受管策略时的 Global 编排器策略 | 将审批和评审控制保留在 Global 中。环境覆盖设置无法更改编排器控制。本地执行与云容器执行具有各自独立的策略作用域。 |
| 受管应用、MCP server、插件、市场和命令规则 | Global 策略 | 将这些控制保留在全局作用域中。不要将字段出现在数据结构中视为可以按环境编辑该字段的证明。 |
| 文件、沙箱和可跨环境使用的网络要求 | 本地执行 | 对于本地执行，MDM 和旧版受管设备要求的优先级高于 Agent Security。设备的系统要求文件的优先级低于 Agent Security。新的企业 requirements.toml 配置不适用于 Work 云容器，后者保留现有的 Work Cloud 策略。 |
| 特定平台的执行器控制 | 运行该步骤的计算机 | 支持情况取决于执行器和平台。 |
| 受管钩子 | 启用后，管理员定义的 MCP 钩子会针对受支持的生命周期事件和工具事件在云端协调器（编排器）上运行。 | 在依赖这些钩子之前，请测试回调连接，确认其接收的事件，并检查失败会如何影响任务。MCP 钩子无法提供完整的 Compliance API 审计跟踪记录。云端编排不支持命令钩子、本地配置钩子和插件钩子，即使工具在本地执行也是如此。对于编排和执行均在本地进行的纯本地 Work 和 Codex 线程，现有的受支持钩子仍然适用。 |
| 代理监听地址、端口和进程设置 | 不属于可跨环境使用的环境策略 | 云端运行时不支持受管 HTTP/SOCKS 监听端口和非回环代理监听器；套接字规则的支持情况取决于执行路径。自定义代理配置与受支持的目标地址限制相互独立。 |
| 仅适用于应用的设置和普通本地默认值 | 云端协调不一定使用这些设置 | 即使通过 Work Cloud 访问本地计算机的功能不使用应用强制实施的控制，这些控制仍可能有效。云端交付和云端浏览器行为需要单独验证。 |
通过 Work Cloud 访问本地计算机的 Agent Security 要求
对于具有本地访问权限的 Work 和 dots，启用受管策略后，受支持的 Global 策略会应用于共享的云端编排器。本地执行要求约束所连接的计算机。Work 云容器和 dots 云计算机使用各自的执行配置和要求。请分别测试本地和云端控制措施。
Agent Security UI 中提供的设置
- 允许的审批策略
- 允许的网页搜索模式
通过 TOML 配置的设置
allowed_approvals_reviewersauto_reviewguardian_policy_configappsmcp_serverspluginsrules
这些编排器要求保留在 Global 中。它们不会配置共享云端功能的权限，也不会使本地执行设置可移植到 Work 云容器或 dots 云计算机。
通过 Work Cloud 访问本地计算机的兼容性限制
是否支持取决于字段、策略的下发方式以及任务的运行位置。启用同步前，请检查成员实际生效的策略。如表中所述，某些控制措施需要在你的部署环境中测试。
在同一策略内，优先级从高到低依次为：特定操作系统的环境覆盖 → 所有操作系统的环境覆盖 → Global。即使较低优先级的策略更具体，仍以较高优先级的策略为准。
对于本地执行，MDM 和旧版受管设备要求的优先级高于 Agent Security，而 Agent Security 的优先级高于设备的系统要求文件。某些要求（包括网络要求）具有特定于字段的合并规则和运行时限制。示例请参阅受管配置。
| 设置或设置类别 | 通过 Work Cloud 访问本地计算机的兼容性 | 管理员指导 |
|---|---|---|
sqlite_home, log_dir, model_catalog_json |
不支持用作受管云端覆盖。 | 本地路径无法更改云端存储或日志的位置。本地模型目录不会沿用到云端。 |
model_provider, model_providers |
通过 Work Cloud 访问本地计算机的受管要求或配置不支持这些字段。 | 自定义推理网关和提供商连接不会通过这些字段沿用到云端。这与模型选择是两回事。 |
enforce_residency |
在任一云端策略中启用时，会阻止通过 Work Cloud 访问本地计算机。 | 如果在任一云端策略中启用 enforce_residency，Work 和 dots 的允许访问本地计算机 都会被禁用。此保护措施不会配置工作区的数据驻留位置，也不会单独禁用 Work Cloud 或 dots。 |
application.network.enabled 和 application.network.domains |
通过 Work Cloud 访问本地计算机不支持这些字段。 | 请勿将这些应用目标地址限制用作通过 Work Cloud 访问本地计算机时的命令网络控制措施。 |
allow_browser_and_computer_use, in_app_browser, additional_developer_instructions |
云端策略下发需要验证。通过 Work Cloud 访问本地计算机会拒绝这些受管要求键。 | 浏览器限制在应用端有检查机制。这并不能证明策略会下发到云端或在云端浏览器中强制执行。additional_developer_instructions 需要编排器支持。 |
experimental_network 和 permissions.<profile>.network |
部分支持。受支持的目标地址和执行器限制与自定义代理配置不同。 | 云端运行时不支持受管 HTTP/SOCKS 监听端口和非回环代理监听器；套接字规则的支持情况取决于执行路径。本地执行的合并行为需单独考虑。命令网络限制不会禁用受管搜索、MCP 或应用工具。 |
功能 / feature_requirements, 模型, computer_use |
部分支持。 | 已停用的开关会被拒绝，例如 tool_search = false、tool_search_always_defer_mcp_tools = false、js_repl = true 和 remote_control = true。某些计算机使用设置仍需进行端到端验证。 |
browser_use, allow_appshots, 反馈, allow_remote_control, 市场来源限制 |
在某些策略下发路径中，应用或 app-server 会强制执行这些控制措施。 | 即使通过 Work Cloud 访问本地计算机时忽略某个字段，应用控制措施仍可能生效。桌面浏览器站点规则不适用于 Work 云容器。请验证实际界面和策略下发路径。 |
配置数据结构包含的某些键可能不适用于通过 Work Cloud 访问本地计算机，或不支持环境覆盖。有关全局基线和优先级，请参阅受管配置。
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 会忽略它们；请改为将提供商、通知和遥测
键放在用户级配置中。配置配置档案文件以
$CODEX_HOME/profile-name.config.toml 的形式与 config.toml 位于同一位置；使用
--profile profile-name 选择一个档案。
对于沙箱和审批键（approval_policy、sandbox_mode 和 sandbox_workspace_write.*），请将本参考与沙箱和审批、可写根目录中的受保护路径及网络访问配合使用。有关测试版权限配置档案，请参阅权限。
Codex 和 ChatGPT Work 不再支持 approval_policy = "untrusted"。
请移除该设置，或选择受支持的策略。项目条目中设置的
trust_level = "untrusted" 在用户级 ~/.codex/config.toml 中仍受支持。请参阅
从已停用的 untrusted 审批策略迁移，
了解示例及审批方式的权衡。
将 model 设置为你已登录的账户或工作区可用的模型。使用示例值前，请参阅
GPT-6.1 Sol 可用性。
| 键 | 类型 / 值 | 详细信息 |
|---|---|---|
agents |
table |
多智能体设置和自定义角色声明。标量设置名为保留名称，不能用作自定义角色名。 |
agents.<name>.config_file |
string (path) |
为该角色声明配置层的 TOML 文件路径；相对路径以声明该角色的配置文件所在目录为基准解析。 |
agents.<name>.description |
string |
向 Codex 展示的角色指导，用于选择并生成该类型的智能体。 |
agents.default_subagent_model |
string |
新生成智能体的默认模型。显式指定的 spawn 模型优先。 |
agents.default_subagent_reasoning_effort |
string |
新生成智能体的默认推理强度。显式指定的 spawn 推理强度优先。 |
agents.enabled |
boolean |
启用或禁用多智能体工具（默认：true）。 |
agents.interrupt_message |
boolean |
智能体回合被中断时，记录模型可见的消息（默认：true）。 |
agents.max_concurrent_threads_per_session |
number |
可同时打开的已生成智能体 thread 的最大数量，不包括主 thread。未设置时，由 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 |
on-request | never | { granular = { sandbox_approval = bool, rules = bool, mcp_elicitations = bool, request_permissions = bool, skill_approval = bool } } |
控制 Codex 何时在执行命令前暂停并请求批准。也可以使用 approval_policy = { granular = { ... } } 允许或自动拒绝特定类别的审批提示，同时让其他提示继续交互。untrusted 不受支持，on-failure 已弃用；交互式运行请使用 on-request，非交互式运行请使用 never。 |
approval_policy.granular.mcp_elicitations |
boolean |
为 true 时，允许显示 MCP elicitation 提示，而不是自动拒绝。 |
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 时，允许显示 skill 脚本的审批提示。 |
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.extra_policy |
string |
用于自动评审的附加本地 Markdown 策略，与主策略一并提供。受管理的 guardian_extra_policy 优先。空白值会被忽略。 |
auto_review.policy |
string |
用于自动评审的本地 Markdown 策略指令。受管理的 guardian_policy_config 优先。空白值会被忽略。 |
background_terminal_max_timeout |
number |
空 write_stdin 轮询的最大等待时间，单位为毫秒（用于后台终端轮询）。默认值：300000（5 分钟）。替代旧的 background_terminal_timeout 键。 |
browser_use.allow_history_access |
boolean |
设为 false 可限制访问浏览器历史记录。受管理要求可以强制实施此限制。 |
browser_use.default_origin_policy |
table |
浏览器来源的默认限制。支持 access、uploads、downloads 和 full_cdp_access，每项可设为 allow 或 deny。 |
browser_use.origins.<origin> |
table |
各浏览器来源的限制，字段与 browser_use.default_origin_policy 相同。须包含 HTTP 或 HTTPS 协议，可包含端口；不含路径、查询参数或片段。本地值不能放宽受管理的拒绝规则。 |
chatgpt_base_url |
string |
覆盖 ChatGPT 登录流程使用的基础 URL。 |
check_for_update_on_startup |
boolean |
启动时检查 Codex 更新（仅在更新由组织集中管理时设为 false）。 |
cli_auth_credentials_store |
file | keyring | auto | ephemeral |
控制 CLI 缓存凭据的存储位置。 |
compact_prompt |
string |
直接覆盖历史记录压缩提示词。 |
computer_use.default_app_access |
allow | deny |
Computer Use 的默认原生应用访问策略。应用专用条目可以提供策略；本地配置不能放宽受管理限制。 |
computer_use.macos.bundle_ids |
map<string, allow | deny> |
以 bundle identifier 为键的 macOS 原生应用访问设置。 |
computer_use.windows.always_allowed_app_ids |
array<string> |
Computer Use 无需询问即可打开的 Windows 应用标识符。不在列表中的应用需要批准；可在 ChatGPT 桌面应用的 Computer Use 设置中删除已保存的条目。 |
computer_use.windows.aumids |
map<string, allow | deny> |
以 Application User Model ID（AUMID）为键的 Windows 打包应用访问设置。 |
computer_use.windows.exes |
array<table> |
Windows 可执行文件访问规则。每条规则必须包含 publisher_name、product_name 和 access（allow 或 deny）；binary_name 可选。 |
default_permissions |
string |
应用于沙箱工具调用的默认权限配置档案名称。内置档案为 :read-only、:workspace 和 :danger-full-access；自定义名称须有对应的 [permissions.<name>] 表。不得与 sandbox_mode 或 [sandbox_workspace_write] 合用。 |
desktop.custom_file_handlers.<id> |
table |
仅限用户级配置。为 ChatGPT 桌面应用定义一个附加的 Open in 目标。示例及处理器 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 |
在 Open in 菜单中显示的名称。必填。 |
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 |
启用 unified exec 的旧名称；优先使用 [features].unified_exec 或 codex --enable unified_exec。 |
features.apps |
boolean |
启用应用（连接器）集成（稳定功能；默认开启）。应用和连接器流量不受沙箱命令网络代理及其域名允许列表控制。 |
features.code_mode.direct_only_tool_namespaces |
array<string> |
code mode 只能通过直接工具调用使用的工具命名空间。 |
features.code_mode.enabled |
boolean |
启用 code mode 功能配置。此功能正在开发中，默认关闭。 |
features.code_mode.excluded_tool_namespaces |
array<string> |
code mode 不纳入嵌套工具说明和执行器暴露范围的工具命名空间。 |
features.context_management.experimental_mode |
boolean |
实验性上下文管理设置。此功能目前不可用。 |
features.enable_request_compression |
boolean |
支持时使用 zstd 压缩流式请求体（稳定功能；默认开启）。 |
features.fast_mode |
boolean |
在 TUI 中启用模型目录的服务层级选择；当前模型声明支持时，也包括 Fast 层级命令（稳定功能；默认开启）。 |
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 socket 目标，而不使用仅限允许列表的访问方式。默认值为 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 socket 策略。默认未设置；添加 allow 条目可允许相应 socket。 |
features.personality |
boolean |
启用个性风格选择控件（稳定功能；默认开启）。 |
features.prevent_idle_sleep |
boolean |
有 turn 正在运行时，防止设备进入睡眠（实验性；默认关闭）。 |
features.remote_plugin |
boolean |
启用远程 plugin 目录（稳定功能；默认开启）。 |
features.rollout_budget.enabled |
boolean |
启用 rollout 预算跟踪。此功能正在开发中，默认关闭。启用时必须设置 features.rollout_budget.limit_tokens。 |
features.rollout_budget.limit_tokens |
integer |
rollout 预算跟踪的正数 token 上限。启用 rollout 预算时必须设置。 |
features.rollout_budget.prefill_token_weight |
number |
rollout 预算统计中，预填充 token 的有限非负乘数。默认值为 1.0。 |
features.rollout_budget.reminder_interval_tokens |
integer |
rollout 预算提醒之间的正数 token 间隔。默认占 limit_tokens 的 10%，最少为 1 token。 |
features.rollout_budget.sampling_token_weight |
number |
rollout 预算统计中，采样 token 的有限非负乘数。默认值为 1.0。 |
features.shell_snapshot |
boolean |
保存 shell 环境快照，加快重复执行命令（稳定功能；默认开启）。 |
features.shell_tool |
boolean |
启用默认 shell 工具以运行命令（稳定功能；默认开启）。 |
features.skill_mcp_dependency_install |
boolean |
允许为 skill 提示并安装缺少的 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 scheme（默认：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 相同的事件 schema；示例及支持的事件请参阅钩子指南。 |
hooks.<Event> |
array<table> |
钩子事件的匹配器分组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SessionEnd、SubagentStart、SubagentStop、UserPromptSubmit、Stop 或 Interrupt。 |
hooks.<Event>[].hooks |
array<table> |
匹配器分组的钩子处理器。支持 command 和 MCP tool 钩子；prompt 和 agent 钩子会被解析，但跳过执行。 |
hooks.<Event>[].hooks[].additionalContextLimit |
integer |
每个处理器的近似 token 阈值，用于将过大的 additionalContext 保存到磁盘，并向模型提供较短预览。默认值为 2500；0 将完整上下文直接传给模型。参见 大体积钩子输出。 |
hooks.<Event>[].hooks[].async |
boolean |
在后台运行 command 钩子，不延迟触发它的操作。默认值为 false；SessionEnd 始终同步运行。参见 在后台运行钩子。 |
hooks.<Event>[].hooks[].commandWindows |
string |
command 钩子的 Windows 专用命令覆盖值。也支持 TOML 别名 command_windows。 |
instructions |
string |
为将来使用保留；优先使用 model_instructions_file 或 AGENTS.md。 |
log_dir |
string (path) |
Codex 写入日志文件的目录；默认值为 $CODEX_HOME/log。显式设置此目录还会在其中启用需主动开启的明文 TUI 日志 codex-tui.log。 |
marketplaces.<name>.ref |
string |
市场的可选 Git 分支、标签或提交。 |
marketplaces.<name>.source |
string |
Git 仓库地址或本地市场根目录。本地来源使用绝对路径；该目录包含 .agents/plugins/marketplace.json。 |
marketplaces.<name>.source_type |
git | local |
已配置 plugin 市场的来源类型。市场可在系统、云端管理、用户或受信任项目的 config.toml 中定义。 |
marketplaces.<name>.sparse_paths |
array<string> |
Git 市场的可选稀疏检出路径。须包含市场目录及其引用的所有本地 plugin 目录。 |
mcp_oauth_callback_port |
integer |
MCP OAuth 登录时使用的本地 HTTP 回调 server 的可选全局固定端口。server 专用 oauth.callback_port 优先。两者均未设置时，Codex 绑定操作系统选定的临时端口。 |
mcp_oauth_callback_url |
string |
MCP OAuth 登录的可选基础回调 URL，例如 devbox 入口 URL。授权 server 支持 issuer identification 时，新添加的预注册客户端原样使用此 URL；没有已保存回调地址的现有客户端会附加 server 专用回调 ID。不支持 issuer identification 时，任何预注册 MCP server 若配置的回调地址缺少必需 ID，则回退到此 URL 并附加该 ID。回调 URL 中的端口不决定监听端口。 |
mcp_oauth_credentials_store |
auto | file | keyring |
MCP OAuth 凭据的首选存储方式。 |
mcp_optional_startup_grace_ms |
integer (milliseconds) |
构建初始工具目录时，可选 MCP server 的共享等待时间。默认值为 1000。设为 0 可改为等待各 server 的 startup_timeout_sec。 |
mcp_servers.<id>.args |
array<string> |
传给 MCP stdio server 的参数。 |
mcp_servers.<id>.auth |
oauth | chatgpt |
MCP HTTP server 在已配置的 bearer token 和授权标头之后尝试的备用认证方式。oauth（默认）在可用时使用已存储的 MCP OAuth 凭据。chatgpt 为可信的第一方 ChatGPT 来源使用当前 ChatGPT 会话，然后回退到已存储的 OAuth。两种模式在没有找到任何凭据来源时都可以尝试无认证连接。 |
mcp_servers.<id>.bearer_token_env_var |
string |
提供 MCP HTTP server bearer token 的环境变量。 |
mcp_servers.<id>.command |
string |
MCP stdio server 的启动命令。 |
mcp_servers.<id>.cwd |
string |
MCP stdio server 进程的工作目录。 |
mcp_servers.<id>.default_tools_approval_mode |
auto | prompt | writes | approve |
此 server 上 MCP 工具的默认审批行为，除非存在工具级覆盖值。 |
mcp_servers.<id>.disabled_tools |
array<string> |
在 enabled_tools 之后应用的拒绝列表。 |
mcp_servers.<id>.enabled |
boolean |
禁用 MCP server，但保留其配置。 |
mcp_servers.<id>.enabled_tools |
array<string> |
MCP server 暴露的工具名称允许列表。 |
mcp_servers.<id>.env |
map<string,string> |
传给 MCP stdio server 的环境变量。 |
mcp_servers.<id>.env_http_headers |
map<string,string> |
从环境变量读取值的 MCP HTTP server 请求标头。 |
mcp_servers.<id>.env_vars |
array<string | { name = string, source = "local" | "remote" }> |
为 MCP stdio server 额外加入允许列表的环境变量。字符串条目默认使用 source = "local"；只有由执行器支持的远程 stdio 才使用 source = "remote"。 |
mcp_servers.<id>.experimental_environment |
local | remote |
MCP server 的实验性运行位置。remote 通过远程执行器启动 stdio server；尚未实现 streamable HTTP 的远程运行。 |
mcp_servers.<id>.http_headers |
map<string,string> |
每个 MCP HTTP 请求附带的静态 HTTP 标头。 |
mcp_servers.<id>.http_headers_helper |
string (command) |
输出 HTTP 标头名称和值组成的 JSON 对象的本地命令。仅支持在本地连接的 HTTP MCP server。显式 bearer token 和 OAuth 凭据优先于辅助程序提供的 Authorization 标头。 |
mcp_servers.<id>.oauth_resource |
string |
MCP 登录期间可选的 RFC 8707 OAuth resource 参数。 |
mcp_servers.<id>.oauth.callback_port |
integer |
此 MCP server 的固定 OAuth 回调监听端口。覆盖 mcp_oauth_callback_port。直接使用带显式 URL 端口的回环回调时，须配置相同的监听端口。 |
mcp_servers.<id>.oauth.callback_url |
string |
server 专用 OAuth 回调地址。如果支持 issuer identification，或 URL 已以 server 专用回调 ID 结尾，预注册客户端会复用此地址。否则，Codex 使用全局或默认回调地址并附加该 ID。没有预注册 ID 的客户端在注册时使用此回调地址。 |
mcp_servers.<id>.oauth.client_id |
string |
对此 MCP server 进行授权及 token 交换时使用的预注册 OAuth 客户端 ID。 |
mcp_servers.<id>.required |
boolean |
为 true 时，如果此已启用的 MCP server 无法初始化，则启动或恢复失败。 |
mcp_servers.<id>.scopes |
array<string> |
对此 MCP server 进行认证时请求的 OAuth scope。 |
mcp_servers.<id>.startup_timeout_ms |
number |
startup_timeout_sec 的毫秒形式别名。 |
mcp_servers.<id>.startup_timeout_sec |
number |
覆盖默认的 10 秒 server 启动超时。 |
mcp_servers.<id>.tool_timeout_sec |
number |
覆盖默认的 60 秒单次工具调用超时。 |
mcp_servers.<id>.tools.<tool>.approval_mode |
auto | prompt | writes | approve |
覆盖此 server 上某个 MCP 工具的审批行为。 |
mcp_servers.<id>.tools.<tool>.output_token_limit |
integer (positive) |
单个 MCP 工具输出的 token 预算，随后还会加上标准的 20% 序列化余量。覆盖模型对此工具的默认输出截断预算。 |
mcp_servers.<id>.url |
string |
MCP streamable HTTP server 的端点。 |
memories.consolidation_model |
string |
全局记忆整合的可选模型覆盖值。 |
memories.disable_on_external_context |
boolean |
为 true 时，使用 MCP 工具调用、网页搜索或工具搜索等外部上下文的 thread 不参与记忆生成。默认值为 false。旧别名：memories.no_memories_if_mcp_or_web_search。 |
memories.extract_model |
string |
按 thread 提取记忆时的可选模型覆盖值。 |
memories.generate_memories |
boolean |
为 false 时，新建 thread 不会作为记忆生成输入保存。默认值为 true。 |
memories.max_raw_memories_for_consolidation |
number |
用于全局整合而保留的近期原始记忆的最大数量。默认值为 256，上限为 4096。 |
memories.max_rollout_age_days |
number |
可用于记忆生成的 thread 的最长保留天数。默认值为 30，范围限定在 0–90。 |
memories.max_rollouts_per_startup |
number |
每次启动扫描处理的 rollout 候选项的最大数量。默认值为 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 |
thread 可参与记忆生成前所需的最短空闲时间。默认值为 6，范围限定在 1–48。 |
memories.use_memories |
boolean |
为 false 时，Codex 不会向后续会话注入已有记忆。默认值为 true。 |
model |
string |
要使用的模型（例如 gpt-6.1-sol）。 |
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 key 的环境变量。 |
model_providers.<id>.env_key_instructions |
string |
提供商 API key 的可选设置指引。 |
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 |
string |
所选模型声明支持的推理强度，例如 low、medium、high、xhigh、max 或 ultra。可用级别取决于模型和客户端。 |
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 metrics 导出器（默认：statsig）。 |
otel.trace_exporter |
none | otlp-http | otlp-grpc |
选择 OpenTelemetry trace 导出器，并提供端点元数据。 |
otel.trace_exporter.<id>.endpoint |
string |
OTEL 日志的 trace 导出器端点。 |
otel.trace_exporter.<id>.headers |
map<string,string> |
OTEL trace 导出器请求附带的静态标头。 |
otel.trace_exporter.<id>.protocol |
binary | json |
OTLP/HTTP trace 导出器使用的协议。 |
otel.trace_exporter.<id>.tls.ca-certificate |
string |
OTEL trace 导出器 TLS 的 CA 证书路径。 |
otel.trace_exporter.<id>.tls.client-certificate |
string |
OTEL trace 导出器 TLS 的客户端证书路径。 |
otel.trace_exporter.<id>.tls.client-private-key |
string |
OTEL trace 导出器 TLS 的客户端私钥路径。 |
permissions.<name>.description |
string |
此命名配置档案的说明。配置档案不会通过 extends 继承父档案的说明。 |
permissions.<name>.extends |
string |
在此命名配置档案之前应用的可选父档案。可指定另一个命名档案、:read-only 或 :workspace；:danger-full-access、未定义的父档案和循环继承会被拒绝。 |
permissions.<name>.filesystem |
table |
命名文件系统权限配置档案。每个键为绝对路径或 :minimal、:workspace_roots 等特殊 token。 |
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 |
在沙箱启动前对匹配项创建快照的平台上，deny-read glob 模式展开的最大深度。设置时至少为 1。 |
permissions.<name>.network.allow_local_binding |
boolean |
允许通过沙箱网络访问更广泛的本地或私有网络。精确本地 IP 字面量或 localhost 允许规则仍可放行特定本地目标，即使此项保持 false。 |
permissions.<name>.network.allow_upstream_proxy |
boolean |
允许沙箱网络串联另一个上游代理。 |
permissions.<name>.network.dangerously_allow_all_unix_sockets |
boolean |
允许任意 Unix socket 目标，而不使用默认的受限集合。仅在严格受控的环境中使用。 |
permissions.<name>.network.dangerously_allow_non_loopback_proxy |
boolean |
允许沙箱网络监听器绑定非回环地址。启用后可能将监听器暴露到 localhost 之外。 |
permissions.<name>.network.domains |
table |
沙箱命令的域名规则。只有 features.network_proxy 或已启用的管理员管理网络要求激活代理时才实施。支持精确主机、*.example.com、**.example.com 和全局 * 允许规则；以 deny 为准。不会限制网页搜索、应用或 MCP server。 |
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 socket 允许列表覆盖值。使用 socket 路径作为键；allow 添加路径，deny 拒绝路径。 |
permissions.<name>.network.unix_sockets.<path> |
allow | deny |
用 allow 将 Unix socket 绝对路径加入有效允许列表，或用 deny 拒绝该路径。被拒绝的条目不会进入有效允许列表。 |
permissions.<name>.workspace_roots |
table |
配置档案定义的工作区根目录；这些目录与会话运行时工作区根目录一同应用 :workspace_roots 文件系统规则。 |
permissions.<name>.workspace_roots.<path> |
boolean |
为 true 时，将路径加入此配置档案的工作区根目录集合。禁用的条目保持不生效。 |
personality |
none | friendly | pragmatic |
支持 supportsPersonality 的模型的默认沟通风格；可按 thread 或 turn 覆盖，也可通过 /personality 覆盖。 |
plan_mode_reasoning_effort |
string |
计划模式专用的推理强度覆盖值，须使用所选模型支持的级别。未设置时，计划模式使用其内置预设默认值。 |
plugins.<plugin>.enabled |
boolean |
使用 plugin-name@marketplace-name 键启用或禁用本地市场中的 plugin。从有效的合并配置中读取；受信任项目设置可覆盖用户、云端管理和系统默认值。刷新市场时，即使 plugin 已禁用，也可安装或刷新已配置的 plugin。此设置不会覆盖工作区管理的启用状态。 |
plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode |
auto | prompt | writes | approve |
plugin 提供的 MCP server 上工具的默认审批行为。 |
plugins.<plugin>.mcp_servers.<server>.disabled_tools |
array<string> |
在 plugin 提供的 MCP server 的 enabled_tools 之后应用的拒绝列表。 |
plugins.<plugin>.mcp_servers.<server>.enabled |
boolean |
启用或禁用已安装 plugin 随附的 MCP server，无需修改 plugin manifest。 |
plugins.<plugin>.mcp_servers.<server>.enabled_tools |
array<string> |
plugin 提供的 MCP server 暴露的工具允许列表。 |
plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode |
auto | prompt | writes | approve |
覆盖 plugin 提供的某个 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 |
新 turn 的首选服务层级。使用 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> |
规范的、不区分大小写的环境变量模式过滤器。include 条目构成允许列表，不能恢复已排除的值。显式 set 值在排除操作之后应用。同一配置层中，不得将 filters 与旧 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> |
排除操作后注入的显式环境变量值；include 过滤器仍可将其移除。 |
show_raw_agent_reasoning |
boolean |
当前模型输出原始推理内容时将其显示出来。 |
skills.config |
array<object> |
存储在 config.toml 中、针对各 skill 的启用状态覆盖值。 |
skills.config.<index>.enabled |
boolean |
启用或禁用引用的 skill。 |
skills.config.<index>.path |
string (path) |
包含 SKILL.md 的 skill 文件夹路径。 |
skills.max_context_tokens |
integer (positive) |
可用 skill 目录的 token 预算。默认占模型上下文窗口的 2%。显式值上限为 10000 token。 |
sqlite_home |
string (path) |
Codex 存储基于 SQLite 的状态数据库的目录，用于智能体作业及其他可恢复运行时状态。 |
suppress_unstable_features_warning |
boolean |
隐藏启用开发中功能开关时显示的警告。 |
tool_output_token_limit |
number |
在历史记录中保存单个工具或函数输出的 token 预算。 |
tool_suggest.disabled_tools |
array<table> |
禁用特定可发现连接器或 plugin 的推荐。每个条目使用 type = "connector" 或 "plugin"，并提供 id。 |
tool_suggest.discoverables |
array<table> |
允许工具推荐其他可发现的连接器或 plugin。每个条目使用 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 server。 |
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 | mxc |
在 Windows 上原生运行 Codex 时使用的 Windows 专用原生沙箱模式。 |
没有匹配的配置选项。
你可以在此处找到 config.toml 的最新 JSON Schema。
要在 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 和 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 搭配使用。
untrusted 条目在 allowed_approval_policies 中仍然有效，适用于
Codex 在项目使用以下设置时推导出的更严格的审批行为：
trust_level = "untrusted"。这并不允许显式设置
approval_policy = "untrusted"。
[models.new_thread] 表提供受管的默认值，而非强制约束。
如果你通过 --model、
--config 或 --profile 显式覆盖模型或推理强度，Codex 会忽略 model 和
model_reasoning_effort，这两个字段均位于 [models.new_thread] 中。service_tier 独立生效。
浏览器要求涵盖三个独立的操作界面。in_app_browser
控制由用户直接打开和使用的浏览器窗格。browser_use
控制由智能体在浏览器中执行的操作。computer_use 控制由智能体在
原生桌面应用中执行的操作。
嵌套的 Browser Use 和 Computer Use 策略值本身并不会授予访问权限。
针对特定来源或应用的 allow 可以覆盖同一策略来源的
回退设置，但常规的功能、审批及其他策略检查仍然适用。当受管要求与
config.toml 同时适用时，只要其中任一方设为 deny，
就以此为准。
| 键 | 类型 / 值 | 详细信息 |
|---|---|---|
additional_developer_instructions |
string |
以单独开发者消息形式添加的受管理开发者指令。Codex 会拒绝超过约 10,000 token 上限的指令，计数包含上下文标记。 |
allow_appshots |
boolean |
设为 false 可为受管理用户禁用 Appshots。省略时，Appshots 不受此要求限制，按产品的一般可用性规则提供。 |
allow_browser_and_computer_use |
boolean |
设为 false 可同时阻止智能体驱动的 Browser Use 和原生应用 Computer Use。设为 true 或省略此项，不会直接启用这两项功能；其他功能、策略和审批检查仍然适用。 |
allow_login_shell |
boolean |
强制指定 shell 工具是否可以启动登录 shell。 |
allow_managed_hooks_only |
boolean |
为 true 时，Codex 跳过用户、项目、会话及 plugin 钩子，但仍允许 requirements.toml 和其他受管理配置层提供的钩子。 |
allow_remote_control |
boolean |
设为 false 可为受管理用户禁用设备远程控制。省略时，设备远程控制不受此要求限制，按产品的一般可用性规则提供。 |
allowed_approval_policies |
array<string> |
允许的审批策略，例如 on-request、never 和 granular。加入 untrusted 可允许不受信任项目派生的更严格策略；不能直接通过 approval_policy 选择该策略。 |
allowed_approvals_reviewers |
array<string> |
approvals_reviewer 允许的值，例如 user 和 auto_review。 |
allowed_chatgpt_workspaces |
array<string> |
将 ChatGPT 登录（包括 Codex access token）限制为所列工作区 ID。空列表禁用 ChatGPT 登录；若允许 API 认证，该方式仍可用。通过本地系统要求文件或 macOS MDM 设置；云端管理值会被忽略。 |
allowed_login_methods |
array<string> |
允许 chatgpt、api 或两者。省略时，不限制登录方式。设置时，列表必须至少包含一种方式。api 允许 API 认证，包括 Amazon Bedrock。通过本地系统要求文件或 macOS MDM 设置。云端管理值会被忽略。 |
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 |
设置某个应用工具的受管理审批模式。 |
auto_review |
table |
受管理的自动评审要求。 |
auto_review.ignore_rules |
array<string> |
Codex 在命令执行策略中忽略 allow 前缀规则的完整模型 slug。须精确匹配 slug，有提供商命名空间时也须包含；与 required_on_models 不同，此项不接受省略命名空间的别名。拒绝规则和网络规则仍然生效。 |
auto_review.required_on_models |
array<string> |
必须使用自动评审的模型 slug。slug 必须非空、不含提供商命名空间，且前后无空白。多个要求来源的列表会合并。 |
browser_use |
table |
智能体驱动的 Browser Use 的受管理要求。 |
browser_use.allow_global_persistent_approval |
boolean |
设为 false 可阻止 Browser Use 创建或采用覆盖所有网站的 Always allow（始终允许）批准，例如允许从任意网站下载。已保存的批准会被忽略，但不会删除。设为 true 或省略此项，不会创建批准。 |
browser_use.allow_history_access |
boolean |
设为 false 可阻止 Browser Use 读取浏览器历史记录。设为 true 或省略时，仍使用正常的历史记录设置和可用性检查。 |
browser_use.default_origin_policy |
table |
当 browser_use.origins 下没有匹配条目定义相应设置时，各项 Browser Use 设置的默认值。匹配的来源规则会替换该策略来源中的默认值。随后，Codex 在受管理要求与用户配置中选择更严格的结果。 |
browser_use.default_origin_policy.access |
allow | deny |
使用 deny 可阻止 Browser Use 访问采用默认策略的来源。被拒绝的来源也会阻止上传、下载、完整浏览器调试访问和自动评审。allow 仅允许继续正常的审批和策略检查。 |
browser_use.default_origin_policy.access_approval_lifetime |
turn | thread |
设置非持久性网站访问批准的有效期：turn 限于当前 turn，thread 持续到当前 thread 结束。persistent_approval 单独控制是否提供 Always allow（始终允许）。产品默认值为 thread。 |
browser_use.default_origin_policy.auto_review |
allow | deny |
使用 deny 可对采用默认策略的来源跳过自动评审，改为请求用户批准。allow 在其他设置允许时保留自动评审。 |
browser_use.default_origin_policy.downloads |
allow | deny |
使用 deny 可阻止 Browser Use 从采用默认策略的来源下载。allow 仅允许继续正常的审批和策略检查。 |
browser_use.default_origin_policy.full_cdp_access |
allow | deny |
使用 deny 可阻止对采用默认策略的来源进行完整 Chrome DevTools Protocol（CDP）访问。allow 仅允许继续正常的主动启用和审批检查。 |
browser_use.default_origin_policy.persistent_approval |
boolean |
设为 false 可阻止 Browser Use 保存或采用针对使用默认策略的来源的 Always allow（始终允许）批准。当前 turn 或 thread 的批准仍可生效。true 在其他条件允许时提供 Always allow 选项，但不会创建批准。 |
browser_use.default_origin_policy.uploads |
allow | deny |
使用 deny 可阻止 Browser Use 向采用默认策略的来源上传。allow 仅允许继续正常的审批和策略检查。 |
browser_use.disable_auto_review |
boolean |
设为 true 可让 Browser Use 跳过自动评审，改为请求用户批准。设为 false 或省略时，只要其他设置允许，仍可使用自动评审。 |
browser_use.origins |
map<string, table> |
针对特定来源的 Browser Use 策略。键采用 <scheme>://<host-pattern>[:<port>] 格式，协议为 http 或 https。可使用精确主机、仅匹配子域名的 *.example.com，或匹配根域名及其子域名的 **.example.com。其他 * 通配符可以跨越点号，因此 region*.example.com 也匹配 region.api.example.com；主机 * 匹配该协议的所有主机。协议和非默认端口参与匹配；显式默认端口会被规范化移除。路径、查询参数、嵌入的用户名或密码，以及通配符协议或端口均无效。在 TOML 中用引号包裹模式，例如 [browser_use.origins."https://**.example.com"]。 |
browser_use.origins.<pattern> |
table |
匹配此模式的来源的策略。多个模式匹配时，Codex 对每项能力采用最严格的值：deny 优先于 allow、false 优先于 true、turn 优先于 thread。 |
browser_use.origins.<pattern>.access |
allow | deny |
使用 deny 可阻止 Browser Use 访问匹配的来源。拒绝访问也会阻止该来源上的上传、下载、完整浏览器调试访问和自动评审。allow 仅允许继续正常的审批和策略检查。 |
browser_use.origins.<pattern>.access_approval_lifetime |
turn | thread |
设置针对匹配来源的非持久性网站访问批准的有效期：turn 限于当前 turn，thread 持续到当前 thread 结束。persistent_approval 单独控制是否提供 Always allow（始终允许）。 |
browser_use.origins.<pattern>.auto_review |
allow | deny |
使用 deny 可对匹配的来源跳过自动评审，改为请求用户批准。allow 在其他设置允许时保留自动评审。 |
browser_use.origins.<pattern>.downloads |
allow | deny |
使用 deny 可阻止 Browser Use 从匹配的来源下载。allow 仅允许继续正常的审批和策略检查。 |
browser_use.origins.<pattern>.full_cdp_access |
allow | deny |
使用 deny 可阻止对匹配的来源进行完整 Chrome DevTools Protocol（CDP）访问。allow 仅允许继续正常的主动启用和审批检查。 |
browser_use.origins.<pattern>.persistent_approval |
boolean |
设为 false 可阻止 Browser Use 保存或采用针对匹配来源的 Always allow（始终允许）批准。当前 turn 或 thread 的批准仍可生效。true 在其他条件允许时提供 Always allow 选项，但不会创建批准。 |
browser_use.origins.<pattern>.uploads |
allow | deny |
使用 deny 可阻止 Browser Use 向匹配的来源上传。allow 仅允许继续正常的审批和策略检查。 |
chatgpt_base_url |
string |
在认证和获取云端策略前强制指定 ChatGPT 服务基础 URL。此项不会配置所有 Codex 网络目标。通过本地系统要求文件或 macOS MDM 设置；云端管理值会被忽略。 |
check_for_update_on_startup |
boolean |
强制指定 Codex 是否在启动时检查更新。 |
cli_auth_credentials_store |
file | keyring | auto | ephemeral |
在加载认证前强制指定 CLI 凭据存储方式。file 使用 CODEX_HOME/auth.json；keyring 要求使用操作系统凭据存储；auto 在凭据存储不可用时回退到文件；ephemeral 在当前进程内存中保存凭据。通过本地系统要求文件或 macOS MDM 设置；云端管理值会被忽略。 |
computer_use |
table |
智能体在原生桌面应用中工作的受管理要求。受管理应用规则和 config.toml 应用规则都会实施；应用必须得到每个策略来源的允许。 |
computer_use.allow_locked_computer_use |
boolean |
设为 false 可阻止用户在受管理的 macOS 设备上启用 Locked Use。此要求会移除启用控件；如果 Locked Use 已启用，不会将其关闭。省略时按产品的一般可用性规则提供。 |
computer_use.allow_persistent_approval |
boolean |
设为 false 可移除跨会话保存应用批准的选项。当前会话的批准仍可用。设为 true 或省略此项，不会批准某个应用。 |
computer_use.default_app_access |
allow | deny |
不匹配平台专用规则的原生应用的默认访问策略。deny 阻止访问。allow 仅允许继续正常的审批和策略检查。产品默认值为 allow。 |
computer_use.macos |
table |
macOS 的 Computer Use 应用规则。 |
computer_use.macos.bundle_ids |
map<string, allow | deny> |
将精确的 macOS bundle identifier 映射为 allow 或 deny。匹配规则会替换同一策略来源中的 computer_use.default_app_access。受管理要求或用户配置任一来源的拒绝规则仍会阻止访问。 |
computer_use.macos.bundle_ids.<bundle-id> |
allow | deny |
使用 deny 可阻止访问此精确 bundle identifier。allow 仅覆盖此策略来源的默认值；其他策略来源和正常审批流程仍须允许该应用。 |
computer_use.windows |
table |
Windows 打包和未打包应用的 Computer Use 应用规则。 |
computer_use.windows.aumids |
map<string, allow | deny> |
将已签名打包应用的精确已注册 Application User Model ID（AUMID）映射为 allow 或 deny。匹配规则会替换同一策略来源中的 computer_use.default_app_access。 |
computer_use.windows.aumids.<aumid> |
allow | deny |
使用 deny 可阻止访问此精确打包应用标识。allow 仅覆盖此策略来源的默认值；其他策略来源和正常审批流程仍须允许该应用。 |
computer_use.windows.exes |
array<table> |
已签名、未打包的 Windows 可执行文件规则。规则匹配可执行文件经验证的发布者及已签名的版本信息，而不是路径或当前文件名。匹配的拒绝规则优先于匹配的允许规则。未签名的可执行文件使用 computer_use.default_app_access；无法明确验证签名身份的可执行文件会被阻止。 |
computer_use.windows.exes[].access |
allow | deny |
必填。匹配可执行文件的访问决定。deny 阻止访问。allow 仅覆盖此策略来源的默认值；其他策略来源和正常审批流程仍须允许该应用。 |
computer_use.windows.exes[].binary_name |
string |
可选。可执行文件已签名版本信息中的 OriginalFilename。匹配不区分大小写。如果匹配发布者和产品的规则要求此值，而可执行文件未提供，Computer Use 会阻止该可执行文件。 |
computer_use.windows.exes[].product_name |
string |
必填。可执行文件已签名版本信息中的精确 ProductName。 |
computer_use.windows.exes[].publisher_name |
string |
必填。可执行文件可信签名证书中的精确发布者名称，格式为 Windows X.500 distinguished name。 |
default_permissions |
string |
受管理的默认权限配置档案。该档案必须在 allowed_permission_profiles 中被允许。请显式设置，以获得可预测的行为；省略时，默认档案只会是 :workspace，且前提是 :workspace 和 :read-only 都被显式允许。 |
enforce_residency |
string |
要求 Codex 服务流量使用受支持的数据驻留区域。目前接受 us。 |
experimental_network |
table |
沙箱本地命令的管理员管理网络要求，通过 requirements.toml 实施。启用后，这些要求可在未启用 features.network_proxy 时启动命令网络代理。浏览器工具会另行检查受管理的网络拒绝规则和排他性允许列表。这些要求不会将浏览器流量送入代理，也不控制网页搜索、应用、MCP server、原生应用流量或其他特定能力的流量。在支持的受管理 Codex Cloud 路径中，这些要求与独立的 Cloud 环境互联网设置共同约束命令网络。在策略允许时，获批的完全沙箱权限提升可绕过命令代理。Work Cloud 不继承这些要求。 |
experimental_network.allow_local_binding |
boolean |
允许通过沙箱网络访问更广泛的本地或私有网络。在支持的 Codex Cloud 代理路径中，即使域名被允许，显式 false 也可阻止上游代理访问。仅当没有适用的要求、所选网络配置档案或代理功能设置提供值时，默认值才为 true。继承的 false 仍是显式值。受支持的、更高优先级的 Cloud 覆盖值可以修改它，而不扩大 Local 的 Global 设置或添加域名 Allow 条目。须核实执行器是否支持。不要将此 Cloud 默认值用于 Local。 |
experimental_network.allow_upstream_proxy |
boolean |
允许沙箱网络串联环境中指定的上游代理。 |
experimental_network.allowed_domains |
array<string> |
受管理网络代理启用时，沙箱命令网络的管理员允许规则。这些规则不适用于网页搜索、应用或 MCP server。不得与 experimental_network.domains 合用。 |
experimental_network.dangerously_allow_all_unix_sockets |
boolean |
允许任意 Unix socket 目标，而不使用仅限允许列表的访问方式。仅在严格受控的环境中使用。 |
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 和全局 * 允许规则。优先使用范围明确的规则，因为 * 会广泛开放外部访问。同一策略中，Environment 规则可替换同名 Global 域名键。更高优先级值替换同名键，其他继承的键保留。组合后，其他匹配的 deny（包括继承的通配符）仍会阻止请求。空的环境映射不会清除 Global 规则。须核实执行器是否支持。不得与 experimental_network.allowed_domains 或 experimental_network.denied_domains 合用。 |
experimental_network.domains.<pattern> |
allow | deny |
允许或拒绝访问匹配域名模式的沙箱网络。多个模式匹配时，拒绝规则优先。 |
experimental_network.enabled |
boolean |
启用沙箱网络要求。当前沙箱关闭命令网络时，此项不会授予网络访问权限。 |
experimental_network.http_port |
integer |
[experimental_network] 要求使用的回环 HTTP 监听端口。 |
experimental_network.managed_allowed_domains_only |
boolean |
网络要求已启用且此项为 true 时，普通用户配置及逐域名批准无法扩大受管理代理的允许列表。若没有有效的已配置或继承 Allow 条目，普通受管理命令没有任何允许的访问目标。只有拒绝规则的策略不会放行其余互联网。此项不覆盖所有工具，也不覆盖已获批的完全沙箱权限提升。 |
experimental_network.socks_port |
integer |
[experimental_network] 要求使用的回环 SOCKS5 监听端口。 |
experimental_network.unix_sockets |
map<string, allow | deny> |
macOS 上管理员管理的沙箱网络 Unix socket 允许列表。路径必须为绝对路径。 |
experimental_network.unix_sockets.<path> |
allow | deny |
在 macOS 上，allow 将 Unix socket 绝对路径加入允许列表；deny 不将其加入。启用允许所有 Unix socket 时，deny 条目无法阻止某个 socket。 |
features |
table |
固定的功能值。运行时功能使用 config.toml 中的规范名称；此处也支持文档列出的应用专用要求键。 |
features.<name> |
boolean |
要求文档列出的某项运行时或应用功能保持启用或禁用。 |
features.apps |
boolean |
为受管理用户固定应用集成的可用性，强制开启或关闭。 |
features.browser_use |
boolean |
设为 false（在 requirements.toml 中），可禁用智能体驱动的 Browser Use。 |
features.browser_use_external |
boolean |
设为 false（在 requirements.toml 中），可阻止 Codex 通过 ChatGPT 浏览器扩展操作支持的浏览器，包括已有标签页和已登录会话。 |
features.browser_use_full_cdp_access |
boolean |
设为 false（在 requirements.toml 中），可禁用本地运行时的完整 Chrome DevTools Protocol 访问，包括 Browser Developer 模式，并阻止 ChatGPT 桌面应用启用对应设置。省略时按产品的一般可用性规则提供。 |
features.computer_use |
boolean |
设为 false（在 requirements.toml 中），可禁用 Computer Use、Record & Replay 及相关安装或启用流程。 |
features.fast_mode |
boolean |
为受管理用户固定规范的 fast_mode 功能，强制开启或关闭。 |
features.guardian_approval |
boolean |
为受管理用户固定 Guardian 审批的可用性，强制开启或关闭。 |
features.in_app_browser |
boolean |
设为 false（在 requirements.toml 中），可禁用用户直接打开和操作的内置浏览器面板。 |
features.in_app_chat |
boolean |
设为 false 可在 ChatGPT 桌面应用中隐藏 ChatGPT 和 ChatGPT Work 会话界面及相关云端自动化界面。此设置不会阻止 ChatGPT Voice，也不会停止已有云端任务。设为 true 不会绕过账户、工作区权限或功能逐步开放检查。 |
features.in_app_dictation |
boolean |
设为 false 可禁用桌面应用内的语音转写。设为 true 不会绕过其他可用性检查。 |
features.in_app_local_automation |
boolean |
设为 false 可禁用桌面应用中的本地定时任务。设为 true 不会绕过其他可用性检查。 |
features.in_app_updates |
boolean |
设为 false（在 requirements.toml 中），可禁用应用内更新。省略此要求时，默认仍启用更新。 |
features.memories |
boolean |
为受管理用户固定记忆功能的可用性，强制开启或关闭。 |
features.multi_agent |
boolean |
为受管理用户固定多智能体功能的可用性，强制开启或关闭。 |
features.plugin_sharing |
boolean |
设为 false（在云端管理的 requirements.toml 中），可禁用本地构建 plugin 的工作区共享。 |
features.plugins |
boolean |
为受管理用户固定 plugin 的可用性，强制开启或关闭。 |
features.realtime_conversation |
boolean |
设为 false 可禁用 Codex CLI 中实验性的 /voice 命令。不要依赖此设置来阻止桌面应用中的 ChatGPT Voice 或 app-server 语音会话。设为 true 不会绕过客户端或功能逐步开放检查。 |
features.remote_plugin |
boolean |
为受管理用户固定远程 plugin 目录的可用性，强制开启或关闭。 |
features.workspace_dependencies |
boolean |
为受管理用户固定随附的工作区依赖运行时的可用性，强制开启或关闭。 |
feedback |
table |
受管理的反馈设置。 |
feedback.enabled |
boolean |
强制指定用户是否可通过 Codex 客户端提交反馈。 |
guardian_extra_policy |
string |
用于自动评审的附加受管理 Markdown 策略，与主策略一并提供。优先于本地 [auto_review].extra_policy。空白值会被忽略。 |
guardian_policy_config |
string |
用于自动评审的受管理 Markdown 策略指令。优先于本地 [auto_review].policy。空白值会被忽略。 |
hooks |
table |
管理员强制实施的受管理生命周期钩子。要求提供受管理钩子目录，并使用与内联 [hooks] 相同的事件 schema，该内联配置位于 config.toml。 |
hooks.<Event> |
array<table> |
钩子事件的匹配器分组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SessionEnd、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。 |
hooks.<Event>[].hooks |
array<table> |
匹配器分组的钩子处理器。支持 command 和 MCP tool 钩子；prompt 和 agent 钩子会被解析，但跳过执行。 |
hooks.<Event>[].hooks[].additionalContextLimit |
integer |
每个处理器的近似 token 阈值，用于将过大的 additionalContext 保存到磁盘，并向模型提供较短预览。默认值为 2500；0 将完整上下文直接传给模型。参见 大体积钩子输出。 |
hooks.<Event>[].hooks[].async |
boolean |
在后台运行 command 钩子，不延迟触发它的操作。默认值为 false；SessionEnd 始终同步运行。参见 在后台运行钩子。 |
hooks.<Event>[].hooks[].commandWindows |
string |
command 钩子的 Windows 专用命令覆盖值。也支持 TOML 别名 command_windows。 |
hooks.managed_dir |
string (absolute path) |
macOS 和 Linux 上存放受管理钩子脚本的目录。Codex 在加载受管理钩子前，验证其为绝对路径且确实存在。 |
hooks.windows_managed_dir |
string (absolute path) |
Windows 上存放受管理钩子脚本的目录。Codex 在加载受管理钩子前，验证其为绝对路径且确实存在。 |
in_app_browser |
table |
内置浏览器面板的要求。这些设置不控制智能体驱动的 Browser Use。 |
in_app_browser.allow_external_browser_settings_import |
boolean |
设为 false 可阻止用户将外部浏览器的设置或浏览数据导入内置浏览器。设为 true 或省略时，只要其他产品检查允许，导入功能仍可用。此设置仅限受管理配置，不可通过 config.toml 覆盖。 |
log_dir |
string (path) |
强制指定 Codex 写入本地日志文件的目录。 |
marketplaces |
table |
plugin 市场来源的管理员要求。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 ref。省略时，此规则允许匹配仓库的任意 ref。 |
marketplaces.allowed_sources.<name>.source |
git | host_pattern | local |
市场来源匹配器类型。单个仓库使用 git；按正则表达式匹配 Git 主机使用 host_pattern；本地目录使用 local。 |
marketplaces.allowed_sources.<name>.url |
string |
source = "git" 时必填的 Git 仓库 URL。Codex 会规范化已配置和允许的 URL，再要求精确匹配。 |
marketplaces.restrict_to_allowed_sources |
boolean |
为 true 时，要求执行 marketplace add、plugin install、refresh 及运行时加载所使用的已配置市场来源与 allowed_sources 匹配。OpenAI 精选 Git 目录（包括 API key 目录）也必须匹配允许列表。随附 plugin 和远程安装的工作区 plugin 独立于此精选 Git 来源策略。 |
mcp_servers |
table |
可以启用的 MCP server 允许列表。MCP server 的名称（<id>）及身份都必须与条目匹配。不在允许列表中或身份不匹配的已配置 MCP server 会被禁用。 |
mcp_servers.<id>.identity |
table |
单个 MCP server 的身份规则。设置 command（stdio）或 url（streamable HTTP）中的一项。 |
mcp_servers.<id>.identity.command |
string | table |
通过精确命令字符串允许 MCP stdio server，或使用匹配器表要求精确可执行文件及有序参数匹配器。字符串形式不检查参数、cwd、env 或 env_vars。 |
mcp_servers.<id>.identity.command.args |
array<table> |
stdio server 的有序参数匹配器。已配置参数列表长度必须相同，且每个位置都匹配。命令匹配器不检查 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 server 配置的 command 必须精确匹配的可执行文件。 |
mcp_servers.<id>.identity.url |
string | table |
通过精确 URL 字符串允许 MCP streamable HTTP server，或使用 exact、prefix、regex 值匹配器表。 |
mcp_servers.<id>.identity.url.expression |
string |
regex URL 匹配器使用的正则表达式。表达式必须有效，且匹配完整 URL 值。 |
mcp_servers.<id>.identity.url.match |
exact | prefix | regex |
已配置 MCP server URL 的匹配操作。 |
mcp_servers.<id>.identity.url.value |
string |
exact 或 prefix URL 匹配器使用的值。 |
model_catalog_json |
string (path) |
强制指定 Codex 启动时使用的 JSON 模型目录。 |
model_provider |
string |
强制指定模型提供商 ID，覆盖本地和会话配置。 |
model_providers |
map<string, table> |
受管理的模型提供商定义。每个条目会整体替换同 ID 的已配置提供商，不与用户定义逐字段合并。其他 ID 的提供商仍可用。 |
model_providers.<id> |
table |
完整的受管理提供商定义。使用与 config.toml 相同的字段，包括 name、base_url、认证和传输设置。 |
models |
table |
包含 [models.new_thread] 表。 |
models.new_thread |
table |
新本地 thread 启动时应用的可选默认值。优先于用户和项目默认值，但仍可被显式覆盖值替代。 |
models.new_thread.model |
string |
新 thread 的默认模型。显式覆盖模型或推理强度中的任意一项时，这两个字段都会被忽略。 |
models.new_thread.model_reasoning_effort |
string |
新 thread 的默认推理强度。显式覆盖模型或推理强度中的任意一项时，这两个字段都会被忽略。 |
models.new_thread.service_tier |
string |
新 thread 的默认服务层级。显式覆盖服务层级时，此字段会被忽略。 |
permissions |
table |
以配置档案名称为键的管理员定义权限配置档案。字段与 config.toml 相同。 |
permissions.<name> |
table |
管理员定义的权限配置档案。名称不能以 : 开头，不能使用保留名称 filesystem，也不能与已加载配置中的档案重名。字段与 config.toml 相同；完整 schema 请参阅权限指南。 |
permissions.filesystem.deny_read |
array<string> |
管理员强制实施的文件系统读取拒绝规则。条目可以是路径或 glob 模式，用户不能通过本地配置放宽。 |
plugins |
table |
以 plugin 标识符为键的 plugin 专用 MCP server 允许列表。此表存在时，若 plugin 随附的 server 没有匹配的 plugin 及 server 条目，就会被禁用。 |
plugins.<plugin>.mcp_servers |
table |
某个 plugin 随附的 MCP server 的允许列表。plugin server 要求使用与顶层 mcp_servers 要求相同的精确身份和匹配器形式。 |
plugins.<plugin>.mcp_servers.<server>.identity |
table |
单个 plugin 随附 MCP server 的身份规则。设置 command（stdio）或 url（streamable HTTP）中的一项。 |
plugins.<plugin>.mcp_servers.<server>.identity.command |
string | table |
通过精确命令字符串允许 plugin 的 stdio MCP server，或使用匹配器表要求精确可执行文件及有序参数匹配器。 |
plugins.<plugin>.mcp_servers.<server>.identity.command.args |
array<table> |
plugin 随附 stdio server 的有序参数匹配器。已配置参数列表长度必须相同，且每个位置都匹配。 |
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 |
plugin 随附 stdio server 配置的 command 必须精确匹配的可执行文件。 |
plugins.<plugin>.mcp_servers.<server>.identity.url |
string | table |
通过精确 URL 字符串允许 plugin 的 streamable HTTP MCP server，或使用 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 |
plugin 随附 MCP server 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 原生沙箱实现（elevated 和 unelevated）。列表不得为空。两者均被允许且未选择模式时，Codex 优先使用 elevated。此列表不限制可用时的 mxc 沙箱。 |
没有匹配的配置选项。