Appearance
本文是 Codex 配置文件的完整键值参考手册，涵盖 ~/.codex/config.toml 和 .codex/config.toml 支持的所有配置项，以及企业用 requirements.toml 的管控键。配合 配置基础 和 高级配置 使用，本文专注于"有什么键、类型是什么、默认是什么"，而非使用方法。
Codex 配置项完整参考
用户级配置存放在 ~/.codex/config.toml，也可以在仓库里加 .codex/config.toml 做项目级覆盖（仅受信任项目）。
核心模型选项
| 键 | 类型 | 说明 |
|---|---|---|
model | string | 默认模型（如 gpt-5.4） |
review_model | string | /review 使用的模型覆盖，默认用当前 session 模型 |
model_provider | string | 来自 model_providers 的 provider id，默认 openai |
openai_base_url | string | 内置 openai provider 的 base URL 覆盖 |
model_context_window | number | 当前模型可用的上下文 token 数 |
model_auto_compact_token_limit | number | 触发自动历史压缩的 token 阈值，未设置时用模型默认值 |
model_catalog_json | string (path) | 启动时加载的 JSON 模型目录路径，Profile 级可覆盖 |
oss_provider | lmstudio | ollama | 使用 --oss 时的默认本地 provider |
审批策略
| 键 | 类型 | 说明 |
|---|---|---|
approval_policy | untrusted | on-request | never | { granular = {...} } | 控制 Codex 执行命令前何时暂停审批。granular 对象可对不同类型的审批请求分别设置 |
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 | guardian_subagent | 决定由谁审查审批请求，默认 user |
allow_login_shell | boolean | 允许 shell 工具使用 login shell 语义，默认 true |
沙箱模式
| 键 | 类型 | 说明 |
|---|---|---|
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 原生沙箱模式 |
windows.sandbox_private_desktop | boolean | Windows 上在私有桌面运行最终沙箱子进程 |
认证与登录
| 键 | 类型 | 说明 |
|---|---|---|
cli_auth_credentials_store | file | keyring | auto | CLI 凭据存储方式，默认 file |
chatgpt_base_url | string | ChatGPT 登录流使用的 base URL |
forced_chatgpt_workspace_id | string (uuid) | 限制 ChatGPT 登录到特定工作区 |
forced_login_method | chatgpt | api | 强制使用特定认证方式 |
mcp_oauth_credentials_store | auto | file | keyring | MCP OAuth 凭据的存储方式，默认 auto |
mcp_oauth_callback_port | integer | MCP OAuth 回调服务器的固定端口 |
mcp_oauth_callback_url | string | MCP OAuth 登录的重定向 URI 覆盖 |
模型推理与详细程度
| 键 | 类型 | 说明 |
|---|---|---|
model_reasoning_effort | minimal | low | medium | high | xhigh | 推理强度，仅 Responses API 生效 |
plan_mode_reasoning_effort | none | minimal | low | medium | high | xhigh | Plan 模式的推理强度覆盖 |
model_reasoning_summary | auto | concise | detailed | none | 推理摘要详细程度 |
model_verbosity | low | medium | high | GPT-5 Responses API 文本详细程度覆盖 |
model_supports_reasoning_summaries | boolean | 强制启用或禁用推理元数据 |
指令覆盖
| 键 | 类型 | 说明 |
|---|---|---|
developer_instructions | string | 注入到 session 的额外开发者指令 |
compact_prompt | string | 历史压缩提示的内联覆盖 |
commit_attribution | string | 覆盖 commit co-author trailer，设为空字符串禁用 |
model_instructions_file | string (path) | 替换内置指令的文件路径 |
experimental_compact_prompt_file | string (path) | 从文件加载压缩提示覆盖（实验性） |
MCP Servers
| 键 | 类型 | 说明 |
|---|---|---|
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>.url | string | MCP streamable HTTP server 的端点 |
mcp_servers.<id>.bearer_token_env_var | string | MCP HTTP server 的 Bearer token 环境变量 |
mcp_servers.<id>.http_headers | map<string,string> | MCP HTTP 请求的静态 header |
mcp_servers.<id>.enabled | boolean | 禁用 MCP server 而不删除配置 |
mcp_servers.<id>.required | boolean | true 时若 MCP server 初始化失败则中止启动 |
mcp_servers.<id>.startup_timeout_sec | number | MCP server 启动超时，默认 10s |
mcp_servers.<id>.tool_timeout_sec | number | MCP server 单个工具调用超时，默认 60s |
mcp_servers.<id>.enabled_tools | array<string> | MCP server 暴露的工具允许列表 |
mcp_servers.<id>.disabled_tools | array<string> | 在允许列表之后应用的工具拒绝列表 |
mcp_servers.<id>.scopes | array<string> | 认证时请求的 OAuth scope |
子代理（[agents]）
| 键 | 类型 | 说明 |
|---|---|---|
agents.max_threads | number | 最大并发 agent 线程数，默认 6 |
agents.max_depth | number | 最大嵌套 spawn 深度（root session 从 0 开始），默认 1 |
agents.job_max_runtime_seconds | number | spawn_agents_on_csv 任务每个 worker 的默认超时，未设置时默认 1800s |
agents.<name>.description | string | 选择和生成该 agent 类型时展示给 Codex 的角色描述 |
agents.<name>.config_file | string (path) | 该角色的 TOML 配置层文件路径 |
agents.<name>.nickname_candidates | array<string> | 该角色 spawn 的 agent 的可选展示昵称池 |
Feature Flags（[features]）
| 键 | 默认值 | 说明 |
|---|---|---|
features.unified_exec | true（Windows 除外） | 使用统一的 PTY-backed exec 工具 |
features.shell_snapshot | true | 快照 shell 环境以加速重复命令 |
features.undo | false | 启用撤销支持 |
features.multi_agent | true | 启用多 agent 协作工具 |
features.personality | true | 启用通信风格选择控件 |
features.shell_tool | true | 启用默认 shell 工具 |
features.fast_mode | true | 启用 Fast 模式路径 |
features.smart_approvals | false | 将部分审批请求路由给 guardian subagent |
features.apps | false | 启用 ChatGPT Apps/Connectors 支持 |
features.codex_hooks | false | 从 hooks.json 启用生命周期 hooks |
features.prevent_idle_sleep | false | 防止任务运行时机器休眠 |
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> | 注入到所有子进程的显式环境变量覆盖 |
Profiles（命名配置集）
| 键 | 类型 | 说明 |
|---|---|---|
profile | string | 启动时应用的默认 profile |
profiles.<name>.* | various | 任意受支持配置键的 profile 级覆盖 |
profiles.<name>.model_catalog_json | string (path) | profile 级模型目录覆盖 |
profiles.<name>.web_search | disabled | cached | live | profile 级联网模式覆盖 |
profiles.<name>.personality | none | friendly | pragmatic | profile 级通信风格覆盖 |
自定义 Model Provider
| 键 | 类型 | 说明 |
|---|---|---|
model_providers.<id>.name | string | Provider 展示名称 |
model_providers.<id>.base_url | string | Provider API base URL |
model_providers.<id>.env_key | string | 提供 API key 的环境变量名 |
model_providers.<id>.wire_api | responses | Provider 使用的协议，responses 是唯一支持的值 |
model_providers.<id>.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>.auth.command | string | 获取 Bearer token 的命令，必须将 token 打印到 stdout |
model_providers.<id>.auth.timeout_ms | number | token 命令最大运行时间（毫秒），默认 5000 |
model_providers.<id>.auth.refresh_interval_ms | number | 主动刷新 token 的间隔（毫秒），默认 300000；设为 0 只在认证失败时刷新 |
历史记录与文件打开器
| 键 | 类型 | 说明 |
|---|---|---|
history.persistence | save-all | none | 是否保存 session 记录到 history.jsonl |
history.max_bytes | number | 历史文件大小上限（字节），超出时清理最旧记录 |
file_opener | vscode | vscode-insiders | windsurf | cursor | none | 引用链接使用的 URI scheme |
TUI 选项
| 键 | 类型 | 说明 |
|---|---|---|
tui.notifications | boolean | array<string> | 启用 TUI 通知；可选限定特定事件类型 |
tui.notification_method | auto | osc9 | bel | 终端通知方式，默认 auto |
tui.animations | boolean | 启用终端动画，默认 true |
tui.alternate_screen | auto | always | never | 备用屏幕控制，默认 auto |
tui.show_tooltips | boolean | 显示欢迎屏幕的新手引导提示，默认 true |
tui.status_line | array<string> | null | TUI 底部状态栏项目列表，null 禁用 |
tui.terminal_title | array<string> | null | 终端标题内容列表，默认 ["spinner", "project"] |
tui.theme | string | 语法高亮主题（kebab-case 名称） |
hide_agent_reasoning | boolean | 在 TUI 和 codex exec 输出中隐藏推理事件 |
show_raw_agent_reasoning | boolean | 显示模型原始推理内容 |
OTel 遥测
| 键 | 类型 | 说明 |
|---|---|---|
otel.environment | string | OTel 事件的环境标签，默认 dev |
otel.exporter | none | otlp-http | otlp-grpc | OTel 日志导出器类型 |
otel.trace_exporter | none | otlp-http | otlp-grpc | OTel trace 导出器类型 |
otel.log_user_prompt | boolean | 在 OTel 日志里包含原始用户 prompt |
analytics.enabled | boolean | 启用或禁用匿名遥测 |
feedback.enabled | boolean | 允许通过 /feedback 提交反馈，默认 true |
其他配置项
| 键 | 类型 | 说明 |
|---|---|---|
notify | array<string> | 通知外部程序的命令（接收 JSON payload） |
check_for_update_on_startup | boolean | 启动时检查更新，默认 true |
personality | none | friendly | pragmatic | 默认通信风格 |
service_tier | flex | fast | 新 turn 的首选服务层级 |
web_search | disabled | cached | live | 联网模式，默认 cached |
project_doc_max_bytes | number | 读取 AGENTS.md 的最大字节数 |
project_root_markers | array<string> | 项目根目录标志文件列表 |
log_dir | string (path) | Codex 日志文件目录 |
projects.<path>.trust_level | string | 标记项目为受信任或不受信任 |
requirements.toml（企业管控）
requirements.toml 是管理员用的强制配置文件，约束用户无法覆盖的安全敏感设置。详见企业托管配置。
| 键 | 类型 | 说明 |
|---|---|---|
allowed_approval_policies | array<string> | approval_policy 的允许值（如 untrusted、on-request） |
allowed_sandbox_modes | array<string> | sandbox_mode 的允许值 |
allowed_web_search_modes | array<string> | web_search 的允许值 |
features | table | 按 config.toml 的 [features] 键名固定 feature 状态 |
features.<name> | boolean | 要求特定 feature 保持启用或禁用 |
mcp_servers | table | 允许启用的 MCP server 白名单（名称 + 身份必须同时匹配） |
rules.prefix_rules | array<table> | 管理员强制的命令前缀规则 |
IDE 自动补全
在 VS Code 或 Cursor 里编辑 config.toml 时，可以安装 Even Better TOML 扩展，并在 config.toml 顶部加：
toml
#:schema https://developers.openai.com/codex/config-schema.json这样编辑时会有自动补全和类型检查。
常见问题
Q: approval_policy 的各个值分别是什么行为？
A: untrusted — 只有已知安全的只读命令可以自动运行，其他都会弹出审批；on-request — 由模型决定何时请求审批（默认，适合交互式使用）；never — 从不弹出审批（无人值守场景，有风险）。
Q: requirements.toml 和 config.toml 的区别是什么？
A: config.toml 是用户/项目级配置，用户可以修改。requirements.toml 是管理员级强制约束，用户的 config.toml 不能覆盖 requirements.toml 限制的配置项。
Q: 我想接入不支持 openai provider ID 的自定义 LLM，怎么做？
A: 在 [model_providers] 下新建一个自定义 ID（不能用 openai、ollama、lmstudio），配置 base_url 和认证信息，然后用 model_provider = "你的id" 指向它。