把本页当成 Codex 配置文件的可检索参考手册来使用。若你想先看概念解释和典型示例，请从 配置基础 和 高级配置 开始。
config.toml
用户级配置位于 ~/.codex/config.toml。你也可以在 .codex/config.toml 中添加项目级覆盖配置。Codex 只会在你信任该项目时加载项目级 .codex/ 配置层。
项目级配置不能覆盖机器本地的 provider、认证、通知、配置档案或 telemetry 路由键。Codex 会忽略项目本地 .codex/config.toml 中的 openai_base_url、chatgpt_base_url、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url 和 otel；这些键应放在用户级配置中。
对于和沙箱、审批有关的配置键，例如 approval_policy、sandbox_mode 和 sandbox_workspace_write.*，建议把本页与 沙箱与审批、可写根目录中的受保护路径 以及 网络访问 搭配阅读。关于 beta 权限配置档案，请参见权限。
| 键 | 类型 / 可选值 | 说明 |
|---|---|---|
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。 |
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 | 全局 consolidation 保留的近期 raw memories 最大数量。默认 256，上限 4096。 |
memories.max_unused_days |
number | 记忆距离上次使用超过多少天后不再参与 consolidation。默认 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 rate-limit 窗口剩余百分比达到该阈值后，才会开始记忆生成。默认 25，范围限制为 0-100。 |
memories.extract_model |
string | 针对单线程记忆提取使用的可选模型覆盖。 |
memories.consolidation_model |
string | 针对全局记忆 consolidation 使用的可选模型覆盖。 |
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 | auto_review |
在 on-request 或细粒度审批策略下，指定由谁审核符合条件的审批提示。默认是 user；设为 auto_review 时，会由评审子智能体自动审核。这不会改变沙箱边界，也不会影响原本已在沙箱内允许执行的动作。 |
auto_review.policy |
string | 自动评审使用的本地 Markdown 策略指令。若管理员下发了 guardian_policy_config，则以托管配置为准；空值会被忽略。 |
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。 |
tool_suggest.disabled_tools |
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 | 在 [features].codex_git_commit 启用时使用的 commit co-author trailer。默认是 Codex <noreply@openai.com>；设为 "" 可禁用。 |
compact_prompt |
string | 对历史压缩提示词的内联覆盖。 |
default_permissions |
string | 应用于 sandboxed tool calls 的默认 permissions profile 名称。内建值为 :read-only、:workspace 和 :danger-full-access；自定义 profile 名称必须有对应的 [permissions.<name>] 表。 |
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_git_commit |
boolean | 启用由 Codex 生成 git commit。启用后，Codex 会使用 commit_attribution 在生成的 commit message 中追加 Co-authored-by: trailer。 |
features.hooks |
boolean | 启用从 hooks.json 或内联 [hooks] 配置加载的生命周期钩子。features.codex_hooks 是已弃用 alias。 |
hooks |
table | 在 config.toml 中内联配置的生命周期钩子。使用与 hooks.json 相同的事件 schema；示例和支持事件请参见 Hooks。 |
features.plugin_hooks |
boolean | 选择启用已启用插件中打包的生命周期 hooks。本版本默认关闭；设置为 true 才会启用。 |
features.enable_request_compression |
boolean | 在支持时使用 zstd 压缩流式请求体（Stable；默认开启）。 |
features.fast_mode |
boolean | 启用 TUI 中基于模型目录的 service tier 选择；当当前模型声明 Fast tier 时，也会启用对应命令（Stable；默认开启）。 |
features.memories |
boolean | 启用 记忆（默认关闭）。 |
features.multi_agent |
boolean | 启用多智能体协作工具，例如 spawn_agent、send_input、resume_agent、wait_agent、close_agent（Stable；默认开启）。 |
features.personality |
boolean | 启用 personality 选择控件（Stable；默认开启）。 |
features.network_proxy |
boolean | table |
启用 sandboxed networking。设置 domains 等网络策略选项时使用 table 形式（实验性；默认关闭）。 |
features.network_proxy.enabled |
boolean | 启用 sandboxed networking。默认 false。 |
features.network_proxy.domains |
map<string, allow | deny> |
sandboxed networking 的域名策略。默认未设置，表示在添加 allow 规则前不允许外部目的地。支持精确主机、只匹配子域名的 *.example.com、同时匹配 apex 和子域名的 **.example.com，以及全局 * allow 规则；* 会宽泛打开公共出站访问，应优先使用更窄规则。添加 deny 规则可阻止目的地，冲突时 deny 优先。 |
features.network_proxy.unix_sockets |
map<string, allow | none> |
sandboxed networking 的 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 listener 地址。默认 false；启用后可能把 proxy listener 暴露到 localhost 之外。 |
features.network_proxy.dangerously_allow_all_unix_sockets |
boolean | 允许任意 Unix socket 目的地，而不是只允许 allowlist 条目。默认 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.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.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>.default_tools_approval_mode |
auto | prompt | approve |
该 MCP server 中工具的默认审批行为，除非有单工具覆盖。 |
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 | { name = string, source = "local" | "remote" }> |
额外允许转发给 MCP stdio server 的环境变量。字符串条目默认使用 source = "local"；只有在 executor-backed remote stdio 场景下才使用 source = "remote"。 |
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>.experimental_environment |
local | remote |
MCP server 的实验性运行位置。remote 会通过远程 executor 环境启动 stdio server；streamable HTTP 的 remote placement 尚未实现。 |
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。 |
mcp_servers.<id>.tools.<tool>.approval_mode |
auto | prompt | approve |
对该 MCP server 中单个工具的审批行为覆盖。 |
| model | string | 要使用的模型，例如 gpt-5.5。 |
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.amazon-bedrock.aws.profile |
string | 内建 amazon-bedrock provider 使用的 AWS profile 名称。 |
model_providers.amazon-bedrock.aws.region |
string | 内建 amazon-bedrock provider 使用的 AWS region。 |
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>.workspace_roots |
table | 由 profile 定义的 workspace roots，会和当前 session 的运行时 workspace roots 一起接收 :workspace_roots 文件系统规则。 |
permissions.<name>.workspace_roots.<path> |
boolean | 值为 true 时，把该路径加入这个 profile 的 workspace root 集合；禁用的条目保持不生效。 |
permissions.<name>.filesystem |
table | 命名的文件系统权限 profile。每个 key 可以是绝对路径，或 :minimal、:workspace_roots 等特殊标记。 |
permissions.<name>.filesystem.glob_scan_max_depth |
number | 在某些需要在 sandbox 启动前快照匹配结果的平台上，展开 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" |
相对于每个有效 workspace root 配置访问权限。用 "." 表示 root 本身；可用 "**/*.env" 这类 glob 子路径配合 "deny" 拒绝读取。 |
permissions.<name>.network.allow_local_binding |
boolean | 允许通过 sandboxed networking 进行更宽的本地 / 私有网络访问。当它保持 false 时，精确本地 IP literal 或 localhost allow 规则仍可允许特定本地目标。 |
permissions.<name>.network.allow_upstream_proxy |
boolean | 允许 sandboxed networking 级联到另一个 upstream proxy。 |
permissions.<name>.network.dangerously_allow_all_unix_sockets |
boolean | 允许任意 Unix socket 目的地，而不是默认受限集合。只能在严格受控环境中使用。 |
permissions.<name>.network.dangerously_allow_non_loopback_proxy |
boolean | 允许 sandboxed networking listener 绑定非 loopback 地址。启用后可能把 listener 暴露到 localhost 之外。 |
permissions.<name>.network.enable_socks5 |
boolean | 当该 permissions profile 启用 sandboxed networking 时，暴露 SOCKS5 支持。 |
permissions.<name>.network.enable_socks5_udp |
boolean | 在启用 SOCKS5 listener 时允许 UDP。 |
permissions.<name>.network.enabled |
boolean | 是否为该命名 permissions profile 启用网络访问。这会改变 sandbox 网络策略，但不会自行启动网络代理。 |
permissions.<name>.network.proxy_url |
string | 当该 permissions profile 启用 sandboxed networking 时使用的 HTTP listener URL。 |
permissions.<name>.network.socks_url |
string | 该 permissions profile 使用的 SOCKS5 proxy endpoint。 |
permissions.<name>.network.mode |
limited | full |
子进程流量使用的网络代理模式。 |
permissions.<name>.network.domains |
table | sandboxed networking 的域名规则。支持精确主机、只匹配子域名的 *.example.com、同时匹配 apex 和子域名的 **.example.com，以及全局 * allow 规则。冲突时 deny 优先。 |
permissions.<name>.network.domains.<pattern> |
allow | deny |
允许或拒绝精确主机，或 *.example.com、**.example.com 这类限定通配符模式。 |
permissions.<name>.network.unix_sockets |
table | sandboxed networking 的 Unix socket allowlist 覆盖。键为 socket 路径；allow 会加入路径，none 会清除继承来的 allow 条目。 |
permissions.<name>.network.unix_sockets.<path> |
allow | none |
用 allow 把绝对 Unix socket 路径加入有效 allowlist，或用 none 清除继承来的 allow 条目。none 不是独立的 deny-list 决策。 |
| 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 |
string | 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 |
string | 新 turn 的 service tier 偏好。内建值包括 flex 和 fast；旧版 fast 配置会映射为请求值 priority，模型目录提供的 tier ID 也可以存储在这里。 |
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 工具配置。旧版布尔写法仍被接受，但对象写法可额外设置搜索上下文大小、允许域名，以及近似用户位置。 |
plugins.<plugin>.mcp_servers.<server>.enabled |
boolean | 在不修改插件 manifest 的前提下，启用或禁用已安装插件打包的 MCP server。 |
plugins.<plugin>.mcp_servers.<server>.default_tools_approval_mode |
auto | prompt | 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 | approve |
对插件提供的 MCP 工具的单工具审批行为覆盖。 |
| tui | table | TUI 专属选项，例如是否启用内联桌面通知。 |
tui.alternate_screen |
auto | always | never |
控制 TUI 是否使用 alternate screen（默认 auto；在 Zellij 中会自动跳过，以保留 scrollback）。 |
tui.animations |
boolean | 启用终端动画，例如 welcome screen、shimmer、spinner（默认 true）。 |
tui.vim_mode_default |
boolean | 启动时让输入框进入 Vim normal mode，而不是 insert mode（默认 false）。仍可在会话中用 /vim 切换。 |
tui.raw_output_mode |
boolean | 启动 TUI 时使用 raw scrollback mode，便于在终端中选择和复制（默认 false）。可通过 /raw 或默认 alt-r 绑定切换。 |
tui.model_availability_nux.<model> |
integer | 以模型 slug 为 key 的内部启动提示状态。 |
tui.notification_method |
auto | osc9 | bel |
终端通知使用的方法（默认 auto）。 |
tui.notification_condition |
unfocused | always |
控制 TUI 通知只在终端失焦时触发，还是无论焦点状态都触发。默认 unfocused。 |
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 主题名）。 |
tui.keymap.<context>.<action> |
string | array<string> |
TUI 动作的快捷键绑定。支持的 context 包括 global、chat、composer、editor、pager、list 和 approval；特定 context 的绑定会覆盖 tui.keymap.global。 |
tui.keymap.<context>.<action> = [] |
empty array | 在对应 keymap context 中解除该动作绑定。按键名使用 ctrl-a、shift-enter、page-down 或 minus 这类规范化字符串。 |
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 和 auto_review。 |
guardian_policy_config |
string | 自动评审使用的托管 Markdown 策略指令。它的优先级高于本地 [auto_review].policy；空值会被忽略。 |
allowed_sandbox_modes |
array<string> |
sandbox_mode 允许使用的值。 |
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、live）。disabled 永远允许；若为空数组，则效果上只允许 disabled。 |
features |
table | 按 config.toml 中 [features] 的 canonical key 固定 feature 值。 |
features.<name> |
boolean | 要求某个 canonical feature key 必须保持启用或禁用。 |
features.in_app_browser |
boolean | 在 requirements.toml 中设为 false 可禁用 app 内浏览器面板。 |
features.browser_use |
boolean | 在 requirements.toml 中设为 false 可禁用 Browser Use 和 Browser Agent 可用性。 |
features.computer_use |
boolean | 在 requirements.toml 中设为 false 可禁用 Computer Use 可用性及相关安装或设置流程。 |
experimental_network |
table | 从 requirements.toml 强制执行的网络访问要求。这些约束与 features.network_proxy 相互独立，可以在没有用户功能开关的情况下配置 sandboxed networking。 |
experimental_network.enabled |
boolean | 启用 sandboxed networking 要求。如果当前激活的沙箱关闭命令联网，这不会授予网络访问。 |
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 使用环境中的 upstream proxy。 |
experimental_network.dangerously_allow_non_loopback_proxy |
boolean | 允许 [experimental_network] 要求使用非 loopback listener 地址。启用后可能把 listener 暴露到 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 时，在 sandboxed networking 要求生效期间，只有管理员管理的 allow 规则继续有效；用户新增的 allowlist 条目会被忽略。若没有托管 allow 规则，用户新增的域名 allow 规则也不会继续有效。 |
experimental_network.unix_sockets |
map<string, allow | none> |
管理员管理的 Unix socket 策略，用于 sandboxed networking。 |
experimental_network.allow_local_binding |
boolean | 允许 sandboxed networking 进行更宽的本地 / 私有网络访问。当它保持 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、SessionStart、UserPromptSubmit 或 Stop。 |
hooks.<Event>[].hooks |
array<table> |
matcher 分组下的钩子处理器。当前支持 command hooks；prompt 和 agent hook handlers 会被解析但跳过。 |
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。 |
permissions.filesystem.deny_read |
array<string> |
管理员强制的文件系统读拒绝规则。条目可以是路径或 glob pattern，用户不能通过本地配置放宽这些规则。 |
| 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。 |