配置参考

配置参考

查询 OpenAI Codex 的 `config.toml` 和 `requirements.toml` 配置参考，了解配置键、类型、默认值、限制规则、审批行为与本地客户端运行方式，并帮助团队在实际项目中查找配置键、文件位置、权限边界、工具接入和排查线索，把 Codex 行为沉淀成稳定、可复用的协作规范。

配置参考#

Codex 中文站说明： 本页围绕“配置参考”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。

config.toml 与 requirements.toml 的完整参考

把本页当成 Codex 配置文件的可检索参考手册来使用。若你想先看概念解释和典型示例，请从 配置基础 和 高级配置 开始。

config.toml#

用户级配置位于 ~/.codex/config.toml。你也可以在 .codex/config.toml 中添加项目级覆盖配置。Codex 只会在你信任该项目时加载项目级 .codex/ 配置层。

项目级配置不能覆盖机器本地的 provider、认证、host-owned app request metadata、通知、配置档案选择或 telemetry 路由键。Codex 会忽略项目本地 .codex/config.toml 中的 openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url 和 otel；provider、通知和 telemetry 键应放在用户级配置中。配置档案文件与 config.toml 放在同一目录，格式为 $CODEX_HOME/profile-name.config.toml，并通过 --profile profile-name 选择。

对于和沙箱、审批有关的配置键，例如 approval_policy、sandbox_mode 和 sandbox_workspace_write.*，建议把本页与 沙箱与审批、可写根目录中的受保护路径 以及 网络访问 搭配阅读。关于 beta 权限配置档案，请参见权限。

键类型 / 可选值说明
modelstring要使用的模型，例如 gpt-5.5。
review_modelstring/review 使用的可选模型覆盖值（默认使用当前 session 模型）。
model_providerstring从 model_providers 中选择的提供方 ID（默认 openai）。
openai_base_urlstring内建 openai model provider 的 base URL 覆盖值。
model_context_windownumber当前激活模型可用的 context window token 数。
model_auto_compact_token_limitnumber触发自动历史压缩的 token 阈值（未设置时使用模型默认值）。
model_auto_compact_token_limit_scope`total \body_after_prefix`控制自动压缩阈值统计完整活动上下文（total，默认），还是只统计已携带压缩窗口前缀之后新增的内容（body_after_prefix）。
model_catalog_jsonstring (path)启动时加载的可选 JSON model catalog 路径。选中的 $CODEX_HOME/profile-name.config.toml 配置档案文件可以覆盖该值。
oss_provider`lmstudio \ollama`运行 --oss 时使用的默认本地 provider（未设置时会提示用户选择）。
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_approvalboolean为 true 时，允许沙箱升级时的审批提示显示出来。
approval_policy.granular.rulesboolean为 true 时，允许由 execpolicy 提示词规则触发的审批提示显示出来。
approval_policy.granular.mcp_elicitationsboolean为 true 时，允许 MCP elicitation 提示真正显示出来，而不是被自动拒绝。
approval_policy.granular.request_permissionsboolean为 true 时，允许 request_permissions 工具触发的提示显示出来。
approval_policy.granular.skill_approvalboolean为 true 时，允许技能脚本触发的审批提示显示出来。
approvals_reviewer`user \auto_review`在 on-request 或细粒度审批策略下，指定由谁审核符合条件的审批提示。默认是 user；设为 auto_review 时，会由评审子智能体自动审核。这不会改变沙箱边界，也不会影响原本已在沙箱内允许执行的动作。
auto_review.policystring自动评审使用的本地 Markdown 策略指令。若管理员下发了 guardian_policy_config，则以托管配置为准；空值会被忽略。
allow_login_shellboolean是否允许基于 shell 的工具使用 login-shell 语义。默认 true；若设为 false，则 login = true 的请求会被拒绝，未显式设置 login 时默认使用非 login shell。
sandbox_mode`read-only \workspace-write \danger-full-access`命令执行期间的文件系统与网络访问沙箱策略。
sandbox_workspace_write.writable_rootsarray当 sandbox_mode = "workspace-write" 时的额外可写根目录。
sandbox_workspace_write.network_accessboolean在 workspace-write sandbox 中允许向外联网。
sandbox_workspace_write.exclude_tmpdir_env_varboolean在 workspace-write 模式下，将 $TMPDIR 排除出可写根目录。
sandbox_workspace_write.exclude_slash_tmpboolean在 workspace-write 模式下，将 /tmp 排除出可写根目录。
windows.sandbox`unelevated \elevated`在 Windows 原生模式下运行 Codex 时使用的原生 sandbox 模式（仅 Windows）。
windows.sandbox_private_desktopboolean在原生 Windows 上，默认让最终 sandboxed 子进程运行在私有桌面中。只有为兼容旧版 Winsta0\Default 行为时才应设为 false。
computer_use.windows.always_allowed_app_idsarrayComputer Use 无需提示即可打开的 Windows app 标识符。列表外的 app 仍需审批；可在 ChatGPT 桌面应用的 Computer Use 设置中删除已保存条目。
notifyarray用于通知的命令；Codex 会向其传入一个 JSON payload。
check_for_update_on_startupboolean启动时是否检查 Codex 更新（只有在更新由中心化方式统一管理时才建议设为 false）。
feedback.enabledboolean在本地客户端中启用通过 /feedback 提交反馈（默认 true）。
analytics.enabledboolean为当前机器 / 配置档案启用或关闭分析数据上报。未设置时使用客户端默认值。
instructionsstring预留给未来使用；当前请优先使用 model_instructions_file 或 AGENTS.md。
developer_instructionsstring注入到会话中的额外开发者指令（可选）。
log_dirstring (path)Codex 写日志文件的目录，例如 codex-tui.log；默认值是 $CODEX_HOME/log。
sqlite_homestring (path)Codex 存放基于 SQLite 的状态数据库目录，供智能体作业与其他可恢复运行时状态使用。
compact_promptstring对历史压缩提示词的内联覆盖。
model_instructions_filestring (path)用于替代内建 instructions 的文件，而不是使用 AGENTS.md。
personality`none \friendly \pragmatic`对支持 supportsPersonality 的模型设置默认沟通风格；可在对话线程 / 会话轮次级别或通过 /personality 覆盖。
service_tierstring新会话轮次的 service tier 偏好。使用 fast 或当前模型公布的其它 tier；fast 会映射为请求值 priority。
experimental_compact_prompt_filestring (path)从文件加载历史压缩提示词覆盖值（实验性）。
skills.configarray保存在 config.toml 中的按技能启用覆盖配置。
skills.config..pathstring (path)指向技能文件夹的路径，该文件夹内应包含 SKILL.md。
skills.config..enabledboolean启用或禁用对应技能。
apps..enabledboolean启用或禁用某个具体 app / connector（默认 true）。
apps._default.enabledboolean对所有 app 生效的默认启用状态，除非被单个 app 覆盖。
apps._default.destructive_enabledboolean默认是否允许带 destructive_hint = true 的 app 工具。
apps._default.open_world_enabledboolean默认是否允许带 open_world_hint = true 的 app 工具。
apps._default.approvals_reviewer`user \auto_review`app 工具审批提示的默认 reviewer，除非被单个 app 覆盖。省略时，app 会继承顶层 approvals_reviewer。
apps._default.default_tools_approval_mode`auto \prompt \writes \approve`没有单 app 或单工具覆盖时，app 工具使用的默认审批行为。
apps..destructive_enabledboolean是否允许该 app 中声明了 destructive_hint = true 的工具。
apps..open_world_enabledboolean是否允许该 app 中声明了 open_world_hint = true 的工具。
apps..default_tools_enabledboolean该 app 中工具的默认启用状态，除非单个工具另有覆盖。
apps..approvals_reviewer`user \auto_review`该 app 工具审批提示的 reviewer。会覆盖 apps._default.approvals_reviewer。
apps..default_tools_approval_mode`auto \prompt \writes \approve`该 app 中工具的默认审批行为，除非单个工具另有覆盖。
apps..tools..enabledboolean对单个 app 工具的启用状态覆盖，例如 repos/list。
apps..tools..approval_mode`auto \prompt \writes \approve`对单个 app 工具的审批行为覆盖。
tool_suggest.discoverablesarray
允许对额外的可发现连接器或插件给出工具建议。每一项都应包含 type = "connector" 或 "plugin"，以及对应的 id。
tool_suggest.disabled_toolsarray
禁用特定可发现连接器或插件的工具建议。每一项都应包含 type = "connector" 或 "plugin"，以及对应的 id。
features.appsboolean启用 App（连接器）集成（Stable；默认开启）。
features.hooksboolean启用从 hooks.json 或内联 [hooks] 配置加载的生命周期钩子。features.codex_hooks 是已弃用 alias。
features.code_mode.enabledboolean启用 code mode 功能配置。该功能仍在开发中，默认关闭。
features.code_mode.excluded_tool_namespacesarraycode mode 从嵌套 code-mode 工具指引和 executor 暴露中排除的工具 namespace。
features.code_mode.direct_only_tool_namespacesarraycode mode 只能通过直接工具调用使用的工具 namespace。
features.rollout_budget.enabledboolean启用 rollout budget 跟踪。该功能仍在开发中，默认关闭。启用后必须设置 features.rollout_budget.limit_tokens。
features.rollout_budget.limit_tokensintegerrollout budget 跟踪使用的正 token 上限。启用 rollout budget 时必填。
features.rollout_budget.reminder_interval_tokensintegerrollout budget 提醒之间的正 token 间隔。默认是 limit_tokens 的 10%，最小为 1 token。
features.rollout_budget.sampling_token_weightnumberrollout budget 记账时 sampled tokens 使用的有限非负乘数。默认 1.0。
features.rollout_budget.prefill_token_weightnumberrollout budget 记账时 prefill tokens 使用的有限非负乘数。默认 1.0。
hookstable在 config.toml 中内联配置的生命周期钩子。使用与 hooks.json 相同的事件 schema；示例和支持事件请参见 Hooks。
hooks.array
某个钩子事件的 matcher 分组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。
hooks.[].hooksarray
matcher 分组下的钩子处理器。当前支持 command hooks；prompt 和 agent hook handlers 会被解析但跳过。
hooks.[].hooks[].commandWindowsstringcommand hooks 的 Windows 专用命令覆盖。也接受 TOML alias command_windows。
features.memoriesboolean启用 Memories（默认关闭）。
mcp_servers..commandstringMCP stdio server 的启动命令。
mcp_servers..argsarray传给 MCP stdio server 启动命令的参数。
mcp_servers..envmap转发给 MCP stdio server 的环境变量。
mcp_servers..env_vars`array<string \{ name = string, source = "local" \"remote" }>`额外允许转发给 MCP stdio server 的环境变量。字符串条目默认使用 source = "local"；只有在 executor-backed remote stdio 场景下才使用 source = "remote"。
mcp_servers..cwdstringMCP stdio server 进程的工作目录。
mcp_servers..urlstringMCP streamable HTTP server 的端点。
mcp_servers..auth`oauth \chatgpt`在已配置 bearer token 和 authorization headers 之后使用的 MCP HTTP server 认证回退方式。oauth（默认）优先使用已保存的 MCP OAuth 凭据；chatgpt 对受信任的第一方 ChatGPT origin 使用当前 ChatGPT 会话，再回退到已保存的 OAuth。若所有凭据来源都未解析成功，两种模式都可以在无认证状态下连接。
mcp_servers..bearer_token_env_varstring作为 MCP HTTP server bearer token 来源的环境变量名。
mcp_servers..http_headersmap每次 MCP HTTP 请求都携带的静态 HTTP headers。
mcp_servers..env_http_headersmap对 MCP HTTP server，从环境变量填充出来的 HTTP headers。
mcp_servers..enabledboolean在不删除配置的前提下禁用一个 MCP server。
mcp_servers..requiredboolean为 true 时，若该已启用 MCP server 无法初始化，则启动 / 恢复会失败。
mcp_servers..startup_timeout_secnumber覆盖 MCP server 默认 10 秒的启动超时。
mcp_servers..startup_timeout_msnumberstartup_timeout_sec 的毫秒别名。
mcp_servers..tool_timeout_secnumber覆盖 MCP server 默认 60 秒的单工具超时。
mcp_servers..enabled_toolsarrayMCP server 暴露的工具允许列表。
mcp_servers..disabled_toolsarrayMCP server 的 deny list；会在 enabled_tools 之后应用。
mcp_servers..default_tools_approval_mode`auto \prompt \writes \approve`该 MCP server 中工具的默认审批行为，除非有单工具覆盖。
mcp_servers..tools..approval_mode`auto \prompt \writes \approve`对该 MCP server 中单个工具的审批行为覆盖。
mcp_servers..scopesarray对该 MCP server 进行认证时请求的 OAuth 权限范围（scopes）。
mcp_servers..oauth_resourcestringMCP 登录期间附带的可选 RFC 8707 OAuth resource 参数。
mcp_servers..experimental_environment`local \remote`MCP server 的实验性运行位置。remote 会通过远程 executor 环境启动 stdio server；streamable HTTP 的 remote placement 尚未实现。
agentstable多智能体设置和自定义角色声明。标量设置名属于保留名称，不能用作自定义角色名。
agents.enabledboolean启用或停用多智能体工具（默认 true）。
agents.max_concurrent_threads_per_sessionnumber同时打开的子智能体对话线程最大数量，不含主对话线程。未设置时由 Codex 选择默认值。
agents.max_threadsnumberagents.max_concurrent_threads_per_session 的旧别名。
agents.default_subagent_modelstring子智能体的默认模型；生成时显式指定的模型优先。
agents.default_subagent_reasoning_effortstring子智能体的默认推理强度；生成时显式指定的推理强度优先。
agents.interrupt_messageboolean智能体的会话轮次被中断时，是否记录一条模型可见消息（默认 true）。
agents..descriptionstring当 Codex 选择并生成该智能体类型时展示给它的角色说明。
agents..config_filestring (path)该角色使用的 TOML 配置层路径；相对路径相对于声明该角色的配置文件解析。
memories.generate_memoriesboolean为 false 时，新创建的对话线程不会作为记忆生成输入保存。默认 true。
memories.use_memoriesboolean为 false 时，Codex 不会把现有记忆注入到后续会话中。默认 true。
memories.disable_on_external_contextboolean为 true 时，使用 MCP 工具调用、Web 搜索或工具搜索等外部上下文的对话线程不会进入记忆生成。默认 false。旧别名：memories.no_memories_if_mcp_or_web_search。
memories.max_raw_memories_for_consolidationnumber全局记忆合并保留的近期原始记忆最大数量。默认 256，上限 4096。
memories.max_unused_daysnumber记忆距离上次使用超过多少天后不再参与记忆合并。默认 30，范围限制为 0-365。
memories.max_rollout_age_daysnumber参与记忆生成的对话线程最大年龄。默认 30，范围限制为 0-90。
memories.max_rollouts_per_startupnumber每次启动处理的 rollout 候选最大数量。默认 16，上限 128。
memories.min_rollout_idle_hoursnumber对话线程进入记忆生成前需要空闲的最短时间。默认 6，范围限制为 1-48。
memories.min_rate_limit_remaining_percentnumberCodex 速率限制窗口剩余百分比达到该阈值后，才会开始记忆生成。默认 25，范围限制为 0-100。
memories.extract_modelstring针对单线程记忆提取使用的可选模型覆盖。
memories.consolidation_modelstring针对全局记忆合并使用的可选模型覆盖。
features.unified_execboolean使用统一的 PTY 支撑 exec 工具（Stable；除 Windows 外默认开启）。
features.shell_snapshotboolean快照 shell 环境，以加快重复命令（Stable；默认开启）。
features.multi_agentboolean启用多智能体协作工具，例如 spawn_agent、send_input、resume_agent、wait_agent、close_agent（Stable；默认开启）。
features.goalsboolean启用持久化 goals 与自动续跑（Stable；默认开启）。
features.remote_pluginboolean启用远程 plugin 目录（Stable；默认开启）。
features.personalityboolean启用 personality 选择控件（Stable；默认开启）。
features.network_proxy`boolean \table`启用沙箱化网络。设置 domains 等网络策略选项时使用 table 形式（实验性；默认关闭）。
features.network_proxy.enabledboolean启用沙箱化网络。默认 false。
features.network_proxy.domains`map<string, allow \deny>`沙箱化网络的域名策略。默认未设置，表示在添加 allow 规则前不允许外部目的地。支持精确主机、只匹配子域名的 *.example.com、同时匹配 apex 和子域名的 **.example.com，以及全局 allow 规则； 会宽泛打开公共出站访问，应优先使用更窄规则。添加 deny 规则可阻止目的地，冲突时 deny 优先。
features.network_proxy.unix_sockets`map<string, allow \deny>`沙箱化网络的 Unix socket 策略。默认未设置；为允许的 socket 添加 allow 条目。
features.network_proxy.allow_local_bindingboolean允许更宽的本地 / 私有网络访问。默认 false；精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。
features.network_proxy.enable_socks5boolean暴露 SOCKS5 支持。默认 true。
features.network_proxy.enable_socks5_udpboolean允许通过 SOCKS5 使用 UDP。默认 true。
features.network_proxy.allow_upstream_proxyboolean允许通过环境中的 upstream proxy 级联。默认 true。
features.network_proxy.dangerously_allow_non_loopback_proxyboolean允许非 loopback 监听器地址。默认 false；启用后可能把代理监听器暴露到 localhost 之外。
features.network_proxy.dangerously_allow_all_unix_socketsboolean允许任意 Unix socket 目的地，而不是只允许 allowlist 条目。默认 false；只能在严格受控环境中使用。
features.network_proxy.proxy_urlstring沙箱化网络的 HTTP 监听器 URL。默认 "http://127.0.0.1:3128"。
features.network_proxy.socks_urlstringSOCKS5 监听器 URL。默认 "http://127.0.0.1:8081"。
features.web_searchboolean已弃用的旧版开关；优先使用顶层 web_search 设置。
features.web_search_cachedboolean已弃用的旧版开关。若 web_search 未设置，true 会映射到 web_search = "cached"。
features.web_search_requestboolean已弃用的旧版开关。若 web_search 未设置，true 会映射到 web_search = "live"。
features.shell_toolboolean启用默认 shell 工具来运行命令（Stable；默认开启）。
features.enable_request_compressionboolean在支持时使用 zstd 压缩流式请求体（Stable；默认开启）。
features.skill_mcp_dependency_installboolean允许针对技能缺失的 MCP 依赖进行提示并安装（Stable；默认开启）。
features.fast_modeboolean启用 TUI 中基于模型目录的 service tier 选择；当当前模型声明 Fast tier 时，也会启用对应命令（Stable；默认开启）。
features.prevent_idle_sleepboolean在会话轮次正在运行时阻止机器休眠（Experimental；默认关闭）。
suppress_unstable_features_warningboolean压制开启“开发中”功能开关时显示的警告。
model_providers.table自定义模型提供方的定义。
model_providers..namestring自定义 model provider 的显示名称。
model_providers..base_urlstring该模型提供方的 API base URL。
model_providers..env_keystring提供该提供方 API key 的环境变量名。
model_providers..env_key_instructionsstring关于提供方 API key 的可选配置提示。
model_providers..experimental_bearer_tokenstring直接写在配置里的提供方 bearer token（不推荐；应优先使用 env_key）。
model_providers..requires_openai_authboolean该提供方是否使用 OpenAI 认证（默认 false）。
model_providers..wire_apiresponses该 provider 使用的协议。当前唯一支持值是 responses，且省略时默认即为此值。
model_providers..query_paramsmap附加到提供方请求上的额外 query 参数。
model_providers..http_headersmap附加到提供方请求上的静态 HTTP headers。
model_providers..env_http_headersmap仅在环境变量存在时，从环境变量填充的 HTTP headers。
model_providers..request_max_retriesnumber向该提供方发起 HTTP 请求时的重试次数（默认 4）。
model_providers..stream_max_retriesnumberSSE 流中断时的重试次数（默认 5）。
model_providers..stream_idle_timeout_msnumberSSE stream 的空闲超时（毫秒，默认 300000）。
model_providers..supports_websocketsboolean该 provider 是否支持 Responses API 的 WebSocket transport。
model_providers..authtable针对自定义提供方的命令式 bearer token 配置。不要与 env_key、experimental_bearer_token 或 requires_openai_auth 混用。
model_providers..auth.commandstring当 Codex 需要 bearer token 时要执行的命令。该命令必须把 token 打印到 stdout。
model_providers..auth.argsarray传给 token 命令的参数。
model_providers..auth.timeout_msnumbertoken 命令的最长运行时间（毫秒，默认 5000）。
model_providers..auth.refresh_interval_msnumberCodex 主动刷新的 token 周期（毫秒，默认 300000）。设为 0 时，只会在认证重试后刷新。
model_providers..auth.cwdstring (path)执行 token 命令时使用的工作目录。
model_providers.amazon-bedrock.aws.profilestring内建 amazon-bedrock provider 使用的 AWS profile 名称。
model_providers.amazon-bedrock.aws.regionstring内建 amazon-bedrock provider 使用的 AWS region。
model_reasoning_effort`minimal \low \medium \high \xhigh`在支持的模型上调整推理强度（仅 Responses API；xhigh 是否可用取决于模型）。
plan_mode_reasoning_effort`none \minimal \low \medium \high \xhigh`计划模式专用的 reasoning 覆盖值。未设置时，计划模式使用其内建预设默认值。
model_reasoning_summary`auto \concise \detailed \none`选择 reasoning summary 的详细程度，或彻底关闭 summary。
model_verbosity`low \medium \high`可选的 GPT-5 Responses API 输出详细程度覆盖值；未设置时使用模型 / 预设默认值。
model_supports_reasoning_summariesboolean强制 Codex 发送或不发送 reasoning metadata。
shell_environment_policy.inherit`all \core \none`启动子进程时的基础环境继承策略。
shell_environment_policy.ignore_default_excludesboolean在其他过滤之前，保留包含 KEY / SECRET / TOKEN 的环境变量。
shell_environment_policy.excludearray在默认过滤之后继续移除环境变量的 glob pattern 列表。
shell_environment_policy.include_onlyarray白名单 pattern；设置后只保留匹配的变量。
shell_environment_policy.setmap注入到每个子进程里的显式环境变量覆盖。
shell_environment_policy.experimental_use_profileboolean让子进程通过用户 shell profile 运行。
project_root_markersarray项目根标记文件名列表；用于向父目录搜索项目根。
project_doc_max_bytesnumber构建项目指令时，从 AGENTS.md 最多读取的字节数。
project_doc_fallback_filenamesarray当 AGENTS.md 缺失时要尝试的额外文件名。
history.persistence`save-all \none`控制 Codex 是否把 session transcript 持久保存到 history.jsonl。
tool_output_token_limitnumber在历史中保存单次 tool / function 输出时可使用的 token 预算。
background_terminal_max_timeoutnumber后台终端空 write_stdin 轮询的最大等待窗口（毫秒）。默认 300000（5 分钟）。替代旧键 background_terminal_timeout。
history.max_bytesnumber若设置，则通过丢弃最旧条目来限制 history 文件的最大字节数。
file_opener`vscode \vscode-insiders \windsurf \cursor \none`Codex 输出中的 citation 打开时使用的 URI scheme（默认 vscode）。
otel.environmentstring应用于 OpenTelemetry 事件的环境标签（默认 dev）。
otel.exporter`none \otlp-http \otlp-grpc`选择 OpenTelemetry exporter，并提供相应 endpoint 元数据。
otel.trace_exporter`none \otlp-http \otlp-grpc`选择 OpenTelemetry trace exporter，并提供相应 endpoint 元数据。
otel.metrics_exporter`none \statsig \otlp-http \otlp-grpc`选择 OpenTelemetry metrics exporter（默认 statsig）。
otel.log_user_promptboolean是否把原始用户 prompt 一并导出到 OpenTelemetry logs。
otel.exporter..endpointstringOTEL logs exporter 的 endpoint。
otel.exporter..protocol`binary \json`OTLP/HTTP exporter 使用的协议。
otel.exporter..headersmapOTEL exporter 请求所带的静态 headers。
otel.trace_exporter..endpointstringOTEL trace exporter 的 endpoint。
otel.trace_exporter..protocol`binary \json`OTLP/HTTP trace exporter 使用的协议。
otel.trace_exporter..headersmapOTEL trace exporter 请求所带的静态 headers。
otel.exporter..tls.ca-certificatestringOTEL exporter TLS 使用的 CA 证书路径。
otel.exporter..tls.client-certificatestringOTEL exporter TLS 使用的客户端证书路径。
otel.exporter..tls.client-private-keystringOTEL exporter TLS 使用的客户端私钥路径。
otel.trace_exporter..tls.ca-certificatestringOTEL trace exporter TLS 使用的 CA 证书路径。
otel.trace_exporter..tls.client-certificatestringOTEL trace exporter TLS 使用的客户端证书路径。
otel.trace_exporter..tls.client-private-keystringOTEL trace exporter TLS 使用的客户端私钥路径。
tuitableTUI 专属选项，例如是否启用内联桌面通知。
desktop.custom_file_handlers.table仅限用户级配置。为 ChatGPT 桌面 App 定义额外的 Open in（打开方式） 目标。示例和 handler ID 约束参见添加自定义文件处理器。
desktop.custom_file_handlers..labelstringOpen in（打开方式） 菜单中显示的名称。必填。
desktop.custom_file_handlers..iconstringhandler 图标的内建资源路径、Base64 编码的 data:image/... URL、file URI 或本地绝对路径。必填；不支持的来源会使用默认 VS Code 图标。
desktop.custom_file_handlers..commandstring用于检测并启动的可执行文件路径或命令名。必填。
desktop.custom_file_handlers..argsarray插入在命令与文件输入之间的参数（默认 []）。
desktop.custom_file_handlers..input`path \json_argument \json_stdin`App 向 handler 传递文件输入的方式（默认 path）。
desktop.custom_file_handlers..supports_sshboolean是否为 SSH 工作区中的文件提供该 handler（默认 false）。
tui.notifications`boolean \array`启用 TUI 通知；也可限制为特定事件类型。
tui.notification_method`auto \osc9 \bel`终端通知使用的方法（默认 auto）。
tui.notification_condition`unfocused \always`控制 TUI 通知只在终端失焦时触发，还是无论焦点状态都触发。默认 unfocused。
tui.animationsboolean启用终端动画，例如 welcome screen、shimmer、spinner（默认 true）。
tui.alternate_screen`auto \always \never`控制 TUI 是否使用 alternate screen（默认 auto；在 Zellij 中会自动跳过，以保留 scrollback）。
tui.vim_mode_defaultboolean启动时让输入框进入 Vim normal mode，而不是 insert mode（默认 false）。仍可在会话中用 /vim 切换。
tui.raw_output_modeboolean启动 TUI 时使用原始滚动回看（raw scrollback）模式，便于在终端中选择和复制（默认 false）。可通过 /raw 或默认 alt-r 绑定切换。
tui.show_tooltipsboolean是否在 TUI welcome screen 中显示 onboarding tooltips（默认 true）。
tui.status_line`array \null`TUI 底部状态栏项的有序列表。null 表示禁用状态栏。
tui.terminal_title`array \null`终端窗口 / 标签标题项的有序列表。默认是 ["spinner", "project"]；null 表示禁用标题更新。
tui.themestring语法高亮主题覆盖值（kebab-case 主题名）。
tui.keymap..`string \array`TUI 动作的快捷键绑定。支持的 context 包括 global、chat、composer、editor、vim_normal、vim_operator、vim_text_object、pager、list 和 approval。部分 composer 动作会回退到匹配的 tui.keymap.global 绑定；支持特定 context 绑定时，该 context 会优先生效。
tui.keymap.. = []empty array在对应 keymap context 中解除该动作绑定。按键名使用 ctrl-a、shift-enter、page-down 或 minus 这类规范化字符串。
plugins..mcp_servers..enabledboolean在不修改插件 manifest 的前提下，启用或禁用已安装插件打包的 MCP server。
plugins..mcp_servers..default_tools_approval_mode`auto \prompt \writes \approve`插件提供的 MCP server 中工具的默认审批行为。
plugins..mcp_servers..enabled_toolsarray插件提供的 MCP server 暴露工具允许列表。
plugins..mcp_servers..disabled_toolsarray插件提供的 MCP server 的 deny list，会在 enabled_tools 之后应用。
plugins..mcp_servers..tools..approval_mode`auto \prompt \writes \approve`对插件提供的单个 MCP 工具的审批行为覆盖。
tui.model_availability_nux.integer以模型 slug 为 key 的内部启动提示状态。
hide_agent_reasoningboolean在 TUI 与 codex exec 输出中压制 reasoning 事件。
show_raw_agent_reasoningboolean当当前模型会发出 raw reasoning 时，直接显示该内容。
disable_paste_burstboolean关闭 TUI 中的 burst-paste 检测。
windows_wsl_setup_acknowledgedboolean记录 Windows onboarding 是否已确认（仅 Windows）。
chatgpt_base_urlstring覆盖 ChatGPT 登录流程所使用的 base URL。
cli_auth_credentials_store`file \keyring \auto`控制 CLI 把缓存凭据保存在何处（文件型 auth.json 或操作系统 keychain）。
mcp_oauth_credentials_store`auto \file \keyring`MCP OAuth 凭据的首选存储位置。
mcp_oauth_callback_portintegerMCP OAuth 登录时本地 HTTP callback server 使用的固定端口。未设置时由操作系统分配临时端口。
mcp_oauth_callback_urlstringMCP OAuth 登录的可选基础回调 URL 覆盖值，例如 devbox ingress URL。Codex 会在发送最终 OAuth redirect_uri 前追加 server 专属回调 ID，因此请在提供方处注册完整派生 URI。mcp_oauth_callback_port 仍然控制回调监听端口。
experimental_use_unified_exec_toolboolean启用 unified 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 } }`可选的 web search 工具配置。旧版布尔写法仍被接受，但对象写法可额外设置搜索上下文大小、允许域名，以及近似用户位置。
tools.view_imageboolean启用本地图片附件工具 view_image。
web_search`disabled \cached \indexed \live`Web search 模式。默认 "cached"：使用 OpenAI 维护的索引且不访问外部 Web；"indexed" 只在搜索索引放行时访问外部 Web；使用 --yolo 或其他 full access sandbox 设置时默认切到 "live"。"live" 允许不受索引门控的实时检索，"disabled" 会移除该工具。
default_permissionsstring应用于沙箱化工具调用的默认权限配置档案名称。内建值为 :read-only、:workspace 和 :danger-full-access；自定义配置档案名称必须有对应的 [permissions.] 表。不要和 sandbox_mode 或 [sandbox_workspace_write] 混用。
permissions..descriptionstring这个具名配置档案的人类可读说明。配置档案不会通过 extends 继承父级的 description。
permissions..extendsstring可选父级配置档案，会先于当前具名配置档案应用。可以设为另一个具名配置档案、:read-only 或 :workspace；:danger-full-access、未定义父级和继承循环会被拒绝。
permissions..workspace_rootstable由配置档案定义的工作区根目录，会和当前会话的运行时工作区根目录一起接收 :workspace_roots 文件系统规则。
permissions..workspace_roots.boolean值为 true 时，把该路径加入这个配置档案的工作区根目录集合；禁用的条目保持不生效。
permissions..filesystemtable命名的文件系统权限配置档案。每个 key 可以是绝对路径，或 :minimal、:workspace_roots 等特殊标记。
permissions..filesystem.glob_scan_max_depthnumber在某些需要在沙箱启动前快照匹配结果的平台上，展开 deny-read glob pattern 的最大深度。设置时必须至少为 1。
permissions..filesystem.`"read" \"write" \"deny" \table`对某个路径、glob pattern 或特殊标记直接赋权，或在该根下继续做嵌套授权。使用 "deny" 可以拒绝读取匹配路径。
permissions..filesystem.":workspace_roots".`"read" \"write" \"deny"`相对于每个有效工作区根目录配置访问权限。用 "." 表示根目录本身；可用 "**/*.env" 这类 glob 子路径配合 "deny" 拒绝读取。
permissions..network.enabledboolean是否为该命名权限配置档案启用网络访问。这会改变沙箱网络策略，但不会自行启动网络代理。
permissions..network.proxy_urlstring当该权限配置档案启用沙箱化网络时使用的 HTTP 监听器 URL。
permissions..network.enable_socks5boolean当该权限配置档案启用沙箱化网络时，暴露 SOCKS5 支持。
permissions..network.socks_urlstring该权限配置档案使用的 SOCKS5 代理端点。
permissions..network.enable_socks5_udpboolean在启用 SOCKS5 监听器时允许 UDP。
permissions..network.allow_upstream_proxyboolean允许沙箱化网络级联到另一个 upstream proxy。
permissions..network.dangerously_allow_non_loopback_proxyboolean允许沙箱化网络监听器绑定非 loopback 地址。启用后可能把监听器暴露到 localhost 之外。
permissions..network.dangerously_allow_all_unix_socketsboolean允许任意 Unix socket 目的地，而不是默认受限集合。只能在严格受控环境中使用。
permissions..network.mode`limited \full`子进程流量使用的网络代理模式。
permissions..network.domainstable沙箱化网络的域名规则。支持精确主机、只匹配子域名的 *.example.com、同时匹配 apex 和子域名的 **.example.com，以及全局 * allow 规则。冲突时 deny 优先。
permissions..network.domains.`allow \deny`允许或拒绝精确主机，或 *.example.com、**.example.com 这类限定通配符模式。
permissions..network.unix_socketstable沙箱化网络的 Unix socket allowlist 覆盖。键为 socket 路径；allow 会加入路径，deny 会拒绝该路径。
permissions..network.unix_sockets.`allow \deny`用 allow 把绝对 Unix socket 路径加入有效 allowlist，或用 deny 拒绝该路径。被拒绝的条目会从有效 allowlist 中省略。
permissions..network.allow_local_bindingboolean允许通过沙箱化网络进行更宽的本地 / 私有网络访问。当它保持 false 时，精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。
projects..trust_levelstring将某个项目或工作树标记为可信或不可信（"trusted" \"untrusted"）。不可信项目会跳过项目作用域的 .codex/ 配置层，包括项目本地配置、钩子和规则。
notice.hide_full_access_warningboolean记录是否已确认 full access warning 提示。
notice.hide_world_writable_warningboolean记录是否已确认 Windows world-writable 目录警告。
notice.hide_rate_limit_model_nudgeboolean记录是否选择不再看到 rate limit 模型切换提醒。
notice.hide_gpt5_1_migration_promptboolean记录是否已确认 GPT-5.1 迁移提示。
notice.hide_gpt-5.1-codex-max_migration_promptboolean记录是否已确认 gpt-5.1-codex-max 迁移提示。
notice.model_migrationsmap以 old-&gt;new 映射方式记录已确认的模型迁移。
forced_login_method`chatgpt \api`将 Codex 限制为某一种认证方式。
forced_chatgpt_workspace_idstring (uuid)将 ChatGPT 登录限制在某个特定 workspace identifier。

你可以在 这里 找到最新的 config.toml JSON schema。

如果你想在 VS Code 或 Cursor 中编辑 config.toml 时获得自动补全和诊断提示，可以安装 Even Better TOML 扩展，并在 config.toml 顶部加入这一行：

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 强制规则。具体优先级请参见 托管配置。

你也可以在 requirements.toml 中使用 [features]，通过 config.toml 使用的同一组 canonical key 固定运行时功能开关。Requirements 还可以包含文档列出的仅 App 键，它们不属于 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 flag 或 --config 显式选择的启动值优先级更高。显式模型或推理强度覆盖会同时跳过两个托管模型字段；service_tier 会独立处理。

键类型 / 可选值说明
allowed_approval_policiesarrayapproval_policy 允许使用的值，例如 untrusted、on-request、never 和 granular。
allowed_approvals_reviewersarrayapprovals_reviewer 允许使用的值，例如 user 和 auto_review。
guardian_policy_configstring自动评审使用的托管 Markdown 策略指令。它的优先级高于本地 [auto_review].policy；空值会被忽略。
allowed_permission_profilestable完整的权限配置档案允许列表。设为 true 的配置档案会被允许；省略或设为 false 的配置档案会被拒绝，包括未来版本新增的配置档案。合并多个 requirements 来源时，会按配置档案名称匹配条目。
allowed_permission_profiles.boolean允许或拒绝已加载配置或 requirements 来源中定义的内建 / 自定义权限配置档案。较晚、优先级更高的 requirements 来源可以用 false 关闭较早、优先级更低来源允许的配置档案。
default_permissionsstring托管默认权限配置档案。该配置档案必须被 allowed_permission_profiles 允许。请显式设置它，以获得可预测行为；如果省略，只有在 :workspace 和 :read-only 都被显式允许时，Codex 才会默认使用 :workspace。
enforce_residencystring要求 Codex 服务流量使用受支持的数据驻留。目前接受 us。
modelstable新任务使用的托管模型默认值。它们优先于用户和项目默认值，但启动新任务时的显式选择仍可覆盖。
models.new_threadtable启动新的本地 thread 时应用的默认值；每项模型设置都可省略。
models.new_thread.modelstring新 thread 的默认模型。显式 --model 或模型 / 推理相关 --config 覆盖优先。
models.new_thread.model_reasoning_effortstring新 thread 的默认推理强度。显式模型或推理强度覆盖会同时跳过这两个托管模型字段。
models.new_thread.service_tierstring新 thread 的默认 service tier。显式 service-tier 覆盖会独立优先于该值。
permissionstable按配置档案名称组织的管理员定义权限配置档案。使用与 config.toml 相同的配置档案字段。
permissions.table管理员定义的权限配置档案。名称不能以 : 开头，不能使用保留名称 filesystem，也不能和已加载配置中的配置档案重名。使用与 config.toml 相同的配置档案字段；完整 schema 见权限。
allowed_sandbox_modesarraysandbox_mode 允许使用的值。
windowstableWindows 原生沙箱 requirements。
windows.allowed_sandbox_implementationsarraywindows.sandbox 允许使用的原生 Windows 沙箱实现（elevated 和 unelevated）。列表不能为空。两者都允许且未选择模式时，Codex 优先使用 elevated。
remote_sandbox_configarray
针对特定主机的沙箱强制要求。第一个 hostname_patterns 匹配解析后主机名的条目，会覆盖该 requirements 来源顶层的 allowed_sandbox_modes。当前主机级条目只会覆盖沙箱模式。
remote_sandbox_config[].hostname_patternsarray不区分大小写的主机名模式。支持用 * 匹配任意字符序列，用 ? 匹配单个字符。
remote_sandbox_config[].allowed_sandbox_modesarray当该主机级条目命中时要应用的沙箱模式允许列表。
allowed_web_search_modesarrayweb_search 允许使用的值（disabled、cached、indexed、live）。disabled 永远允许；若为空数组，则效果上只允许 disabled。
allow_managed_hooks_onlyboolean为 true 时，Codex 会跳过用户、项目、会话和插件 hooks，但仍允许 requirements.toml 与其他托管配置层提供的托管 hooks。
allow_appshotsboolean设为 false 可为受管理用户禁用 Appshots。如果省略，Appshots 不会受到 requirements 约束，仍按正常产品可用性决定。
allow_remote_controlboolean设为 false 可为受管理用户禁用设备远程控制。如果省略，设备远程控制不会受到 requirements 约束，仍按正常产品可用性决定。
features.plugin_sharingboolean在 cloud-managed requirements.toml 中设为 false 可禁用本地构建插件的工作区共享。
featurestable固定功能值。运行时功能使用 config.toml 中的 canonical key；这里也支持文档列出的仅 App requirements 键。
features.boolean要求某个已记录的运行时功能或 App 功能保持启用或禁用。
features.appsboolean固定受管理用户的 Apps 集成可用性。
features.in_app_browserboolean在 requirements.toml 中设为 false 可禁用内置浏览器面板。
features.browser_useboolean在 requirements.toml 中设为 false 可禁用浏览器中的 Computer Use 和 Browser Agent。
features.browser_use_externalboolean在 requirements.toml 中设为 false 可禁用外部浏览器中的 Computer Use。
features.browser_use_full_cdp_accessboolean在 requirements.toml 中设为 false 可禁用本地运行时中的完整 Chrome DevTools Protocol 访问（包括 Browser Developer mode），并阻止 ChatGPT 桌面应用启用对应设置。省略时按正常产品可用性决定。
features.fast_modeboolean固定受管理用户的 canonical fast_mode 功能开关。
features.guardian_approvalboolean固定受管理用户的 Guardian approval 可用性。
features.memoriesboolean固定受管理用户的 Memories 可用性。
features.multi_agentboolean固定受管理用户的 multi-agent 可用性。
features.pluginsboolean固定受管理用户的插件可用性。
features.remote_pluginboolean固定受管理用户的远程 plugin 目录可用性。
features.computer_useboolean在 requirements.toml 中设为 false 可禁用 Computer Use、Record & Replay 及相关安装或设置流程。
features.workspace_dependenciesboolean固定受管理用户的捆绑工作区依赖运行时可用性。
computer_usetable从 requirements.toml 强制执行的 Computer Use requirements。
computer_use.allow_locked_computer_useboolean设为 false 可阻止 Computer Use 在托管 macOS 设备锁定后继续操作。如果省略，锁定状态使用不会被 requirements 约束。
experimental_networktable从 requirements.toml 强制执行的网络访问要求。这些约束与 features.network_proxy 相互独立，可以在没有用户功能开关的情况下配置沙箱化网络。
experimental_network.enabledboolean启用沙箱化网络要求。如果当前激活的沙箱关闭命令联网，这不会授予网络访问。
experimental_network.http_portinteger[experimental_network] 要求使用的 loopback HTTP 监听器端口。
experimental_network.socks_portinteger[experimental_network] 要求使用的 loopback SOCKS5 监听器端口。
experimental_network.allow_upstream_proxyboolean允许沙箱化网络使用环境中的 upstream proxy。
experimental_network.dangerously_allow_non_loopback_proxyboolean允许 [experimental_network] 要求使用非 loopback 监听器地址。启用后可能把监听器暴露到 localhost 之外。
experimental_network.dangerously_allow_all_unix_socketsboolean允许任意 Unix socket 目的地，而不是 allowlist-only 访问。只能在严格受控环境中使用。
experimental_network.domains`map<string, allow \deny>`管理员域名策略。支持精确主机、*.example.com、**.example.com 和全局 * allow 规则；应优先使用更窄规则。冲突时 deny 优先。不要与 experimental_network.allowed_domains 或 experimental_network.denied_domains 混用。
experimental_network.allowed_domainsarray列表形式的管理员 allow 规则。不要与 experimental_network.domains 混用。
experimental_network.denied_domainsarray列表形式的管理员 deny 规则。不要与 experimental_network.domains 混用。
experimental_network.managed_allowed_domains_onlyboolean为 true 时，在沙箱化网络要求生效期间，只有管理员管理的 allow 规则继续有效；用户新增的 allowlist 条目会被忽略。若没有托管 allow 规则，用户新增的域名 allow 规则也不会继续有效。
experimental_network.unix_sockets`map<string, allow \deny>`管理员管理的 Unix socket 策略，用于沙箱化网络。
experimental_network.allow_local_bindingboolean允许沙箱化网络进行更宽的本地 / 私有网络访问。当它保持 false 时，精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。
hookstable管理员强制的托管生命周期钩子。需要配置托管钩子目录，并使用与 config.toml 内联 [hooks] 相同的事件 schema。
hooks.managed_dirstring (absolute path)macOS 和 Linux 上存放托管钩子脚本的目录。Codex 会在加载托管钩子前校验它是绝对路径且已存在。
hooks.windows_managed_dirstring (absolute path)Windows 上存放托管钩子脚本的目录。Codex 会在加载托管钩子前校验它是绝对路径且已存在。
hooks.array
某个钩子事件的 matcher 分组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。
hooks.[].hooksarray
matcher 分组下的钩子处理器。当前支持 command hooks；prompt 和 agent hook handlers 会被解析但跳过。
hooks.[].hooks[].commandWindowsstringcommand hooks 的 Windows 专用命令覆盖。也接受 TOML alias command_windows。
permissions.filesystem.deny_readarray管理员强制的文件系统读拒绝规则。条目可以是路径或 glob pattern，用户不能通过本地配置放宽这些规则。
mcp_serverstable允许启用的 MCP server allowlist。只有当 server 名称（）和身份信息都匹配时，该 MCP server 才能启用。凡是不在 allowlist 中，或身份不匹配的 MCP server，都会被禁用。
mcp_servers..identitytable单个 MCP server 的身份规则。可设置 command（stdio）或 url（streamable HTTP）之一。
mcp_servers..identity.command`string \table`可以用精确的 command 字符串允许一个 MCP stdio server，也可以用 matcher table 要求精确的 executable 和有序参数 matcher。字符串形式不会检查参数、cwd、env 或 env_vars。
mcp_servers..identity.command.executablestringstdio server 配置的 command 必须精确匹配的 executable。
mcp_servers..identity.command.argsarray
stdio server 的有序参数 matcher。已配置的参数列表长度必须相同，且每个位置都要匹配。Command matcher 不会检查 cwd、env 或 env_vars。
mcp_servers..identity.command.args[].match`exact \prefix \regex`该参数位置使用的匹配操作。
mcp_servers..identity.command.args[].valuestringexact 或 prefix 参数 matcher 使用的值。
mcp_servers..identity.command.args[].expressionstringregex 参数 matcher 使用的正则表达式。表达式必须有效，并匹配完整参数值。
mcp_servers..identity.url`string \table`可以用精确的 URL 字符串允许一个 MCP streamable HTTP server，也可以用 exact、prefix 或 regex value matcher table。
mcp_servers..identity.url.match`exact \prefix \regex`已配置 MCP server URL 使用的匹配操作。
mcp_servers..identity.url.valuestringexact 或 prefix URL matcher 使用的值。
mcp_servers..identity.url.expressionstringregex URL matcher 使用的正则表达式。表达式必须有效，并匹配完整 URL 值。
pluginstable按插件标识组织的插件专属 MCP server allowlist。存在该 table 时，没有匹配 plugin 和 server 条目的插件打包 server 会被禁用。
plugins..mcp_serverstable某个插件打包的 MCP server allowlist。插件 server requirements 使用与顶层 mcp_servers requirements 相同的精确身份和 matcher 形态。
plugins..mcp_servers..identitytable某个插件打包 MCP server 的身份规则。可设置 command（stdio）或 url（streamable HTTP）之一。
plugins..mcp_servers..identity.command`string \table`可以用精确的 command 字符串允许某个插件 stdio MCP server，也可以用 matcher table 要求精确 executable 和有序参数 matcher。
plugins..mcp_servers..identity.command.executablestring插件打包 stdio server 配置的 command 必须精确匹配的 executable。
plugins..mcp_servers..identity.command.argsarray
插件打包 stdio server 的有序参数 matcher。已配置的参数列表长度必须相同，且每个位置都要匹配。
plugins..mcp_servers..identity.command.args[].match`exact \prefix \regex`该参数位置使用的匹配操作。
plugins..mcp_servers..identity.command.args[].valuestringexact 或 prefix 参数 matcher 使用的值。
plugins..mcp_servers..identity.command.args[].expressionstringregex 参数 matcher 使用的正则表达式。表达式必须匹配完整参数值。
plugins..mcp_servers..identity.url`string \table`可以用精确的 URL 字符串允许某个插件 streamable HTTP MCP server，也可以用 exact、prefix 或 regex value matcher table。
plugins..mcp_servers..identity.url.match`exact \prefix \regex`插件打包 MCP server URL 使用的匹配操作。
plugins..mcp_servers..identity.url.valuestringexact 或 prefix URL matcher 使用的值。
plugins..mcp_servers..identity.url.expressionstringregex URL matcher 使用的正则表达式。表达式必须匹配完整 URL 值。
marketplacestable插件 marketplace source 的管理员 requirements。只有在 restrict_to_allowed_sources 为 true 时，规则才会生效。
marketplaces.restrict_to_allowed_sourcesboolean为 true 时，用户自配置 marketplace source 必须匹配 allowed_sources，才能执行 marketplace add、插件安装和已配置 Git marketplace 刷新操作。只要 reserved source 和 name 匹配，Codex 管理的 OpenAI marketplaces 仍然允许使用。这不会在运行时过滤已经配置好的用户 marketplaces。
marketplaces.allowed_sourcestable以管理员选择的规则名为键的允许 marketplace source。不同名称会跨 requirements 层累积；同名条目下的字段按正常层级优先级处理。
marketplaces.allowed_sources.table单条允许 source 规则。requirements 合并后的最终 source 值决定 Codex 如何解释同级字段。
marketplaces.allowed_sources..source`git \host_pattern \local`Marketplace source matcher 类型。git 用于单个仓库，host_pattern 用于正则匹配 Git host，local 用于单个目录。
marketplaces.allowed_sources..urlstring当 source = "git" 时必填的 Git 仓库 URL。Codex 会先规范化已配置 URL 和允许 URL，再要求仓库精确匹配。
marketplaces.allowed_sources..refstringgit 规则可选的精确 Git ref。省略时，该规则允许匹配仓库的任意 ref。
marketplaces.allowed_sources..host_patternstring当 source = "host_pattern" 时必填的正则表达式。Codex 会把它与从 HTTPS、SSH 或 SCP-style Git source 解析出来的小写 hostname 匹配。若要匹配完整 host，请使用 ^ 和 $。
marketplaces.allowed_sources..pathstring (absolute path)当 source = "local" 时必填的本地 marketplace 目录。Codex 要求绝对路径，并在路径规范化后比较。
appstable按 app 标识组织的托管 app requirements。Requirements 可以禁用某个 app，或约束单个工具的审批行为。
apps..enabledboolean设为 false 可禁用某个 app。合并多个 requirements 来源时，禁用要求仍会保持收紧。
apps..tools..approval_mode`auto \prompt \writes \approve`设置某个 app 工具的托管审批模式。
rulestable与 .rules 文件合并的管理员强制命令规则。requirements 中的 rules 必须是收紧型限制。
rules.prefix_rulesarray
强制生效的 prefix rules 列表。每条规则都必须包含 pattern 和 decision。
rules.prefix_rules[].patternarray
以前缀 token 形式表达的命令模式。每个 token 位置都要设置 token 或 any_of。
rules.prefix_rules[].pattern[].tokenstring该位置必须匹配的单个字面 token。
rules.prefix_rules[].pattern[].any_ofarray该位置允许的多个备选 token。
rules.prefix_rules[].decision`prompt \forbidden`必填。requirements 中的规则只能是 prompt 或 forbidden，不能是 allow。
rules.prefix_rules[].justificationstring可选的非空说明，会显示在 approval 提示或拒绝消息中。

本站实践建议#

处理“配置参考”相关配置前，建议先备份现有配置文件，并在测试项目中逐项启用。每次只改变一个设置，便于出现异常时快速定位和回滚。

Codex API 与国内使用#

在实践“配置参考”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。