把这份示例配置当作起点来使用。它包含了 Codex 会从 config.toml 中读取的大部分键，同时给出了默认行为、推荐值以及简短说明。
如果你想看解释和背景说明，可参考：
下面这段配置可以作为参考。只把你需要的键和章节复制到 ~/.codex/config.toml（或者项目级的 .codex/config.toml）中，再按你的环境做调整。
# Codex 示例配置（config.toml）
#
# 这份文件列出了 Codex 会从 config.toml 中读取的主要键，
# 并附带默认行为、推荐示例和简要说明。按需调整即可。
#
# 注意
# - 在 TOML 中，根级键必须写在各个 table 之前。
# - 默认值为“未设置”的可选键，会以带注释的形式展示并附加说明。
# - MCP servers、profiles 和 model providers 都只是示例，可按需删除或修改。
################################################################################
# 核心模型选择
################################################################################
# Codex 使用的主模型。多数用户的推荐示例："gpt-5.4"。
model = "gpt-5.4"
# 支持 personality 的模型使用的沟通风格。可选值：none | friendly | pragmatic
# personality = "pragmatic"
# /review 使用的可选模型覆盖值。默认：未设置（沿用当前 session 模型）。
# review_model = "gpt-5.4"
# 从 [model_providers] 中选择的 provider id。默认："openai"。
model_provider = "openai"
# --oss 会话使用的默认 OSS provider。未设置时，Codex 会提示选择。默认：未设置。
# oss_provider = "ollama"
# 偏好的 service tier。只有当 [features] 中启用了 fast_mode 时，`fast` 才会生效。
# service_tier = "flex" # fast | flex
# 可选的手动模型元数据。未设置时，Codex 会使用模型或预设默认值。
# model_context_window = 128000 # tokens；默认：按模型自动决定
# model_auto_compact_token_limit = 64000 # tokens；未设置时使用模型默认值
# tool_output_token_limit = 12000 # 每次工具输出在历史中保留的 token 数
# model_catalog_json = "/absolute/path/to/models.json" # 仅启动时生效的 model catalog 覆盖
# background_terminal_max_timeout = 300000 # ms；空 write_stdin 轮询的最大等待时间（默认 5 分钟）
# log_dir = "/absolute/path/to/codex-logs" # Codex 日志目录；默认 "$CODEX_HOME/log"
# sqlite_home = "/absolute/path/to/codex-state" # SQLite 运行时状态目录（可选）
################################################################################
# 推理与 Verbosity（适用于 Responses API 模型）
################################################################################
# 推理强度：minimal | low | medium | high | xhigh
# model_reasoning_effort = "medium"
# Codex 运行在 plan mode 时使用的可选覆盖值：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"
# 强制开启或关闭当前模型的 reasoning summaries。
# 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/or/relative/path/to/instructions.txt"
# 从文件加载 compact prompt 覆盖值。默认：未设置。
# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"
################################################################################
# Notifications
################################################################################
# 外部通知程序（argv 数组）。未设置时：禁用。
# notify = ["notify-send", "Codex"]
################################################################################
# Approval 与 Sandbox
################################################################################
# 何时请求命令 approval：
# - untrusted：只有已知安全的只读命令会自动运行，其他都会提示
# - on-request：由模型决定何时提示（默认）
# - never：永不提示（风险较高）
# - { granular = { ... } }：按类别允许或自动拒绝指定提示
approval_policy = "on-request"
# 由谁来审核符合条件的审批提示：user（默认）| guardian_subagent
# approvals_reviewer = "user"
# 细粒度策略示例：
# approval_policy = { granular = {
# sandbox_approval = true,
# rules = true,
# mcp_elicitations = true,
# request_permissions = false,
# skill_approval = false
# } }
# 当基于 shell 的工具请求 `login = true` 时，是否允许 login-shell 语义。
# 默认：true。设为 false 会强制使用非 login shell，并拒绝显式 login-shell 请求。
allow_login_shell = true
# 工具调用使用的文件系统 / 网络 sandbox 策略：
# - read-only（默认）
# - workspace-write
# - danger-full-access（无 sandbox；风险极高）
sandbox_mode = "read-only"
# 默认应用的命名 permissions profile。使用 [permissions.<name>] 前需要先设置它。
# default_permissions = "workspace"
################################################################################
# Authentication 与 Login
################################################################################
# CLI 登录凭据保存位置：file（默认）| keyring | auto
cli_auth_credentials_store = "file"
# ChatGPT 登录流程使用的 base URL（不是 OpenAI API URL）。
chatgpt_base_url = "https://chatgpt.com/backend-api/"
# 内建 OpenAI provider 的可选 base URL 覆盖值。
# openai_base_url = "https://us.api.openai.com/v1"
# 将 ChatGPT 登录限制到某个固定 workspace id。默认：未设置。
# forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"
# 当 Codex 原本会自动选择登录方式时，强制指定登录机制。默认：未设置。
# 可选值：chatgpt | api
# forced_login_method = "chatgpt"
# MCP OAuth 凭据的首选存储位置：auto（默认）| file | keyring
mcp_oauth_credentials_store = "auto"
# MCP OAuth callback 的固定端口：1-65535。默认：未设置。
# mcp_oauth_callback_port = 4321
# MCP OAuth 登录的可选 redirect URI 覆盖值（例如远程 devbox ingress）。
# 支持自定义 callback path。`mcp_oauth_callback_port` 仍控制监听端口。
# mcp_oauth_callback_url = "https://devbox.example.internal/callback"
################################################################################
# 项目文档控制
################################################################################
# 从 AGENTS.md 中最多嵌入到第一轮指令里的字节数。默认：32768
project_doc_max_bytes = 32768
# 当某一层目录缺少 AGENTS.md 时，要按顺序尝试的回退文件名。默认：[]
project_doc_fallback_filenames = []
# 向父目录搜索项目根时使用的标记文件名。默认：[".git"]
# project_root_markers = [".git"]
################################################################################
# History 与 File Opener
################################################################################
# 可点击 citation 使用的 URI scheme：vscode（默认）| vscode-insiders | windsurf | cursor | none
file_opener = "vscode"
################################################################################
# UI、通知与杂项
################################################################################
# 压制输出中的内部 reasoning 事件。默认：false
hide_agent_reasoning = false
# 当模型提供 raw reasoning 时，是否显示。默认：false
show_raw_agent_reasoning = false
# 禁用 TUI 中的 burst-paste 检测。默认：false
disable_paste_burst = false
# 记录 Windows onboarding 是否已确认（仅 Windows）。默认：false
windows_wsl_setup_acknowledged = false
# 启动时检查更新。默认：true
check_for_update_on_startup = true
################################################################################
# Web Search
################################################################################
# Web search 模式：disabled | cached | live。默认："cached"
# `cached` 通过 Web 搜索缓存返回结果（OpenAI 维护的索引）。
# cached 返回预索引结果；live 则会抓取最新网页数据。
# 若使用 `--yolo` 或其他完全访问沙箱设置，Web 搜索默认切到 `live`。
web_search = "cached"
# 当前活动配置档案名称。未设置时，不会应用任何配置档案。
# profile = "default"
# 压制启用了“开发中”功能开关时显示的警告。
# suppress_unstable_features_warning = true
################################################################################
# 智能体（多智能体角色与限制）
################################################################################
[agents]
# 同时打开的智能体线程上限。默认：6
# max_threads = 6
# 允许的嵌套生成深度。根 session 从深度 0 开始。默认：1
# max_depth = 1
# spawn_agents_on_csv 作业里每个 worker 的默认超时。未设置时工具默认 1800 秒。
# job_max_runtime_seconds = 1800
# [agents.reviewer]
# description = "Find correctness, security, and test risks in code."
# config_file = "./agents/reviewer.toml" # 相对于定义该角色的 config.toml
# nickname_candidates = ["Athena", "Ada"]
################################################################################
# 技能（按技能覆盖）
################################################################################
# 在不删除技能的前提下，将其禁用或重新启用。
[[skills.config]]
# path = "/path/to/skill/SKILL.md"
# enabled = false
################################################################################
# Sandbox 设置（tables）
################################################################################
# 仅在 sandbox_mode = "workspace-write" 时使用的额外设置。
[sandbox_workspace_write]
# 除工作区（cwd）外的额外可写根目录。默认：[]
writable_roots = []
# 是否允许 sandbox 内向外联网。默认：false
network_access = false
# 是否把 $TMPDIR 排除出可写根目录。默认：false
exclude_tmpdir_env_var = false
# 是否把 /tmp 排除出可写根目录。默认：false
exclude_slash_tmp = false
################################################################################
# 子进程使用的 Shell Environment Policy（table）
################################################################################
[shell_environment_policy]
# inherit：all（默认）| core | none
inherit = "all"
# 是否跳过对名称包含 KEY/SECRET/TOKEN 的默认过滤（大小写不敏感）。默认：false
ignore_default_excludes = false
# 要移除的不区分大小写 glob pattern，例如 "AWS_*"、"AZURE_*"。默认：[]
exclude = []
# 显式键值覆盖（优先级最高）。默认：{}
set = {}
# 白名单；若非空，则只保留匹配到的变量。默认：[]
include_only = []
# 实验性：通过用户 shell profile 运行。默认：false
experimental_use_profile = false
################################################################################
# Managed network proxy 设置
################################################################################
# 启用此 profile 前，先设置 `default_permissions = "workspace"`。
# [permissions.workspace.network]
# enabled = true
# proxy_url = "http://127.0.0.1:43128"
# admin_url = "http://127.0.0.1:43129"
# enable_socks5 = false
# socks_url = "http://127.0.0.1:43130"
# enable_socks5_udp = false
# allow_upstream_proxy = false
# dangerously_allow_non_loopback_proxy = false
# dangerously_allow_non_loopback_admin = false
# dangerously_allow_all_unix_sockets = false
# mode = "limited" # limited | full
# allow_local_binding = false
#
# [permissions.workspace.network.domains]
# "api.openai.com" = "allow"
# "example.com" = "deny"
#
# [permissions.workspace.network.unix_sockets]
# "/var/run/docker.sock" = "allow"
################################################################################
# History（table）
################################################################################
[history]
# save-all（默认）| none
persistence = "save-all"
# history 文件最大字节数；超过后会裁剪最旧条目。示例：5242880
# max_bytes = 5242880
################################################################################
# UI、通知与杂项（tables）
################################################################################
[tui]
# 来自 TUI 的桌面通知：布尔值，或只启用部分事件。默认：true
# 示例：false | ["agent-turn-complete", "approval-requested"]
notifications = false
# 终端提醒使用的通知机制：auto | osc9 | bel。默认："auto"
# notification_method = "auto"
# 是否启用 welcome / status / spinner 动画。默认：true
animations = true
# 是否在 welcome screen 中显示 onboarding tooltips。默认：true
show_tooltips = true
# 控制 alternate screen 使用方式（在 Zellij 中，auto 会跳过以保留 scrollback）。
# alternate_screen = "auto"
# 底部状态栏项的有序列表。未设置时，Codex 默认使用：
# ["model-with-reasoning", "context-remaining", "current-dir"]。
# 设为 [] 则隐藏底栏。
# status_line = ["model", "context-remaining", "git-branch"]
# 终端窗口 / 标签标题项的有序列表。未设置时，Codex 默认使用：
# ["spinner", "project"]。设为 [] 则清空标题。
# 可选值包括 app-name、project、spinner、status、thread、git-branch、model、
# 和 task-progress。
# terminal_title = ["spinner", "project"]
# 语法高亮主题（kebab-case）。可在 TUI 中用 /theme 预览并保存。
# 也可以把自定义 .tmTheme 文件放到 $CODEX_HOME/themes 下。
# theme = "catppuccin-mocha"
# 以 model slug 为键的内部 tooltip 状态。通常由 Codex 自己管理。
# [tui.model_availability_nux]
# "gpt-5.4" = 1
# 为当前机器启用或禁用分析数据上报。未设置时，Codex 使用默认行为。
[analytics]
enabled = true
# 是否允许用户通过 `/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-5.3-codex" = "gpt-5.4" }
################################################################################
# 集中式 Feature Flags（推荐）
################################################################################
[features]
# 将这个 table 留空即可使用默认值。设置显式布尔值则表示手动启用 / 禁用。
# 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
################################################################################
# 在这个 table 下定义 MCP servers。留空则表示禁用。
################################################################################
[mcp_servers]
# --- 示例：STDIO transport ---
# [mcp_servers.docs]
# enabled = true # 可选；默认 true
# required = true # 可选；若无法初始化则启动 / 恢复失败
# command = "docs-server" # 必填
# args = ["--port", "4000"] # 可选
# env = { "API_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"] # 可选 allow-list
# disabled_tools = ["slow-tool"] # 可选 deny-list（在 allow-list 之后应用）
# scopes = ["read:docs"] # 可选 OAuth scopes
# oauth_resource = "https://docs.example.com/" # 可选 OAuth resource
# --- 示例：Streamable HTTP transport ---
# [mcp_servers.github]
# enabled = true # 可选；默认 true
# required = true # 可选；若无法初始化则启动 / 恢复失败
# url = "https://github-mcp.example.com/mcp" # 必填
# bearer_token_env_var = "GITHUB_TOKEN" # 可选；Authorization: Bearer <token>
# http_headers = { "X-Example" = "value" } # 可选静态 headers
# env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选：从环境变量填充的 headers
# startup_timeout_sec = 10.0 # 可选
# tool_timeout_sec = 60.0 # 可选
# enabled_tools = ["list_issues"] # 可选 allow-list
# disabled_tools = ["delete_issue"] # 可选 deny-list
# scopes = ["repo"] # 可选 OAuth scopes
################################################################################
# Model Providers
################################################################################
# 内建 provider 包括：
# - openai
# - ollama
# - lmstudio
#
# 自定义 provider id 不能复用这些内建保留名称。
[model_providers]
# --- 示例：带显式 base URL 或 headers 的 OpenAI data residency ---
# [model_providers.openaidr]
# name = "OpenAI Data Residency"
# base_url = "https://us.api.openai.com/v1" # 示例中的 'us' 为域名前缀
# wire_api = "responses" # 当前唯一支持值
# # 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 分钟）
# # supports_websockets = true # 可选
# # experimental_bearer_token = "sk-example" # 可选；仅开发用途
# # http_headers = { "X-Example" = "value" }
# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }
# --- 示例：Azure / OpenAI 兼容 provider ---
# [model_providers.azure]
# name = "Azure"
# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
# wire_api = "responses"
# query_params = { api-version = "2025-04-01-preview" }
# env_key = "AZURE_OPENAI_API_KEY"
# env_key_instructions = "Set AZURE_OPENAI_API_KEY in your environment"
# # supports_websockets = false
# --- 示例：本地 OSS（例如兼容 Ollama）---
# [model_providers.local_ollama]
# name = "Ollama"
# base_url = "http://localhost:11434/v1"
# wire_api = "responses"
# --- 示例：通过外部凭据助手获取 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-codex-token"
# args = ["--audience", "codex"]
# timeout_ms = 5000
# refresh_interval_ms = 300000
# # cwd = "/path/to/credential-helper"
################################################################################
# Apps / Connectors
################################################################################
# 可选的按 app 控制。
[apps]
# [_default] 会作用于所有 app，除非被单个 app 覆盖。
# [apps._default]
# enabled = true
# destructive_enabled = true
# open_world_enabled = true
#
# [apps.google_drive]
# enabled = false
# destructive_enabled = false # 阻止该 app 中带 destructive_hint 的工具
# default_tools_enabled = true
# default_tools_approval_mode = "prompt" # auto | prompt | approve
#
# [apps.google_drive.tools."files/delete"]
# enabled = false
# approval_mode = "approve"
################################################################################
# Profiles（命名预设）
################################################################################
[profiles]
# [profiles.default]
# model = "gpt-5.4"
# model_provider = "openai"
# approval_policy = "on-request"
# sandbox_mode = "read-only"
# service_tier = "flex"
# oss_provider = "ollama"
# model_reasoning_effort = "medium"
# plan_mode_reasoning_effort = "high"
# model_reasoning_summary = "auto"
# model_verbosity = "medium"
# personality = "pragmatic" # 或 "friendly" 或 "none"
# chatgpt_base_url = "https://chatgpt.com/backend-api/"
# model_catalog_json = "./models.json"
# model_instructions_file = "/absolute/or/relative/path/to/instructions.txt"
# experimental_compact_prompt_file = "./compact_prompt.txt"
# tools_view_image = true
# features = { unified_exec = false }
################################################################################
# Projects（信任级别）
################################################################################
[projects]
# 把特定 worktree 标记为 trusted 或 untrusted。
# [projects."/absolute/path/to/project"]
# trust_level = "trusted" # 或 "untrusted"
################################################################################
# Tools
################################################################################
[tools]
# view_image = true
################################################################################
# OpenTelemetry（OTEL）- 默认关闭
################################################################################
[otel]
# 是否在日志中包含用户 prompt 文本。默认：false
log_user_prompt = false
# 应用于 telemetry 的环境标签。默认："dev"
environment = "dev"
# Exporter：none（默认）| otlp-http | otlp-grpc
exporter = "none"
# Trace exporter：none（默认）| otlp-http | otlp-grpc
trace_exporter = "none"
# Metrics exporter：none | statsig | otlp-http | otlp-grpc
metrics_exporter = "statsig"
# OTLP/HTTP exporter 配置示例
# [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}"
# [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"
# OTLP/gRPC trace exporter 配置示例
# [otel.trace_exporter."otlp-grpc"]
# endpoint = "https://otel.example.com:4317"
# headers = { "x-otlp-meta" = "abc123" }
################################################################################
# Windows
################################################################################
[windows]
# 原生 Windows sandbox 模式（仅 Windows）：unelevated | elevated
sandbox = "unelevated"