config.toml 深度配置指南

# 自定义项目根标记文件
project_root_markers = [".git", ".hg", ".sl"]
​
# 设为空数组 = 将当前工作目录视为项目根，不向上搜索
project_root_markers = []

# 字符串值需要 TOML 引号
codex --config model='"gpt-5.4"'
​
# 布尔/数值直接写
codex --config sandbox_workspace_write.network_access=true
​
# 数组值
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

# ===== 顶层默认值 =====
model = "gpt-5.4"
approval_policy = "on-request"
model_reasoning_effort = "medium"
​
# ===== 深度审查档案 =====
[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
​
# ===== 轻量快速档案 =====
[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"
​
# ===== 本地模型档案 =====
[profiles.local]
model = "deepseek-coder-v3"
model_provider = "ollama"
approval_policy = "on-request"

# 命令行指定
codex --profile deep-review
​
# 或设为默认
profile = "deep-review"  # 写在 config.toml 顶层

# 主模型
model = "gpt-5.4"
​
# 模型提供方（内置：openai / ollama / lmstudio）
model_provider = "openai"
​
# /review 专用模型（默认使用当前会话模型）
# review_model = "gpt-5.4"
​
# 服务层级：fast（快速路径）| flex
# service_tier = "flex"

# 推理力度：minimal | low | medium | high | xhigh
model_reasoning_effort = "medium"
​
# Plan 模式专用推理力度
plan_mode_reasoning_effort = "high"
​
# 推理摘要：auto | concise | detailed | none
model_reasoning_summary = "auto"
​
# 输出详细度（仅 Responses API 生效）：low | medium | high
model_verbosity = "medium"
​
# 强制启用/禁用推理摘要
# model_supports_reasoning_summaries = true

# 手动设置上下文窗口大小（默认自动检测）
# model_context_window = 128000
​
# 自动压缩触发阈值（token 数）
# model_auto_compact_token_limit = 64000
​
# 每次工具输出保留的最大 token 数
# tool_output_token_limit = 12000

# 人格风格：friendly | pragmatic | none
personality = "pragmatic"

# 三档基础策略
approval_policy = "on-request"  # untrusted | on-request | never
​
# 允许 login shell 语义
allow_login_shell = true

approval_policy = { granular = {
  sandbox_approval = true,       # 沙箱相关操作需要审批
  rules = true,                  # 规则匹配的命令需要审批
  mcp_elicitations = true,       # MCP 交互需要审批
  request_permissions = false,   # 权限请求自动拒绝
  skill_approval = false         # Skill 脚本自动拒绝
} }

# 三级沙箱
sandbox_mode = "workspace-write"  # read-only | workspace-write | danger-full-access

[sandbox_workspace_write]
# 额外可写路径（除工作区外）
writable_roots = ["/Users/YOU/.pyenv/shims"]
​
# 是否允许子进程访问网络
network_access = false
​
# 是否将 $TMPDIR 排除出可写范围
exclude_tmpdir_env_var = false
​
# 是否将 /tmp 排除出可写范围
exclude_slash_tmp = false

[sandbox_workspace_write]
exclude_tmpdir_env_var = true  # 排除 $TMPDIR
exclude_slash_tmp = true       # 排除 /tmp

[windows]
sandbox = "elevated"    # elevated（推荐）| unelevated（无管理员权限时的后备）

原始环境变量集
  │
  ├─ inherit 决定起始集
  │
  ├─ 默认排除（名称含 KEY/SECRET/TOKEN，大小写不敏感）
  │   └─ ignore_default_excludes = true 可跳过此步
  │
  ├─ exclude 模式匹配排除（glob 格式，大小写不敏感）
  │
  ├─ include_only 白名单（非空时，仅保留匹配项）
  │
  └─ set 显式覆盖（始终胜出）
      │
      ▼
  最终传递给子进程的变量集

[shell_environment_policy]
inherit = "all"
ignore_default_excludes = false  # 保留自动过滤 KEY/SECRET/TOKEN
exclude = []                     # 不需要额外排除
set = {}                         # 不需要额外设置

[shell_environment_policy]
inherit = "all"
ignore_default_excludes = false
exclude = ["AWS_*", "AZURE_*", "GCP_*", "DOCKER_*"]
set = { NODE_ENV = "development" }

[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin:/usr/local/bin", HOME = "/tmp/codex", LANG = "en_US.UTF-8" }

[shell_environment_policy]
inherit = "all"
include_only = ["PATH", "HOME", "LANG", "JAVA_HOME", "MAVEN_HOME"]

[shell_environment_policy]
experimental_use_profile = false  # 实验性：通过用户 shell profile 运行

[features]
# 在此显式设置为 true/false，未设置的保持默认值

# 在 config.toml 中设置
[features]
undo = true
prevent_idle_sleep = true
​
# 或通过 CLI 临时启用
codex --enable undo --enable prevent_idle_sleep
​
# CLI 仅支持启用，要禁用需在 config.toml 中设为 false

[features]
shell_snapshot = true           # Stable — 加速重复命令
multi_agent = true              # Stable — 子代理并行
fast_mode = true                # Stable — 简单任务快速响应
shell_tool = true               # Stable — 保持 shell 能力
personality = true              # Stable — 人格选择
undo = true                     # Stable — 启用撤销安全网
enable_request_compression = true  # Stable — 压缩请求
skill_mcp_dependency_install = true # Stable — Skill MCP 自动安装
# unified_exec = false          # Windows 用户设为 false
# apps = false                  # Experimental — 暂不启用
# smart_approvals = false       # Experimental — 暂不启用

[tui]
# 语法高亮主题（kebab-case）
theme = "catppuccin-mocha"

[tui]
# 桌面通知：布尔值或事件类型过滤列表
notifications = true
# 精细控制：仅在特定事件时通知
# notifications = ["agent-turn-complete", "approval-requested"]
​
# 通知方式：auto | osc9 | bel
notification_method = "auto"

# 外部通知程序（argv 数组）
notify = ["python3", "/path/to/notify.py"]

[tui]
# 欢迎屏、加载动画等
animations = true
​
# 新手提示（深度用户可关闭）
show_tooltips = false
​
# 交替屏幕控制（auto 在 Zellij 中跳过以保留滚动历史）
# alternate_screen = "auto"

[tui]
# 底部状态栏显示项（有序列表）
# 默认：["model-with-reasoning", "context-remaining", "current-dir"]
status_line = ["model", "context-remaining", "git-branch"]
​
# 设为空数组隐藏状态栏
# status_line = []

[history]
# 持久化模式：save-all | none
persistence = "save-all"
​
# 历史文件最大字节数
max_bytes = 104857600  # 100 MiB

# 搜索模式：disabled | cached | live
web_search = "cached"

[agents]
# 最大并发代理线程数（默认 6）
max_threads = 6
​
# 最大嵌套深度（根会话 = 0，默认 1）
max_depth = 1
​
# CSV 批量任务的每个 worker 超时时间（默认 1800 秒）
# job_max_runtime_seconds = 1800

[agents.reviewer]
description = "Find correctness, security, and test risks in code."
config_file = "./agents/reviewer.toml"
nickname_candidates = ["Athena", "Ada"]

# requirements.toml — 企业标准策略
allowed_web_search_modes = ["disabled", "cached"]
allowed_sandbox_modes = ["workspace-write"]
allowed_approval_policies = ["on-request"]
​
[rules]
prefix_rules = [
  { pattern = [{ token = "git" }, { any_of = ["push", "commit"] }],
    decision = "prompt",
    justification = "Require review before mutating remote history." },
]

requirements.toml（管理员强制，不可覆盖）
  │
  ▼
CLI flags / --config（单次运行覆盖）
  │
  ▼
Profile（命名配置档案）
  │
  ▼
.codex/config.toml（项目级，CWD → 项目根，就近优先）
  │
  ▼
~/.codex/config.toml（用户级）
  │
  ▼
/etc/codex/config.toml（系统级）
  │
  ▼
内置默认值

# 指向自定义提供方
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.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"

# 不需要定义新的 provider，直接覆盖 base URL
openai_base_url = "https://us.api.openai.com/v1"

# 默认本地提供方
oss_provider = "ollama"  # 或 "lmstudio"

[model_providers.openai]
request_max_retries = 4        # API 请求最大重试次数（默认 4，上限 100）
stream_max_retries = 10        # 流式连接最大重试次数（默认 5，上限 100）
stream_idle_timeout_ms = 300000  # 流式空闲超时（默认 300000 = 5 分钟）

[otel]
environment = "staging"       # 环境标签（默认 "dev"）
exporter = "none"             # 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" }
}}

[analytics]
enabled = true   # 匿名使用数据（帮助改进 Codex，无 PII）
​
[feedback]
enabled = true   # /feedback 命令

# URI scheme：vscode | vscode-insiders | windsurf | cursor | none
file_opener = "vscode"

# 额外用户指令（注入在 AGENTS.md 之前）
# developer_instructions = ""
​
# 覆盖内置基础指令
# model_instructions_file = "/path/to/instructions.txt"
​
# 覆盖 git co-author 标记
# commit_attribution = "Codex <codex@openai.com>"

# AGENTS.md 最大读取字节数（默认 32KB）
project_doc_max_bytes = 32768
​
# AGENTS.md 缺失时的回退文件名
project_doc_fallback_filenames = []

# 隐藏内部推理事件（CI 日志中有用）
hide_agent_reasoning = false
​
# 显示原始推理内容
show_raw_agent_reasoning = false

#:schema https://developers.openai.com/codex/config-schema.json
# ============================================================================
# Codex 配置文件 — 全栈开发者 · 生产力全开版
# 位置：~/.codex/config.toml
# 目标：解放双手，彻底释放 GPT-5.4 的 1M 上下文与全部推理能力
# 文档：https://developers.openai.com/codex/config-basic
# ============================================================================
​
# ─────────────────────────── 核心模型选择 ─────────────────────────────────────
​
# model — 主模型名称
# 可选值：gpt-5.4 | gpt-5.4-mini | gpt-5-pro | gpt-4.1 | 或其他兼容模型
# 默认值：gpt-5.4-mini
# 推荐值：gpt-5.4（全量推理能力，支持 1M 上下文）
model = "gpt-5.4"
​
# model_provider — 模型服务提供方
# 可选值：openai | codex | ollama | lmstudio | 自定义 provider 名称
# 默认值：openai
# 推荐值：codex（使用中转代理，加速国内访问）
model_provider = "codex"
​
# profile — 默认激活的配置档案
# 可选值：任意 [profiles.*] 中定义的名称
# 默认值：（无，使用顶层配置）
# 推荐值：auto-max（自动化最大化档案）
profile = "auto-max"
​
# ─────────────────────────── 推理与输出控制 ───────────────────────────────────
​
# model_reasoning_effort — 模型推理力度
# 可选值：minimal | low | medium | high | xhigh
# 默认值：medium
# 推荐值：xhigh（释放 GPT-5.4 全部推理能力，适合复杂工程任务）
model_reasoning_effort = "xhigh"
​
# plan_mode_reasoning_effort — Plan 模式专用推理力度
# 可选值：minimal | low | medium | high | xhigh
# 默认值：（继承 model_reasoning_effort）
# 推荐值：high（架构规划深度推理，同时控制延迟）
plan_mode_reasoning_effort = "high"
​
# model_reasoning_summary — 推理过程摘要模式
# 可选值：auto | concise | detailed | none
# 默认值：auto
# 推荐值：auto（自动判断是否展示推理摘要）
model_reasoning_summary = "auto"
​
# model_verbosity — 输出详细度（仅 Responses API 生效）
# 可选值：low | medium | high
# 默认值：medium
# 推荐值：medium（平衡信息密度与可读性）
model_verbosity = "medium"
​
# ─────────────────────────── 上下文窗口 ──────────────────────────────────────
​
# model_context_window — 手动设置上下文窗口大小（token 数）
# 可选值：任意正整数（受模型实际限制）
# 默认值：自动检测（GPT-5.4 原生 1,048,576）
# 推荐值：1050000（显式声明 ≈1M，确保不被截断）
model_context_window = 1050000
​
# model_auto_compact_token_limit — 自动压缩触发阈值（token 数）
# 可选值：任意正整数（应 < model_context_window）
# 默认值：约为上下文窗口的 50%（~525k）
# 推荐值：700000（~67% 窗口 — 最佳临界点，详见 Section 三.3 证据链）
# 注意：900k（86%）经实测会导致 xhigh 推理余量不足 + 长上下文幻觉加深
model_auto_compact_token_limit = 700000
​
# ─────────────────────────── 沟通风格 ────────────────────────────────────────
​
# personality — 人格风格
# 可选值：friendly | pragmatic | none
# 默认值：friendly
# 推荐值：pragmatic（务实简洁，直击技术要点）
personality = "pragmatic"
​
# ─────────────────────────── 审批与沙箱 ──────────────────────────────────────
​
# approval_policy — 审批策略
# 可选值：untrusted | on-request | never | { granular = {...} }
# 默认值：on-request
# 推荐值：never（彻底解放双手，无需反复确认）
approval_policy = "never"
​
# allow_login_shell — 允许使用 login shell 语义
# 可选值：true | false
# 默认值：false
# 推荐值：true（确保 shell profile 中的环境变量和别名可用）
allow_login_shell = true
​
# sandbox_mode — 沙箱隔离级别（顶层全开，Profile 按需收紧）
# 可选值：read-only | workspace-write | danger-full-access
# 默认值：workspace-write
# 推荐值：danger-full-access（配合 Profile 分层使用）
sandbox_mode = "danger-full-access"
​
# ─────────────────────────── Web 搜索 ────────────────────────────────────────
​
# web_search — Web 搜索模式
# 可选值：disabled | cached | live
# 默认值：cached
# 推荐值：cached（预索引缓存，降低 prompt injection 风险）
web_search = "cached"
​
# ─────────────────────────── 文件与 UI ───────────────────────────────────────
​
# file_opener — 引用链接打开方式
# 可选值：vscode | vscode-insiders | windsurf | cursor | none
# 默认值：none
# 推荐值：vscode（点击引用直接跳转 VS Code）
file_opener = "vscode"
​
# hide_agent_reasoning — 隐藏内部推理事件
# 可选值：true | false
# 默认值：false
# 推荐值：false（保持可见，便于理解 Codex 决策过程）
hide_agent_reasoning = false
​
# check_for_update_on_startup — 启动时检查更新
# 可选值：true | false
# 默认值：true
# 推荐值：true（及时获取新功能和安全修复）
check_for_update_on_startup = true
​
# project_doc_max_bytes — AGENTS.md 最大读取字节数
# 可选值：任意正整数
# 默认值：32768（32 KB）
# 推荐值：32768（默认即可）
project_doc_max_bytes = 32768
​
# ─────────────────────────── 隐私与兼容性 ────────────────────────────────────
​
# disable_response_storage — 禁止 OpenAI 存储响应数据
# 可选值：true | false
# 默认值：false
# 推荐值：true（保护代码隐私，不参与训练）
disable_response_storage = true
​
# windows_wsl_setup_acknowledged — 确认 WSL 环境已配置
# 可选值：true | false
# 默认值：false
# 推荐值：true（Windows 用户跳过 WSL 设置提示）
windows_wsl_setup_acknowledged = true
​
# suppress_unstable_features_warning — 抑制实验性功能警告
# 可选值：true | false
# 默认值：false
# 推荐值：true（减少干扰，配合 never 策略使用）
suppress_unstable_features_warning = true
​
# ─────────────────────────── workspace-write 沙箱细节 ─────────────────────────
​
[sandbox_workspace_write]
# writable_roots — 额外可写路径（除工作区外）
# 可选值：路径字符串数组
# 默认值：[]
# 推荐值：[]（按需添加，如 pyenv/npm 全局路径）
writable_roots = []
​
# network_access — 沙箱内进程是否可访问网络
# 可选值：true | false
# 默认值：false
# 推荐值：true（允许 npm install / pip install 等网络操作，免审批）
network_access = true
​
# exclude_tmpdir_env_var — 是否将 $TMPDIR 排除出可写范围
# 可选值：true | false
# 默认值：false
# 推荐值：false（保持临时目录可写）
exclude_tmpdir_env_var = false
​
# exclude_slash_tmp — 是否将 /tmp 排除出可写范围
# 可选值：true | false
# 默认值：false
# 推荐值：false（保持 /tmp 可写）
exclude_slash_tmp = false
​
# ─────────────────────────── Shell 环境策略 ───────────────────────────────────
​
[shell_environment_policy]
# inherit — 环境变量继承模式
# 可选值：all | core | none
# 默认值：all
# 推荐值：all（继承所有变量，依赖排除规则过滤敏感信息）
inherit = "all"
​
# ignore_default_excludes — 是否跳过默认排除规则（KEY/SECRET/TOKEN）
# 可选值：true | false
# 默认值：false
# 推荐值：false（保留自动过滤，防止密钥泄露）
ignore_default_excludes = false
​
# exclude — 额外排除模式（glob 格式，大小写不敏感）
# 可选值：字符串数组，支持 * ? [A-Z] 通配符
# 默认值：[]
# 推荐值：[]（默认排除已足够，按需添加云厂商变量如 "AWS_*"）
exclude = []
​
# set — 显式设置的环境变量（始终优先）
# 可选值：键值对对象
# 默认值：{}
# 推荐值：{}（按需设置 NODE_ENV 等）
set = {}
​
# ─────────────────────────── Feature Flags ───────────────────────────────────
​
[features]
# plan_tool — 启用规划工具（任务分解与多步骤规划）
# 可选值：true | false  |  默认值：false  |  推荐值：true
plan_tool = true
​
# apply_patch_freeform — 自由格式补丁应用
# 可选值：true | false  |  默认值：false  |  推荐值：true
apply_patch_freeform = true
​
# view_image_tool — 图片查看工具（截图分析、UI 审查）
# 可选值：true | false  |  默认值：false  |  推荐值：true
view_image_tool = true
​
# shell_snapshot — Shell 环境快照加速重复命令
# 可选值：true | false  |  默认值：true  |  推荐值：true
shell_snapshot = true
​
# multi_agent — 子代理协作（spawn_agent 等多代理并行）
# 可选值：true | false  |  默认值：true  |  推荐值：true
multi_agent = true
​
# fast_mode — Fast 模式路径（简单任务快速响应）
# 可选值：true | false  |  默认值：true  |  推荐值：true
fast_mode = true
​
# shell_tool — Shell 命令执行能力（核心功能）
# 可选值：true | false  |  默认值：true  |  推荐值：true
shell_tool = true
​
# personality — 人格选择控件（/personality 命令）
# 可选值：true | false  |  默认值：true  |  推荐值：true
personality = true
​
# undo — 基于 git ghost snapshot 的逐轮撤销（安全网）
# 可选值：true | false  |  默认值：false  |  推荐值：true
undo = true
​
# skill_mcp_dependency_install — Skill MCP 依赖自动安装
# 可选值：true | false  |  默认值：true  |  推荐值：true
skill_mcp_dependency_install = true
​
# rmcp_client — 远程 MCP 客户端支持
# 可选值：true | false  |  默认值：false  |  推荐值：true
rmcp_client = true
​
# elevated_windows_sandbox — Windows 提升权限沙箱
# 可选值：true | false  |  默认值：false  |  推荐值：true
elevated_windows_sandbox = true
​
# unified_exec — 统一 PTY-backed exec 工具
# 可选值：true | false  |  默认值：true（Windows 默认 false）
# 推荐值：false（自定义中转时关闭以提升兼容性）
unified_exec = false
​
# streamable_shell — 流式 Shell 输出（实验性）
# 可选值：true | false  |  默认值：false  |  推荐值：false
streamable_shell = false
​
# enable_request_compression — zstd 压缩流式请求体
# 可选值：true | false  |  默认值：true
# 推荐值：false（自定义中转可能不支持 zstd，关闭确保兼容）
enable_request_compression = false
​
# ─────────────────────────── 配置档案（Profiles）─────────────────────────────
​
# auto-max：自动化最大化档案（默认激活）
# 无审批 + workspace-write 沙箱：日常开发的最佳平衡
[profiles.auto-max]
approval_policy = "never"
sandbox_mode = "workspace-write"
​
# review：代码审查档案
# 需要审批确认，适合 Code Review 场景
[profiles.review]
approval_policy = "on-request"
sandbox_mode = "workspace-write"
​
# ─────────────────────────── 历史记录 ────────────────────────────────────────
​
[history]
# persistence — 会话历史持久化模式
# 可选值：save-all | none  |  默认值：save-all  |  推荐值：save-all
persistence = "save-all"
​
# max_bytes — 历史文件最大字节数
# 可选值：任意正整数  |  默认值：104857600（100 MiB）  |  推荐值：104857600
max_bytes = 104857600
​
# ─────────────────────────── TUI 终端界面 ────────────────────────────────────
​
[tui]
# notifications — 桌面通知
# 可选值：true | false | 事件类型数组  |  默认值：true  |  推荐值：true
notifications = true
​
# animations — 欢迎屏与加载动画
# 可选值：true | false  |  默认值：true  |  推荐值：true
animations = true
​
# show_tooltips — 新手提示
# 可选值：true | false  |  默认值：true  |  推荐值：false（熟练用户关闭）
show_tooltips = false
​
# ─────────────────────────── 匿名数据 ────────────────────────────────────────
​
[analytics]
# enabled — 匿名使用统计
# 可选值：true | false  |  默认值：true  |  推荐值：true
enabled = true
​
[feedback]
# enabled — /feedback 命令
# 可选值：true | false  |  默认值：true  |  推荐值：true
enabled = true
​
# ─────────────────────────── 通知抑制 ────────────────────────────────────────
​
[notice]
# hide_gpt5_1_migration_prompt — 隐藏 GPT-5.1 迁移提示
# 可选值：true | false  |  默认值：false
# 推荐值：true（已选择 GPT-5.4，无需迁移提醒）
hide_gpt5_1_migration_prompt = true
​
# ─────────────────────────── Windows 沙箱 ────────────────────────────────────
​
[windows]
# sandbox — Windows 沙箱模式
# 可选值：elevated | unelevated  |  默认值：elevated  |  推荐值：elevated
sandbox = "elevated"
​
# ─────────────────────────── MCP 服务器 ──────────────────────────────────────
​
[mcp_servers]
# MCP 配置见下一章节
​
# ─────────────────────────── 模型提供方 ──────────────────────────────────────
​
[model_providers.codex]
# name — 提供方显示名称
name = "codex"
# base_url — API 端点（中转代理，加速国内访问）
base_url = "https://codex.ai02.cn"
# wire_api — API 协议类型（responses | chat）
wire_api = "responses"
# requires_openai_auth — 是否需要 OpenAI 认证
requires_openai_auth = true