古法编程

这页可以直接用来查 OpenAI Codex 的配置键、类型、默认值和覆盖规则，适合排查 config.toml 为什么不生效、哪些项目级设置会被忽略，以及 requirements.toml 能强制限制哪些安全项。配合 JSON schema 和 VS Code/Cursor 的 TOML 插件可获得自动补全；experimental_instructions_file 已弃用，需改为 model_instructions_file。

OpenAI Codex 配置参考：config.toml 与 requirements.toml

需要概念说明和示例时，先看 Config basics 和 Advanced Config。沙箱、审批、权限和安全相关配置，分别参考 Sandbox and approvals、Protected paths in writable roots、Network access 和 Permissions。

用户级配置存放在 ~/.codex/config.toml。项目级覆盖可以放在 .codex/config.toml，但只有在你信任该项目时，Codex 才会加载项目级配置。

项目级 .codex/config.toml 不能覆盖本机相关的 provider、认证、通知、profile 或遥测路由键。以下键在项目级配置中会被忽略：openai_base_url、chatgpt_base_url、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url 和 otel，请放到用户级配置里。

config.toml

config.toml 是用户和项目可写的主配置文件。下面按功能分组列出可用键。

核心模型选项

键 类型 说明
model string 使用的模型，例如 gpt-5.5
review_model string /review 使用的模型覆盖，不填则使用当前 session 的模型
model_provider string model_providers 中的 provider id，默认 openai
openai_base_url string 内置 openai model provider 的 base URL 覆盖
model_context_window number 当前模型可用的上下文 token 数
model_auto_compact_token_limit number 触发自动历史压缩的 token 阈值，不设置时使用模型默认值
model_catalog_json string (path) 启动时加载的 JSON model catalog 路径；profiles.<name>.model_catalog_json 可按 profile 覆盖
oss_provider lmstudio | ollama 使用 --oss 时的默认本地 provider；未设置会提示选择

审批策略

键 类型 说明
approval_policy untrusted | on-request | never | { granular = {...} } 控制 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 elicitation 提示出现，而不是自动拒绝
approval_policy.granular.request_permissions boolean true 时允许 request_permissions 工具触发的提示出现
approval_policy.granular.skill_approval boolean true 时允许 skill 脚本审批提示出现
approvals_reviewer user | auto_review 在 on-request 或 granular 审批策略下，由谁审查符合条件的审批提示。默认 user；auto_review 使用 reviewer subagent。这个设置不会改变已在沙箱内允许的沙箱动作或审查动作
auto_review.policy string 自动审查使用的本地 Markdown policy 指令；受管的 guardian_policy_config 优先。空值会被忽略
allow_login_shell boolean 允许 shell 工具使用 login-shell 语义。默认 true；设为 false 后，login = true 会被拒绝，未写 login 时默认使用 non-login shell

沙箱模式

键 类型 说明
sandbox_mode read-only | workspace-write | danger-full-access 命令执行时的文件系统和网络访问策略
sandbox_workspace_write.writable_roots array<string> 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.sandbox_private_desktop boolean 默认把最终的沙箱子进程运行在 private desktop 上。只有为了兼容旧的 Winsta0\\Default 行为时才设为 false

通知与更新

键 类型 说明
notify array<string> 通知时执行的命令，Codex 会传入 JSON payload
check_for_update_on_startup boolean 启动时检查 Codex 更新。只有在更新由中心统一管理时才设为 false
feedback.enabled boolean 是否允许在各个 Codex 界面通过 /feedback 提交反馈，默认 true
analytics.enabled boolean 是否为当前机器或 profile 启用分析数据。未设置时使用客户端默认值

指令覆盖

键 类型 说明
instructions string 预留给未来使用；优先用 model_instructions_file 或 AGENTS.md
developer_instructions string 注入到 session 的额外开发者指令
compact_prompt string 历史压缩提示的内联覆盖
commit_attribution string 当启用 [features].codex_git_commit 时使用的 commit co-author trailer。默认 Codex <noreply@openai.com>；设为空字符串可禁用
model_instructions_file string (path) 替换内置指令文件，不使用 AGENTS.md
experimental_compact_prompt_file string (path) 从文件加载历史压缩提示覆盖（实验性）

显示与交互

键 类型 说明
personality none | friendly | pragmatic 支持 supportsPersonality 的模型所使用的默认沟通风格，可在单轮、单线程或通过 /personality 覆盖
service_tier string 新 turn 的首选 service tier。内置值包括 flex 和 fast；旧的 fast 配置会映射为请求值 priority，catalog 提供的 tier id 也可以存储
file_opener vscode | vscode-insiders | windsurf | cursor | none 打开 Codex 输出引用链接时使用的 URI scheme，默认 vscode

日志、状态与历史

键 类型 说明
log_dir string (path) Codex 写日志文件的目录，例如 codex-tui.log；默认 $CODEX_HOME/log
sqlite_home string (path) Codex 存放基于 SQLite 的状态数据库目录，用于 agent jobs 和其他可恢复运行状态
history.persistence save-all | none 控制是否把 session transcript 保存到 history.jsonl
tool_output_token_limit number 单个工具或函数输出写入 history 时的 token 上限
background_terminal_max_timeout number 空的 write_stdin 轮询的最大等待窗口，单位毫秒。默认 300000（5 分钟）。替代旧键 background_terminal_timeout
history.max_bytes number 如果设置，会通过丢弃最旧条目来限制 history 文件大小（字节）

Skills 与应用

键 类型 说明
skills.config array 存在于 config.toml 里的按 skill 启用覆盖
skills.config.<index>.path string (path) 包含 SKILL.md 的 skill 文件夹路径
skills.config.<index>.enabled boolean 启用或禁用对应 skill
apps.<id>.enabled boolean 启用或禁用某个 app / connector，默认 true
apps._default.enabled boolean 所有 app 的默认启用状态，除非被单独覆盖
apps._default.destructive_enabled boolean 带 destructive_hint = true 的 app tools 默认允许或拒绝状态
apps._default.open_world_enabled boolean 带 open_world_hint = true 的 app tools 默认允许或拒绝状态
apps.<id>.destructive_enabled boolean 允许或阻止该 app 中带 destructive_hint = true 的 tools
apps.<id>.open_world_enabled boolean 允许或阻止该 app 中带 open_world_hint = true 的 tools
apps.<id>.default_tools_enabled boolean 该 app 中 tools 的默认启用状态，除非单独覆盖
apps.<id>.default_tools_approval_mode auto | prompt | approve 该 app 中 tools 的默认审批方式，除非单独覆盖
apps.<id>.tools.<tool>.enabled boolean 单个 app tool 的启用覆盖，例如 repos/list
apps.<id>.tools.<tool>.approval_mode auto | prompt | approve 单个 app tool 的审批方式覆盖

Tool suggestion

键 类型 说明
tool_suggest.discoverables array 允许对额外可发现的 connector 或 plugin 进行 tool suggestion。每个条目使用 type = "connector" 或 "plugin"，以及一个 id
tool_suggest.disabled_tools array 禁止对指定的可发现 connector 或 plugin 进行 tool suggestion。每个条目使用 type = "connector" 或 "plugin"，以及一个 id

Hooks

键 类型 说明
features.hooks boolean 启用从 hooks.json 或 inline [hooks] 配置加载 lifecycle hooks。features.codex_hooks 是已弃用别名
hooks table 在 config.toml 里直接配置的 lifecycle hooks，事件结构与 hooks.json 相同
hooks.<Event> array 某个 hook 事件的 matcher groups，例如 PreToolUse、PermissionRequest、PostToolUse、PreCompact、PostCompact、SessionStart、SubagentStart、SubagentStop、UserPromptSubmit 或 Stop
hooks.<Event>[].hooks array 某个 matcher group 的 hook handlers；目前只支持 command hooks，prompt 和 agent hook handlers 会被解析但跳过
hooks.<Event>[].hooks[].commandWindows string command hook 在 Windows 下的命令覆盖，command_windows 也可用
键 类型 说明
features.network_proxy boolean | table 启用 sandboxed networking。需要设置网络策略时用 table 形式，默认关闭
features.network_proxy.enabled boolean 启用 sandboxed networking，默认 false
features.network_proxy.domains map<string, allow | deny> sandboxed networking 的域名策略。默认不允许外部目标，除非添加 allow 规则。支持精确主机、*.example.com 仅匹配子域、**.example.com 匹配根域和子域、全局 * 允许规则；建议优先使用范围更小的规则，因为 * 会广泛打开公共出站访问。冲突时 deny 优先
features.network_proxy.unix_sockets map<string, allow | none> sandboxed networking 的 Unix socket 策略。默认不设置；添加 allow 才能放行指定 socket
features.network_proxy.allow_local_binding boolean 允许更宽泛的本地 / 私有网络访问。默认 false；但精确的本地 IP 字面量或 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 允许透传环境中的上游代理，默认 true
features.network_proxy.dangerously_allow_non_loopback_proxy boolean 允许非 loopback 监听地址。默认 false，开启后可能把 proxy listener 暴露到 localhost 之外
features.network_proxy.dangerously_allow_all_unix_sockets boolean 允许任意 Unix socket 目标，而不是只允许白名单。默认 false，仅限严格受控环境使用
features.network_proxy.proxy_url string sandboxed networking 的 HTTP listener URL，默认 "http://127.0.0.1:3128"
features.network_proxy.socks_url string SOCKS5 listener 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"
tools.web_search boolean | object 可选的 web search 工具配置。旧的 boolean 形式仍可用；object 形式可设置搜索上下文大小、允许域名和大致用户位置
web_search disabled | cached | live Web search 模式。默认 cached；cached 使用 OpenAI 维护的索引，不抓取实时页面；如果使用 --yolo 或其他 full access 沙箱设置，默认会变成 live。live 用于抓取最新网页数据，disabled 则移除该工具

Model provider

键 类型 说明
model_providers.<id> table 自定义 provider 定义。内置 provider id openai、ollama 和 lmstudio 被保留，不能覆盖
model_providers.<id>.name string 自定义 provider 的展示名称
model_providers.<id>.base_url string provider 的 API base URL
model_providers.<id>.env_key string 提供 provider API key 的环境变量
model_providers.<id>.env_key_instructions string 可选的 API key 设置说明
model_providers.<id>.experimental_bearer_token string 直接填写 provider 的 bearer token，不推荐，优先用 env_key
model_providers.<id>.requires_openai_auth boolean 该 provider 使用 OpenAI 认证，默认 false
model_providers.<id>.wire_api responses provider 使用的协议，唯一支持值是 responses，省略时默认也是它
model_providers.<id>.query_params map<string,string> 追加到 provider 请求上的额外 query 参数
model_providers.<id>.http_headers map<string,string> 添加到 provider 请求的静态 header
model_providers.<id>.env_http_headers map<string,string> 在环境变量存在时注入到 provider 请求的 header
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 该 provider 是否支持 Responses API WebSocket transport
model_providers.<id>.auth table 用命令返回 bearer token 的 provider 认证配置，不要与 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 Plan 模式专用的推理覆盖，不设置时使用 Plan mode 内置预设
model_reasoning_summary auto | concise | detailed | none 选择推理摘要的详细程度，或完全关闭摘要
model_verbosity low | medium | high GPT-5 Responses API 的 verbosity 覆盖，不设置时用所选模型或预设默认值
model_supports_reasoning_summaries boolean 强制 Codex 发送或不发送 reasoning metadata

Shell 环境变量策略

键 类型 说明
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> 白名单模式；设置后只保留匹配的变量
shell_environment_policy.set map<string,string> 注入到每个子进程的显式环境变量覆盖
shell_environment_policy.experimental_use_profile boolean 启动子进程时使用用户 shell profile

Project root 与项目文档

键 类型 说明
project_root_markers array<string> 搜索项目根目录时使用的标志文件名列表
project_doc_max_bytes number 构建项目指令时从 AGENTS.md 读取的最大字节数
project_doc_fallback_filenames array<string> 找不到 AGENTS.md 时额外尝试的文件名

Profile 相关配置

键 类型 说明
profile string 启动时应用的默认 profile，等同于 --profile
profiles.<name>.* various 任意受支持配置键的 profile 级覆盖
profiles.<name>.service_tier string profile 级的新 turn service tier 偏好
profiles.<name>.plan_mode_reasoning_effort none | minimal | low | medium | high | xhigh profile 级 Plan 模式推理覆盖
profiles.<name>.web_search disabled | cached | live profile 级 web search 模式覆盖，默认 cached
profiles.<name>.personality none | friendly | pragmatic profile 级沟通风格覆盖
profiles.<name>.model_catalog_json string (path) profile 级 model catalog JSON 路径覆盖，只在启动时应用，并覆盖该 profile 的顶层 model_catalog_json
profiles.<name>.model_instructions_file string (path) profile 级内置指令文件替换
profiles.<name>.experimental_use_unified_exec_tool boolean 启用 unified exec 的旧名称，优先用 [features].unified_exec
profiles.<name>.oss_provider lmstudio | ollama --oss session 的 profile 级 provider
profiles.<name>.tools_view_image boolean 启用或禁用该 profile 的 view_image 工具
profiles.<name>.analytics.enabled boolean profile 级分析数据开关覆盖
profiles.<name>.windows.sandbox unelevated | elevated profile 级 Windows 沙箱模式覆盖

其他配置

键 类型 说明
features.apps boolean 启用 ChatGPT Apps/connectors 支持（experimental）
features.hooks boolean 启用从 hooks.json 或 inline [hooks] 加载 lifecycle hooks。features.codex_hooks 已弃用
features.codex_git_commit boolean 启用 Codex 生成 git commits；开启后会用 commit_attribution 在 commit message 末尾追加 Co-authored-by: trailer
features.memories boolean 启用 Memories，默认关闭
features.unified_exec boolean 使用统一的 PTY-backed exec 工具，稳定版；Windows 上默认不启用
features.shell_snapshot boolean 快照 shell 环境以加速重复命令，稳定版；默认开启
features.undo boolean 启用 undo 支持，稳定版；默认关闭
features.multi_agent boolean 启用多 agent 协作工具 spawn_agent、send_input、resume_agent、wait_agent 和 close_agent，稳定版；默认开启
features.personality boolean 启用 personality 选择控件，稳定版；默认开启
features.fast_mode boolean 在 TUI 中启用 model-catalog 的 service tier 选择，包括当活动模型暴露 Fast-tier 命令时的 Fast-tier 命令，稳定版；默认开启
features.prevent_idle_sleep boolean 在 turn 运行期间防止机器睡眠，实验性；默认关闭
suppress_unstable_features_warning boolean 隐藏启用开发中 feature flag 时出现的警告
tools.view_image boolean 启用本地图片附件工具 view_image
hide_agent_reasoning boolean 在 TUI 和 codex exec 输出中隐藏 reasoning 事件
show_raw_agent_reasoning boolean 在活动模型输出原始 reasoning 内容时直接显示
disable_paste_burst boolean 禁用 TUI 中的 burst-paste 检测
windows_wsl_setup_acknowledged boolean 记录 Windows onboarding 确认状态，仅 Windows 有效
notice.hide_full_access_warning boolean 记录对 full access 警告提示的确认
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

requirements.toml

requirements.toml 是管理员强制配置文件，用来约束用户不能覆盖的安全敏感设置。对位置、部署和示例，见 Admin-enforced requirements。ChatGPT Business 和 Enterprise 用户还可能应用云端拉取的 requirements，优先级见安全文档。

在 requirements.toml 里可以用 [features] 按与 config.toml 相同的规范键锁定 feature flag。未列出的键保持不受约束。

键 类型 说明
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 policy 指令，优先于本地 [auto_review].policy。空值会被忽略
allowed_sandbox_modes array<string> sandbox_mode 的允许值
remote_sandbox_config array 按主机名匹配的沙箱要求。第一个命中 hostname_patterns 的条目会覆盖该 requirements 来源的顶层 allowed_sandbox_modes。当前只覆盖 sandbox modes
remote_sandbox_config[].hostname_patterns array<string> 大小写不敏感的主机名模式，支持 * 匹配任意字符序列，? 匹配单个字符
remote_sandbox_config[].allowed_sandbox_modes array<string> 命中该主机专用条目时适用的 sandbox mode 列表
allowed_web_search_modes array<string> web_search 的允许值（disabled、cached、live）；disabled 始终允许，空列表等同于只允许 disabled
allow_managed_hooks_only boolean true 时跳过用户、项目、session 和 plugin hooks，只允许 requirements.toml 及其他受管配置层中的 managed hooks
plugin_sharing boolean 云端受管 requirements.toml 可设为 false，以禁止本地构建插件的 workspace sharing
features table 按 config.toml 的 [features] canonical 名称锁定 feature 值
features.<name> boolean 要求某个 canonical feature 键保持启用或禁用
features.in_app_browser boolean 设为 false 可禁用 in-app browser pane
features.browser_use boolean 设为 false 可禁用 Browser Use 和 Browser Agent availability
features.computer_use boolean 设为 false 可禁用 Computer Use availability 及相关安装或启用流程

受管网络与 hooks

键 类型 说明
experimental_network table 来自 requirements.toml 的网络访问要求。这个约束与 features.network_proxy 分开，可以在不依赖用户 feature flag 的情况下配置 sandboxed networking
experimental_network.enabled boolean 启用 sandboxed networking requirements；如果当前 sandbox 仍禁止命令网络访问，这不会自动授予网络权限
experimental_network.http_port integer [experimental_network] 里使用的 loopback HTTP listener 端口
experimental_network.socks_port integer [experimental_network] 里使用的 loopback SOCKS5 listener 端口
experimental_network.allow_upstream_proxy boolean 允许 sandboxed networking 通过环境中的上游代理转发
experimental_network.dangerously_allow_non_loopback_proxy boolean 允许 [experimental_network] 使用非 loopback 监听地址。开启后可能把 listener 暴露到 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 时，仅管理员受管 allow 规则在 sandboxed networking requirements 生效期间有效；用户追加的 allow 规则会被忽略
experimental_network.unix_sockets map<string, allow | none> 管理员管理的 Unix socket 策略
experimental_network.allow_local_binding boolean 允许更宽泛的本地 / 私有网络访问；但精确的本地 IP 字面量或 localhost allow 规则仍可放行特定目标
hooks.managed_dir string (absolute path) macOS 和 Linux 上的受管 hook 目录，Codex 会在加载前验证必须是绝对路径且存在
hooks.windows_managed_dir string (absolute path) Windows 上的受管 hook 目录，Codex 会在加载前验证必须是绝对路径且存在
hooks.<Event> array 某个 hook 事件的 matcher groups
hooks.<Event>[].hooks array 某个 matcher group 的 hook handlers；目前只支持 command hooks，prompt 和 agent hook handlers 会被解析但跳过
hooks.<Event>[].hooks[].commandWindows string command hook 在 Windows 下的命令覆盖，command_windows 也可用
permissions.filesystem.deny_read array<string> 管理员强制的文件系统读拒绝规则，条目可为路径或 glob，用户无法用本地配置削弱它们

受管 MCP、规则与权限

键 类型 说明
mcp_servers table 允许启用的 MCP server 白名单。server 名称和 identity 必须同时匹配，未在白名单内或 identity 不匹配的 server 都会被禁用
mcp_servers.<id>.identity table 单个 MCP server 的 identity 规则，二选一配置 command（stdio）或 url（streamable HTTP）
mcp_servers.<id>.identity.command string 当 mcp_servers.<id>.command 与此命令一致时允许该 MCP stdio server
mcp_servers.<id>.identity.url string 当 mcp_servers.<id>.url 与此 URL 一致时允许该 MCP streamable HTTP server
rules table 与 .rules 文件合并的管理员强制命令规则。requirements 规则必须是 restrictive 的
rules.prefix_rules array 强制的前缀规则列表，每条都要包含 pattern 和 decision
rules.prefix_rules[].pattern array 用 pattern tokens 表示的命令前缀，每个 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 可选的非空理由，会显示在审批提示或拒绝消息中

获取 JSON schema

config.toml 的最新 JSON schema 见 config-schema.json。

在 VS Code 或 Cursor 中编辑 config.toml 时，可以安装 Even Better TOML 扩展，并在文件顶部添加：

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

这样可以获得自动补全和诊断信息。

注意：experimental_instructions_file 已更名为 model_instructions_file。Codex 已弃用旧键，现有配置请尽快改名。

常见问题

OpenAI Codex 的 config.toml 和 requirements.toml 有什么区别？

config.toml 是用户级或项目级可写配置，能控制模型、沙箱、MCP、TUI、遥测等行为；requirements.toml 是管理员强制配置，用来限制用户不能放宽的安全敏感项。前者可以被本地修改，后者会覆盖并约束用户设置。

为什么我在 .codex/config.toml 里写了某些键，但 Codex 没生效？

常见原因是该项目不受信任，项目级配置根本没有加载；或者你写的是不能在项目级覆盖的键，比如 openai_base_url、model_provider、notify、profile、profiles 或 otel。这类键要放到 ~/.codex/config.toml。

OpenAI Codex 怎么接入自定义 model provider？

在 [model_providers.<id>] 下新建一个自定义 provider id，不能使用内置的 openai、ollama 或 lmstudio。然后配置 base_url、认证方式以及需要的 header 或 query 参数，再把 model_provider 指向这个 id。