把本页当成 Codex 配置文件的可检索参考手册来使用。若你想先看概念解释和典型示例，请从 配置基础 和 高级配置 开始。
config.toml
用户级配置位于 ~/.codex/config.toml。你也可以在 .codex/config.toml 中添加项目级覆盖配置。Codex 只会在你信任该项目时加载这些项目级配置文件。
对于和沙箱、审批有关的配置键，例如 approval_policy、sandbox_mode 和 sandbox_workspace_write.*，建议把本页与 沙箱与审批、可写根目录中的受保护路径 以及 网络访问 搭配阅读。
| 键 | 类型 / 可选值 | 说明 |
|---|---|---|
agents.<name>.config_file |
string (path) |
该角色使用的 TOML 配置层路径；相对路径相对于声明该角色的配置文件解析。 |
agents.<name>.description |
string | 当 Codex 选择并生成该智能体类型时展示给它的角色说明。 |
agents.<name>.nickname_candidates |
array<string> |
可选的显示昵称候选池，用于该角色生成的智能体。 |
agents.job_max_runtime_seconds |
number | spawn_agents_on_csv 任务中每个 worker 的默认超时时间。未设置时回退到每个 worker 1800 秒。 |
agents.max_depth |
number | 允许的智能体线程最大嵌套深度（根 session 深度为 0；默认 1）。 |
agents.max_threads |
number | 允许同时打开的智能体线程最大数量。未设置时默认 6。 |
allow_login_shell |
boolean | 是否允许基于 shell 的工具使用 login-shell 语义。默认 true；若设为 false，则 login = true 的请求会被拒绝，未显式设置 login 时默认使用非 login shell。 |
analytics.enabled |
boolean | 为当前机器 / 配置档案启用或关闭分析数据上报。未设置时使用客户端默认值。 |
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.mcp_elicitations |
boolean | 为 true 时，允许 MCP elicitation 提示真正显示出来，而不是被自动拒绝。 |
approval_policy.granular.request_permissions |
boolean | 为 true 时，允许 request_permissions 工具触发的提示显示出来。 |
approval_policy.granular.rules |
boolean | 为 true 时，允许由 execpolicy prompt 规则触发的 approval 提示显示出来。 |
approval_policy.granular.sandbox_approval |
boolean | 为 true 时，允许 sandbox 升级时的 approval 提示显示出来。 |
approval_policy.granular.skill_approval |
boolean | 为 true 时，允许技能脚本触发的审批提示显示出来。 |
approvals_reviewer |
user | guardian_subagent |
选择由谁审核符合条件的审批提示。默认是 user；设为 guardian_subagent 时，会把受支持的审批交给 Guardian 评审子智能体。 |
apps._default.destructive_enabled |
boolean | 默认是否允许带 destructive_hint = true 的 app 工具。 |
apps._default.enabled |
boolean | 对所有 app 生效的默认启用状态，除非被单个 app 覆盖。 |
apps._default.open_world_enabled |
boolean | 默认是否允许带 open_world_hint = true 的 app 工具。 |
apps.<id>.default_tools_approval_mode |
auto | prompt | approve |
该 app 中工具的默认 approval 行为，除非单个工具另有覆盖。 |
apps.<id>.default_tools_enabled |
boolean | 该 app 中工具的默认启用状态，除非单个工具另有覆盖。 |
apps.<id>.destructive_enabled |
boolean | 是否允许该 app 中声明了 destructive_hint = true 的工具。 |
apps.<id>.enabled |
boolean | 启用或禁用某个具体 app / connector（默认 true）。 |
apps.<id>.open_world_enabled |
boolean | 是否允许该 app 中声明了 open_world_hint = true 的工具。 |
apps.<id>.tools.<tool>.approval_mode |
auto | prompt | approve |
对单个 app 工具的 approval 行为覆盖。 |
apps.<id>.tools.<tool>.enabled |
boolean | 对单个 app 工具的启用状态覆盖，例如 repos/list。 |
tool_suggest.discoverables |
array<table> |
允许对额外的可发现连接器或插件给出工具建议。每一项都应包含 type = "connector" 或 "plugin"，以及对应的 id。 |
background_terminal_max_timeout |
number | 后台终端空 write_stdin 轮询的最大等待窗口（毫秒）。默认 300000（5 分钟）。替代旧键 background_terminal_timeout。 |
chatgpt_base_url |
string | 覆盖 ChatGPT 登录流程所使用的 base URL。 |
check_for_update_on_startup |
boolean | 启动时是否检查 Codex 更新（只有在更新由中心化方式统一管理时才建议设为 false）。 |
cli_auth_credentials_store |
file | keyring | auto |
控制 CLI 把缓存凭据保存在何处（文件型 auth.json 或操作系统 keychain）。 |
commit_attribution |
string | 覆盖默认的 commit co-author trailer 文本。设为空字符串可关闭自动署名。 |
compact_prompt |
string | 对历史压缩提示词的内联覆盖。 |
default_permissions |
string | 应用于 sandboxed tool calls 的默认 permissions profile 名称。 |
developer_instructions |
string | 注入到 session 中的额外 开发者指令（可选）。 |
disable_paste_burst |
boolean | 关闭 TUI 中的 burst-paste 检测。 |
experimental_compact_prompt_file |
string (path) |
从文件加载历史压缩提示词覆盖值（实验性）。 |
experimental_use_unified_exec_tool |
boolean | 启用 unified exec 的旧键名；优先使用 [features].unified_exec 或 codex --enable unified_exec。 |
features.apps |
boolean | 启用 ChatGPT Apps / connectors 支持（Experimental）。 |
features.codex_hooks |
boolean | 启用从 hooks.json 加载的生命周期钩子（Under development；默认关闭）。 |
features.enable_request_compression |
boolean | 在支持时使用 zstd 压缩流式请求体（Stable；默认开启）。 |
features.fast_mode |
boolean | 启用 Fast mode 选择以及 service_tier = "fast" 路径（Stable；默认开启）。 |
features.multi_agent |
boolean | 启用多智能体协作工具，例如 spawn_agent、send_input、resume_agent、wait_agent、close_agent（Stable；默认开启）。 |
features.personality |
boolean | 启用 personality 选择控件（Stable；默认开启）。 |
features.prevent_idle_sleep |
boolean | 在 turn 正在运行时阻止机器休眠（Experimental；默认关闭）。 |
features.shell_snapshot |
boolean | 快照 shell 环境，以加快重复命令（Stable；默认开启）。 |
features.shell_tool |
boolean | 启用默认 shell 工具来运行命令（Stable；默认开启）。 |
features.skill_mcp_dependency_install |
boolean | 允许针对技能缺失的 MCP 依赖进行提示并安装（Stable；默认开启）。 |
features.smart_approvals |
boolean | 把符合条件的审批请求转交给守护评审子智能体（Experimental；默认关闭）。 |
features.undo |
boolean | 启用 undo 支持（Stable；默认关闭）。 |
features.unified_exec |
boolean | 使用统一的 PTY 支撑 exec 工具（Stable；除 Windows 外默认开启）。 |
features.web_search |
boolean | 已弃用的旧版开关；优先使用顶层 web_search 设置。 |
features.web_search_cached |
boolean | 已弃用的旧版开关。若 web_search 未设置，true 会映射到 web_search = "cached"。 |
features.web_search_request |
boolean | 已弃用的旧版开关。若 web_search 未设置，true 会映射到 web_search = "live"。 |
feedback.enabled |
boolean | 在各个 Codex 界面中启用通过 /feedback 提交反馈（默认 true）。 |
file_opener |
vscode | vscode-insiders | windsurf | cursor | none |
Codex 输出中的 citation 打开时使用的 URI scheme（默认 vscode）。 |
forced_chatgpt_workspace_id |
string (uuid) |
将 ChatGPT 登录限制在某个特定 workspace identifier。 |
forced_login_method |
chatgpt | api |
将 Codex 限制为某一种认证方式。 |
hide_agent_reasoning |
boolean | 在 TUI 与 codex exec 输出中压制 reasoning 事件。 |
history.max_bytes |
number | 若设置，则通过丢弃最旧条目来限制 history 文件的最大字节数。 |
history.persistence |
save-all | none |
控制 Codex 是否把 session transcript 持久保存到 history.jsonl。 |
| instructions | string | 预留给未来使用；当前请优先使用 model_instructions_file 或 AGENTS.md。 |
log_dir |
string (path) |
Codex 写日志文件的目录，例如 codex-tui.log；默认值是 $CODEX_HOME/log。 |
mcp_oauth_callback_port |
integer | MCP OAuth 登录时本地 HTTP callback server 使用的固定端口。未设置时由操作系统分配临时端口。 |
mcp_oauth_callback_url |
string | MCP OAuth 登录的可选 redirect URI 覆盖值，例如 devbox ingress URL。mcp_oauth_callback_port 仍然控制回调监听端口。 |
mcp_oauth_credentials_store |
auto | file | keyring |
MCP OAuth 凭据的首选存储位置。 |
mcp_servers.<id>.args |
array<string> |
传给 MCP stdio server 启动命令的参数。 |
mcp_servers.<id>.bearer_token_env_var |
string | 作为 MCP HTTP server bearer token 来源的环境变量名。 |
mcp_servers.<id>.command |
string | MCP stdio server 的启动命令。 |
mcp_servers.<id>.cwd |
string | MCP stdio server 进程的工作目录。 |
mcp_servers.<id>.disabled_tools |
array<string> |
MCP server 的 deny list；会在 enabled_tools 之后应用。 |
mcp_servers.<id>.enabled |
boolean | 在不删除配置的前提下禁用一个 MCP server。 |
mcp_servers.<id>.enabled_tools |
array<string> |
MCP 服务端暴露的工具允许列表。 |
mcp_servers.<id>.env |
map<string,string> |
转发给 MCP stdio server 的环境变量。 |
mcp_servers.<id>.env_http_headers |
map<string,string> |
对 MCP HTTP server，从环境变量填充出来的 HTTP headers。 |
mcp_servers.<id>.env_vars |
array<string> |
额外允许转发给 MCP stdio server 的环境变量名。 |
mcp_servers.<id>.http_headers |
map<string,string> |
每次 MCP HTTP 请求都携带的静态 HTTP headers。 |
mcp_servers.<id>.oauth_resource |
string | MCP 登录期间附带的可选 RFC 8707 OAuth resource 参数。 |
mcp_servers.<id>.required |
boolean | 为 true 时，若该已启用 MCP server 无法初始化，则启动 / 恢复会失败。 |
mcp_servers.<id>.scopes |
array<string> |
对该 MCP server 进行认证时请求的 OAuth scopes。 |
mcp_servers.<id>.startup_timeout_ms |
number | startup_timeout_sec 的毫秒别名。 |
mcp_servers.<id>.startup_timeout_sec |
number | 覆盖 MCP server 默认 10 秒的启动超时。 |
mcp_servers.<id>.tool_timeout_sec |
number | 覆盖 MCP server 默认 60 秒的单工具超时。 |
mcp_servers.<id>.url |
string | MCP streamable HTTP server 的 endpoint。 |
| model | string | 要使用的模型，例如 gpt-5.4。 |
model_auto_compact_token_limit |
number | 触发自动历史压缩的 token 阈值（未设置时使用模型默认值）。 |
model_catalog_json |
string (path) |
启动时加载的可选 JSON model catalog 路径。profiles.<name>.model_catalog_json 可在 profile 级覆盖该值。 |
model_context_window |
number | 当前激活模型可用的 context window token 数。 |
model_instructions_file |
string (path) |
用于替代内建 instructions 的文件，而不是使用 AGENTS.md。 |
model_provider |
string | 从 model_providers 中选择的 provider id（默认 openai）。 |
model_providers.<id>.base_url |
string | 该 model provider 的 API base URL。 |
model_providers.<id>.env_http_headers |
map<string,string> |
仅在环境变量存在时，从环境变量填充的 HTTP headers。 |
model_providers.<id>.env_key |
string | 提供该 provider API key 的环境变量名。 |
model_providers.<id>.env_key_instructions |
string | 关于 provider API key 的可选配置提示。 |
model_providers.<id>.experimental_bearer_token |
string | 直接写在配置里的 provider bearer token（不推荐；应优先使用 env_key）。 |
model_providers.<id>.http_headers |
map<string,string> |
附加到 provider 请求上的静态 HTTP headers。 |
model_providers.<id>.name |
string | 自定义 model provider 的显示名称。 |
model_providers.<id>.query_params |
map<string,string> |
附加到 provider 请求上的额外 query 参数。 |
model_providers.<id>.request_max_retries |
number | 向该 provider 发起 HTTP 请求时的重试次数（默认 4）。 |
model_providers.<id>.requires_openai_auth |
boolean | 该 provider 是否使用 OpenAI 认证（默认 false）。 |
model_providers.<id>.stream_idle_timeout_ms |
number | SSE stream 的空闲超时（毫秒，默认 300000）。 |
model_providers.<id>.stream_max_retries |
number | SSE 流中断时的重试次数（默认 5）。 |
model_providers.<id>.supports_websockets |
boolean | 该 provider 是否支持 Responses API 的 WebSocket transport。 |
model_providers.<id>.auth |
table | 针对自定义 provider 的命令式 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.<id>.wire_api |
responses | 该 provider 使用的协议。当前唯一支持值是 responses，且省略时默认即为此值。 |
model_reasoning_effort |
minimal | low | medium | high | xhigh |
在支持的模型上调整 推理强度（仅 Responses API；xhigh 是否可用取决于模型）。 |
model_reasoning_summary |
auto | concise | detailed | none |
选择 reasoning summary 的详细程度，或彻底关闭 summary。 |
model_supports_reasoning_summaries |
boolean | 强制 Codex 发送或不发送 reasoning metadata。 |
model_verbosity |
low | medium | high |
可选的 GPT-5 Responses API 输出详细程度覆盖值；未设置时使用模型 / 预设默认值。 |
notice.hide_full_access_warning |
boolean | 记录是否已确认 full access warning 提示。 |
notice.hide_gpt-5.1-codex-max_migration_prompt |
boolean | 记录是否已确认 gpt-5.1-codex-max 迁移提示。 |
notice.hide_gpt5_1_migration_prompt |
boolean | 记录是否已确认 GPT-5.1 迁移提示。 |
notice.hide_rate_limit_model_nudge |
boolean | 记录是否选择不再看到 rate limit 模型切换提醒。 |
notice.hide_world_writable_warning |
boolean | 记录是否已确认 Windows world-writable 目录警告。 |
notice.model_migrations |
map<string,string> |
以 old->new 映射方式记录已确认的模型迁移。 |
| notify | array<string> |
用于通知的命令；Codex 会向其传入一个 JSON payload。 |
openai_base_url |
string | 内建 openai model provider 的 base URL 覆盖值。 |
oss_provider |
lmstudio | ollama |
运行 --oss 时使用的默认本地 provider（未设置时会提示用户选择）。 |
otel.environment |
string | 应用于 OpenTelemetry 事件的环境标签（默认 dev）。 |
otel.exporter |
none | otlp-http | otlp-grpc |
选择 OpenTelemetry exporter，并提供相应 endpoint 元数据。 |
otel.exporter.<id>.endpoint |
string | OTEL logs exporter 的 endpoint。 |
otel.exporter.<id>.headers |
map<string,string> |
OTEL exporter 请求所带的静态 headers。 |
otel.exporter.<id>.protocol |
binary | json |
OTLP/HTTP exporter 使用的协议。 |
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.log_user_prompt |
boolean | 是否把原始用户 prompt 一并导出到 OpenTelemetry logs。 |
otel.metrics_exporter |
none | statsig | otlp-http | otlp-grpc |
选择 OpenTelemetry metrics exporter（默认 statsig）。 |
otel.trace_exporter |
none | otlp-http | otlp-grpc |
选择 OpenTelemetry trace exporter，并提供相应 endpoint 元数据。 |
otel.trace_exporter.<id>.endpoint |
string | OTEL trace exporter 的 endpoint。 |
otel.trace_exporter.<id>.headers |
map<string,string> |
OTEL trace exporter 请求所带的静态 headers。 |
otel.trace_exporter.<id>.protocol |
binary | json |
OTLP/HTTP trace exporter 使用的协议。 |
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 使用的客户端私钥路径。 |
permissions.<name>.filesystem |
table | 命名的文件系统权限 profile。每个 key 可以是绝对路径，或 :minimal、:project_roots 等特殊标记。 |
permissions.<name>.filesystem.":project_roots".<subpath> |
"read" | "write" | "none" |
相对于检测到的项目根配置访问权限。用 "." 表示项目根本身。 |
permissions.<name>.filesystem.<path> |
"read" | "write" | "none" | table |
对某个路径或特殊标记直接赋权，或在该根下继续做嵌套授权。 |
permissions.<name>.network.allow_local_binding |
boolean | 允许通过 managed proxy 执行本地 bind / listen 操作。 |
permissions.<name>.network.allow_upstream_proxy |
boolean | 允许 managed proxy 再级联到其他 upstream proxy。 |
permissions.<name>.network.dangerously_allow_all_unix_sockets |
boolean | 允许 proxy 使用任意 Unix socket，而不是默认受限集合。 |
permissions.<name>.network.dangerously_allow_non_loopback_proxy |
boolean | 允许 managed proxy listener 绑定非 loopback 地址。 |
permissions.<name>.network.enable_socks5 |
boolean | 当该 permissions profile 启用 managed network proxy 时，额外暴露 SOCKS5 listener。 |
permissions.<name>.network.enable_socks5_udp |
boolean | 在启用 SOCKS5 listener 时允许 UDP。 |
permissions.<name>.network.enabled |
boolean | 是否为该命名 permissions profile 启用网络访问。 |
permissions.<name>.network.mode |
limited | full |
子进程流量使用的 network proxy 模式。 |
permissions.<name>.network.proxy_url |
string | 当该 permissions profile 启用 managed network proxy 时使用的 HTTP proxy endpoint。 |
permissions.<name>.network.socks_url |
string | 该 permissions profile 使用的 SOCKS5 proxy endpoint。 |
permissions.<name>.network.domains |
map<string, allow | deny> |
托管代理的域名规则。键可以是域名或通配模式，值为 allow 或 deny。 |
permissions.<name>.network.unix_sockets |
map<string, allow | none> |
托管代理的 Unix socket 规则。键为 socket 路径，值为 allow 或 none。 |
| personality | none | friendly | pragmatic |
对支持 supportsPersonality 的模型设置默认沟通风格；可在 thread / turn 级别或通过 /personality 覆盖。 |
plan_mode_reasoning_effort |
none | minimal | low | medium | high | xhigh |
计划模式 专用的 reasoning 覆盖值。未设置时，计划模式 使用其内建预设默认值。 |
| profile | string | 启动时应用的默认 profile（等价于 --profile）。 |
profiles.<name>.* |
various | 对任意受支持配置键做 profile 级覆盖。 |
profiles.<name>.analytics.enabled |
boolean | 配置档案级分析数据上报开关覆盖。 |
profiles.<name>.experimental_use_unified_exec_tool |
boolean | 启用 unified exec 的旧键名；优先使用 [features].unified_exec。 |
profiles.<name>.model_catalog_json |
string (path) |
profile 级 model catalog JSON 路径覆盖（仅启动时生效；会覆盖该 profile 下顶层的 model_catalog_json）。 |
profiles.<name>.model_instructions_file |
string (path) |
profile 级内建 instruction 文件替代路径。 |
profiles.<name>.oss_provider |
lmstudio | ollama |
profile 级 --oss 默认 provider。 |
profiles.<name>.personality |
none | friendly | pragmatic |
对支持 personality 的模型做 profile 级沟通风格覆盖。 |
profiles.<name>.plan_mode_reasoning_effort |
none | minimal | low | medium | high | xhigh |
profile 级 计划模式 reasoning 覆盖。 |
profiles.<name>.service_tier |
flex | fast |
profile 级新 turn service tier 偏好。 |
profiles.<name>.tools_view_image |
boolean | 在该 profile 中启用或禁用 view_image 工具。 |
profiles.<name>.web_search |
disabled | cached | live |
profile 级 web search 模式覆盖（默认 "cached"）。 |
profiles.<name>.windows.sandbox |
unelevated | elevated |
profile 级 Windows sandbox 模式覆盖。 |
project_doc_fallback_filenames |
array<string> |
当 AGENTS.md 缺失时要尝试的额外文件名。 |
project_doc_max_bytes |
number | 构建项目指令时，从 AGENTS.md 最多读取的字节数。 |
project_root_markers |
array<string> |
项目根标记文件名列表；用于向父目录搜索项目根。 |
projects.<path>.trust_level |
string | 将某个项目或 worktree 标记为可信或不可信（"trusted" | "untrusted"）。不可信项目会跳过项目级 .codex/ 配置层。 |
review_model |
string | /review 使用的可选模型覆盖值（默认使用当前 session 模型）。 |
sandbox_mode |
read-only | workspace-write | danger-full-access |
命令执行期间的文件系统与网络访问 sandbox 策略。 |
sandbox_workspace_write.exclude_slash_tmp |
boolean | 在 workspace-write 模式下，将 /tmp 排除出可写根目录。 |
sandbox_workspace_write.exclude_tmpdir_env_var |
boolean | 在 workspace-write 模式下，将 $TMPDIR 排除出可写根目录。 |
sandbox_workspace_write.network_access |
boolean | 在 workspace-write sandbox 中允许向外联网。 |
sandbox_workspace_write.writable_roots |
array<string> |
当 sandbox_mode = "workspace-write" 时的额外可写根目录。 |
service_tier |
flex | fast |
新 turn 的 service tier 偏好。 |
shell_environment_policy.exclude |
array<string> |
在默认过滤之后继续移除环境变量的 glob pattern 列表。 |
shell_environment_policy.experimental_use_profile |
boolean | 让子进程通过用户 shell profile 运行。 |
shell_environment_policy.ignore_default_excludes |
boolean | 在其他过滤之前，保留包含 KEY / SECRET / TOKEN 的环境变量。 |
shell_environment_policy.include_only |
array<string> |
白名单 pattern；设置后只保留匹配的变量。 |
shell_environment_policy.inherit |
all | core | none |
启动子进程时的基础环境继承策略。 |
shell_environment_policy.set |
map<string,string> |
注入到每个子进程里的显式环境变量覆盖。 |
show_raw_agent_reasoning |
boolean | 当当前模型会发出 raw reasoning 时，直接显示该内容。 |
skills.config |
array<object> |
保存在 config.toml 中的按技能启用覆盖配置。 |
skills.config.<index>.enabled |
boolean | 启用或禁用对应技能。 |
skills.config.<index>.path |
string (path) |
指向技能文件夹的路径，该文件夹内应包含 SKILL.md。 |
sqlite_home |
string (path) |
Codex 存放基于 SQLite 的状态数据库目录，供智能体作业与其他可恢复运行时状态使用。 |
suppress_unstable_features_warning |
boolean | 压制开启“开发中” 功能开关 时显示的警告。 |
tool_output_token_limit |
number | 在历史中保存单次 tool / function 输出时可使用的 token 预算。 |
tools.view_image |
boolean | 启用本地图片附件工具 view_image。 |
tools.web_search |
boolean | { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } } |
可选的 web search 工具配置。旧版布尔写法仍被接受，但对象写法可额外设置搜索上下文大小、允许域名，以及近似用户位置。 |
| tui | table | TUI 专属选项，例如是否启用内联桌面通知。 |
tui.alternate_screen |
auto | always | never |
控制 TUI 是否使用 alternate screen（默认 auto；在 Zellij 中会自动跳过，以保留 scrollback）。 |
tui.animations |
boolean | 启用终端动画，例如 welcome screen、shimmer、spinner（默认 true）。 |
tui.model_availability_nux.<model> |
integer | 以模型 slug 为 key 的内部启动提示状态。 |
tui.notification_method |
auto | osc9 | bel |
终端失焦时通知使用的方法（默认 auto）。 |
tui.notifications |
boolean | array<string> |
启用 TUI 通知；也可限制为特定事件类型。 |
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 主题名）。 |
web_search |
disabled | cached | live |
Web search 模式（默认 "cached"；cached 使用 OpenAI 维护的索引，不会抓取实时页面；若使用 --yolo 或其他 full access sandbox 设置，则默认切到 "live"）。"live" 会抓取最新网页数据，"disabled" 会移除该工具。 |
windows_wsl_setup_acknowledged |
boolean | 记录 Windows onboarding 是否已确认（仅 Windows）。 |
windows.sandbox |
unelevated | elevated |
在 Windows 原生模式下运行 Codex 时使用的原生 sandbox 模式（仅 Windows）。 |
windows.sandbox_private_desktop |
boolean | 在原生 Windows 上，默认让最终 sandboxed 子进程运行在私有桌面中。只有为兼容旧版 Winsta0\Default 行为时才应设为 false。 |
你可以在 这里 找到最新的 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 相同的标准键名固定 功能开关。没有写出的键不会受到限制。
| 键 | 类型 / 可选值 | 说明 |
|---|---|---|
allowed_approval_policies |
array<string> |
approval_policy 允许使用的值，例如 untrusted、on-request、never 和 granular。 |
allowed_approvals_reviewers |
array<string> |
approvals_reviewer 允许使用的值，例如 user 和 guardian_subagent。 |
allowed_sandbox_modes |
array<string> |
sandbox_mode 允许使用的值。 |
allowed_web_search_modes |
array<string> |
web_search 允许使用的值（disabled、cached、live）。disabled 永远允许；若为空数组，则效果上只允许 disabled。 |
| features | table | 按 config.toml 中 [features] 的 canonical key 固定 feature 值。 |
features.<name> |
boolean | 要求某个 canonical feature key 必须保持启用或禁用。 |
mcp_servers |
table | 允许启用的 MCP 服务端允许列表。只有当服务端名称（<id>）和身份信息都匹配时，该 MCP 服务端才能启用。凡是不在允许列表中，或身份不匹配的 MCP 服务端，都会被禁用。 |
mcp_servers.<id>.identity |
table | 单个 MCP server 的身份规则。可设置 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 与该值匹配时，允许该 MCP streamable HTTP server。 |
| rules | table | 与 .rules 文件合并的管理员强制命令规则。requirements 中的 rules 必须是收紧型限制。 |
rules.prefix_rules |
array<table> |
强制生效的 prefix rules 列表。每条规则都必须包含 pattern 和 decision。 |
rules.prefix_rules[].decision |
prompt | forbidden |
必填。requirements 中的规则只能是 prompt 或 forbidden，不能是 allow。 |
rules.prefix_rules[].justification |
string | 可选的非空说明，会显示在 approval 提示或拒绝消息中。 |
rules.prefix_rules[].pattern |
array<table> |
以前缀 token 形式表达的命令模式。每个 token 位置都要设置 token 或 any_of。 |
rules.prefix_rules[].pattern[].any_of |
array<string> |
该位置允许的多个备选 token。 |
rules.prefix_rules[].pattern[].token |
string | 该位置必须匹配的单个字面 token。 |