Codex 完整指南（五）：config.toml 配置详解｜模型、审批与沙箱机制
本文详解 OpenAI Codex 配置：~/.codex/config.toml 的位置与优先级，覆盖 model、approval_policy、sandbox_mode、features、Profiles、CLI 覆盖，并讲解模型提供方、OSS/Azure、环境变量与遥测，帮助快速搭建安全高效的 AI 编程代理环境。
·
1. 引言
在前几篇文章里，博主已经编写了Codex相关的文章，有兴趣的童鞋可以先阅读：
- 《Codex 完整指南（一）：快速入门｜工程级 AI 编程代理》
- 《Codex 完整指南（二）：核心概念详解｜工程级 AI 编程智能体》
- 《Codex 完整指南（三）：OpenAI 官方实战指南整理｜251 篇（最新）》
- 《Codex 完整指南（四）：多端使用全景图｜IDE、CLI、Cloud 与团队集成》
Codex 会在本地执行命令、读写文件、请求审批，其行为几乎完全由 ~/.codex/config.toml 决定。默认配置虽然安全，但在真实工程场景下往往限制较多。
本文将围绕 Codex 的配置体系展开，从基础配置到高级用法，重点说明每个关键配置项的作用与影响范围，帮助大家快速搭建一套符合自己工作流的 Codex 运行环境。
2. 基础配置
Codex 会从 ~/.codex/config.toml 读取本地设置，你可以使用这个文件来更改默认值（比如模型）、设置审批与沙箱行为，以及配置 MCP 服务器。
2.1 配置文件
Codex 将其配置存储在：~/.codex/config.toml，要从 Codex IDE 扩展打开该配置文件：
- 点击右上角的齿轮图标；
- 选择 Codex 设置（Codex Settings）；
- 然后选择 打开 config.toml（Open config.toml）
CLI 与 IDE 扩展共用同一个 config.toml 文件。你可以使用它来：
- 设置默认模型与提供商
- 配置审批策略与沙箱设置
- 配置 MCP 服务器
2.2 配置优先级
Codex 在解析值时遵循以下顺序：
- CLI 标志（例如
--model）； - 通过
--profile <名称>指定的配置文件值（Profile）； config.toml顶层值；- 内置默认值 。
使用这种优先级意味着你可以在顶层设置共享默认值，将可变的值保持在 Profile 中，要进行单次覆盖（包括 TOML 引号规则），请参阅高级配置（Advanced Config）：https://developers.openai.com/codex/config-advanced#one-off-overrides-from-the-cli
备注：在受管理的机器上，你的组织也可能通过
requirements.toml强制执行约束，例如不允许approval_policy = "never"或sandbox_mode = "danger-full-access"。
2.3 常见配置选项
以下是最常修改的一些配置，所有示例都在 config.toml 顶层配置中设置。
① 默认模型：选择 CLI 和 IDE 中 Codex 默认使用的模型
model = "gpt-5.2"
② 审批提示： 控制 Codex 在执行生成命令之前何时暂停询问
approval_policy = "on-request"
③ 沙箱级别：调整 Codex 在执行命令时对文件系统和网络访问的程度
sandbox_mode = "workspace-write"
④ 推理强度：调整在模型支持时 Codex 使用多少推理能力
model_reasoning_effort = "high"
⑤ 命令环境：限制或扩展哪些环境变量会被传递给被启动的命令：
[shell_environment_policy]
include_only = ["PATH", "HOME"]
2.4 功能开关
可选的实验性功能可以通过 config.toml 中的 [features] 表来切换：
[features]
shell_snapshot = true # 加快重复命令的速度
web_search_request = true # 允许模型请求网页搜索
支持的功能（成熟度标签表示该功能的稳定性与实验性质，可以根据需要选择开启或保持默认）：
| 键 | 默认值 | 成熟度 | 描述 |
|---|---|---|---|
| apply_patch_freeform | false | Experimental | 包含自由形式的 apply_patch 工具 |
| elevated_windows_sandbox | false | Experimental | 使用提升权限的 Windows 沙箱 |
| exec_policy | true | Experimental | 对 shell / unified_exec 强制策略检查 |
| experimental_windows_sandbox | false | Experimental | 使用 Windows 限制令牌沙箱 |
| remote_compaction | true | Experimental | 启用远程压缩（仅限 ChatGPT 授权） |
| remote_models | false | Experimental | 刷新远程模型列表以显示可用性 |
| shell_snapshot | false | Beta | 快速完成重复命令 |
| shell_tool | true | Stable | 启用默认的 shell 工具 |
| unified_exec | false | Beta | 使用统一的 PTY 执行工具 |
| undo | true | Stable | 支持通过每次操作的 git 快照进行撤销 |
| web_search_request | false | Stable | 允许模型发起网页搜索请求 |
如果要快速启用某个功能，可以 在 config.toml 的 [features] 部分添加：
feature_name = true
或者从命令行运行：
codex --enable feature_name
如果要同时启用多个功能：
codex --enable feature_a --enable feature_b
要停用某个功能，将其设置为：
feature_name = false
这样就可以灵活控制 Codex 的实验性与高级功能。
3. 高级配置
3.1 Profiles
Profiles 允许你保存一组具名的配置集合，并在 CLI 中快速切换。
Profiles 目前仍处于实验阶段，未来版本中可能会变更或移除；
Codex IDE 扩展目前 不支持 Profiles。
在 config.toml 中通过 [profiles.<name>] 定义profiles，然后运行：
codex --profile <name>
示例：
model = "gpt-5-codex"
approval_policy = "on-request"
[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"
如果你想让某个 profile 成为默认值，可在 config.toml 顶层添加：
profile = "deep-review"
除非在命令行中显式覆盖，否则 Codex 会自动加载该 profile。
3.2 通过 CLI 进行单次覆盖
除了编辑 ~/.codex/config.toml 之外，你还可以在 单次运行时 通过 CLI 覆盖配置：
- 优先使用已有的专用参数（例如
--model） - 如需覆盖任意键，使用
-c / --config
示例：
# 专用参数
codex --model gpt-5.2
# 通用键值覆盖（值是 TOML，而不是 JSON）
codex --config model='"gpt-5.2"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'
注意事项：
- 配置键支持 点号语法 来设置嵌套值（例如：
mcp_servers.context7.enabled=false）； --config的值会按 TOML 解析；- 如有疑问，请加引号以避免
shell按空格拆分，如果无法解析为 TOML，Codex 会将其当作字符串处理。
3.3 配置与状态文件位置
Codex 会将本地状态存储在 CODEX_HOME 目录下（默认是 ~/.codex），你可能会看到的常见文件包括：
config.toml：本地配置；auth.json：使用文件方式存储凭据时或系统的 keychain / keyring；history.jsonl：启用历史记录持久化时，其他每用户状态，例如日志和缓存。
关于认证（包括凭据存储方式）的更多细节，请参见 Authentication，完整配置键列表请参见 Configuration Reference。
3.4 项目根目录检测
Codex 会从当前工作目录向上查找项目配置（例如 .codex/ 层级和 AGENTS.md），直到找到“项目根目录”，默认情况下，只要目录中包含 .git，就会被视为项目根目录，可以在 config.toml 中自定义该行为：
# 当目录中包含以下任意标记时，将其视为项目根目录
project_root_markers = [".git", ".hg", ".sl"]
如果设置为空数组：
project_root_markers = []
则 Codex 不再向上搜索父目录，而是将当前工作目录视为项目根目录。
3.5 自定义模型提供方
模型提供方定义了 Codex 如何连接模型（基础 URL、API 协议、可选 HTTP 头），你可以定义额外的提供方，并通过 model_provider 指向它们：
model = "gpt-5.1"
model_provider = "proxy"
[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"
[model_providers.ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"
[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"
如有需要，可添加请求头：
[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }
3.6 OpenAI 基础 URL 覆盖
如果你只是想让内置 OpenAI 提供方指向一个 LLM 代理或路由器，可以直接设置 OPENAI_BASE_URL，无需修改 config.toml：
export OPENAI_BASE_URL="https://api.openai.com/v1"
codex
3.7 OSS 模式（本地模型提供方）
当你使用 --oss 参数时，Codex 可以运行在本地“开源”模型提供方之上（例如 Ollama 或 LM Studio），如果使用 --oss 但未指定提供方，Codex 会使用 oss_provider 作为默认值：
# 使用 --oss 时的默认本地提供方
oss_provider = "ollama" # 或 "lmstudio"
3.8 Azure 提供方及单独调优
[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
[model_providers.openai]
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000
3.9 模型推理、输出冗长度与限制
model_reasoning_summary = "none" # 禁用推理摘要
model_verbosity = "low" # 缩短回复
model_supports_reasoning_summaries = true # 强制启用推理
model_context_window = 128000 # 上下文窗口大小
model_verbosity仅对使用 Responses API 的提供方生效。 Chat Completions 提供方会忽略该设置。
3.10 审批策略与沙箱模式
选择审批严格度（影响 Codex 何时暂停）以及沙箱级别（影响文件 / 网络访问）。更深入的示例请参见 Sandbox & approvals。
approval_policy = "untrusted" # 其他选项：on-request, on-failure, never
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
exclude_tmpdir_env_var = false # 允许 $TMPDIR
exclude_slash_tmp = false # 允许 /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false # 是否允许外部网络访问
在
workspace-write模式下，某些环境仍会将.git/和.codex/设为只读。因此，即使工作区可写，git commit等命令仍可能需要审批，如果你希望 Codex 跳过特定命令（例如阻止沙箱外的git commit），请使用 rules。
完全禁用沙箱（⚠️仅在你的环境已自行隔离进程时使用）：
sandbox_mode = "danger-full-access"
3.11 Shell 环境变量策略
shell_environment_policy 控制 Codex 启动子进程时传递哪些环境变量（例如执行模型提出的工具命令时）。可以从一个干净环境（inherit = "none"）或精简环境（inherit = "core"）开始，再叠加排除、包含和覆盖规则，避免泄露密钥，同时仍保留必要路径或标志。
[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin", MY_FLAG = "1" }
ignore_default_excludes = false
exclude = ["AWS_*", "AZURE_*"]
include_only = ["PATH", "HOME"]
匹配规则为不区分大小写的 glob 模式（*, ?, [A-Z]）。当 ignore_default_excludes = false 时，会在你自定义规则前自动过滤 KEY/SECRET/TOKEN。
3.12 可观测性与遥测
你可以启用 OpenTelemetry（OTel）日志导出，用于跟踪 Codex 运行情况（API 请求、SSE 事件、提示词、工具审批 / 结果等）。默认关闭，需要在 [otel] 中显式启用：
[otel]
environment = "staging" # 默认为 "dev"
exporter = "none" # 可设为 otlp-http 或 otlp-grpc
log_user_prompt = false # 默认不记录用户提示内容
选择导出器：
[otel]
exporter = { otlp-http = {
endpoint = "https://otel.example.com/v1/logs",
protocol = "binary",
headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" }
}}
[otel]
exporter = { otlp-grpc = {
endpoint = "https://otel.example.com:4317",
headers = { "x-otlp-meta" = "abc123" }
}}
当 exporter = "none" 时，Codex 会记录事件但不会发送，导出器会异步批量发送，并在退出时刷新。
会发送哪些事件？
Codex 会为运行和工具使用发送结构化日志事件，示例包括：
codex.conversation_starts(model, reasoning settings, sandbox/approval policy)codex.api_requestandcodex.sse_event(durations, status, token counts)codex.user_prompt(length; content redacted unless explicitly enabled)codex.tool_decision(approved/denied and whether the decision came from config vs user)codex.tool_result(duration, success, output snippet)
更详细的安全与隐私说明请参见 Security。
指标（Metrics）
默认情况下，Codex 会周期性地向 OpenAI 发送少量匿名使用与健康数据，用于检测故障并了解功能使用情况。这些数据 不包含任何 PII（个人可识别信息），如需完全关闭指标收集：
[analytics]
enabled = false
默认上下文字段（适用于所有事件 / 指标）
surfaceversionauth_modemodel
指标目录
| Metric | Type | Fields | Description |
|---|---|---|---|
features.state |
counter | key, value |
Feature values that differ from defaults (emit one row per non-default). |
thread.started |
counter | is_git |
New thread created. |
task.compact |
counter | type |
Number of compactions per type (remote or local), including manual and auto. |
task.user_shell |
counter | Number of user shell actions (! in the TUI for example). |
|
task.review |
counter | Number of reviews triggered. | |
approval.requested |
counter | tool, approved |
Tool approval request result (approved: yes or no). |
conversation.turn.count |
counter | User/assistant turns per thread, recorded at the end of the thread. | |
mcp.call |
counter | status |
MCP tool invocation result (ok or error string). |
model.call.duration_ms |
histogram | status, attempt |
Model API request duration. |
tool.call |
counter | tool, status |
Tool invocation result (ok or error string). |
tool.call.duration_ms |
histogram | tool, success |
Tool execution time. |
user.feedback.submitted |
counter | category, include_logs, success |
Feedback submission via /feedback. |
反馈控制
默认支持通过 /feedback 提交反馈，如需禁用：
[feedback]
enabled = false
隐藏或显示推理事件
hide_agent_reasoning = true
show_raw_agent_reasoning = true
仅在你的工作流允许的情况下启用原始推理内容。
通知
使用 notify 在 Codex 触发事件时调用外部程序（目前支持 agent-turn-complete）。
notify = ["python3", "/path/to/notify.py"]
示例脚本：
#!/usr/bin/env python3
import json, subprocess, sys
def main() -> int:
notification = json.loads(sys.argv[1])
if notification.get("type") != "agent-turn-complete":
return 0
title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
message = " ".join(notification.get("input-messages", []))
subprocess.check_output([
"terminal-notifier",
"-title", title,
"-message", message,
"-group", "codex-" + notification.get("thread-id", ""),
"-activate", "com.googlecode.iterm2",
])
return 0
if __name__ == "__main__":
sys.exit(main())
历史记录持久化
默认情况下，Codex 会将会话记录保存在 CODEX_HOME 下：
[history]
persistence = "none"
限制历史文件大小：
[history]
max_bytes = 104857600 # 100 MiB
可点击的文件引用
file_opener = "vscode" # 或 cursor, windsurf, vscode-insiders, none
3.13 项目指令发现
Codex 会读取 AGENTS.md 并在会话首轮中注入项目指引，相关配置：
project_doc_max_bytesproject_doc_fallback_filenames
详见 Custom instructions with AGENTS.md。
3.14 TUI options
TUI（终端界面）选项
直接运行 codex 会启动交互式 TUI，专属配置位于 [tui] 下，包括：
tui.notificationstui.animationstui.scroll_*
4. 完整配置参考
以下是 Codex 的 config.toml 和 requirements.toml 的完整参考文档。
4.1 config.toml
用户级别的配置位于：~/.codex/config.toml
| Key | Type / Values | Details |
|---|---|---|
| approval_policy | untrusted | on-failure |
| chatgpt_base_url | string | 覆盖 ChatGPT 登录流程中使用的基础 URL。 |
| check_for_update_on_startup | boolean | 在启动时检查 Codex 更新（仅在更新由集中管理时才设置为 false）。 |
| cli_auth_credentials_store | file | keyring |
| compact_prompt | string | 内联覆盖用于历史压缩的提示词。 |
| developer_instructions | string | 注入到会话中的额外开发者指令（可选）。 |
| disable_paste_burst | boolean | 在 TUI 中禁用批量粘贴检测。 |
| experimental_compact_prompt_file | string (path) | 从文件加载历史压缩提示词的覆盖版本（实验性）。 |
| experimental_instructions_file | string (path) | 实验性：使用该文件替代内置指令，而不是 AGENTS.md。 |
| experimental_use_freeform_apply_patch | boolean | 启用自由格式 apply_patch 的旧名称；推荐使用 [features].apply_patch_freeform 或 codex --enable apply_patch_freeform。 |
| experimental_use_unified_exec_tool | boolean | 启用 unified exec 的旧名称；推荐使用 [features].unified_exec 或 codex --enable unified_exec。 |
| features.apply_patch_freeform | boolean | 暴露自由格式的 apply_patch 工具（实验性）。 |
| features.elevated_windows_sandbox | boolean | 启用提升权限的 Windows 沙箱管道（实验性）。 |
| features.exec_policy | boolean | 对 shell / unified_exec 强制执行规则检查（实验性；默认开启）。 |
| features.experimental_windows_sandbox | boolean | 运行 Windows 受限令牌沙箱（实验性）。 |
| features.powershell_utf8 | boolean | 强制 PowerShell 使用 UTF-8 输出（默认 true）。 |
| features.remote_compaction | boolean | 启用远程历史压缩（仅 ChatGPT 登录；实验性；默认开启）。 |
| features.remote_models | boolean | 在显示就绪状态前刷新远程模型列表（实验性）。 |
| features.shell_snapshot | boolean | 对 shell 环境进行快照以加速重复命令（beta）。 |
| features.shell_tool | boolean | 启用默认的 shell 工具以运行命令（稳定版；默认开启）。 |
| features.tui2 | boolean | 启用 TUI2 界面（实验性）。 |
| features.unified_exec | boolean | 使用统一的、基于 PTY 的 exec 工具（beta）。 |
| features.web_search_request | boolean | 允许模型发起 Web 搜索请求（稳定）。 |
| feedback.enabled | boolean | 通过 /feedback 启用跨 Codex 界面的反馈提交（默认 true）。 |
| file_opener | vscode | vscode-insiders |
| forced_chatgpt_workspace_id | string (uuid) | 将 ChatGPT 登录限制到指定的工作区标识符。 |
| forced_login_method | chatgpt | api |
| hide_agent_reasoning | boolean | 在 TUI 和 codex exec 输出中隐藏推理事件。 |
| history.max_bytes | number | 如果设置，将通过丢弃最旧条目来限制历史文件大小（字节）。 |
| history.persistence | save-all | none |
| include_apply_patch_tool | boolean | 启用自由格式 apply_patch 的旧名称；推荐使用 [features].apply_patch_freeform。 |
| instructions | string | 保留供未来使用；推荐使用 experimental_instructions_file 或 AGENTS.md。 |
| mcp_oauth_credentials_store | auto | file |
| mcp_servers..args | array | 传递给 MCP stdio server 命令的参数。 |
| mcp_servers..bearer_token_env_var | string | 为 MCP HTTP server 提供 bearer token 的环境变量。 |
| mcp_servers..command | string | MCP stdio server 的启动命令。 |
| mcp_servers..cwd | string | MCP stdio server 进程的工作目录。 |
| mcp_servers..disabled_tools | array | 在 enabled_tools 之后应用的工具拒绝列表。 |
| mcp_servers..enabled | boolean | 在不移除配置的情况下禁用 MCP server。 |
| mcp_servers..enabled_tools | array | MCP server 暴露的工具名称白名单。 |
| mcp_servers..env | map<string,string> | 转发给 MCP stdio server 的环境变量。 |
| mcp_servers..env_http_headers | map<string,string> | 从环境变量填充的 HTTP Header（用于 MCP HTTP server）。 |
| mcp_servers..env_vars | array | 额外允许的 MCP stdio server 环境变量白名单。 |
| mcp_servers..http_headers | map<string,string> | 每次 MCP HTTP 请求都会包含的静态 Header。 |
| mcp_servers..startup_timeout_ms | number | startup_timeout_sec 的毫秒别名。 |
| mcp_servers..startup_timeout_sec | number | 覆盖 MCP server 默认 10 秒的启动超时。 |
| mcp_servers..tool_timeout_sec | number | 覆盖 MCP server 默认 60 秒的单工具超时。 |
| mcp_servers..url | string | MCP 可流式 HTTP server 的端点。 |
| model | string | 使用的模型（例如 gpt-5-codex）。 |
| model_auto_compact_token_limit | number | 触发自动历史压缩的 token 阈值（未设置则使用模型默认值）。 |
| model_context_window | number | 当前模型可用的上下文窗口 token 数。 |
| model_provider | string | 来自 model_providers 的 provider id（默认：openai）。 |
| model_providers..base_url | string | 模型提供方的 API 基础 URL。 |
| model_providers..env_http_headers | map<string,string> | 从环境变量填充的 HTTP Header。 |
| model_providers..env_key | string | 提供方 API Key 所在的环境变量。 |
| model_providers..env_key_instructions | string | 可选的 API Key 配置说明。 |
| model_providers..experimental_bearer_token | string | 直接提供 bearer token（不推荐；请使用 env_key）。 |
| model_providers..http_headers | map<string,string> | 添加到提供方请求中的静态 HTTP Header。 |
| model_providers..name | string | 自定义模型提供方的显示名称。 |
| model_providers..query_params | map<string,string> | 附加到请求中的额外查询参数。 |
| model_providers..request_max_retries | number | 提供方 HTTP 请求的最大重试次数（默认 4）。 |
| model_providers..requires_openai_auth | boolean | 提供方是否使用 OpenAI 认证（默认 false）。 |
| model_providers..stream_idle_timeout_ms | number | SSE 流的空闲超时（毫秒，默认 300000）。 |
| model_providers..stream_max_retries | number | SSE 流中断的最大重试次数（默认 5）。 |
| model_providers..wire_api | chat | responses |
| model_reasoning_effort | minimal | low |
| model_reasoning_summary | auto | concise |
| model_supports_reasoning_summaries | boolean | 即使是未知模型也强制 Codex 发送推理元数据。 |
| model_verbosity | low | medium |
| notice.hide_full_access_warning | boolean | 记录是否确认“完全访问权限”警告。 |
| 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 | 记录是否选择退出速率限制模型切换提示。 |
| notice.hide_world_writable_warning | boolean | 记录是否确认 Windows 全局可写目录警告。 |
| notice.model_migrations | map<string,string> | 记录已确认的模型迁移映射（旧 → 新）。 |
| notify | array | 用于通知的命令；会接收来自 Codex 的 JSON 负载。 |
| oss_provider | lmstudio | ollama |
| otel.environment | string | 应用于 OpenTelemetry 事件的环境标签（默认 dev）。 |
| otel.exporter | none | otlp-http |
| otel.exporter..endpoint | string | OTEL 日志导出端点。 |
| otel.exporter..headers | map<string,string> | OTEL 导出请求中包含的静态 Header。 |
| otel.exporter..protocol | binary | json |
| otel.exporter..tls.ca-certificate | string | OTEL 导出器 TLS 的 CA 证书路径。 |
| otel.exporter..tls.client-certificate | string | OTEL 导出器 TLS 的客户端证书路径。 |
| otel.exporter..tls.client-private-key | string | OTEL 导出器 TLS 的客户端私钥路径。 |
| otel.log_user_prompt | boolean | 选择是否在 OpenTelemetry 日志中导出原始用户提示词。 |
| otel.trace_exporter | none | otlp-http |
| otel.trace_exporter..endpoint | string | Trace 导出端点。 |
| otel.trace_exporter..headers | map<string,string> | Trace 导出请求的静态 Header。 |
| otel.trace_exporter..protocol | binary | json |
| otel.trace_exporter..tls.ca-certificate | string | Trace 导出器 TLS 的 CA 证书路径。 |
| otel.trace_exporter..tls.client-certificate | string | Trace 导出器 TLS 的客户端证书路径。 |
| otel.trace_exporter..tls.client-private-key | string | Trace 导出器 TLS 的客户端私钥路径。 |
| profile | string | 启动时应用的默认 profile（等价于 --profile）。 |
| profiles..* | various | 对任意支持配置项的 profile 级别覆盖。 |
| profiles..experimental_use_freeform_apply_patch | boolean | 启用自由格式 apply_patch 的旧名称。 |
| profiles..experimental_use_unified_exec_tool | boolean | 启用 unified exec 的旧名称。 |
| profiles..include_apply_patch_tool | boolean | 启用自由格式 apply_patch 的旧名称。 |
| profiles..oss_provider | lmstudio | ollama |
| project_doc_fallback_filenames | array | 当 AGENTS.md 缺失时尝试的额外文件名。 |
| project_doc_max_bytes | number | 构建项目指令时从 AGENTS.md 读取的最大字节数。 |
| project_root_markers | array | 用于查找项目根目录的标记文件名列表。 |
| projects. |
string | 将项目或 worktree 标记为受信任或不受信任（"trusted" |
| review_model | string | /review 使用的模型覆盖。 |
| sandbox_mode | read-only | workspace-write |
| 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_workspace_write.writable_roots | array | workspace-write 模式下额外的可写目录。 |
| shell_environment_policy.exclude | array | 默认处理后移除的环境变量 glob 模式。 |
| 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 | 白名单模式，仅保留匹配的变量。 |
| shell_environment_policy.inherit | all | core |
| shell_environment_policy.set | map<string,string> | 注入到每个子进程的显式环境变量。 |
| show_raw_agent_reasoning | boolean | 当模型输出推理时展示原始推理内容。 |
| skills.config | array | 存储在 config.toml 中的技能级别启用配置。 |
| skills.config..enabled | boolean | 启用或禁用对应技能。 |
| skills.config..path | string (path) | 包含 SKILL.md 的技能目录路径。 |
| tool_output_token_limit | number | 单个工具/函数输出存入历史的 token 上限。 |
| tui | table | TUI 专用选项，例如启用桌面内联通知。 |
| tui.animations | boolean | 启用终端动画（欢迎页、闪光、加载器）（默认 true）。 |
| tui.notifications | boolean | array |
| tui.scroll_events_per_tick | number | TUI2 中用于标准化滚动的事件密度。 |
| tui.scroll_invert | boolean | 反转 TUI2 的鼠标滚动方向。 |
| tui.scroll_mode | auto | wheel |
| tui.scroll_trackpad_accel_events | number | 触发 +1x 加速所需的触控板事件数。 |
| tui.scroll_trackpad_accel_max | number | 触控板滚动的最大加速倍数。 |
| tui.scroll_trackpad_lines | number | TUI2 的触控板滚动基础灵敏度。 |
| tui.scroll_wheel_like_max_duration_ms | number | 自动模式下回退为滚轮的持续时间阈值（毫秒）。 |
| tui.scroll_wheel_lines | number | TUI2 中每次滚轮刻度滚动的行数。 |
| tui.scroll_wheel_tick_detect_max_ms | number | 自动模式下滚轮刻度检测阈值（毫秒）。 |
| tui.show_tooltips | boolean | 在 TUI 欢迎界面显示新手提示（默认 true）。 |
| windows_wsl_setup_acknowledged | boolean | 记录 Windows 引导流程的确认状态（仅 Windows）。 |
4.2 requirements.toml
requirements.toml 是由管理员强制执行的配置文件，用于限制用户无法覆盖的安全敏感设置。
有关详情、路径和示例，请参见 Admin-enforced requirements
| Key | Type / Values | Details |
|---|---|---|
| allowed_approval_policies | array<string> |
approval_policy 允许使用的取值。 |
| allowed_sandbox_modes | array<string> |
sandbox_mode 允许使用的取值。 |
5. 示例配置
下面的代码片段可以作为参考使用，只需将配置项和配置段复制到 ~/.codex/config.toml 中，然后根据你的实际环境调整相应的值。
# Codex 示例配置（config.toml）
#
# 本文件列出了 Codex 会从 config.toml 读取的所有键、它们的默认值，
# 以及简要说明。这里的值与 CLI 编译进来的“实际默认值”一致。
# 可按需调整。
#
# 备注
# - 根级键必须出现在 TOML 的表（table）之前。
# - 默认值为 “未设置（unset）” 的可选键会以注释形式展示并附带说明。
# - MCP 服务器、profiles（配置文件）以及模型提供方都是示例；可删除或修改。
################################################################################
# 核心模型选择
################################################################################
# Codex 使用的主模型。默认：所有平台均为 "gpt-5.2-codex"。
model = "gpt-5.2-codex"
# /review 功能（代码审查）使用的模型。默认："gpt-5.2-codex"。
review_model = "gpt-5.2-codex"
# 从 [model_providers] 中选择的提供方 id。默认："openai"。
model_provider = "openai"
# 用于 --oss 会话的默认开源提供方。未设置时，Codex 会提示选择。默认：未设置。
# oss_provider = "ollama"
# 可选的手动模型元数据。未设置时，Codex 会根据 model 自动检测。
# 取消注释以强制指定这些值。
# model_context_window = 128000 # token 数；默认：按模型自动决定
# model_auto_compact_token_limit = 0 # token 数；未设置时使用模型默认值
# tool_output_token_limit = 10000 # 每个工具输出存储的 token 数；对 gpt-5.2-codex 默认是 10000
################################################################################
# 推理与详细度（支持 Responses API 的模型）
################################################################################
# 推理强度：minimal | low | medium | high | xhigh（默认：medium；在 gpt-5.2-codex 与 gpt-5.2 上为 xhigh）
model_reasoning_effort = "medium"
# 推理摘要：auto | concise | detailed | none（默认：auto）
model_reasoning_summary = "auto"
# GPT-5 系列（Responses API）的文本输出详细度：low | medium | high（默认：medium）
model_verbosity = "medium"
# 为当前模型强制启用推理摘要（默认：false）
model_supports_reasoning_summaries = false
################################################################################
# 指令覆盖
################################################################################
# 额外的用户指令会在 AGENTS.md 之前注入。默认：未设置。
# developer_instructions = ""
#（已忽略）可选的旧版基础指令覆盖（建议使用 AGENTS.md）。默认：未设置。
# instructions = ""
# 历史压缩提示词（compaction prompt）的内联覆盖。默认：未设置。
# compact_prompt = ""
# 用文件路径覆盖内置的基础指令。默认：未设置。
# experimental_instructions_file = "/absolute/or/relative/path/to/instructions.txt"
# 从文件加载历史压缩提示词覆盖。默认：未设置。
# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"
################################################################################
# 通知
################################################################################
# 外部通知程序（argv 数组）。未设置时：禁用。
# 示例：notify = ["notify-send", "Codex"]
notify = [ ]
################################################################################
# 审批与沙箱
################################################################################
# 何时请求命令审批：
# - untrusted：仅已知安全的只读命令自动执行；其余命令会提示确认
# - on-failure：在沙箱中自动执行；仅在失败时提示升级/放权
# - on-request：由模型决定何时询问（默认）
# - never：从不询问（风险较大）
approval_policy = "on-request"
# 工具调用的文件系统/网络沙箱策略：
# - read-only（默认）
# - workspace-write
# - danger-full-access（无沙箱；极其危险）
sandbox_mode = "read-only"
################################################################################
# 认证与登录
################################################################################
# CLI 登录凭据的持久化方式：file（默认） | keyring | auto
cli_auth_credentials_store = "file"
# ChatGPT 认证流程的基础 URL（不是 OpenAI API）。默认：
chatgpt_base_url = "https://chatgpt.com/backend-api/"
# 将 ChatGPT 登录限制到指定 workspace id。默认：未设置。
# forced_chatgpt_workspace_id = ""
# 当 Codex 通常会自动选择时，强制指定登录机制。默认：未设置。
# 可选值：chatgpt | api
# forced_login_method = "chatgpt"
# MCP OAuth 凭据的首选存储方式：auto（默认） | file | keyring
mcp_oauth_credentials_store = "auto"
################################################################################
# 项目文档控制
################################################################################
# 从 AGENTS.md 中最多嵌入到首轮指令的字节数。默认：32768
project_doc_max_bytes = 32768
# 当某一层目录缺少 AGENTS.md 时，按顺序尝试的备用文件名。默认：[]
project_doc_fallback_filenames = []
# 在向上查找父目录时，用来识别项目根目录的标记文件名。默认：[".git"]
# project_root_markers = [".git"]
################################################################################
# 历史与文件打开方式
################################################################################
# 可点击引用（citations）的 URI scheme：vscode（默认） | vscode-insiders | windsurf | cursor | none
file_opener = "vscode"
################################################################################
# UI、通知与杂项
################################################################################
# 抑制内部推理事件的输出。默认：false
hide_agent_reasoning = false
# 当可用时显示原始推理内容。默认：false
show_raw_agent_reasoning = false
# 禁用 TUI 中的“突发粘贴（burst-paste）”检测。默认：false
disable_paste_burst = false
# 记录 Windows 入门设置确认（仅 Windows）。默认：false
windows_wsl_setup_acknowledged = false
# 启动时检查更新。默认：true
check_for_update_on_startup = true
################################################################################
# Profiles（命名预设）
################################################################################
# 当前启用的 profile 名称。未设置时，不应用任何 profile。
# profile = "default"
################################################################################
# Skills（按技能覆盖）
################################################################################
# 在不删除技能的情况下禁用或重新启用某个技能。
[[skills.config]]
# path = "/path/to/skill"
# enabled = false
################################################################################
# 实验性开关（旧版；优先使用 [features]）
################################################################################
experimental_use_unified_exec_tool = false
# 通过自由编辑路径包含 apply_patch（影响默认工具集）。默认：false
experimental_use_freeform_apply_patch = false
################################################################################
# 沙箱设置（表）
################################################################################
# 仅在 sandbox_mode = "workspace-write" 时使用的额外设置。
[sandbox_workspace_write]
# 除工作区（cwd）外额外允许写入的根目录。默认：[]
writable_roots = []
# 允许在沙箱内进行出站网络访问。默认：false
network_access = false
# 将 $TMPDIR 从可写根目录中排除。默认：false
exclude_tmpdir_env_var = false
# 将 /tmp 从可写根目录中排除。默认：false
exclude_slash_tmp = false
################################################################################
# 生成子进程的 Shell 环境策略（表）
################################################################################
[shell_environment_policy]
# inherit：all（默认） | core | none
inherit = "all"
# 对名称包含 KEY/SECRET/TOKEN（不区分大小写）的变量，跳过默认排除规则。默认：true
ignore_default_excludes = true
# 要移除的（不区分大小写）glob 模式（例如："AWS_*", "AZURE_*"）。默认：[]
exclude = []
# 显式 key/value 覆盖（始终优先）。默认：{}
set = {}
# 白名单；若非空，则只保留匹配的变量。默认：[]
include_only = []
# 实验性：通过用户 shell profile 运行。默认：false
experimental_use_profile = false
################################################################################
# 历史（表）
################################################################################
[history]
# save-all（默认） | none
persistence = "save-all"
# 历史文件最大字节数；超过后会裁剪最旧条目。示例：5242880
# max_bytes = 0
################################################################################
# UI、通知与杂项（表）
################################################################################
[tui]
# 来自 TUI 的桌面通知：布尔值或过滤列表。默认：true
# 示例：false | ["agent-turn-complete", "approval-requested"]
notifications = false
# 启用欢迎/状态/加载动画。默认：true
animations = true
# 在欢迎界面显示入门提示。默认：true
show_tooltips = true
# 可选的 TUI2 滚动调优（未设置则使用默认值）。
# scroll_events_per_tick = 0
# scroll_wheel_lines = 0
# scroll_trackpad_lines = 0
# scroll_trackpad_accel_events = 0
# scroll_trackpad_accel_max = 0
# scroll_mode = "auto" # auto | wheel | trackpad
# scroll_wheel_tick_detect_max_ms = 0
# scroll_wheel_like_max_duration_ms = 0
# scroll_invert = false
# 控制用户是否可以通过 `/feedback` 提交反馈。默认：true
[feedback]
enabled = true
# 产品内提示（多由 Codex 自动设置）。
[notice]
# hide_full_access_warning = true
# hide_world_writable_warning = true
# hide_rate_limit_model_nudge = true
# hide_gpt5_1_migration_prompt = true
# "hide_gpt-5.1-codex-max_migration_prompt" = true
# model_migrations = { "gpt-4.1" = "gpt-5.1" }
################################################################################
# 集中式功能开关（推荐）
################################################################################
[features]
# 将该表留空即可接受默认值。设置显式布尔值以选择加入/退出。
shell_tool = true
web_search_request = false
unified_exec = false
shell_snapshot = false
apply_patch_freeform = false
exec_policy = true
experimental_windows_sandbox = false
elevated_windows_sandbox = false
remote_compaction = true
remote_models = false
powershell_utf8 = true
tui2 = false
################################################################################
# 在此表下定义 MCP 服务器。留空则禁用。
################################################################################
[mcp_servers]
# --- 示例：STDIO 传输 ---
# [mcp_servers.docs]
# enabled = true # 可选；默认 true
# command = "docs-server" # 必填
# args = ["--port", "4000"] # 可选
# env = { "API_KEY" = "value" } # 可选：按原样复制的 key/value
# env_vars = ["ANOTHER_SECRET"] # 可选：从父进程环境转发这些变量
# cwd = "/path/to/server" # 可选：工作目录覆盖
# startup_timeout_sec = 10.0 # 可选；默认 10.0 秒
# # startup_timeout_ms = 10000 # 可选：启动超时（毫秒）的别名
# tool_timeout_sec = 60.0 # 可选；默认 60.0 秒
# enabled_tools = ["search", "summarize"] # 可选：允许列表
# disabled_tools = ["slow-tool"] # 可选：禁用列表（在允许列表之后生效）
# --- 示例：可流式 HTTP 传输 ---
# [mcp_servers.github]
# enabled = true # 可选；默认 true
# url = "https://github-mcp.example.com/mcp" # 必填
# bearer_token_env_var = "GITHUB_TOKEN" # 可选；Authorization: Bearer <token>
# http_headers = { "X-Example" = "value" } # 可选：静态请求头
# env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选：从环境变量填充的请求头
# startup_timeout_sec = 10.0 # 可选
# tool_timeout_sec = 60.0 # 可选
# enabled_tools = ["list_issues"] # 可选：允许列表
################################################################################
# 模型提供方（扩展/覆盖内置）
################################################################################
# 内置包括：
# - openai（Responses API；需要登录或通过认证流程提供 OPENAI_API_KEY）
# - oss（Chat Completions API；默认指向 http://localhost:11434/v1）
[model_providers]
# --- 示例：用显式 base URL 或 headers 覆盖 OpenAI ---
# [model_providers.openai]
# name = "OpenAI"
# base_url = "https://api.openai.com/v1" # 未设置时的默认值
# wire_api = "responses" # "responses" | "chat"（默认因情况而异）
# # requires_openai_auth = true # 内置 OpenAI 默认 true
# # request_max_retries = 4 # 默认 4；最大 100
# # stream_max_retries = 5 # 默认 5；最大 100
# # stream_idle_timeout_ms = 300000 # 默认 300_000（5 分钟）
# # experimental_bearer_token = "sk-example" # 可选：仅开发用途的直接 bearer token
# # http_headers = { "X-Example" = "value" }
# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }
# --- 示例：Azure（根据端点选择 Chat/Responses）---
# [model_providers.azure]
# name = "Azure"
# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
# wire_api = "responses" # 或按端点使用 "chat"
# query_params = { api-version = "2025-04-01-preview" }
# env_key = "AZURE_OPENAI_API_KEY"
# # env_key_instructions = "在环境变量中设置 AZURE_OPENAI_API_KEY"
# --- 示例：本地 OSS（例如 Ollama 兼容）---
# [model_providers.ollama]
# name = "Ollama"
# base_url = "http://localhost:11434/v1"
# wire_api = "chat"
################################################################################
# Profiles（命名预设）
################################################################################
[profiles]
# [profiles.default]
# model = "gpt-5.2-codex"
# model_provider = "openai"
# approval_policy = "on-request"
# sandbox_mode = "read-only"
# oss_provider = "ollama"
# model_reasoning_effort = "medium"
# model_reasoning_summary = "auto"
# model_verbosity = "medium"
# chatgpt_base_url = "https://chatgpt.com/backend-api/"
# experimental_compact_prompt_file = "./compact_prompt.txt"
# include_apply_patch_tool = false
# experimental_use_unified_exec_tool = false
# experimental_use_freeform_apply_patch = false
# tools_web_search = false
# features = { unified_exec = false }
################################################################################
# Projects（信任级别）
################################################################################
# 将特定 worktree 标记为可信或不可信。
[projects]
# [projects."/absolute/path/to/project"]
# trust_level = "trusted" # 或 "untrusted"
################################################################################
# OpenTelemetry（OTEL）- 默认禁用
################################################################################
[otel]
# 在日志中包含用户提示文本。默认：false
log_user_prompt = false
# 应用于遥测数据的环境标签。默认："dev"
environment = "dev"
# 导出器：none（默认） | otlp-http | otlp-grpc
exporter = "none"
# Trace 导出器：none（默认） | otlp-http | otlp-grpc
trace_exporter = "none"
# 示例：OTLP/HTTP 导出器配置
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs"
# protocol = "binary" # "binary" | "json"
# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"
# 示例：OTLP/gRPC 导出器配置
# [otel.exporter."otlp-grpc"]
# endpoint = "https://otel.example.com:4317",
# headers = { "x-otlp-meta" = "abc123" }
# 示例：带双向 TLS 的 OTLP 导出器
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs"
# protocol = "binary"
# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"
# [otel.exporter."otlp-http".tls]
# ca-certificate = "certs/otel-ca.pem"
# client-certificate = "/etc/codex/certs/client.pem"
# client-private-key = "/etc/codex/certs/client-key.pem"
6. 文末
本文从工程实践角度，系统整理了 Codex 的基础配置与高级配置方式。合理配置 approval_policy、sandbox_mode、模型与 Profiles，是提升 Codex 使用体验的关键。
如果你希望 Codex 在保证安全边界的前提下，尽量减少打断、提高执行效率，建议优先从审批策略与沙箱级别入手进行调整，其余配置按需逐步放开即可。谢谢大家的阅读，本文完。
有“AI”的1024 = 2048，欢迎大家加入2048 AI社区
更多推荐
8
0- 0
已为社区贡献45条内容
所有评论(0)