配置参考
将此页面作为 Codex 配置文件的可搜索参考。有关概念说明和示例，请先查看配置基础和高级配置。
config.toml
Section titled “config.toml”用户级配置位于 ~/.codex/config.toml。你也可以在 .codex/config.toml 文件中添加项目范围的覆盖配置。只有在你信任项目时，Codex 才会加载项目范围的配置文件。
项目范围的配置无法覆盖机器本地的 provider、身份验证、主机拥有的应用请求元数据、通知、配置 profile 选择或遥测路由键。当这些键出现在项目本地的 .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；请将 provider、通知和遥测键放入用户级配置中。配置profile 文件与 config.toml 位于同一目录，文件名为 $CODEX_HOME/profile-name.config.toml；使用 --profile profile-name 选择配置文件。
对于沙箱和审批键（approval_policy、sandbox_mode 以及 sandbox_workspace_write.*），请将此参考与沙箱和审批、可写根目录中的受保护路径和网络访问结合使用。有关 beta 权限 profile，请参阅权限。
| 键 | 类型 | 描述 |
|---|---|---|
model |
string |
要使用的模型（例如 gpt-5.5）。 |
review_model |
string |
/review 使用的可选模型覆盖值（默认为当前会话模型）。 |
model_provider |
string |
model_providers 中的提供商 ID（默认值：openai）。 |
openai_base_url |
string |
内置 openai 模型提供商的基础 URL 覆盖值。 |
model_context_window |
number |
当前模型可用的上下文窗口令牌数。 |
model_auto_compact_token_limit |
number |
触发历史记录自动压缩的令牌阈值（未设置时使用模型默认值）。 |
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 配置文件可以针对各个配置文件覆盖此设置。 |
oss_provider |
lmstudio | ollama |
使用 --oss 运行时的默认本地提供商（未设置时默认提示选择）。 |
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.sandbox_approval |
boolean |
为 true 时，允许显示沙箱权限提升批准提示。 |
approval_policy.granular.rules |
boolean |
为 true 时，允许显示由 execpolicy prompt 规则触发的批准提示。 |
approval_policy.granular.mcp_elicitations |
boolean |
为 true 时，允许显示 MCP 引导提示，而不是自动拒绝。 |
approval_policy.granular.request_permissions |
boolean |
为 true 时，允许显示来自 request_permissions 工具的提示。 |
approval_policy.granular.skill_approval |
boolean |
为 true 时，允许显示技能脚本批准提示。 |
approvals_reviewer |
user | auto_review |
在 on-request 或粒度化批准策略下审核符合条件的批准提示的对象。默认为 user；auto_review 使用审核子代理。此设置不会改变沙箱策略，也不会改变沙箱内已获允许的审核操作。 |
auto_review.policy |
string |
用于自动审核的本地 Markdown 策略说明。托管的 guardian_policy_config 优先级更高。空白值会被忽略。 |
allow_login_shell |
boolean |
允许基于 shell 的工具使用登录 shell 语义。默认为 true；为 false 时会拒绝 login = true 请求，省略 login 时默认使用非登录 shell。 |
sandbox_mode |
read-only | workspace-write | danger-full-access |
命令执行期间文件系统和网络访问的沙箱策略。 |
sandbox_workspace_write.writable_roots |
array<string> |
当 sandbox_mode = "workspace-write" 时要额外允许写入的根目录。 |
sandbox_workspace_write.network_access |
boolean |
允许在 workspace-write 沙箱内访问外部网络。 |
sandbox_workspace_write.exclude_tmpdir_env_var |
boolean |
在 workspace-write 模式下，将 $TMPDIR 排除在可写根目录之外。 |
sandbox_workspace_write.exclude_slash_tmp |
boolean |
在 workspace-write 模式下，将 /tmp 排除在可写根目录之外。 |
windows.sandbox |
unelevated | elevated |
在 Windows 上原生运行 Codex 时使用的 Windows 专用原生沙箱模式。 |
windows.sandbox_private_desktop |
boolean |
在原生 Windows 上默认在私有桌面中运行最终的沙箱子进程。仅在需要兼容旧版 Winsta0\\Default 行为时设置为 false。 |
computer_use.windows.always_allowed_app_ids |
array<string> |
Computer Use 无需提示即可打开的 Windows 应用标识符。不在列表中的应用需要批准；请从 ChatGPT 桌面应用的 Computer Use 设置中删除已保存的条目。 |
notify |
array<string> |
用于通知的命令；接收来自 Codex 的 JSON 负载。 |
check_for_update_on_startup |
boolean |
启动时检查 Codex 更新（仅在更新由集中式系统管理时设置为 false）。 |
feedback.enabled |
boolean |
在本地客户端中启用通过 /feedback 提交反馈（默认值：true）。 |
analytics.enabled |
boolean |
启用或禁用此计算机/配置文件的分析功能。未设置时使用客户端默认值。 |
instructions |
string |
为将来使用而保留；优先使用 model_instructions_file 或 AGENTS.md。 |
developer_instructions |
string |
注入会话的其他开发者说明（可选）。 |
log_dir |
string (path) |
Codex 写入日志文件的目录；默认为 $CODEX_HOME/log。显式设置此项还会在该目录中启用可选的纯文本 TUI 日志 codex-tui.log。 |
sqlite_home |
string (path) |
Codex 存储由 SQLite 支持的状态数据库的目录，该数据库用于代理任务和其他可恢复的运行时状态。 |
compact_prompt |
string |
历史记录压缩提示的内联覆盖值。 |
model_instructions_file |
string (path) |
用于替代内置说明，而不是使用 AGENTS.md。 |
personality |
none | friendly | pragmatic |
为声明支持 supportsPersonality 的模型设置默认交流风格；可按线程/轮次或通过 /personality 覆盖。 |
service_tier |
string |
新轮次的首选服务层级。使用 fast 或当前模型声明支持的其他层级；fast 映射到请求值 priority。 |
experimental_compact_prompt_file |
string (path) |
从文件加载压缩提示词覆盖（实验性功能）。 |
skills.config |
array<object> |
存储在 config.toml 中的按技能启用覆盖设置。 |
skills.config.<index>.path |
string (path) |
包含 SKILL.md 的技能文件夹路径。 |
skills.config.<index>.enabled |
boolean |
启用或禁用所引用的技能。 |
apps.<id>.enabled |
boolean |
按 id 启用或禁用特定应用/连接器（默认值：true）。 |
apps._default.enabled |
boolean |
所有应用的默认启用状态，除非按应用覆盖。 |
apps._default.destructive_enabled |
boolean |
对带有 destructive_hint = true 的应用工具的默认允许/拒绝设置。 |
apps._default.open_world_enabled |
boolean |
对带有 open_world_hint = true 的应用工具的默认允许/拒绝设置。 |
apps._default.approvals_reviewer |
user | auto_review |
应用工具审批提示的默认审核者，除非按应用覆盖。省略时，应用继承顶层 approvals_reviewer 值。 |
apps._default.default_tools_approval_mode |
auto | prompt | writes | approve |
对没有按应用或按工具覆盖的应用工具的默认审批行为。 |
apps.<id>.destructive_enabled |
boolean |
允许或阻止此应用中声明 destructive_hint = true 的工具。 |
apps.<id>.open_world_enabled |
boolean |
允许或阻止此应用中声明 open_world_hint = true 的工具。 |
apps.<id>.default_tools_enabled |
boolean |
此应用中工具的默认启用状态，除非存在按工具覆盖。 |
apps.<id>.approvals_reviewer |
user | auto_review |
此应用工具审批提示的审核者。覆盖 apps._default.approvals_reviewer。 |
apps.<id>.default_tools_approval_mode |
auto | prompt | writes | approve |
此应用中工具的默认审批行为，除非存在按工具覆盖。 |
apps.<id>.tools.<tool>.enabled |
boolean |
应用工具的按工具启用覆盖设置（例如 repos/list）。 |
apps.<id>.tools.<tool>.approval_mode |
auto | prompt | writes | approve |
单个应用工具的按工具审批行为覆盖设置。 |
tool_suggest.discoverables |
array<table> |
允许为其他可发现的连接器或插件提供工具建议。每个条目使用 type = "connector" 或 "plugin"，以及一个 id。 |
tool_suggest.disabled_tools |
array<table> |
禁用对特定可发现连接器或插件的建议。每个条目使用 type = "connector" 或 "plugin"，以及一个 id。 |
features.apps |
boolean |
启用应用（连接器）集成（稳定；默认开启）。 |
features.hooks |
boolean |
启用从 hooks.json 或内联 [hooks] 配置加载的生命周期钩子。features.codex_hooks 是已弃用的别名。 |
features.code_mode.enabled |
boolean |
启用代码模式功能配置。此功能正在开发中，默认关闭。 |
features.code_mode.excluded_tool_namespaces |
array<string> |
代码模式从嵌套代码模式工具指导和执行器暴露中排除的工具命名空间。 |
features.code_mode.direct_only_tool_namespaces |
array<string> |
代码模式只能通过直接工具调用使用的工具命名空间。 |
features.rollout_budget.enabled |
boolean |
启用 rollout 预算跟踪。此功能正在开发中，默认关闭。启用后必须设置 features.rollout_budget.limit_tokens。 |
features.rollout_budget.limit_tokens |
integer |
rollout 预算跟踪的正令牌上限。启用 rollout 预算时必需。 |
features.rollout_budget.reminder_interval_tokens |
integer |
rollout 预算提醒之间的正令牌间隔。默认为 limit_tokens 的 10%，最小为 1 个令牌。 |
features.rollout_budget.sampling_token_weight |
number |
rollout 预算计算中采样令牌的有限非负乘数。默认为 1.0。 |
features.rollout_budget.prefill_token_weight |
number |
rollout 预算计算中预填充令牌的有限非负乘数。默认为 1.0。 |
hooks |
table |
在 config.toml 中内联配置的生命周期钩子。使用与 hooks.json 相同的事件架构；示例和支持的事件请参阅 Hooks 指南。 |
hooks. |
array<table> |
钩子事件的匹配器组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。 |
hooks.[].hooks |
array<table> |
匹配器组的钩子处理程序。目前支持命令钩子；提示和代理钩子处理程序会被解析但跳过。 |
hooks.[].hooks[].commandWindows |
string |
命令钩子的 Windows 专用命令覆盖值。也接受 TOML 别名 command_windows。 |
features.memories |
boolean |
启用 Memories（默认关闭）。 |
mcp_servers.<id>.command |
string |
MCP stdio 服务器的启动命令。 |
mcp_servers.<id>.args |
array<string> |
传递给 MCP stdio 服务器命令的参数。 |
mcp_servers.<id>.env |
map<string,string> |
转发给 MCP stdio 服务器的环境变量。 |
mcp_servers.<id>.env_vars |
array<string | { name = string, source = "local" | "remote" }> |
要为 MCP stdio 服务器加入白名单的其他环境变量。字符串条目的默认值为 source = "local"；仅对由执行器支持的远程 stdio 使用 source = "remote"。 |
mcp_servers.<id>.cwd |
string |
MCP stdio 服务器进程的工作目录。 |
mcp_servers.<id>.url |
string |
MCP 可流式传输 HTTP 服务器的端点。 |
mcp_servers.<id>.auth |
oauth | chatgpt |
在已配置的 bearer token 和授权标头之后，用于 MCP HTTP 服务器的身份验证回退方式。oauth（默认值）在可用时使用已存储的 MCP OAuth 凭据。chatgpt 对受信任的第一方 ChatGPT origin 使用当前 ChatGPT 会话，然后回退到已存储的 OAuth。如果没有凭据来源解析成功，两种模式都可以在无身份验证的情况下连接。 |
mcp_servers.<id>.bearer_token_env_var |
string |
为 MCP HTTP 服务器提供 bearer token 的环境变量。 |
mcp_servers.<id>.http_headers |
map<string,string> |
每个 MCP HTTP 请求中包含的静态 HTTP 标头。 |
mcp_servers.<id>.env_http_headers |
map<string,string> |
从环境变量填充的 MCP HTTP 服务器 HTTP 标头。 |
mcp_servers.<id>.enabled |
boolean |
禁用 MCP 服务器，但不移除其配置。 |
mcp_servers.<id>.required |
boolean |
为 true 时，如果此已启用 MCP 服务器无法初始化，则启动或恢复失败。 |
mcp_servers.<id>.startup_timeout_sec |
number |
覆盖 MCP 服务器默认的 10 秒启动超时时间。 |
mcp_servers.<id>.startup_timeout_ms |
number |
以毫秒为单位的 startup_timeout_sec 别名。 |
mcp_servers.<id>.tool_timeout_sec |
number |
覆盖 MCP 服务器默认的每个工具 60 秒超时时间。 |
mcp_servers.<id>.enabled_tools |
array<string> |
MCP 服务器暴露的工具名称允许列表。 |
mcp_servers.<id>.disabled_tools |
array<string> |
在 MCP 服务器的 enabled_tools 之后应用的拒绝列表。 |
mcp_servers.<id>.default_tools_approval_mode |
auto | prompt | writes | approve |
此服务器上 MCP 工具的默认批准行为，除非存在按工具覆盖设置。 |
mcp_servers.<id>.tools.<tool>.approval_mode |
auto | prompt | writes | approve |
此服务器上单个 MCP 工具的按工具批准行为覆盖设置。 |
mcp_servers.<id>.scopes |
array<string> |
向该 MCP 服务器进行身份验证时请求的 OAuth 作用域。 |
mcp_servers.<id>.oauth_resource |
string |
MCP 登录期间要包含的可选 RFC 8707 OAuth resource 参数。 |
mcp_servers.<id>.experimental_environment |
local | remote |
MCP 服务器的实验性部署位置。remote 通过远程执行器环境启动 stdio 服务器；可流式传输 HTTP 的远程部署尚未实现。 |
agents |
table |
多代理设置和自定义角色声明。标量设置名称已保留，不能用作自定义角色名称。 |
agents.enabled |
boolean |
启用或禁用多代理工具（默认值：true）。 |
agents.max_concurrent_threads_per_session |
number |
可同时打开的已生成代理线程最大数量，不包括主线程。未设置时，由 Codex 选择默认值。 |
agents.max_threads |
number |
agents.max_concurrent_threads_per_session 的旧版别名。 |
agents.default_subagent_model |
string |
已生成代理的默认模型。显式指定的生成模型优先。 |
agents.default_subagent_reasoning_effort |
string |
已生成代理的默认推理力度。显式指定的生成力度优先。 |
agents.interrupt_message |
boolean |
代理轮次被中断时记录一条模型可见消息（默认值：true）。 |
agents.<name>.description |
string |
Codex 在选择和生成该代理类型时显示的角色指导。 |
agents.<name>.config_file |
string (path) |
该角色的 TOML 配置层路径；相对路径相对于声明该角色的配置文件解析。 |
memories.generate_memories |
boolean |
为 false 时，新创建的线程不会存储为记忆生成输入。默认为 true。 |
memories.use_memories |
boolean |
为 false 时，Codex 不会将现有记忆注入未来会话。默认为 true。 |
memories.disable_on_external_context |
boolean |
为 true 时，使用 MCP 工具调用、网页搜索或工具搜索等外部上下文的线程不会参与记忆生成。默认为 false。旧版别名：memories.no_memories_if_mcp_or_web_search。 |
memories.max_raw_memories_for_consolidation |
number |
全局整合时保留的最近原始记忆最大数量。默认为 256，上限为 4096。 |
memories.max_unused_days |
number |
记忆上次使用后，在不再符合整合条件前允许经过的最大天数。默认为 30，限制在 0-365 范围内。 |
memories.max_rollout_age_days |
number |
参与记忆生成的线程最大存续天数。默认为 30，限制在 0-90 范围内。 |
memories.max_rollouts_per_startup |
number |
每次启动处理的 rollout 候选最大数量。默认为 16，上限为 128。 |
memories.min_rollout_idle_hours |
number |
在线程符合记忆生成条件前必须经过的最短空闲时间。默认为 6，限制在 1-48 范围内。 |
memories.min_rate_limit_remaining_percent |
number |
开始生成记忆前，Codex 速率限制窗口中必须剩余的最低百分比。默认为 25，限制在 0-100 范围内。 |
memories.extract_model |
string |
按线程提取记忆时的可选模型覆盖值。 |
memories.consolidation_model |
string |
全局整合记忆时的可选模型覆盖值。 |
features.unified_exec |
boolean |
使用统一的、基于 PTY 的 exec 工具（稳定；除 Windows 外默认启用）。 |
features.shell_snapshot |
boolean |
对 shell 环境进行快照以加快重复命令执行（稳定；默认开启）。 |
features.multi_agent |
boolean |
启用多代理协作工具（spawn_agent、send_input、resume_agent、wait_agent 和 close_agent）（稳定；默认开启）。 |
features.goals |
boolean |
启用持久化目标和自动继续（稳定；默认开启）。 |
features.remote_plugin |
boolean |
启用远程插件目录（稳定；默认开启）。 |
features.personality |
boolean |
启用个性选择控件（稳定；默认开启）。 |
features.network_proxy |
boolean | table |
启用沙箱网络。设置 domains 等网络策略选项时使用表形式（实验性功能；默认关闭）。 |
features.network_proxy.enabled |
boolean |
启用沙箱网络。默认为 false。 |
features.network_proxy.domains |
map<string, allow | deny> |
沙箱网络的域名策略。默认未设置，这意味着在添加 allow 规则前不允许访问外部目标。支持精确主机、仅匹配子域名的 *.example.com、匹配根域名及子域名的 **.example.com，以及全局 * 允许规则；建议使用范围明确的规则，因为 * 会广泛开放公共出站访问。为阻止的目标添加 deny 规则；冲突时 deny 优先。 |
features.network_proxy.unix_sockets |
map<string, allow | deny> |
沙箱网络的 Unix socket 策略。默认未设置；为允许的 socket 添加 allow 条目。 |
features.network_proxy.allow_local_binding |
boolean |
允许更广泛的本地/私有网络访问。默认为 false；精确的本地 IP 字面量或 localhost 允许规则仍可允许特定本地目标。 |
features.network_proxy.enable_socks5 |
boolean |
提供 SOCKS5 支持。默认为 true。 |
features.network_proxy.enable_socks5_udp |
boolean |
允许通过 SOCKS5 使用 UDP。默认为 true。 |
features.network_proxy.allow_upstream_proxy |
boolean |
允许通过环境中的上游代理进行链式连接。默认为 true。 |
features.network_proxy.dangerously_allow_non_loopback_proxy |
boolean |
允许非 loopback 监听地址。默认为 false；启用后可能使代理监听器暴露到 localhost 之外。 |
features.network_proxy.dangerously_allow_all_unix_sockets |
boolean |
允许任意 Unix socket 目标，而不是仅允许白名单中的目标。默认为 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.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"。 |
features.shell_tool |
boolean |
启用用于运行命令的默认 shell 工具（稳定；默认开启）。 |
features.enable_request_compression |
boolean |
在支持时使用 zstd 压缩流式请求正文（稳定；默认开启）。 |
features.skill_mcp_dependency_install |
boolean |
允许为技能提示并安装缺失的 MCP 依赖（稳定；默认开启）。 |
features.fast_mode |
boolean |
在 TUI 中启用模型目录服务层级选择，包括当前模型声明支持的 Fast 层级命令（稳定；默认开启）。 |
features.prevent_idle_sleep |
boolean |
在轮次正在运行期间阻止计算机进入睡眠状态（实验性功能；默认关闭）。 |
suppress_unstable_features_warning |
boolean |
禁止在启用开发中的功能标志时显示警告。 |
model_providers.<id> |
table |
自定义提供商定义。内置提供商 ID（openai、ollama 和 lmstudio）已保留，不能覆盖。 |
model_providers.<id>.name |
string |
自定义模型提供商的显示名称。 |
model_providers.<id>.base_url |
string |
模型提供商的 API 基础 URL。 |
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>.requires_openai_auth |
boolean |
提供商使用 OpenAI 身份验证（默认为 false）。 |
model_providers.<id>.wire_api |
responses |
提供商使用的协议。responses 是唯一支持的值；省略时默认为该值。 |
model_providers.<id>.query_params |
map<string,string> |
附加到提供商请求的额外查询参数。 |
model_providers.<id>.http_headers |
map<string,string> |
添加到提供商请求的静态 HTTP 标头。 |
model_providers.<id>.env_http_headers |
map<string,string> |
存在时从环境变量填充的 HTTP 标头。 |
model_providers.<id>.request_max_retries |
number |
向提供商发送 HTTP 请求时的重试次数（默认值：4）。 |
model_providers.<id>.stream_max_retries |
number |
SSE 流中断时的重试次数（默认值：5）。 |
model_providers.<id>.stream_idle_timeout_ms |
number |
SSE 流的空闲超时时间（毫秒，默认值：300000）。 |
model_providers.<id>.supports_websockets |
boolean |
该提供商是否支持 Responses API WebSocket 传输。 |
model_providers.<id>.auth |
table |
自定义提供商的命令驱动 bearer token 配置。不要与 env_key、experimental_bearer_token 或 requires_openai_auth 组合使用。 |
model_providers.<id>.auth.command |
string |
Codex 需要 bearer token 时运行的命令。该命令必须将 token 输出到 stdout。 |
model_providers.<id>.auth.args |
array<string> |
传递给 token 命令的参数。 |
model_providers.<id>.auth.timeout_ms |
number |
token 命令的最大运行时间（毫秒；默认值：5000）。 |
model_providers.<id>.auth.refresh_interval_ms |
number |
Codex 主动刷新 token 的频率（毫秒；默认值：300000）。设置为 0 时，仅在身份验证重试后刷新。 |
model_providers.<id>.auth.cwd |
string (path) |
token 命令的工作目录。 |
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 取决于模型）。 |
plan_mode_reasoning_effort |
none | minimal | low | medium | high | xhigh |
Plan 模式专用的推理覆盖设置。未设置时，Plan 模式使用其内置预设默认值。 |
model_reasoning_summary |
auto | concise | detailed | none |
选择推理摘要的详细程度，或完全禁用摘要。 |
model_verbosity |
low | medium | high |
可选的 GPT-5 Responses API 详细程度覆盖设置；未设置时，使用所选模型或预设的默认值。 |
model_supports_reasoning_summaries |
boolean |
强制 Codex 发送或不发送推理元数据。 |
shell_environment_policy.inherit |
all | core | none |
生成子进程时的基础环境继承策略。 |
shell_environment_policy.ignore_default_excludes |
boolean |
在运行其他筛选器之前保留名称中包含 KEY、SECRET 或 TOKEN 的变量。 |
shell_environment_policy.exclude |
array<string> |
在默认规则之后移除环境变量的 glob 模式。 |
shell_environment_policy.include_only |
array<string> |
模式白名单；设置后仅保留匹配的变量。 |
shell_environment_policy.set |
map<string,string> |
注入每个子进程的显式环境覆盖设置。 |
shell_environment_policy.experimental_use_profile |
boolean |
生成子进程时使用用户 shell 配置文件。 |
project_root_markers |
array<string> |
项目根目录标记文件名列表；搜索项目根目录时用于检查父目录。 |
project_doc_max_bytes |
number |
构建项目说明时从 AGENTS.md 读取的最大字节数。 |
project_doc_fallback_filenames |
array<string> |
AGENTS.md 缺失时尝试使用的其他文件名。 |
history.persistence |
save-all | none |
控制 Codex 是否将会话记录保存到 history.jsonl。 |
tool_output_token_limit |
number |
在历史记录中存储单个工具或函数输出的令牌预算。 |
background_terminal_max_timeout |
number |
空 write_stdin 轮询（后台终端轮询）的最大轮询窗口（毫秒）。默认值：300000（5 分钟）。替代旧版 background_terminal_timeout 键。 |
history.max_bytes |
number |
如果设置，则通过删除最早的条目，将历史文件大小限制在指定字节数以内。 |
file_opener |
vscode | vscode-insiders | windsurf | cursor | none |
用于从 Codex 输出打开引用的 URI 方案（默认值：vscode）。 |
otel.environment |
string |
应用于所发出 OpenTelemetry 事件的环境标签（默认值：dev）。 |
otel.exporter |
none | otlp-http | otlp-grpc |
选择 OpenTelemetry 导出器，并提供所需的端点元数据。 |
otel.trace_exporter |
none | otlp-http | otlp-grpc |
选择 OpenTelemetry 跟踪导出器，并提供所需的端点元数据。 |
otel.metrics_exporter |
none | statsig | otlp-http | otlp-grpc |
选择 OpenTelemetry 指标导出器（默认为 statsig）。 |
otel.log_user_prompt |
boolean |
选择通过 OpenTelemetry 日志导出原始用户提示。 |
otel.exporter.<id>.endpoint |
string |
OTEL 日志的导出器端点。 |
otel.exporter.<id>.protocol |
binary | json |
OTLP/HTTP 导出器使用的协议。 |
otel.exporter.<id>.headers |
map<string,string> |
OTEL 导出器请求中包含的静态标头。 |
otel.trace_exporter.<id>.endpoint |
string |
OTEL 日志的跟踪导出器端点。 |
otel.trace_exporter.<id>.protocol |
binary | json |
OTLP/HTTP 跟踪导出器使用的协议。 |
otel.trace_exporter.<id>.headers |
map<string,string> |
OTEL 跟踪导出器请求中包含的静态标头。 |
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.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 的客户端私钥路径。 |
desktop.custom_file_handlers.<id> |
table |
仅限用户级别。为 ChatGPT 桌面应用定义额外的 打开方式 目标。示例和处理程序 ID 约束请参阅添加自定义文件处理程序。 |
desktop.custom_file_handlers.<id>.label |
string |
打开方式 菜单中显示的名称。必需。 |
desktop.custom_file_handlers.<id>.icon |
string |
处理程序图标的内置资源路径、Base64 编码的 data:image/... URL、文件 URI 或本地绝对路径。必需；不支持的来源会使用默认 VS Code 图标。 |
desktop.custom_file_handlers.<id>.command |
string |
用于检测和启动的可执行文件路径或命令名称。必需。 |
desktop.custom_file_handlers.<id>.args |
array<string> |
插入命令与文件输入之间的参数（默认值：[]）。 |
desktop.custom_file_handlers.<id>.input |
path | json_argument | json_stdin |
应用向处理程序发送文件输入的方式（默认值：path）。 |
desktop.custom_file_handlers.<id>.supports_ssh |
boolean |
为 SSH 工作区中的文件提供此处理程序（默认值：false）。 |
tui |
table |
TUI 专用选项，例如启用内联桌面通知。 |
tui.notifications |
boolean | array<string> |
启用 TUI 通知；也可以限制为特定事件类型。 |
tui.notification_method |
auto | osc9 | bel |
终端通知的方法（默认值：auto）。 |
tui.notification_condition |
unfocused | always |
控制 TUI 通知仅在终端未聚焦时触发，还是无论焦点状态如何都触发。默认为 unfocused。 |
tui.animations |
boolean |
启用终端动画（欢迎屏幕、闪光效果、微调器）（默认值：true）。 |
tui.alternate_screen |
auto | always | never |
控制 TUI 是否使用备用屏幕（默认值：auto；在 Zellij 中，auto 会跳过备用屏幕以保留滚动历史）。 |
tui.vim_mode_default |
boolean |
以 Vim 普通模式而不是插入模式启动编辑器（默认值：false）。仍可通过 /vim 在每个会话中切换。 |
tui.raw_output_mode |
boolean |
以原始滚动历史模式启动 TUI，便于在终端中进行复制选择（默认值：false）。可以通过 /raw 或默认的 alt-r 键绑定切换。 |
tui.show_tooltips |
boolean |
在 TUI 欢迎屏幕中显示入门工具提示（默认值：true）。 |
tui.status_line |
array<string> | null |
TUI 页脚状态栏项目标识符的有序列表。null 会禁用状态栏。 |
tui.terminal_title |
array<string> | null |
终端窗口/标签页标题项目标识符的有序列表。默认为 ["spinner", "project"]；null 会禁用标题更新。 |
tui.theme |
string |
语法高亮主题覆盖值（kebab-case 主题名称）。 |
tui.keymap.<context>.<action> |
string | array<string> |
TUI 操作的键盘快捷键绑定。支持的上下文包括 global、chat、composer、editor、vim_normal、vim_operator、vim_text_object、pager、list 和 approval。选定的 composer 操作会回退到匹配的 tui.keymap.global 绑定；在支持时，上下文专用绑定优先。 |
tui.keymap.<context>.<action> = [] |
empty array |
在该键映射上下文中取消绑定操作。键名使用规范化字符串，例如 ctrl-a、shift-enter、page-down 或 minus。 |
plugins.<plugin>.mcp_servers.<server>.enabled |
boolean |
启用或禁用已安装插件捆绑的 MCP 服务器，而不更改插件清单。 |
plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode |
auto | prompt | writes | approve |
插件提供的 MCP 服务器上工具的默认批准行为。 |
plugins.<plugin>.mcp_servers.<server>.enabled_tools |
array<string> |
插件提供的 MCP 服务器暴露的工具允许列表。 |
plugins.<plugin>.mcp_servers.<server>.disabled_tools |
array<string> |
在插件提供的 MCP 服务器上应用于 enabled_tools 之后的拒绝列表。 |
plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode |
auto | prompt | writes | approve |
插件提供的 MCP 工具的按工具批准行为覆盖设置。 |
tui.model_availability_nux.<model> |
integer |
按模型 slug 存储的内部启动工具提示状态。 |
hide_agent_reasoning |
boolean |
在 TUI 和 codex exec 输出中隐藏推理事件。 |
show_raw_agent_reasoning |
boolean |
当前模型发出原始推理内容时显示该内容。 |
disable_paste_burst |
boolean |
禁用 TUI 中的快速粘贴检测。 |
windows_wsl_setup_acknowledged |
boolean |
记录 Windows 入门流程确认状态（仅限 Windows）。 |
chatgpt_base_url |
string |
覆盖 ChatGPT 登录流程使用的基础 URL。 |
cli_auth_credentials_store |
file | keyring | auto |
控制 CLI 存储缓存凭据的位置（基于文件的 auth.json 或操作系统密钥链）。 |
mcp_oauth_credentials_store |
auto | file | keyring |
MCP OAuth 凭据的首选存储位置。 |
mcp_oauth_callback_port |
integer |
MCP OAuth 登录期间本地 HTTP 回调服务器使用的可选固定端口。未设置时，Codex 绑定到操作系统选择的临时端口。 |
mcp_oauth_callback_url |
string |
MCP OAuth 登录的可选基础回调 URL 覆盖值（例如 devbox ingress URL）。Codex 会在发送最终 OAuth redirect_uri 前附加服务器专用的回调 ID，因此请向提供商注册完整的派生 URI。mcp_oauth_callback_port 仍控制回调监听器端口。 |
experimental_use_unified_exec_tool |
boolean |
启用统一 exec 的旧版名称；优先使用 [features].unified_exec 或 codex --enable unified_exec。 |
tools.web_search |
boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } } |
可选的网页搜索工具配置。仍接受旧版布尔形式，但对象形式允许设置搜索上下文大小、允许的域名和用户的大致位置。 |
tools.view_image |
boolean |
启用本地图像附件工具 view_image。 |
web_search |
disabled | cached | indexed | live |
网页搜索模式（默认值："cached"；cached 使用 OpenAI 维护的索引，不访问外部网络；indexed 仅在搜索索引控制下允许外部访问；如果使用 --yolo 或其他完全访问沙箱设置，则默认为 "live"）。使用 "live" 进行不受限制的实时检索，或使用 "disabled" 移除该工具。 |
default_permissions |
string |
应用于沙箱工具调用的默认权限配置文件名称。内置配置文件为 :read-only、:workspace 和 :danger-full-access；自定义配置文件名称需要匹配的 [permissions.<name>] 表。不要与 sandbox_mode 或 [sandbox_workspace_write] 组合使用。 |
permissions.<name>.description |
string |
此命名配置文件的人类可读描述。配置文件不会通过 extends 继承父配置文件的描述。 |
permissions.<name>.extends |
string |
在此命名配置文件之前应用的可选父配置文件。可设置为其他命名配置文件、:read-only 或 :workspace；:danger-full-access、未定义的父配置文件和循环会被拒绝。 |
permissions.<name>.workspace_roots |
table |
配置文件定义的工作区根目录，这些目录会与会话的运行时工作区根目录一起接收 :workspace_roots 文件系统规则。 |
permissions.<name>.workspace_roots.<path> |
boolean |
当值为 true 时，将路径加入配置文件的工作区根目录集合。禁用的条目仍保持非活动状态。 |
permissions.<name>.filesystem |
table |
命名的文件系统权限配置文件。每个键都是绝对路径或特殊标记，例如 :minimal 或 :workspace_roots。 |
permissions.<name>.filesystem.glob_scan_max_depth |
number |
在沙箱启动前对匹配项进行快照的平台上，展开拒绝读取 glob 模式时的最大深度。设置后必须至少为 1。 |
permissions.<name>.filesystem.<path-or-glob> |
"read" | "write" | "deny" | table |
为路径、glob 模式或特殊标记授予直接访问权限，或限定该根目录下的嵌套条目。使用 "deny" 拒绝读取匹配路径。 |
permissions.<name>.filesystem.":workspace_roots".<subpath-or-glob> |
"read" | "write" | "deny" |
相对于每个有效工作区根目录的作用域文件系统访问权限。使用 "." 表示根目录本身；如 "**/*.env" 的 glob 子路径可以使用 "deny" 拒绝读取。 |
permissions.<name>.network.enabled |
boolean |
为此命名权限配置文件启用网络访问。这会更改沙箱网络策略，但不会自行启动网络代理。 |
permissions.<name>.network.proxy_url |
string |
此权限配置文件启用沙箱网络时使用的 HTTP 监听器 URL。 |
permissions.<name>.network.enable_socks5 |
boolean |
此权限配置文件启用沙箱网络时提供 SOCKS5 支持。 |
permissions.<name>.network.socks_url |
string |
此权限配置文件使用的 SOCKS5 代理端点。 |
permissions.<name>.network.enable_socks5_udp |
boolean |
启用时允许通过 SOCKS5 监听器使用 UDP。 |
permissions.<name>.network.allow_upstream_proxy |
boolean |
允许沙箱网络通过其他上游代理进行链式连接。 |
permissions.<name>.network.dangerously_allow_non_loopback_proxy |
boolean |
允许沙箱网络监听器使用非 loopback 绑定地址。启用后可能使监听器暴露到 localhost 之外。 |
permissions.<name>.network.dangerously_allow_all_unix_sockets |
boolean |
允许任意 Unix socket 目标，而不是默认的受限集合。仅在严格受控的环境中使用。 |
permissions.<name>.network.mode |
limited | full |
子进程流量使用的网络代理模式。 |
permissions.<name>.network.domains |
table |
沙箱网络的域名规则。支持精确主机、仅匹配子域名的 *.example.com、匹配根域名及子域名的 **.example.com，以及全局 * 允许规则。冲突时 deny 优先。 |
permissions.<name>.network.domains.<pattern> |
allow | deny |
允许或拒绝精确主机或范围明确的通配符模式，例如 *.example.com 或 **.example.com。 |
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>.network.allow_local_binding |
boolean |
允许通过沙箱网络访问更广泛的本地/私有网络。当此项保持为 false 时，精确的本地 IP 字面量或 localhost 允许规则仍可允许特定本地目标。 |
projects.<path>.trust_level |
string |
将项目或工作树标记为受信任或不受信任（"trusted" | "untrusted"）。不受信任的项目会跳过项目作用域的 .codex/ 层，包括项目本地配置、钩子和规则。 |
notice.hide_full_access_warning |
boolean |
记录完全访问权限警告提示的确认状态。 |
notice.hide_world_writable_warning |
boolean |
记录 Windows 全局可写目录警告的确认状态。 |
notice.hide_rate_limit_model_nudge |
boolean |
记录退出速率限制模型切换提醒的状态。 |
notice.hide_gpt5_1_migration_prompt |
boolean |
记录 GPT-5.1 迁移提示的确认状态。 |
notice.hide_gpt-5.1-codex-max_migration_prompt |
boolean |
记录 gpt-5.1-codex-max 迁移提示的确认状态。 |
notice.model_migrations |
map<string,string> |
以旧模型到新模型的映射记录已确认的模型迁移。 |
forced_login_method |
chatgpt | api |
将 Codex 限制为特定的身份验证方法。 |
forced_chatgpt_workspace_id |
string (uuid) |
将 ChatGPT 登录限制为特定的工作区标识符。 |
你可以在此处找到 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
Section titled “requirements.toml”requirements.toml 是由管理员强制执行的配置文件，用于限制用户无法覆盖的安全敏感设置。有关详情、位置和示例，请参阅管理员强制执行的要求。
对于 ChatGPT Business 和 Enterprise 用户，Codex 还可以应用从云端获取的 要求。有关优先级的详情，请参阅安全页面。
在 requirements.toml 中使用 [features]，通过与 config.toml 相同的规范键来固定运行时功能标志。要求还可以包含文档中记录的、仅适用于应用且不属于 config.toml 的键。省略的键不受约束。
受管权限配置文件允许列表要求 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 独立生效。
| 键 | 类型 | 描述 |
|---|---|---|
allowed_approval_policies |
array<string> |
approval_policy 的允许值（例如 untrusted、on-request、never 和 granular）。 |
allowed_approvals_reviewers |
array<string> |
approvals_reviewer 的允许值，例如 user 和 auto_review。 |
guardian_policy_config |
string |
用于自动审查的托管 Markdown 策略说明。其优先级高于本地 [auto_review].policy。空值会被忽略。 |
allowed_permission_profiles |
table<boolean> |
允许的权限配置文件完整列表。设置为 true 的配置文件允许使用。省略或设置为 false 的配置文件会被拒绝，包括未来版本中新增的配置文件。合并需求来源时，条目按配置文件名称匹配。 |
allowed_permission_profiles.<name> |
boolean |
允许或拒绝已加载配置或需求来源中定义的内置或自定义权限配置文件。后续的更高优先级需求来源可以使用 false，关闭先前较低优先级来源允许的配置文件。 |
default_permissions |
string |
托管的默认权限配置文件。该配置文件必须由 allowed_permission_profiles 允许。请显式设置此项以获得可预测的行为；如果省略，只有在显式允许 :workspace 和 :read-only 时，Codex 才会将默认值设为 :workspace。 |
enforce_residency |
string |
要求 Codex 服务流量使用受支持的数据驻留区域。目前接受 us。 |
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 指南。 |
allowed_sandbox_modes |
array<string> |
sandbox_mode 的允许值。 |
windows |
table |
原生 Windows 沙箱需求。 |
windows.allowed_sandbox_implementations |
array<string> |
windows.sandbox 的允许原生 Windows 沙箱实现（elevated 和 unelevated）。列表不能为空。当两者都允许且未选择模式时，Codex 优先使用 elevated。 |
remote_sandbox_config |
array<table> |
特定主机的沙箱需求。第一个 hostname_patterns 与解析出的主机名匹配的条目，会覆盖该需求来源顶层的 allowed_sandbox_modes。特定主机的条目目前只能覆盖沙箱模式。 |
remote_sandbox_config[].hostname_patterns |
array<string> |
不区分大小写的主机名模式。支持用 * 匹配任意字符序列，用 ? 匹配一个字符。 |
remote_sandbox_config[].allowed_sandbox_modes |
array<string> |
此特定主机条目匹配时应用的允许沙箱模式。 |
allowed_web_search_modes |
array<string> |
web_search 的允许值（disabled、cached、indexed、live）。始终允许 disabled；空列表实际上只允许 disabled。 |
allow_managed_hooks_only |
boolean |
为 true 时，Codex 跳过用户、项目、会话和插件钩子，同时仍允许来自 requirements.toml 和其他托管配置层的托管钩子。 |
allow_appshots |
boolean |
设置为 false 可为托管用户禁用 Appshots。省略时，需求不会限制 Appshots，其行为遵循产品的正常可用性。 |
allow_remote_control |
boolean |
设置为 false 可为托管用户禁用设备远程控制。省略时，需求不会限制设备远程控制，其行为遵循产品的正常可用性。 |
features.plugin_sharing |
boolean |
在云托管的 requirements.toml 中设置为 false，可禁用本地构建插件的工作区共享。 |
features |
table |
固定的功能值。运行时功能请使用 config.toml 中的规范名称；此处也支持已记录的仅应用需求键。 |
features.<name> |
boolean |
要求已记录的运行时功能或应用功能保持启用或禁用。 |
features.apps |
boolean |
为托管用户固定 Apps 集成的启用或禁用状态。 |
features.in_app_browser |
boolean |
在 requirements.toml 中设置为 false，可禁用内置浏览器窗格。 |
features.browser_use |
boolean |
在 requirements.toml 中设置为 false，可禁用浏览器中的 Computer Use 以及 Browser Agent 的可用性。 |
features.browser_use_external |
boolean |
在 requirements.toml 中设置为 false，可禁用外部浏览器中的 Computer Use。 |
features.browser_use_full_cdp_access |
boolean |
在 requirements.toml 中设置为 false，可禁用本地运行时中的完整 Chrome DevTools Protocol 访问，包括 Browser Developer 模式，并阻止 ChatGPT 桌面应用启用相应设置。省略时，遵循产品的正常可用性。 |
features.fast_mode |
boolean |
为托管用户固定规范 fast_mode 功能的启用或禁用状态。 |
features.guardian_approval |
boolean |
为托管用户固定 Guardian 审批可用性的启用或禁用状态。 |
features.memories |
boolean |
为托管用户固定 Memories 可用性的启用或禁用状态。 |
features.multi_agent |
boolean |
为托管用户固定多智能体可用性的启用或禁用状态。 |
features.plugins |
boolean |
为托管用户固定插件可用性的启用或禁用状态。 |
features.remote_plugin |
boolean |
为托管用户固定远程插件目录是否可用。 |
features.computer_use |
boolean |
在 requirements.toml 中设置为 false，可禁用 Computer Use、Record & Replay 以及相关的安装或启用流程。 |
features.workspace_dependencies |
boolean |
为托管用户固定捆绑的工作区依赖运行时是否可用。 |
computer_use |
table |
从 requirements.toml 强制执行的 Computer Use 要求。 |
computer_use.allow_locked_computer_use |
boolean |
设置为 false，可阻止 Computer Use 在托管 macOS 设备锁定后运行。省略时，锁定状态下的使用不受要求限制。 |
experimental_network |
table |
从 requirements.toml 强制执行的网络访问要求。这些限制独立于 features.network_proxy，可以在不启用用户功能标志的情况下配置沙箱网络。 |
experimental_network.enabled |
boolean |
启用沙箱网络要求。当活动沙箱关闭命令网络时，此设置不会授予网络访问权限。 |
experimental_network.http_port |
integer |
用于 [experimental_network] 要求的回环 HTTP 监听端口。 |
experimental_network.socks_port |
integer |
用于 [experimental_network] 要求的回环 SOCKS5 监听端口。 |
experimental_network.allow_upstream_proxy |
boolean |
允许沙箱网络通过环境中的上游代理进行链式连接。 |
experimental_network.dangerously_allow_non_loopback_proxy |
boolean |
允许 [experimental_network] 要求使用非回环监听地址。启用后，监听器可能暴露给 localhost 之外的地址。 |
experimental_network.dangerously_allow_all_unix_sockets |
boolean |
允许任意 Unix socket 目标，而不是仅允许访问白名单中的目标。仅在严格控制的环境中使用。 |
experimental_network.domains |
map<string, allow | deny> |
用于沙箱网络的管理员域名策略，采用映射形式。支持精确主机、仅匹配子域名的 *.example.com、匹配根域名及子域名的 **.example.com，以及全局 * 允许规则；由于 * 会广泛开放公共出站访问，建议优先使用范围明确的规则。发生冲突时，deny 优先。不要与 experimental_network.allowed_domains 或 experimental_network.denied_domains 组合使用。 |
experimental_network.allowed_domains |
array<string> |
用于沙箱网络的管理员允许规则列表。不要与 experimental_network.domains 组合使用。 |
experimental_network.denied_domains |
array<string> |
用于沙箱网络的管理员拒绝规则列表。不要与 experimental_network.domains 组合使用。 |
experimental_network.managed_allowed_domains_only |
boolean |
为 true 时，在沙箱网络要求生效期间，仅管理员管理的允许规则有效；用户添加的白名单规则会被忽略。如果没有托管允许规则，用户添加的域名允许规则不会生效。 |
experimental_network.unix_sockets |
map<string, allow | deny> |
用于沙箱网络的管理员管理 Unix socket 策略。 |
experimental_network.allow_local_binding |
boolean |
允许沙箱网络访问更广泛的本地网络或私有网络。即使此设置保持为 false，精确的本地 IP 字面量或 localhost 允许规则仍可允许访问特定本地目标。 |
hooks |
table |
管理员强制执行的托管生命周期钩子。需要托管钩子目录，并使用与 config.toml 中内联 [hooks] 相同的事件架构。 |
hooks.managed_dir |
string (absolute path) |
macOS 和 Linux 上包含托管钩子脚本的目录。Codex 会在加载托管钩子前验证该路径为绝对路径且存在。 |
hooks.windows_managed_dir |
string (absolute path) |
Windows 上包含托管钩子脚本的目录。Codex 会在加载托管钩子前验证该路径为绝对路径且存在。 |
hooks. |
array<table> |
钩子事件的匹配器组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。 |
hooks.[].hooks |
array<table> |
匹配器组的钩子处理程序。目前支持命令钩子；提示词和智能体钩子处理程序会被解析但跳过。 |
hooks.[].hooks[].commandWindows |
string |
仅限 Windows 的命令钩子命令覆盖值。也接受 TOML 别名 command_windows。 |
permissions.filesystem.deny_read |
array<string> |
管理员强制执行的文件系统读取拒绝规则。条目可以是路径或 glob 模式，用户无法通过本地配置削弱这些规则。 |
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.executable |
string |
stdio 服务器配置的 command 必须精确匹配的可执行文件。 |
mcp_servers.<id>.identity.command.args |
array<table> |
stdio 服务器的有序参数匹配器。配置的参数列表长度必须相同，并且每个位置都必须匹配。命令匹配器不会检查 cwd、env 或 env_vars。 |
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.args[].expression |
string |
regex 参数匹配器使用的正则表达式。表达式必须有效，并匹配完整的参数值。 |
mcp_servers.<id>.identity.url |
string | table |
通过精确的 URL 字符串允许 MCP streamable HTTP 服务器，或使用包含 exact、prefix 或 regex 值匹配器的表。 |
mcp_servers.<id>.identity.url.match |
exact | prefix | regex |
配置的 MCP 服务器 URL 的匹配操作。 |
mcp_servers.<id>.identity.url.value |
string |
exact 或 prefix URL 匹配器使用的值。 |
mcp_servers.<id>.identity.url.expression |
string |
regex URL 匹配器使用的正则表达式。表达式必须有效，并匹配完整的 URL 值。 |
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.executable |
string |
插件捆绑的 stdio 服务器的配置命令必须精确匹配的可执行文件。 |
plugins.<plugin>.mcp_servers.<server>.identity.command.args |
array<table> |
插件捆绑的 stdio 服务器的有序参数匹配器。配置的参数列表长度必须相同，并且每个位置都必须匹配。 |
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.args[].expression |
string |
regex 参数匹配器使用的正则表达式。表达式必须匹配完整的参数值。 |
plugins.<plugin>.mcp_servers.<server>.identity.url |
string | table |
通过精确的 URL 字符串允许插件的 streamable HTTP MCP 服务器，或使用包含 exact、prefix 或 regex 值匹配器的表。 |
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 匹配器使用的值。 |
plugins.<plugin>.mcp_servers.<server>.identity.url.expression |
string |
regex URL 匹配器使用的正则表达式。表达式必须匹配完整的 URL 值。 |
marketplaces |
table |
插件市场来源的管理员需求。当 restrict_to_allowed_sources 为 true 时，规则生效。 |
marketplaces.restrict_to_allowed_sources |
boolean |
为 true 时，要求用户配置的市场来源与 allowed_sources 匹配，适用于添加市场、安装插件以及刷新已配置的 Git 市场。当保留的来源和名称匹配时，由 Codex 管理的 OpenAI 市场仍然允许使用。此设置不会在运行时过滤已配置的用户市场。 |
marketplaces.allowed_sources |
table |
按管理员选择的规则名称索引的允许市场来源。不同名称会在各需求层之间累积；同名字段使用正常的层级优先级。 |
marketplaces.allowed_sources.<name> |
table |
一个允许的来源规则。需求合并后的最终 source 值决定 Codex 如何解释同级字段。 |
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.allowed_sources.<name>.ref |
string |
git 规则的可选精确 Git ref。省略时，该规则允许匹配仓库的任意 ref。 |
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 要求使用绝对路径，并在规范化后比较路径。 |
apps |
table |
按应用标识符索引的托管应用需求。需求可以禁用应用，或限制单个工具的审批行为。 |
apps.<id>.enabled |
boolean |
设置为 false 可禁用应用。当合并多个需求来源时，禁用需求仍然具有限制性。 |
apps.<id>.tools.<tool>.approval_mode |
auto | prompt | writes | approve |
设置单个应用工具的托管审批模式。 |
rules |
table |
与 .rules 文件合并的管理员强制命令规则。需求规则必须具有限制性。 |
rules.prefix_rules |
array<table> |
强制前缀规则列表。每条规则都必须包含 pattern 和 decision。 |
rules.prefix_rules[].pattern |
array<table> |
以模式令牌表示的命令前缀。每个令牌设置 token 或 any_of。 |
rules.prefix_rules[].pattern[].token |
string |
此位置的单个字面量令牌。 |
rules.prefix_rules[].pattern[].any_of |
array<string> |
此位置允许的替代令牌列表。 |
rules.prefix_rules[].decision |
prompt | forbidden |
必填。需求规则只能提示或禁止，不能允许。 |
rules.prefix_rules[].justification |
string |
可选的非空理由，会显示在审批提示或拒绝消息中。 |