本文提供一份可用作起点的 Codex 完整配置示例（config.toml），包含所有主要配置块和每个字段的说明注释。只需把你需要的字段复制到 ~/.codex/config.toml 或项目级 .codex/config.toml 里，按需修改即可。不需要的字段注释掉或直接删除，未出现的键保持内置默认值。

Codex 完整配置示例

将以下配置的所需部分复制到 ~/.codex/config.toml（用户级）或仓库的 .codex/config.toml（项目级）：

• 配置概念和常用选项说明：配置基础
• 高级场景（Provider、Profiles、OTel 等）：高级配置
• 完整键值速查：配置参考
• 沙箱和审批：审批与沙箱

# Codex 完整配置示例 (config.toml)
#
# 说明：
# - 根级 key 必须在所有 table 之前声明（TOML 规则）
# - 注释掉的 key 保持内置默认值不变
# - MCP servers、Profiles、model providers 都是示例，按需修改或删除

################################################################################
# 核心模型选择
################################################################################

# 主模型。多数用户推荐 "gpt-5.4"
model = "gpt-5.4"

# 通信风格，适用于支持该功能的模型：none | friendly | pragmatic
# personality = "pragmatic"

# /review 使用的模型覆盖，默认使用当前 session 模型
# review_model = "gpt-5.4"

# model provider id，来自 [model_providers]，默认 "openai"
model_provider = "openai"

# --oss 模式的默认本地 provider，未设置时 Codex 会提示选择
# oss_provider = "ollama"

# 首选服务层级。fast 仅在 [features].fast_mode = true 时生效
# service_tier = "flex"  # fast | flex

# 模型元数据覆盖（通常不需要手动设置，保持 auto）
# model_context_window = 128000
# model_auto_compact_token_limit = 64000
# tool_output_token_limit = 12000
# model_catalog_json = "/absolute/path/to/models.json"
# background_terminal_max_timeout = 300000  # ms
# log_dir = "/absolute/path/to/codex-logs"
# sqlite_home = "/absolute/path/to/codex-state"

################################################################################
# 推理与详细程度（Responses API 模型）
################################################################################

# 推理强度：minimal | low | medium | high | xhigh
# model_reasoning_effort = "medium"

# Plan 模式的推理强度覆盖：none | minimal | low | medium | high | xhigh
# plan_mode_reasoning_effort = "high"

# 推理摘要详细程度：auto | concise | detailed | none
# model_reasoning_summary = "auto"

# GPT-5 系列文本详细程度（仅 Responses API）：low | medium | high
# model_verbosity = "medium"

# 强制启用或禁用推理摘要元数据
# model_supports_reasoning_summaries = true

################################################################################
# 指令覆盖
################################################################################

# 在 AGENTS.md 之前注入的额外开发者指令
# developer_instructions = ""

# 历史压缩提示的内联覆盖
# compact_prompt = ""

# 覆盖 commit co-author trailer；设为 "" 禁用
# commit_attribution = "Jane Doe <jane@example.com>"

# 替换内置基础指令的文件路径
# model_instructions_file = "/absolute/path/to/instructions.txt"

# 从文件加载压缩提示覆盖
# experimental_compact_prompt_file = "/path/to/compact_prompt.txt"

################################################################################
# 通知
################################################################################

# 外部通知程序（接收 JSON payload 的命令数组）
# notify = ["notify-send", "Codex"]

################################################################################
# 审批策略与沙箱
################################################################################

# 命令审批时机：
# - untrusted: 只有已知安全的只读命令自动运行，其他都提示
# - on-request: 由模型决定何时请求审批（默认）
# - never: 从不提示（无人值守场景，有风险）
# - { granular = { ... } }: 对不同类型的审批请求分别控制
approval_policy = "on-request"

# 审批请求由谁来审查：user（默认） | guardian_subagent
# approvals_reviewer = "user"

# 允许 shell 工具使用 login shell 语义，默认 true
allow_login_shell = true

# 文件系统/网络沙箱策略：
# - read-only（默认）
# - workspace-write
# - danger-full-access（完全关闭沙箱，极度危险）
sandbox_mode = "read-only"

# 默认命名权限 profile（使用前需要先在 [permissions.<name>] 里定义）
# default_permissions = "workspace"

################################################################################
# 认证与登录
################################################################################

# CLI 凭据存储方式：file（默认）| keyring | auto
cli_auth_credentials_store = "file"

# ChatGPT 认证流的 base URL
chatgpt_base_url = "https://chatgpt.com/backend-api/"

# 内置 OpenAI provider 的 base URL 覆盖
# openai_base_url = "https://us.api.openai.com/v1"

# 限制 ChatGPT 登录到特定工作区 ID
# forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

# 强制使用特定认证方式：chatgpt | api
# forced_login_method = "chatgpt"

# MCP OAuth 凭据存储方式：auto（默认）| file | keyring
mcp_oauth_credentials_store = "auto"

# MCP OAuth 回调的固定端口
# mcp_oauth_callback_port = 4321

################################################################################
# 项目文档控制
################################################################################

# AGENTS.md 读取的最大字节数，默认 32768
project_doc_max_bytes = 32768

# AGENTS.md 不存在时的备用文件名列表，默认 []
project_doc_fallback_filenames = []

# 项目根目录标志文件列表，默认 [".git"]
# project_root_markers = [".git"]

################################################################################
# 历史记录与文件打开器
################################################################################

# 引用链接使用的 URI scheme：vscode（默认）| vscode-insiders | windsurf | cursor | none
file_opener = "vscode"

################################################################################
# 输出控制
################################################################################

# 在 TUI 和 codex exec 输出中隐藏推理事件，默认 false
hide_agent_reasoning = false

# 显示原始推理内容，默认 false
show_raw_agent_reasoning = false

# 禁用 TUI 中的粘贴检测，默认 false
disable_paste_burst = false

# Windows 引导确认标记（仅 Windows），默认 false
windows_wsl_setup_acknowledged = false

# 启动时检查更新，默认 true
check_for_update_on_startup = true

################################################################################
# 联网模式
################################################################################

# 联网模式：disabled | cached（默认，使用 OpenAI 缓存索引）| live（实时抓取）
# 使用 --yolo 或全访问沙箱时默认切换为 live
web_search = "cached"

# 默认 Profile 名称（等同于 --profile）
# profile = "default"

# 已激活实验性 feature flag 时，禁止显示警告
# suppress_unstable_features_warning = true

################################################################################
# 子代理（多 Agent 配置）
################################################################################

[agents]
# 最大并发 agent 线程数，默认 6
# max_threads = 6

# 最大嵌套 spawn 深度，root session 从 0 开始，默认 1
# max_depth = 1

# spawn_agents_on_csv 每个 worker 的默认超时（秒），默认 1800
# job_max_runtime_seconds = 1800

# 自定义 agent 角色示例：
# [agents.reviewer]
# description = "代码审查员：找出正确性、安全性和测试风险"
# config_file = "./agents/reviewer.toml"
# nickname_candidates = ["Athena", "Ada"]

################################################################################
# Skills（per-skill 覆盖）
################################################################################

# 单独禁用或重新启用某个 skill，不需要删除它
[[skills.config]]
# path = "/path/to/skill/SKILL.md"
# enabled = false

################################################################################
# 沙箱详细设置（table）
################################################################################

# workspace-write 模式下的额外配置
[sandbox_workspace_write]
# 额外可写目录（超出 workspace/cwd 范围），默认 []
writable_roots = []
# 允许沙箱内出站网络，默认 false
network_access = false
# 排除 $TMPDIR，默认 false
exclude_tmpdir_env_var = false
# 排除 /tmp，默认 false
exclude_slash_tmp = false

################################################################################
# Shell 环境变量策略（table）
################################################################################

[shell_environment_policy]
# inherit: all（默认）| core | none
inherit = "all"
# 保留包含 KEY/SECRET/TOKEN 的变量（跳过默认过滤），默认 false
ignore_default_excludes = false
# 要移除的变量（大小写不敏感 glob），默认 []
exclude = []
# 显式注入的环境变量（始终生效），默认 {}
set = {}
# 白名单；非空时只保留匹配的变量，默认 []
include_only = []
# 实验性：通过用户 shell profile 运行，默认 false
experimental_use_profile = false

################################################################################
# 历史记录（table）
################################################################################

[history]
# save-all（默认）| none
persistence = "save-all"
# 历史文件大小上限（字节），超出时清理最旧记录
# max_bytes = 5242880

################################################################################
# TUI 选项（table）
################################################################################

[tui]
# 桌面通知：boolean 或事件类型列表，默认 true
# 例如：false 或 ["agent-turn-complete", "approval-requested"]
notifications = false

# 终端通知方式：auto | osc9 | bel，默认 "auto"
# notification_method = "auto"

# 启用欢迎/状态/spinner 动画，默认 true
animations = true

# 显示欢迎屏幕的新手引导提示，默认 true
show_tooltips = true

# 备用屏幕控制（auto 在 Zellij 中自动跳过以保留滚动缓冲）
# alternate_screen = "auto"

# 底部状态栏项目列表（未设置时 Codex 使用默认列表，设为 [] 隐藏）
# status_line = ["model", "context-remaining", "git-branch"]

# 终端标题项目列表（未设置时 Codex 使用 ["spinner", "project"]，设为 [] 清除）
# terminal_title = ["spinner", "project"]

# 语法高亮主题（kebab-case），也可在 TUI 里用 /theme 预览和保存
# theme = "catppuccin-mocha"

################################################################################
# 分析遥测（table）
################################################################################

# 启用或禁用匿名遥测，未设置时使用 Codex 默认行为
[analytics]
enabled = true

# 控制是否允许从 /feedback 提交反馈，默认 true
[feedback]
enabled = true

################################################################################
# Feature Flags（集中管理，推荐方式）
################################################################################

[features]
# 保持空 table 接受所有默认值；需要覆盖时加具体 key
# shell_tool = true
# apps = false
# codex_hooks = false
# unified_exec = true
# shell_snapshot = true
# multi_agent = true
# personality = true
# fast_mode = true
# smart_approvals = false
# enable_request_compression = true
# skill_mcp_dependency_install = true
# prevent_idle_sleep = false

################################################################################
# MCP Servers（table）
################################################################################

[mcp_servers]

# --- stdio 传输示例 ---
# [mcp_servers.docs]
# enabled = true
# required = 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    # 可选，默认 10s
# tool_timeout_sec = 60.0       # 可选，默认 60s
# enabled_tools = ["search"]    # 可选白名单
# disabled_tools = ["slow"]     # 可选黑名单

# --- HTTP 传输示例 ---
# [mcp_servers.github]
# enabled = true
# url = "https://github-mcp.example.com/mcp"
# bearer_token_env_var = "GITHUB_TOKEN"
# http_headers = { "X-Example" = "value" }

################################################################################
# Model Providers（自定义 Provider）
################################################################################

# 内置保留 ID：openai、ollama、lmstudio，不能覆盖
[model_providers]

# --- Azure 示例 ---
# [model_providers.azure]
# name = "Azure"
# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
# env_key = "AZURE_OPENAI_API_KEY"
# wire_api = "responses"
# query_params = { api-version = "2025-04-01-preview" }

# --- 命令认证 Bearer token 示例 ---
# [model_providers.proxy]
# name = "OpenAI using LLM proxy"
# base_url = "https://proxy.example.com/v1"
# wire_api = "responses"
# [model_providers.proxy.auth]
# command = "/usr/local/bin/fetch-token"
# args = ["--audience", "codex"]
# timeout_ms = 5000
# refresh_interval_ms = 300000

################################################################################
# Profiles（命名配置集）
################################################################################

[profiles]

# [profiles.daily]
# model = "gpt-5.4"
# approval_policy = "on-request"
# sandbox_mode = "workspace-write"

# [profiles.ci]
# model = "gpt-5.4"
# approval_policy = "never"
# sandbox_mode = "danger-full-access"

################################################################################
# Projects（信任级别）
################################################################################

[projects]
# 标记特定 worktree 为受信任或不受信任
# [projects."/absolute/path/to/project"]
# trust_level = "trusted"

################################################################################
# Tools
################################################################################

[tools]
# view_image = true

################################################################################
# OpenTelemetry（OTel）— 默认禁用
################################################################################

[otel]
# 在日志里包含用户 prompt 文本，默认 false
log_user_prompt = false
# 遥测环境标签，默认 "dev"
environment = "dev"
# 日志导出器：none（默认）| otlp-http | otlp-grpc
exporter = "none"
# Trace 导出器：none（默认）| otlp-http | otlp-grpc
trace_exporter = "none"
# Metrics 导出器：none | statsig | otlp-http | otlp-grpc
metrics_exporter = "statsig"

################################################################################
# Windows
################################################################################

[windows]
# Windows 原生沙箱模式：unelevated | elevated
sandbox = "unelevated"

---

常见问题

Q: 我只需要修改两三个字段，还要把整个文件复制过去吗？

A: 不需要。config.toml 里只写你需要覆盖的字段就行，未声明的键自动使用内置默认值。不需要的注释块可以完全删除，不会影响其他配置。

Q: 项目级 .codex/config.toml 和用户级 ~/.codex/config.toml 可以同时存在吗？

A: 可以。两者都会被读取，项目级的优先级更高（同一个 key 项目级覆盖用户级）。这个机制适合把团队共用设置放项目级，把个人偏好放用户级。

Q: TOML 格式有什么需要注意的？

A: 字符串要加引号（model = "gpt-5.4"），数组用方括号（exclude = ["AWS_*"]），嵌套 table 用 [section.subsection] 语法。安装 Even Better TOML VS Code 扩展后可以获得自动补全和错误提示。