ChatGPT 中文教程
联系我 goolvyouyou@gmail.com

配置参考

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 权限配置档案，请参见权限。

键 类型 / 可选值 说明
model string 要使用的模型，例如 gpt-5.5。
review_model string /review 使用的可选模型覆盖值（默认使用当前 session 模型）。
model_provider string 从 model_providers 中选择的提供方 ID（默认 openai）。
openai_base_url string 内建 openai model provider 的 base URL 覆盖值。
model_context_window number 当前激活模型可用的 context window token 数。
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 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_approval boolean 为 true 时，允许沙箱升级时的审批提示显示出来。
approval_policy.granular.rules boolean 为 true 时，允许由 execpolicy 提示词规则触发的审批提示显示出来。
approval_policy.granular.mcp_elicitations boolean 为 true 时，允许 MCP elicitation 提示真正显示出来，而不是被自动拒绝。
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 的工具使用 login-shell 语义。默认 true；若设为 false，则 login = true 的请求会被拒绝，未显式设置 login 时默认使用非 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 中允许向外联网。
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 时使用的原生 sandbox 模式（仅 Windows）。
windows.sandbox_private_desktop boolean 在原生 Windows 上，默认让最终 sandboxed 子进程运行在私有桌面中。只有为兼容旧版 Winsta0\Default 行为时才应设为 false。
computer_use.windows.always_allowed_app_ids array<string> Computer Use 无需提示即可打开的 Windows app 标识符。列表外的 app 仍需审批；可在 ChatGPT 桌面应用的 Computer Use 设置中删除已保存条目。
notify array<string> 用于通知的命令；Codex 会向其传入一个 JSON payload。
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-tui.log；默认值是 $CODEX_HOME/log。
sqlite_home string (path) Codex 存放基于 SQLite 的状态数据库目录，供智能体作业与其他可恢复运行时状态使用。
compact_prompt string 对历史压缩提示词的内联覆盖。
model_instructions_file string (path) 用于替代内建 instructions 的文件，而不是使用 AGENTS.md。
personality none | friendly | pragmatic 对支持 supportsPersonality 的模型设置默认沟通风格；可在对话线程 / 会话轮次级别或通过 /personality 覆盖。
service_tier string 新会话轮次的 service tier 偏好。内建值包括 flex 和 fast；旧版 fast 配置会映射为请求值 priority，模型目录提供的 tier ID 也可以存储在这里。
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 启用或禁用某个具体 app / connector（默认 true）。
apps._default.enabled boolean 对所有 app 生效的默认启用状态，除非被单个 app 覆盖。
apps._default.destructive_enabled boolean 默认是否允许带 destructive_hint = true 的 app 工具。
apps._default.open_world_enabled boolean 默认是否允许带 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.<id>.destructive_enabled boolean 是否允许该 app 中声明了 destructive_hint = true 的工具。
apps.<id>.open_world_enabled boolean 是否允许该 app 中声明了 open_world_hint = true 的工具。
apps.<id>.default_tools_enabled boolean 该 app 中工具的默认启用状态，除非单个工具另有覆盖。
apps.<id>.approvals_reviewer user | auto_review 该 app 工具审批提示的 reviewer。会覆盖 apps._default.approvals_reviewer。
apps.<id>.default_tools_approval_mode auto | prompt | writes | approve 该 app 中工具的默认审批行为，除非单个工具另有覆盖。
apps.<id>.tools.<tool>.enabled boolean 对单个 app 工具的启用状态覆盖，例如 repos/list。
apps.<id>.tools.<tool>.approval_mode auto | prompt | writes | approve 对单个 app 工具的审批行为覆盖。
tool_suggest.discoverables array<table> 允许对额外的可发现连接器或插件给出工具建议。每一项都应包含 type = "connector" 或 "plugin"，以及对应的 id。
tool_suggest.disabled_tools array<table> 禁用特定可发现连接器或插件的工具建议。每一项都应包含 type = "connector" 或 "plugin"，以及对应的 id。
features.apps boolean 启用 App（连接器）集成（Stable；默认开启）。
features.hooks boolean 启用从 hooks.json 或内联 [hooks] 配置加载的生命周期钩子。features.codex_hooks 是已弃用 alias。
features.code_mode.enabled boolean 启用 code mode 功能配置。该功能仍在开发中，默认关闭。
features.code_mode.excluded_tool_namespaces array<string> code mode 从嵌套 code-mode 工具指引和 executor 暴露中排除的工具 namespace。
features.code_mode.direct_only_tool_namespaces array<string> code mode 只能通过直接工具调用使用的工具 namespace。
features.rollout_budget.enabled boolean 启用 rollout budget 跟踪。该功能仍在开发中，默认关闭。启用后必须设置 features.rollout_budget.limit_tokens。
features.rollout_budget.limit_tokens integer rollout budget 跟踪使用的正 token 上限。启用 rollout budget 时必填。
features.rollout_budget.reminder_interval_tokens integer rollout budget 提醒之间的正 token 间隔。默认是 limit_tokens 的 10%，最小为 1 token。
features.rollout_budget.sampling_token_weight number rollout budget 记账时 sampled tokens 使用的有限非负乘数。默认 1.0。
features.rollout_budget.prefill_token_weight number rollout budget 记账时 prefill tokens 使用的有限非负乘数。默认 1.0。
hooks table 在 config.toml 中内联配置的生命周期钩子。使用与 hooks.json 相同的事件 schema；示例和支持事件请参见 Hooks。
hooks.<Event> array<table> 某个钩子事件的 matcher 分组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。
hooks.<Event>[].hooks array<table> matcher 分组下的钩子处理器。当前支持 command hooks；prompt 和 agent hook handlers 会被解析但跳过。
hooks.<Event>[].hooks[].commandWindows string command hooks 的 Windows 专用命令覆盖。也接受 TOML alias command_windows。
features.memories boolean 启用 Memories（默认关闭）。
mcp_servers.<id>.command string MCP stdio server 的启动命令。
mcp_servers.<id>.args array<string> 传给 MCP stdio server 启动命令的参数。
mcp_servers.<id>.env map<string,string> 转发给 MCP stdio server 的环境变量。
mcp_servers.<id>.env_vars array<string | { name = string, source = "local" | "remote" }> 额外允许转发给 MCP stdio server 的环境变量。字符串条目默认使用 source = "local"；只有在 executor-backed remote stdio 场景下才使用 source = "remote"。
mcp_servers.<id>.cwd string MCP stdio server 进程的工作目录。
mcp_servers.<id>.url string MCP streamable HTTP server 的端点。
mcp_servers.<id>.auth oauth | chatgpt 在已配置 bearer token 和 authorization headers 之后使用的 MCP HTTP server 认证回退方式。oauth（默认）优先使用已保存的 MCP OAuth 凭据；chatgpt 对受信任的第一方 ChatGPT origin 使用当前 ChatGPT 会话，再回退到已保存的 OAuth。若所有凭据来源都未解析成功，两种模式都可以在无认证状态下连接。
mcp_servers.<id>.bearer_token_env_var string 作为 MCP HTTP server bearer token 来源的环境变量名。
mcp_servers.<id>.http_headers map<string,string> 每次 MCP HTTP 请求都携带的静态 HTTP headers。
mcp_servers.<id>.env_http_headers map<string,string> 对 MCP HTTP server，从环境变量填充出来的 HTTP headers。
mcp_servers.<id>.enabled boolean 在不删除配置的前提下禁用一个 MCP server。
mcp_servers.<id>.required boolean 为 true 时，若该已启用 MCP server 无法初始化，则启动 / 恢复会失败。
mcp_servers.<id>.startup_timeout_sec number 覆盖 MCP server 默认 10 秒的启动超时。
mcp_servers.<id>.startup_timeout_ms number startup_timeout_sec 的毫秒别名。
mcp_servers.<id>.tool_timeout_sec number 覆盖 MCP server 默认 60 秒的单工具超时。
mcp_servers.<id>.enabled_tools array<string> MCP server 暴露的工具允许列表。
mcp_servers.<id>.disabled_tools array<string> MCP server 的 deny list；会在 enabled_tools 之后应用。
mcp_servers.<id>.default_tools_approval_mode auto | prompt | writes | approve 该 MCP server 中工具的默认审批行为，除非有单工具覆盖。
mcp_servers.<id>.tools.<tool>.approval_mode auto | prompt | writes | approve 对该 MCP server 中单个工具的审批行为覆盖。
mcp_servers.<id>.scopes array<string> 对该 MCP server 进行认证时请求的 OAuth 权限范围（scopes）。
mcp_servers.<id>.oauth_resource string MCP 登录期间附带的可选 RFC 8707 OAuth resource 参数。
mcp_servers.<id>.experimental_environment local | remote MCP server 的实验性运行位置。remote 会通过远程 executor 环境启动 stdio server；streamable HTTP 的 remote placement 尚未实现。
agents.max_threads number 允许同时打开的智能体对话线程最大数量。未设置时默认 6。
agents.max_depth number 允许的智能体对话线程最大嵌套深度（根会话深度为 0；默认 1）。
agents.job_max_runtime_seconds number spawn_agents_on_csv 任务中每个 worker 的默认超时时间。未设置时回退到每个 worker 1800 秒。
agents.interrupt_message boolean 智能体的会话轮次被中断时，是否记录一条模型可见消息（默认 true）。
agents.<name>.description string 当 Codex 选择并生成该智能体类型时展示给它的角色说明。
agents.<name>.config_file string (path) 该角色使用的 TOML 配置层路径；相对路径相对于声明该角色的配置文件解析。
agents.<name>.nickname_candidates array<string> 可选的显示昵称候选池，用于该角色生成的智能体。
memories.generate_memories boolean 为 false 时，新创建的对话线程不会作为记忆生成输入保存。默认 true。
memories.use_memories boolean 为 false 时，Codex 不会把现有记忆注入到后续会话中。默认 true。
memories.disable_on_external_context boolean 为 true 时，使用 MCP 工具调用、Web 搜索或工具搜索等外部上下文的对话线程不会进入记忆生成。默认 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 工具（Stable；除 Windows 外默认开启）。
features.shell_snapshot boolean 快照 shell 环境，以加快重复命令（Stable；默认开启）。
features.multi_agent boolean 启用多智能体协作工具，例如 spawn_agent、send_input、resume_agent、wait_agent、close_agent（Stable；默认开启）。
features.goals boolean 启用持久化 goals 与自动续跑（Stable；默认开启）。
features.remote_plugin boolean 启用远程 plugin 目录（Stable；默认开启）。
features.personality boolean 启用 personality 选择控件（Stable；默认开启）。
features.network_proxy boolean | table 启用沙箱化网络。设置 domains 等网络策略选项时使用 table 形式（实验性；默认关闭）。
features.network_proxy.enabled boolean 启用沙箱化网络。默认 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_binding boolean 允许更宽的本地 / 私有网络访问。默认 false；精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。
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 允许通过环境中的 upstream proxy 级联。默认 true。
features.network_proxy.dangerously_allow_non_loopback_proxy boolean 允许非 loopback 监听器地址。默认 false；启用后可能把代理监听器暴露到 localhost 之外。
features.network_proxy.dangerously_allow_all_unix_sockets boolean 允许任意 Unix socket 目的地，而不是只允许 allowlist 条目。默认 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 工具来运行命令（Stable；默认开启）。
features.enable_request_compression boolean 在支持时使用 zstd 压缩流式请求体（Stable；默认开启）。
features.skill_mcp_dependency_install boolean 允许针对技能缺失的 MCP 依赖进行提示并安装（Stable；默认开启）。
features.fast_mode boolean 启用 TUI 中基于模型目录的 service tier 选择；当当前模型声明 Fast tier 时，也会启用对应命令（Stable；默认开启）。
features.prevent_idle_sleep boolean 在会话轮次正在运行时阻止机器休眠（Experimental；默认关闭）。
suppress_unstable_features_warning boolean 压制开启“开发中”功能开关时显示的警告。
model_providers.<id> table 自定义模型提供方的定义。
model_providers.<id>.name string 自定义 model provider 的显示名称。
model_providers.<id>.base_url string 该模型提供方的 API base URL。
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>.requires_openai_auth boolean 该提供方是否使用 OpenAI 认证（默认 false）。
model_providers.<id>.wire_api responses 该 provider 使用的协议。当前唯一支持值是 responses，且省略时默认即为此值。
model_providers.<id>.query_params map<string,string> 附加到提供方请求上的额外 query 参数。
model_providers.<id>.http_headers map<string,string> 附加到提供方请求上的静态 HTTP headers。
model_providers.<id>.env_http_headers map<string,string> 仅在环境变量存在时，从环境变量填充的 HTTP headers。
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 stream 的空闲超时（毫秒，默认 300000）。
model_providers.<id>.supports_websockets boolean 该 provider 是否支持 Responses API 的 WebSocket transport。
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 provider 使用的 AWS profile 名称。
model_providers.amazon-bedrock.aws.region string 内建 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_summaries boolean 强制 Codex 发送或不发送 reasoning metadata。
shell_environment_policy.inherit all | core | none 启动子进程时的基础环境继承策略。
shell_environment_policy.ignore_default_excludes boolean 在其他过滤之前，保留包含 KEY / SECRET / TOKEN 的环境变量。
shell_environment_policy.exclude array<string> 在默认过滤之后继续移除环境变量的 glob pattern 列表。
shell_environment_policy.include_only array<string> 白名单 pattern；设置后只保留匹配的变量。
shell_environment_policy.set map<string,string> 注入到每个子进程里的显式环境变量覆盖。
shell_environment_policy.experimental_use_profile boolean 让子进程通过用户 shell profile 运行。
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 是否把 session transcript 持久保存到 history.jsonl。
tool_output_token_limit number 在历史中保存单次 tool / function 输出时可使用的 token 预算。
background_terminal_max_timeout number 后台终端空 write_stdin 轮询的最大等待窗口（毫秒）。默认 300000（5 分钟）。替代旧键 background_terminal_timeout。
history.max_bytes number 若设置，则通过丢弃最旧条目来限制 history 文件的最大字节数。
file_opener vscode | vscode-insiders | windsurf | cursor | none Codex 输出中的 citation 打开时使用的 URI scheme（默认 vscode）。
otel.environment string 应用于 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_prompt boolean 是否把原始用户 prompt 一并导出到 OpenTelemetry logs。
otel.exporter.<id>.endpoint string OTEL logs exporter 的 endpoint。
otel.exporter.<id>.protocol binary | json OTLP/HTTP exporter 使用的协议。
otel.exporter.<id>.headers map<string,string> OTEL exporter 请求所带的静态 headers。
otel.trace_exporter.<id>.endpoint string OTEL trace exporter 的 endpoint。
otel.trace_exporter.<id>.protocol binary | json OTLP/HTTP trace exporter 使用的协议。
otel.trace_exporter.<id>.headers map<string,string> OTEL trace exporter 请求所带的静态 headers。
otel.exporter.<id>.tls.ca-certificate string OTEL exporter TLS 使用的 CA 证书路径。
otel.exporter.<id>.tls.client-certificate string OTEL exporter TLS 使用的客户端证书路径。
otel.exporter.<id>.tls.client-private-key string OTEL exporter TLS 使用的客户端私钥路径。
otel.trace_exporter.<id>.tls.ca-certificate string OTEL trace exporter TLS 使用的 CA 证书路径。
otel.trace_exporter.<id>.tls.client-certificate string OTEL trace exporter TLS 使用的客户端证书路径。
otel.trace_exporter.<id>.tls.client-private-key string OTEL trace exporter TLS 使用的客户端私钥路径。
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 启用终端动画，例如 welcome screen、shimmer、spinner（默认 true）。
tui.alternate_screen auto | always | never 控制 TUI 是否使用 alternate screen（默认 auto；在 Zellij 中会自动跳过，以保留 scrollback）。
tui.vim_mode_default boolean 启动时让输入框进入 Vim normal mode，而不是 insert mode（默认 false）。仍可在会话中用 /vim 切换。
tui.raw_output_mode boolean 启动 TUI 时使用原始滚动回看（raw scrollback）模式，便于在终端中选择和复制（默认 false）。可通过 /raw 或默认 alt-r 绑定切换。
tui.show_tooltips boolean 是否在 TUI welcome screen 中显示 onboarding tooltips（默认 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 动作的快捷键绑定。支持的 context 包括 global、chat、composer、editor、vim_normal、vim_operator、vim_text_object、pager、list 和 approval。部分 composer 动作会回退到匹配的 tui.keymap.global 绑定；支持特定 context 绑定时，该 context 会优先生效。
tui.keymap.<context>.<action> = [] empty array 在对应 keymap context 中解除该动作绑定。按键名使用 ctrl-a、shift-enter、page-down 或 minus 这类规范化字符串。
plugins.<plugin>.mcp_servers.<server>.enabled boolean 在不修改插件 manifest 的前提下，启用或禁用已安装插件打包的 MCP server。
plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode auto | prompt | writes | approve 插件提供的 MCP server 中工具的默认审批行为。
plugins.<plugin>.mcp_servers.<server>.enabled_tools array<string> 插件提供的 MCP server 暴露工具允许列表。
plugins.<plugin>.mcp_servers.<server>.disabled_tools array<string> 插件提供的 MCP server 的 deny list，会在 enabled_tools 之后应用。
plugins.<plugin>.mcp_servers.<server>.tools.<tool>.approval_mode auto | prompt | writes | approve 对插件提供的单个 MCP 工具的审批行为覆盖。
tui.model_availability_nux.<model> integer 以模型 slug 为 key 的内部启动提示状态。
hide_agent_reasoning boolean 在 TUI 与 codex exec 输出中压制 reasoning 事件。
show_raw_agent_reasoning boolean 当当前模型会发出 raw reasoning 时，直接显示该内容。
disable_paste_burst boolean 关闭 TUI 中的 burst-paste 检测。
windows_wsl_setup_acknowledged boolean 记录 Windows onboarding 是否已确认（仅 Windows）。
chatgpt_base_url string 覆盖 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_port integer MCP OAuth 登录时本地 HTTP callback server 使用的固定端口。未设置时由操作系统分配临时端口。
mcp_oauth_callback_url string MCP OAuth 登录的可选基础回调 URL 覆盖值，例如 devbox ingress URL。Codex 会在发送最终 OAuth redirect_uri 前追加 server 专属回调 ID，因此请在提供方处注册完整派生 URI。mcp_oauth_callback_port 仍然控制回调监听端口。
experimental_use_unified_exec_tool boolean 启用 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_image boolean 启用本地图片附件工具 view_image。
web_search disabled | cached | indexed | live Web search 模式。默认 "cached"：使用 OpenAI 维护的索引且不访问外部 Web；"indexed" 只在搜索索引放行时访问外部 Web；使用 --yolo 或其他 full access sandbox 设置时默认切到 "live"。"live" 允许不受索引门控的实时检索，"disabled" 会移除该工具。
default_permissions string 应用于沙箱化工具调用的默认权限配置档案名称。内建值为 :read-only、:workspace 和 :danger-full-access；自定义配置档案名称必须有对应的 [permissions.<name>] 表。不要和 sandbox_mode 或 [sandbox_workspace_write] 混用。
permissions.<name>.description string 这个具名配置档案的人类可读说明。配置档案不会通过 extends 继承父级的 description。
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 命名的文件系统权限配置档案。每个 key 可以是绝对路径，或 :minimal、:workspace_roots 等特殊标记。
permissions.<name>.filesystem.glob_scan_max_depth number 在某些需要在沙箱启动前快照匹配结果的平台上，展开 deny-read glob pattern 的最大深度。设置时必须至少为 1。
permissions.<name>.filesystem.<path-or-glob> "read" | "write" | "deny" | table 对某个路径、glob pattern 或特殊标记直接赋权，或在该根下继续做嵌套授权。使用 "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 允许沙箱化网络级联到另一个 upstream proxy。
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、同时匹配 apex 和子域名的 **.example.com，以及全局 * allow 规则。冲突时 deny 优先。
permissions.<name>.network.domains.<pattern> allow | deny 允许或拒绝精确主机，或 *.example.com、**.example.com 这类限定通配符模式。
permissions.<name>.network.unix_sockets table 沙箱化网络的 Unix socket allowlist 覆盖。键为 socket 路径；allow 会加入路径，deny 会拒绝该路径。
permissions.<name>.network.unix_sockets.<path> allow | deny 用 allow 把绝对 Unix socket 路径加入有效 allowlist，或用 deny 拒绝该路径。被拒绝的条目会从有效 allowlist 中省略。
permissions.<name>.network.allow_local_binding boolean 允许通过沙箱化网络进行更宽的本地 / 私有网络访问。当它保持 false 时，精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。
projects.<path>.trust_level string 将某个项目或工作树标记为可信或不可信（"trusted" | "untrusted"）。不可信项目会跳过项目作用域的 .codex/ 配置层，包括项目本地配置、钩子和规则。
notice.hide_full_access_warning boolean 记录是否已确认 full access warning 提示。
notice.hide_world_writable_warning boolean 记录是否已确认 Windows world-writable 目录警告。
notice.hide_rate_limit_model_nudge boolean 记录是否选择不再看到 rate limit 模型切换提醒。
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> 以 old->new 映射方式记录已确认的模型迁移。
forced_login_method chatgpt | api 将 Codex 限制为某一种认证方式。
forced_chatgpt_workspace_id string (uuid) 将 ChatGPT 登录限制在某个特定 workspace identifier。

你可以在 这里 找到最新的 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 强制规则。具体优先级请参见 托管配置。

你也可以在 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_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 的配置档案会被拒绝，包括未来版本新增的配置档案。合并多个 requirements 来源时，会按配置档案名称匹配条目。
allowed_permission_profiles.<name> boolean 允许或拒绝已加载配置或 requirements 来源中定义的内建 / 自定义权限配置档案。较晚、优先级更高的 requirements 来源可以用 false 关闭较早、优先级更低来源允许的配置档案。
default_permissions string 托管默认权限配置档案。该配置档案必须被 allowed_permission_profiles 允许。请显式设置它，以获得可预测行为；如果省略，只有在 :workspace 和 :read-only 都被显式允许时，Codex 才会默认使用 :workspace。
enforce_residency string 要求 Codex 服务流量使用受支持的数据驻留。目前接受 us。
models table 新任务使用的托管模型默认值。它们优先于用户和项目默认值，但启动新任务时的显式选择仍可覆盖。
models.new_thread table 启动新的本地 thread 时应用的默认值；每项模型设置都可省略。
models.new_thread.model string 新 thread 的默认模型。显式 --model 或模型 / 推理相关 --config 覆盖优先。
models.new_thread.model_reasoning_effort string 新 thread 的默认推理强度。显式模型或推理强度覆盖会同时跳过这两个托管模型字段。
models.new_thread.service_tier string 新 thread 的默认 service tier。显式 service-tier 覆盖会独立优先于该值。
permissions table 按配置档案名称组织的管理员定义权限配置档案。使用与 config.toml 相同的配置档案字段。
permissions.<name> table 管理员定义的权限配置档案。名称不能以 : 开头，不能使用保留名称 filesystem，也不能和已加载配置中的配置档案重名。使用与 config.toml 相同的配置档案字段；完整 schema 见权限。
allowed_sandbox_modes array<string> sandbox_mode 允许使用的值。
windows table Windows 原生沙箱 requirements。
windows.allowed_sandbox_implementations array<string> windows.sandbox 允许使用的原生 Windows 沙箱实现（elevated 和 unelevated）。列表不能为空。两者都允许且未选择模式时，Codex 优先使用 elevated。
remote_sandbox_config array<table> 针对特定主机的沙箱强制要求。第一个 hostname_patterns 匹配解析后主机名的条目，会覆盖该 requirements 来源顶层的 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 会跳过用户、项目、会话和插件 hooks，但仍允许 requirements.toml 与其他托管配置层提供的托管 hooks。
allow_appshots boolean 设为 false 可为受管理用户禁用 Appshots。如果省略，Appshots 不会受到 requirements 约束，仍按正常产品可用性决定。
allow_remote_control boolean 设为 false 可为受管理用户禁用设备远程控制。如果省略，设备远程控制不会受到 requirements 约束，仍按正常产品可用性决定。
features.plugin_sharing boolean 在 cloud-managed requirements.toml 中设为 false 可禁用本地构建插件的工作区共享。
features table 固定功能值。运行时功能使用 config.toml 中的 canonical key；这里也支持文档列出的仅 App requirements 键。
features.<name> boolean 要求某个已记录的运行时功能或 App 功能保持启用或禁用。
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 mode），并阻止 ChatGPT 桌面应用启用对应设置。省略时按正常产品可用性决定。
features.fast_mode boolean 固定受管理用户的 canonical fast_mode 功能开关。
features.guardian_approval boolean 固定受管理用户的 Guardian approval 可用性。
features.memories boolean 固定受管理用户的 Memories 可用性。
features.multi_agent boolean 固定受管理用户的 multi-agent 可用性。
features.plugins boolean 固定受管理用户的插件可用性。
features.remote_plugin boolean 固定受管理用户的远程 plugin 目录可用性。
features.computer_use boolean 在 requirements.toml 中设为 false 可禁用 Computer Use、Record & Replay 及相关安装或设置流程。
features.workspace_dependencies boolean 固定受管理用户的捆绑工作区依赖运行时可用性。
computer_use table 从 requirements.toml 强制执行的 Computer Use requirements。
computer_use.allow_locked_computer_use boolean 设为 false 可阻止 Computer Use 在托管 macOS 设备锁定后继续操作。如果省略，锁定状态使用不会被 requirements 约束。
experimental_network table 从 requirements.toml 强制执行的网络访问要求。这些约束与 features.network_proxy 相互独立，可以在没有用户功能开关的情况下配置沙箱化网络。
experimental_network.enabled boolean 启用沙箱化网络要求。如果当前激活的沙箱关闭命令联网，这不会授予网络访问。
experimental_network.http_port integer [experimental_network] 要求使用的 loopback HTTP 监听器端口。
experimental_network.socks_port integer [experimental_network] 要求使用的 loopback SOCKS5 监听器端口。
experimental_network.allow_upstream_proxy boolean 允许沙箱化网络使用环境中的 upstream proxy。
experimental_network.dangerously_allow_non_loopback_proxy boolean 允许 [experimental_network] 要求使用非 loopback 监听器地址。启用后可能把监听器暴露到 localhost 之外。
experimental_network.dangerously_allow_all_unix_sockets boolean 允许任意 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_domains array<string> 列表形式的管理员 allow 规则。不要与 experimental_network.domains 混用。
experimental_network.denied_domains array<string> 列表形式的管理员 deny 规则。不要与 experimental_network.domains 混用。
experimental_network.managed_allowed_domains_only boolean 为 true 时，在沙箱化网络要求生效期间，只有管理员管理的 allow 规则继续有效；用户新增的 allowlist 条目会被忽略。若没有托管 allow 规则，用户新增的域名 allow 规则也不会继续有效。
experimental_network.unix_sockets map<string, allow | deny> 管理员管理的 Unix socket 策略，用于沙箱化网络。
experimental_network.allow_local_binding boolean 允许沙箱化网络进行更宽的本地 / 私有网络访问。当它保持 false 时，精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。
hooks table 管理员强制的托管生命周期钩子。需要配置托管钩子目录，并使用与 config.toml 内联 [hooks] 相同的事件 schema。
hooks.managed_dir string (absolute path) macOS 和 Linux 上存放托管钩子脚本的目录。Codex 会在加载托管钩子前校验它是绝对路径且已存在。
hooks.windows_managed_dir string (absolute path) Windows 上存放托管钩子脚本的目录。Codex 会在加载托管钩子前校验它是绝对路径且已存在。
hooks.<Event> array<table> 某个钩子事件的 matcher 分组，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop。
hooks.<Event>[].hooks array<table> matcher 分组下的钩子处理器。当前支持 command hooks；prompt 和 agent hook handlers 会被解析但跳过。
hooks.<Event>[].hooks[].commandWindows string command hooks 的 Windows 专用命令覆盖。也接受 TOML alias command_windows。
permissions.filesystem.deny_read array<string> 管理员强制的文件系统读拒绝规则。条目可以是路径或 glob pattern，用户不能通过本地配置放宽这些规则。
mcp_servers table 允许启用的 MCP server allowlist。只有当 server 名称（<id>）和身份信息都匹配时，该 MCP server 才能启用。凡是不在 allowlist 中，或身份不匹配的 MCP server，都会被禁用。
mcp_servers.<id>.identity table 单个 MCP server 的身份规则。可设置 command（stdio）或 url（streamable HTTP）之一。
mcp_servers.<id>.identity.command string | table 可以用精确的 command 字符串允许一个 MCP stdio server，也可以用 matcher table 要求精确的 executable 和有序参数 matcher。字符串形式不会检查参数、cwd、env 或 env_vars。
mcp_servers.<id>.identity.command.executable string stdio server 配置的 command 必须精确匹配的 executable。
mcp_servers.<id>.identity.command.args array<table> stdio server 的有序参数 matcher。已配置的参数列表长度必须相同，且每个位置都要匹配。Command matcher 不会检查 cwd、env 或 env_vars。
mcp_servers.<id>.identity.command.args[].match exact | prefix | regex 该参数位置使用的匹配操作。
mcp_servers.<id>.identity.command.args[].value string exact 或 prefix 参数 matcher 使用的值。
mcp_servers.<id>.identity.command.args[].expression string regex 参数 matcher 使用的正则表达式。表达式必须有效，并匹配完整参数值。
mcp_servers.<id>.identity.url string | table 可以用精确的 URL 字符串允许一个 MCP streamable HTTP server，也可以用 exact、prefix 或 regex value matcher table。
mcp_servers.<id>.identity.url.match exact | prefix | regex 已配置 MCP server URL 使用的匹配操作。
mcp_servers.<id>.identity.url.value string exact 或 prefix URL matcher 使用的值。
mcp_servers.<id>.identity.url.expression string regex URL matcher 使用的正则表达式。表达式必须有效，并匹配完整 URL 值。
plugins table 按插件标识组织的插件专属 MCP server allowlist。存在该 table 时，没有匹配 plugin 和 server 条目的插件打包 server 会被禁用。
plugins.<plugin>.mcp_servers table 某个插件打包的 MCP server allowlist。插件 server requirements 使用与顶层 mcp_servers requirements 相同的精确身份和 matcher 形态。
plugins.<plugin>.mcp_servers.<server>.identity table 某个插件打包 MCP server 的身份规则。可设置 command（stdio）或 url（streamable HTTP）之一。
plugins.<plugin>.mcp_servers.<server>.identity.command string | table 可以用精确的 command 字符串允许某个插件 stdio MCP server，也可以用 matcher table 要求精确 executable 和有序参数 matcher。
plugins.<plugin>.mcp_servers.<server>.identity.command.executable string 插件打包 stdio server 配置的 command 必须精确匹配的 executable。
plugins.<plugin>.mcp_servers.<server>.identity.command.args array<table> 插件打包 stdio server 的有序参数 matcher。已配置的参数列表长度必须相同，且每个位置都要匹配。
plugins.<plugin>.mcp_servers.<server>.identity.command.args[].match exact | prefix | regex 该参数位置使用的匹配操作。
plugins.<plugin>.mcp_servers.<server>.identity.command.args[].value string exact 或 prefix 参数 matcher 使用的值。
plugins.<plugin>.mcp_servers.<server>.identity.command.args[].expression string regex 参数 matcher 使用的正则表达式。表达式必须匹配完整参数值。
plugins.<plugin>.mcp_servers.<server>.identity.url string | table 可以用精确的 URL 字符串允许某个插件 streamable HTTP MCP server，也可以用 exact、prefix 或 regex value matcher table。
plugins.<plugin>.mcp_servers.<server>.identity.url.match exact | prefix | regex 插件打包 MCP server URL 使用的匹配操作。
plugins.<plugin>.mcp_servers.<server>.identity.url.value string exact 或 prefix URL matcher 使用的值。
plugins.<plugin>.mcp_servers.<server>.identity.url.expression string regex URL matcher 使用的正则表达式。表达式必须匹配完整 URL 值。
marketplaces table 插件 marketplace source 的管理员 requirements。只有在 restrict_to_allowed_sources 为 true 时，规则才会生效。
marketplaces.restrict_to_allowed_sources boolean 为 true 时，用户自配置 marketplace source 必须匹配 allowed_sources，才能执行 marketplace add、插件安装和已配置 Git marketplace 刷新操作。只要 reserved source 和 name 匹配，Codex 管理的 OpenAI marketplaces 仍然允许使用。这不会在运行时过滤已经配置好的用户 marketplaces。
marketplaces.allowed_sources table 以管理员选择的规则名为键的允许 marketplace source。不同名称会跨 requirements 层累积；同名条目下的字段按正常层级优先级处理。
marketplaces.allowed_sources.<name> table 单条允许 source 规则。requirements 合并后的最终 source 值决定 Codex 如何解释同级字段。
marketplaces.allowed_sources.<name>.source git | host_pattern | local Marketplace source matcher 类型。git 用于单个仓库，host_pattern 用于正则匹配 Git host，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-style Git source 解析出来的小写 hostname 匹配。若要匹配完整 host，请使用 ^ 和 $。
marketplaces.allowed_sources.<name>.path string (absolute path) 当 source = "local" 时必填的本地 marketplace 目录。Codex 要求绝对路径，并在路径规范化后比较。
apps table 按 app 标识组织的托管 app requirements。Requirements 可以禁用某个 app，或约束单个工具的审批行为。
apps.<id>.enabled boolean 设为 false 可禁用某个 app。合并多个 requirements 来源时，禁用要求仍会保持收紧。
apps.<id>.tools.<tool>.approval_mode auto | prompt | writes | approve 设置某个 app 工具的托管审批模式。
rules table 与 .rules 文件合并的管理员强制命令规则。requirements 中的 rules 必须是收紧型限制。
rules.prefix_rules array<table> 强制生效的 prefix rules 列表。每条规则都必须包含 pattern 和 decision。
rules.prefix_rules[].pattern array<table> 以前缀 token 形式表达的命令模式。每个 token 位置都要设置 token 或 any_of。
rules.prefix_rules[].pattern[].token string 该位置必须匹配的单个字面 token。
rules.prefix_rules[].pattern[].any_of array<string> 该位置允许的多个备选 token。
rules.prefix_rules[].decision prompt | forbidden 必填。requirements 中的规则只能是 prompt 或 forbidden，不能是 allow。
rules.prefix_rules[].justification string 可选的非空说明，会显示在 approval 提示或拒绝消息中。