一个完整的 config.toml 示例，可以直接复制并根据需要调整。
使用此示例配置作为起点。它包含了 Codex 从 config.toml 中读取的大多数配置项，同时附带了默认行为、推荐值（在有用的情况下）以及简短注释。
有关详细说明和指导，请参阅：
将下面的代码片段作为参考。只复制你需要的配置项和节（section）到 ~/.codex/config.toml（或项目级别的 .codex/config.toml）中，然后根据你的设置调整对应值。
# Codex 示例配置 (config.toml)## 本文件列出了 Codex 从 config.toml 中读取的主要配置项，# 同时包含了默认行为、推荐示例和简要说明。根据需要调整。## 注意# - 根级配置项必须出现在 TOML 表之前。# - 默认为"未设置"的可选配置项以注释形式显示并附带说明。# - MCP 服务器、配置文件和模型提供商仅为示例；根据需要删除或编辑。
################################################################################
# 核心模型选择
################################################################################
# Codex 使用的主模型。推荐大多数用户使用的示例："gpt-5.5"。
model = "gpt-5.5"
# 支持的模型的沟通风格。允许的值：none | friendly | pragmatic
# personality = "pragmatic"
# /review 的可选模型覆盖。默认：未设置（使用当前会话模型）。
# review_model = "gpt-5.5"
# 从 [model_providers] 中选择的提供商 ID。默认："openai"。
model_provider = "openai"
# --oss 会话的默认 OSS 提供商。未设置时，Codex 会提示。默认：未设置。
# oss_provider = "ollama"
# 首选服务层级。内置示例：fast | flex；模型目录可以添加更多。
# service_tier = "flex"
# 可选的手动模型元数据。未设置时，Codex 使用模型或预设默认值。
# model_context_window = 128000 # tokens；默认：自动根据模型# model_auto_compact_token_limit = 64000 # tokens；未设置则使用模型默认值# tool_output_token_limit = 12000 # 每个工具输出存储的 tokens
# model_catalog_json = "/absolute/path/to/models.json" # 可选仅在启动时生效的模型目录覆盖# 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 的运行时状态目录
################################################################################
# 推理和详细程度（支持 Responses API 的模型）
################################################################################
# 推理力度：minimal | low | medium | high | xhigh
# model_reasoning_effort = "medium"
# Codex 在计划模式下运行时的可选覆盖：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 = ""
# 覆盖默认的提交共同作者署名。仅在# [features].codex_git_commit 启用时生效。启用且未设置时，Codex 使用# "Codex <noreply@openai.com>"。设置为 "" 可禁用它。# commit_attribution = "Jane Doe <jane@example.com>"
# 用文件路径覆盖内置的基础指令。默认：未设置。
# model_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"]
################################################################################
# 审批和沙箱
################################################################################
# 何时请求命令审批：# - untrusted：仅已知安全的只读命令自动运行；其他命令提示# - on-request：模型决定何时询问（默认）# - never：永不提示（有风险）# - { granular = { ... } }：允许或自动拒绝选定的提示类别
approval_policy = "on-request"
# 谁审核符合条件的审批提示：user（默认） | auto_review
# approvals_reviewer = "user"
# 示例细粒度策略：# approval_policy = { granular = {# sandbox_approval = true,# rules = true,# mcp_elicitations = true,# request_permissions = false,# skill_approval = false# } }
# 当基于 shell 的工具请求 `login = true` 时，允许登录 shell 语义。# 默认：true。设置为 false 可强制使用非登录 shell 并拒绝显式的登录 shell 请求。
allow_login_shell = true
# 工具调用的文件系统/网络沙箱策略：# - read-only（默认）# - workspace-write# - danger-full-access（无沙箱；极其危险）
sandbox_mode = "read-only"
# 默认应用的命名权限配置文件。内置：# :read-only | :workspace | :danger-full-access# 仅当你同时定义了 [permissions.workspace] 时，才使用自定义名称，如 "workspace"。# default_permissions = ":workspace"
################################################################################
# 认证和登录
################################################################################
# CLI 登录凭据的持久化位置：file（默认） | keyring | auto
cli_auth_credentials_store = "file"
# ChatGPT 认证流程的基础 URL（非 OpenAI API）。
chatgpt_base_url = "https://chatgpt.com/backend-api/"
# 内置 OpenAI 提供商的可选基础 URL 覆盖。
# openai_base_url = "https://us.api.openai.com/v1"
# 将 ChatGPT 登录限制到特定的工作空间 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 回调的可选固定端口：1-65535。默认：未设置。
# mcp_oauth_callback_port = 4321
# MCP OAuth 登录的可选重定向 URI 覆盖（例如，远程开发机入口）。# 支持自定义回调路径。`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"]
################################################################################
# 历史和文件打开器
################################################################################
# 可点击引用的 URI 方案：vscode（默认） | vscode-insiders | windsurf | cursor | none
file_opener = "vscode"
################################################################################
# UI、通知和杂项
################################################################################
# 抑制输出版中的内部推理事件。默认：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 | live。默认："cached"# cached 从网页搜索缓存（OpenAI 维护的索引）提供结果。# cached 返回预索引结果；live 获取最新数据。# 如果你使用 --yolo 或其他完全访问沙箱设置，网页搜索默认为 live。
web_search = "cached"
# 活跃的配置文件名称。未设置时，不应用任何配置文件。
# profile = "default"
# 抑制启用开发中功能标志时显示的警告。
# suppress_unstable_features_warning = true
################################################################################
# 代理（多代理角色和限制）
################################################################################
[agents]
# 最大并发打开的代理线程数。默认：6
# max_threads = 6
# 最大嵌套生成深度。根会话从深度 0 开始。默认：1
# max_depth = 1
# spawn_agents_on_csv 任务中每个工作器的默认超时时间。未设置时，工具默认为 1800 秒。
# job_max_runtime_seconds = 1800
# [agents.reviewer]# description = "查找代码中的正确性、安全性和测试风险。"# config_file = "./agents/reviewer.toml" # 相对于定义它的 config.toml# nickname_candidates = ["Athena", "Ada"]
################################################################################
# 技能（每个技能覆盖）
################################################################################
# 不删除而禁用或重新启用特定技能。
[[skills.config]]
# path = "/path/to/skill/SKILL.md"# enabled = 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（不区分大小写）的变量名的默认排除。默认：false
ignore_default_excludes = false
# 要移除的不区分大小写的 glob 模式（例如，"AWS**", "AZURE**"）。默认：[]
exclude = []
# 显式的键/值覆盖（始终优先）。默认：{}
set = {}
# 白名单；如果非空，仅保留匹配的变量。默认：[]
include_only = []
# 实验性：通过用户 shell 配置文件运行。默认：false
experimental_use_profile = false
################################################################################
# 沙箱网络设置
################################################################################
# 在配置沙箱网络规则之前，需要先启用此功能。
# [features.network_proxy]# enabled = true# domains = { "api.openai.com" = "allow", "example.com" = "deny" }## 精确主机名仅匹配自身。# "*.example.com" 仅匹配子域名；"**.example.com" 匹配顶点域名及子域名。# "*" 允许任何未被拒绝的公共主机，因此尽可能使用有范围的规则。# `allow_local_binding = false` 默认阻止回环和私有目标地址。# 为一个目标添加精确的本地 IP 文字或 `localhost` 允许规则，或仅在需要更广泛的本地访问时将其设置为 true。## 在启用此配置文件之前设置 `default_permissions = "workspace"`。# 继承此配置文件的 `:workspace_roots` 文件系统规则的额外工作区根目录示例。# [permissions.workspace.workspace_roots]# "~/code/app" = true# "~/code/shared-lib" = true## 文件系统配置文件示例。使用 `"deny"` 拒绝精确路径或# glob 模式的读取。在使用无界模式（如 `**`）时，# 需要在需要预展开 glob 匹配的平台上设置 glob_scan_max_depth。# [permissions.workspace.filesystem]# glob_scan_max_depth = 3# ":workspace_roots" = { "." = "write", "**/*.env" = "deny" }# "/absolute/path/to/secrets" = "deny"## [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]
# save-all（默认） | none
persistence = "save-all"
# 历史记录文件的最大字节数；超出时修剪最旧的条目。示例：5242880
# max_bytes = 5242880
################################################################################
# UI、通知和杂项（表）
################################################################################
[tui]
# TUI 的桌面通知：布尔值或筛选列表。默认：true# 示例：false | ["agent-turn-complete", "approval-requested"]
notifications = false
# 终端提醒的通知机制：auto | osc9 | bel。默认："auto"
# notification_method = "auto"
# 通知何时触发：unfocused（默认） | always
# notification_condition = "unfocused"
# 启用欢迎/状态/加载动画。默认：true
animations = true
# 在欢迎屏幕显示入门工具提示。默认：true
show_tooltips = true
# 控制备用屏幕使用（auto 在 Zellij 中跳过以保留回滚历史）。
# alternate_screen = "auto"
# 页脚状态栏项目 ID 的有序列表。未设置时，Codex 使用：# ["model-with-reasoning", "context-remaining", "current-dir"]。# 设置为 [] 可隐藏页脚。# status_line = ["model", "context-remaining", "git-branch"]
# 终端窗口/标签标题项目 ID 的有序列表。未设置时，Codex 使用：# ["spinner", "project"]。设置为 [] 可清空标题。# 可用 ID 包括 app-name、project、spinner、status、thread、git-branch、model# 和 task-progress。# terminal_title = ["spinner", "project"]
# 语法高亮主题（kebab-case）。在 TUI 中使用 /theme 预览和保存。# 你也可以在 $CODEX_HOME/themes 下添加自定义 .tmTheme 文件。# theme = "catppuccin-mocha"
# 自定义按键绑定。上下文特定的绑定会覆盖 [tui.keymap.global]。# 使用 [] 取消绑定一个操作。# [tui.keymap.global]# open_transcript = "ctrl-t"# open_external_editor = []## [tui.keymap.composer]# submit = ["enter", "ctrl-m"]
# 按模型 slug 键控的内部工具提示状态。通常由 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" }
################################################################################
# 集中式功能标志（推荐）
################################################################################
[features]
# 将此表留空以接受默认值。设置明确的布尔值来选择加入/退出。# shell_tool = true# apps = false# hooks = false# plugin_hooks = false # 默认关闭；设置为 true 可选择加入插件捆绑的 hooks。# codex_git_commit = false# unified_exec = true# shell_snapshot = true# multi_agent = true# personality = true# network_proxy = false# fast_mode = true# enable_request_compression = true# skill_mcp_dependency_install = true# prevent_idle_sleep = false
################################################################################
# 记忆（表）
################################################################################
# 通过 [features].memories 启用记忆功能，然后在此处调整记忆行为。# [memories]# generate_memories = true# use_memories = true# disable_on_external_context = false # 旧版别名：no_memories_if_mcp_or_web_search
################################################################################
# 生命周期 hooks 可以在此处内联配置或在同级的 hooks.json 中配置。
################################################################################
# [hooks]# [[hooks.PreToolUse]]# matcher = "^Bash$"## [[hooks.PreToolUse.hooks]]# type = "command"# command = 'python3 "/absolute/path/to/pre_tool_use_policy.py"'# timeout = 30# statusMessage = "正在检查 Bash 命令"
################################################################################
# 在此表下定义 MCP 服务器。留空以禁用。
################################################################################
[mcp_servers]
# --- 示例：STDIO 传输 ---
# [mcp_servers.docs]# enabled = true # 可选；默认 true# required = true # 可选；如果此服务器无法初始化，则启动/恢复失败# command = "docs-server" # 必填# args = ["--port", "4000"] # 可选# env = { "API_KEY" = "value" } # 可选的键/值对，按原样复制# env_vars = ["ANOTHER_SECRET"] # 可选：转发本地父环境变量# env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]# cwd = "/path/to/server" # 可选的工作目录覆盖# experimental_environment = "remote" # 实验性：通过远程执行器运行 stdio# 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"] # 可选的拒绝列表（在允许列表之后应用）# scopes = ["read:docs"] # 可选的 OAuth 范围# oauth_resource = "https://docs.example.com/" # 可选的 OAuth 资源
# --- 示例：Streamable HTTP 传输 ---
# [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" } # 可选的静态请求头# env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选从环境变量填充的请求头# startup_timeout_sec = 10.0 # 可选# tool_timeout_sec = 60.0 # 可选# enabled_tools = ["list_issues"] # 可选的允许列表# disabled_tools = ["delete_issue"] # 可选的拒绝列表# scopes = ["repo"] # 可选的 OAuth 范围
################################################################################
# 模型提供商
################################################################################
# 内置包括：# - openai# - ollama# - lmstudio# - amazon-bedrock# 这些 ID 是保留的。自定义提供商请使用不同的 ID。
[model_providers]
# --- 示例：内置 Amazon Bedrock 提供商选项 ---
# model_provider = "amazon-bedrock"# model = "<bedrock-model-id>"# [model_providers.amazon-bedrock.aws]# profile = "default"# region = "eu-central-1"
# --- 示例：OpenAI 数据驻留，使用显式基础 URL 或请求头 ---
# [model_providers.openaidr]# name = "OpenAI Data Residency"# base_url = "https://us.api.openai.com/v1" # 使用 'us' 域名前缀的示例# wire_api = "responses" # 唯一支持的值# # requires_openai_auth = true # 仅对由 OpenAI 认证支持的提供商使用# # 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" # 可选的仅供开发使用的直接 bearer token# # http_headers = { "X-Example" = "value" }# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }
# --- 示例：Azure/OpenAI 兼容提供商 ---
# [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 = "在您的环境中设置 AZURE_OPENAI_API_KEY"# # supports_websockets = false
# --- 示例：基于命令的 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
# --- 示例：本地 OSS（例如，Ollama 兼容）---
# [model_providers.local_ollama]# name = "Ollama"# base_url = "http://localhost:11434/v1"# wire_api = "responses"
################################################################################
# 应用/连接器
################################################################################
# 可选的应用逐项控制。
[apps]
# [_default] 适用于所有应用，除非按应用覆盖。# [apps._default]# enabled = true# destructive_enabled = true# open_world_enabled = true## [apps.google_drive]# enabled = false# destructive_enabled = false # 阻止此应用的破坏性提示工具# default_tools_enabled = true# default_tools_approval_mode = "prompt" # auto | prompt | approve## [apps.google_drive.tools."files/delete"]# enabled = false# approval_mode = "approve"
# Codex 可以提议安装的连接器或插件的可选工具建议允许列表。# [tool_suggest]# discoverables = [# { type = "connector", id = "gmail" },# { type = "plugin", id = "figma@openai-curated" },# ]# disabled_tools = [# { type = "plugin", id = "slack@openai-curated" },# { type = "connector", id = "connector_googlecalendar" },# ]
################################################################################
# 配置文件（命名的预设）
################################################################################
[profiles]
# [profiles.default]# model = "gpt-5.4"# model_provider = "openai"# approval_policy = "on-request"# sandbox_mode = "read-only"# service_tier = "flex" # 或其他支持的服务层级 ID# 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."/absolute/path/to/project"]# trust_level = "trusted" # 或 "untrusted"
################################################################################
# 工具
################################################################################
[tools]
# view_image = true
################################################################################
# OpenTelemetry (OTEL) - 默认禁用
################################################################################
[otel]
# 在日志中包含用户提示文本。默认：false
log_user_prompt = false
# 应用于遥测的环境标签。默认："dev"
environment = "dev"
# 导出器：none（默认） | otlp-http | otlp-grpc
exporter = "none"
# 链路导出器：none（默认） | otlp-http | otlp-grpc
trace_exporter = "none"
# 指标导出器：none | statsig | otlp-http | otlp-grpc
metrics_exporter = "statsig"
# 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}"# [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 链路导出器配置示例# [otel.trace_exporter."otlp-grpc"]# endpoint = "https://otel.example.com:4317"# headers = { "x-otlp-meta" = "abc123" }
################################################################################
# Windows
################################################################################
[windows]
# 原生 Windows 沙箱模式（仅 Windows）：unelevated | elevated
sandbox = "unelevated"