本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/config-sample

示例配置

一个可复制并按需调整的完整 config.toml 示例

使用此示例配置作为起点。它包含了 Codex 从 config.toml 读取的大多数键，以及默认行为、在有帮助时推荐的值和简短说明。

有关解释和指导，请参阅：

• 配置基础
• 高级配置
• 配置参考
• 沙箱和审批
• 托管配置

将下面的代码片段用作参考。只需将你需要的键和节复制到 ~/.codex/config.toml（或项目级的 .codex/config.toml）中，然后根据你的环境调整值。

# Codex 示例配置（config.toml）
#
# 此文件列出了 Codex 从 config.toml 读取的主要键，以及默认
# 行为、推荐示例和值得简要说明的解释。请按需调整。
#
# 说明
# - 在 TOML 中，根键必须出现在表之前。
# - 默认值为“未设置”的可选键会以带注释的形式显示并附带说明。
# - MCP 服务器、profiles 和 model providers 仅为示例；可删除或修改。

################################################################################

# 核心模型选择

################################################################################

# Codex 使用的主模型。对大多数用户推荐的示例："gpt-5.5"。

model = "gpt-5.5"

# 适用于支持模型的沟通风格。允许值：none | friendly | pragmatic

# personality = "pragmatic"

# /review 的可选模型覆盖。默认：未设置（使用当前会话模型）。

# review_model = "gpt-5.5"

# 从 [model_providers] 中选择的 provider id。默认："openai"。

model_provider = "openai"

# --oss 会话的默认 OSS provider。未设置时，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 轮询窗口的最大时长（默认 5m）

# 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 在 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 = ""

# history compaction prompt 的内联覆盖。默认：未设置。

# compact_prompt = ""

# 覆盖默认的 commit 共同作者 trailer。仅当

# [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"

# 从文件加载 compact prompt 覆盖。默认：未设置。

# 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"

# granular 策略示例：

# 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

# 工具调用的文件系统/网络沙箱策略：

# - read-only（默认）

# - workspace-write

# - danger-full-access（无沙箱；风险极高）

sandbox_mode = "read-only"

# 默认应用的命名权限 profile。内置值：

# :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 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 回调的可选固定端口：1-65535。默认：未设置。

# mcp_oauth_callback_port = 4321

# MCP OAuth 登录的可选重定向 URI 覆盖（例如远程 devbox ingress）。

# 支持自定义回调路径。`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 scheme：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

################################################################################

# Web 搜索

################################################################################

# Web 搜索模式：disabled | cached | live。默认："cached"

# cached 从 Web 搜索缓存（由 OpenAI 维护的索引）中提供结果。

# cached 返回预先建立索引的结果；live 获取最新数据。

# 如果你使用 --yolo 或其他完全访问沙箱设置，Web 搜索默认使用 live。

web_search = "cached"

# 活动 profile 名称。未设置时，不应用任何 profile。

# profile = "default"

# 启用开发中功能标志时，抑制显示的警告。

# suppress_unstable_features_warning = true

################################################################################

# Agents（多 agent 角色和限制）

################################################################################

[agents]

# 同时打开的 agent 线程最大数量。默认：6

# max_threads = 6

# 嵌套生成的最大深度。根会话从深度 0 开始。默认：1

# max_depth = 1

# spawn_agents_on_csv 作业中每个 worker 的默认超时时间。未设置时，该工具默认使用 1800 秒。

# job_max_runtime_seconds = 1800

# [agents.reviewer]

# description = "在代码中查找正确性、安全性和测试风险。"

# config_file = "./agents/reviewer.toml" # 相对于定义它的 config.toml

# nickname_candidates = ["Athena", "Ada"]

################################################################################

# Skills（按 skill 的覆盖）

################################################################################

# 禁用或重新启用特定 skill，而无需删除它。

[[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 profile 运行。默认：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` 默认阻止 loopback 和私有目标。

# 为单个目标添加精确的本地 IP 字面量或 `localhost` 允许规则，或仅在需要更广泛本地访问时将其设为 true。

#

# 在启用此 profile 之前，先设置 `default_permissions = "workspace"`。

# 示例：继承此 profile 的

# `:workspace_roots` 文件系统规则的额外工作区根目录。

# [permissions.workspace.workspace_roots]

# "~/code/app" = true

# "~/code/shared-lib" = true

#

# 文件系统 profile 示例。对精确路径或

# glob 模式使用 `"deny"` 可拒绝读取。在需要预展开 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"

# 启用欢迎/状态/spinner 动画。默认：true

animations = true

# 在欢迎界面显示引导工具提示。默认：true

show_tooltips = true

# 控制 alternate screen 的使用（在 Zellij 中 auto 会跳过它以保留滚动回溯）。

# 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

# 为此机器启用或禁用 analytics。未设置时，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

################################################################################

# Memories（表）

################################################################################

# 使用 [features].memories 启用 memories，然后在此处调整 memory 行为。

# [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 scopes

# oauth_resource = "https://docs.example.com/" # 可选 OAuth resource

# --- 示例：可流式 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" } # 可选静态 headers

# env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选，从环境变量填充的 headers

# startup_timeout_sec = 10.0 # 可选

# tool_timeout_sec = 60.0 # 可选

# enabled_tools = ["list_issues"] # 可选允许列表

# disabled_tools = ["delete_issue"] # 可选拒绝列表

# scopes = ["repo"] # 可选 OAuth scopes

################################################################################

# Model Providers

################################################################################

# 内置项包括：

# - openai

# - ollama

# - lmstudio

# - amazon-bedrock

# 这些 ID 是保留的。自定义 providers 请使用其他 ID。

[model_providers]

# --- 示例：内置 Amazon Bedrock provider 选项 ---

# model_provider = "amazon-bedrock"

# model = "<bedrock-model-id>"

# [model_providers.amazon-bedrock.aws]

# profile = "default"

# region = "eu-central-1"

# --- 示例：通过显式 base URL 或 headers 实现 OpenAI 数据驻留 ---

# [model_providers.openaidr]

# name = "OpenAI Data Residency"

# base_url = "https://us.api.openai.com/v1" # 带有 'us' 域名前缀的示例

# wire_api = "responses" # 唯一支持的值

# # requires_openai_auth = true # 仅用于由 OpenAI auth 支持的 providers

# # request_max_retries = 4 # 默认 4；最大 100

# # stream_max_retries = 5 # 默认 5；最大 100

# # stream_idle_timeout_ms = 300000 # 默认 300_000（5m）

# # 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 兼容 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 = "在你的环境中设置 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 / Connectors

################################################################################

# 可选的按 app 控制。

[apps]

# [_default] 适用于所有 apps，除非针对某个 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"

# connectors 或插件的可选工具建议允许列表，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]

# [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]

# 将特定工作树标记为 trusted 或 untrusted。

# [projects."/absolute/path/to/project"]

# trust_level = "trusted" # 或 "untrusted"

################################################################################

# Tools

################################################################################

[tools]

# view_image = true

################################################################################

# OpenTelemetry (OTEL) - 默认禁用

################################################################################

[otel]

# 在日志中包含用户提示文本。默认：false

log_user_prompt = false

# 应用于遥测的环境标签。默认："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 沙箱模式（仅 Windows）：unelevated | elevated

sandbox = "unelevated"