高级配置

身份 非官方简体中文镜像

翻译状态 AI 翻译 / AI 审校

来源版本 官方未提供

同步日期 2026-07-26

官方原文 learn.chatgpt.com

当你需要更精细地控制提供商、策略和集成时，可以使用这些选项。若要快速开始，请参阅配置基础。

如需了解项目指导、可复用能力、自定义斜杠命令、子代理工作流和集成，请参阅自定义。如需了解配置键，请参阅配置参考。

配置文件

配置文件可以让你保存命名的配置层，并通过 CLI 在它们之间切换。当你传入 --profile profile-name 时，Codex 会加载 ~/.codex/config.toml，然后叠加 ~/.codex/profile-name.config.toml。配置文件名称可以包含字母、数字、连字符和下划线。

为每个配置文件创建一个单独的 TOML 文件。在配置文件中使用顶层配置键；不要将它们嵌套在 [profiles.profile-name] 下。

~/.codex/deep-review.config.toml

model = "gpt-5.5"
model_reasoning_effort = "xhigh"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"

codex --profile deep-review
codex exec --profile deep-review "review this change"

由于配置文件位于基础用户配置之上、项目配置和 CLI 配置之下，因此其中只需要包含与基础配置不同的值。配置文件还可以覆盖 model_catalog_json；当两个文件都设置了该值时，Codex 会使用配置文件中的值。

在 Codex 0.134.0 及更高版本中，--profile 不再从 config.toml 读取 [profiles.profile-name]，顶层的 profile = "profile-name" 选择器也不再受支持。请将旧版配置文件设置移至 ~/.codex/profile-name.config.toml，然后从 config.toml 中移除对应的 [profiles.profile-name] 表和 profile = "profile-name" 选择器。

CLI 的单次覆盖

除了编辑 ~/.codex/config.toml 外，你还可以通过 CLI 为单次运行覆盖配置：

• 如果存在专用标志，优先使用它们（例如 --model）。
• 当你需要覆盖任意键时，使用 -c / --config。

示例：

# 专用标志
codex --model gpt-5.4

# 通用键值覆盖（值为 TOML，而不是 JSON）
codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

注意：

• 键可以使用点号表示法设置嵌套值（例如 mcp_servers.context7.enabled=false）。
• --config 的值会按 TOML 解析。如有疑问，请将值加引号，以免 shell 按空格拆分值。
• 如果值无法解析为 TOML，Codex 会将其视为字符串。

配置和状态位置

Codex 将本地状态存储在 CODEX_HOME 下（默认为 ~/.codex）。

你可能会在其中看到的常见文件：

• config.toml（本地配置）
• auth.json（如果使用基于文件的凭据存储）或操作系统钥匙串/密钥环
• history.jsonl（如果启用了历史记录持久化）
• 其他每用户状态，例如日志和缓存

如需了解身份验证详情（包括凭据存储模式），请参阅身份验证。如需查看完整的配置键列表，请参阅配置参考。

如需了解签入代码仓库或系统路径中的共享默认值、规则和技能，请参阅团队配置。

如果你只需要让内置 OpenAI 提供商指向 LLM 代理、路由器或启用了数据驻留的项目，请在 config.toml 中设置 openai_base_url，而不是定义新提供商。这会更改内置 openai 提供商的基础 URL，无需单独的 model_providers.<id> 条目。

openai_base_url = "https://us.api.openai.com/v1"

项目配置文件（.codex/config.toml）

除了用户配置外，Codex 还会从仓库中的 .codex/config.toml 文件读取项目范围的覆盖配置。Codex 会从项目根目录向当前工作目录逐级查找，并加载找到的每个 .codex/config.toml。如果多个文件定义了同一个键，则距离当前工作目录最近的文件优先。

出于安全考虑，Codex 仅在项目受信任时加载项目范围的配置文件。如果项目不受信任，Codex 会忽略项目的 .codex/ 配置层，包括 .codex/config.toml、项目本地钩子和项目本地规则。用户配置层和系统配置层保持独立，仍会正常加载。

项目配置中的相对路径（例如 model_instructions_file）是相对于包含该 config.toml 的 .codex/ 文件夹解析的。

项目配置文件不能覆盖重定向凭据、修改由主机拥有的应用请求元数据、更改提供商身份验证、选择配置文件，或运行机器本地通知/遥测命令的设置。Codex 会忽略项目本地 .codex/config.toml 中的以下键，并在发现这些键时打印启动警告：openai_base_url、chatgpt_base_url、apps_mcp_product_sku、model_provider、model_providers、notify、profile、profiles、experimental_realtime_ws_base_url 和 otel。请在用户级别的 ~/.codex/config.toml 中设置提供商、通知和遥测键；使用 --profile profile-name 和 ~/.codex/profile-name.config.toml 选择配置文件。

钩子

Codex 还可以从 hooks.json 文件或 config.toml 文件中的内联 [hooks] 表加载生命周期钩子；这些文件应位于活动配置层旁边。

实际使用中，最有用的四个位置是：

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

项目本地钩子仅在项目 .codex/ 配置层受信任时加载。用户级钩子不受项目信任状态影响。

内联 TOML 钩子使用与 hooks.json 相同的事件结构：

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

如果同一配置层同时包含 hooks.json 和内联 [hooks]，Codex 会同时加载两者并发出警告。每个配置层建议只使用一种表示形式。

如需查看当前事件列表、输入字段、输出行为和限制，请参阅钩子。

代理角色（config.toml 中的 [agents]）

如需了解子代理角色配置（config.toml 中的 [agents]），请参阅子代理。

项目根目录检测

Codex 会从工作目录开始向上查找，直到到达项目根目录，以发现项目配置（例如 .codex/ 配置层和 AGENTS.md）。

默认情况下，Codex 将包含 .git 的目录视为项目根目录。若要自定义此行为，请在 config.toml 中设置 project_root_markers：

# 当目录包含以下任一标记时，将其视为项目根目录。
project_root_markers = [".git", ".hg", ".sl"]

将 project_root_markers = [] 设置为空数组，可跳过对父目录的查找，并将当前工作目录视为项目根目录。

自定义模型提供商

模型提供商定义了 Codex 如何连接到模型（基础 URL、线协议 API、身份验证和可选的 HTTP 标头）。自定义提供商不能复用保留的内置提供商 ID：openai、ollama 和 lmstudio。

定义其他提供商，并将 model_provider 指向它们：

model = "gpt-5.4"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

在需要时添加请求标头：

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

当提供商需要 Codex 从外部凭据助手获取 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

身份验证命令不会接收 stdin，并且必须将令牌打印到 stdout。Codex 会去除令牌两端的空白，将空令牌视为错误，并在 refresh_interval_ms 到期时主动刷新；将 refresh_interval_ms = 0 设置为仅在身份验证重试后刷新。不要将 [model_providers.<id>.auth] 与 env_key、experimental_bearer_token 或 requires_openai_auth 结合使用。

Amazon Bedrock 提供商

Codex 内置 amazon-bedrock 模型提供商。将其直接设置为 model_provider；与自定义提供商不同，此内置提供商仅支持嵌套的 AWS 配置文件和区域覆盖。

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

如果省略 profile，Codex 会使用标准 AWS 凭据链。将 region 设置为应处理请求的受支持 Bedrock 区域。

如需查看完整设置流程、身份验证选项、支持的模型和功能可用性，请参阅将 ChatGPT Work 和 Codex 与 Amazon Bedrock 配合使用。

OSS 模式（本地提供商）

传入 --oss 时，Codex 可以使用 Ollama 或 LM Studio 等本地“开源”提供商运行。使用 --local-provider 为单次运行选择一个提供商，或设置 oss_provider 作为默认值。如果两者都未设置，交互式 CLI 会提示你进行选择；codex exec 会报错退出。

# 与 `--oss` 一起使用的默认本地提供商
oss_provider = "ollama" # 或 "lmstudio"

Azure 提供商和按提供商调优

[model_providers.azure]
name = "Azure"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

若要更改内置 OpenAI 提供商的基础 URL，请使用 openai_base_url；不要创建 [model_providers.openai]，因为你无法覆盖内置提供商 ID。

使用数据驻留的 ChatGPT 客户

启用了数据驻留的项目可以创建模型提供商，并使用正确的前缀更新 base_url。

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # 将 'us' 替换为域名前缀

模型推理、详细程度和限制

model_reasoning_summary = "none"          # 禁用摘要
model_verbosity = "low"                   # 缩短响应
model_supports_reasoning_summaries = true # 强制启用推理
model_context_window = 128000             # 上下文窗口大小

model_verbosity 仅适用于使用 Responses API 的提供商。Chat Completions 提供商会忽略此设置。

审批策略和沙箱模式

选择审批严格程度（影响 Codex 何时暂停）和沙箱级别（影响文件/网络访问）。

编辑 config.toml 时需要注意的操作细节，请参阅常见沙箱和审批组合、可写根目录中的受保护路径和网络访问。

如需了解同时配置文件系统和网络访问的测试权限配置文件，请参阅权限。

你还可以使用细粒度审批策略（approval_policy = { granular = { ... } }）来允许或自动拒绝单独的提示类别。当你希望对某些情况进行正常的交互式审批，但希望其他情况（例如 request_permissions 或技能脚本提示）自动以默认拒绝方式失败时，这会很有用。

设置 approvals_reviewer = "auto_review"，可将符合条件的交互式审批请求交由自动审核处理。这会更改审核者，而不会改变沙箱边界。

使用 [auto_review].policy 配置本地审核者策略说明。托管的 guardian_policy_config 优先级更高。

approval_policy = "untrusted"   # 其他选项：on-request、never 或 { granular = { ... } }
approvals_reviewer = "user"     # 或用于自动审核的 "auto_review"
sandbox_mode = "workspace-write"
allow_login_shell = false       # 可选强化：禁止 shell 工具使用登录 shell

# 细粒度审批策略示例
# approval_policy = { granular = {
# sandbox_approval = true,
# rules = true,
# mcp_elicitations = true,
# request_permissions = false,
# skill_approval = false
# } }
[sandbox_workspace_write]
exclude_tmpdir_env_var = false  # 允许使用 $TMPDIR
exclude_slash_tmp = false       # 允许使用 /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # 选择启用出站网络

[auto_review]
policy = """
使用你所在组织的自动审核策略。
"""

命名权限配置文件

如需了解内置配置文件、自定义配置文件语法以及完整的文件系统和网络配置模型，请参阅权限。

如需查看完整的键列表和要求约束，请参阅配置参考和托管配置。

在 workspace-write 模式下，某些环境会让 .git/ 和 .codex/ 保持只读，即使工作区的其余部分可写。这就是为什么像 git commit 这样的命令仍可能需要批准才能在沙箱外运行。如果你希望 Codex 跳过特定命令（例如阻止 git commit 在沙箱外运行），请使用规则。

完全禁用沙箱（仅当你的环境已经隔离进程时使用）：

sandbox_mode = "danger-full-access"

Shell 环境策略

shell_environment_policy 控制 Codex 传递给其启动的任何子进程的环境变量（例如，运行模型提出的工具命令时）。从干净环境（inherit = "none"）或精简环境（inherit = "core"）开始，然后叠加排除项、包含项和覆盖项，以避免泄露机密，同时仍提供任务所需的路径、密钥或标志。

[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin", MY_FLAG = "1" }
ignore_default_excludes = false
exclude = ["AWS_*", "AZURE_*"]
include_only = ["PATH", "HOME"]

模式是不区分大小写的 glob（*、?、[A-Z]）；ignore_default_excludes = false 会在包含项和排除项生效前保留自动的 KEY/SECRET/TOKEN 过滤器。

MCP 服务器

如需了解配置详情，请参阅专门的 MCP 文档。

可观测性和遥测

启用 OpenTelemetry（OTel）日志导出，以跟踪 Codex 运行情况（API 请求、SSE/事件、提示、工具审批/结果）。该功能默认禁用；可通过 [otel] 选择启用：

[otel]
environment = "staging"   # 默认为 "dev"
exporter = "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" }
}}

如果 exporter = "none"，Codex 会记录事件但不会发送任何内容。导出器会异步批处理，并在关闭时刷新。事件元数据包括服务名称、CLI 版本、环境标签、会话 ID、模型、沙箱/审批设置以及每个事件的字段（请参阅配置参考）。

导出的内容

Codex 会为运行和工具使用发出结构化日志事件。具有代表性的事件类型包括：

• codex.conversation_starts（模型、推理设置、沙箱/审批策略）
• codex.api_request（尝试次数、状态/成功情况、耗时和错误详情）
• codex.sse_event（流事件类型、成功/失败、耗时，以及 response.completed 中的令牌计数）
• codex.websocket_request 和 codex.websocket_event（请求耗时，以及每条消息的类型/成功/错误）
• codex.user_prompt（长度；除非明确启用，否则内容会被编辑）
• codex.tool_decision（已批准/已拒绝，以及决定来自配置还是用户）
• codex.tool_result（耗时、成功情况、输出片段）

导出的 OTel 指标

启用 OTel 指标管道后，Codex 会为 API、流和工具活动发出计数器与耗时直方图。

下面的每个指标还包含默认元数据标签：auth_mode、originator、session_source、model 和 app.version。

指标	类型	字段	描述
codex.api_request	counter	status, success	按 HTTP 状态和成功/失败情况统计 API 请求数。
codex.api_request.duration_ms	histogram	status, success	API 请求耗时，单位为毫秒。
codex.sse_event	counter	kind, success	按事件类型和成功/失败情况统计 SSE 事件数。
codex.sse_event.duration_ms	histogram	kind, success	SSE 事件处理耗时，单位为毫秒。
codex.websocket.request	counter	success	按成功/失败情况统计 WebSocket 请求数。
codex.websocket.request.duration_ms	histogram	success	WebSocket 请求耗时，单位为毫秒。
codex.websocket.event	counter	kind, success	按类型和成功/失败情况统计 WebSocket 消息/事件数。
codex.websocket.event.duration_ms	histogram	kind, success	WebSocket 消息/事件处理耗时，单位为毫秒。
codex.tool.call	counter	tool, success	按工具名称和成功/失败情况统计工具调用次数。
codex.tool.call.duration_ms	histogram	tool, success	按工具名称和结果统计工具执行耗时。

如需了解遥测相关的更多安全和隐私指南，请参阅安全性。

指标

默认情况下，Codex 会定期向 OpenAI 发送少量匿名使用情况和运行状况数据。这有助于检测 Codex 是否正常工作，并了解正在使用的功能和配置选项，从而让 Codex 团队专注于最重要的事项。这些指标不包含任何个人身份信息（PII）。指标收集独立于 OTel 日志/跟踪导出。

如果你希望在一台设备上完全禁用 ChatGPT 桌面应用、Codex CLI 和 Codex IDE extension 的指标收集，请在配置中设置 analytics 标志：

[analytics]
enabled = false

每个指标都包含自身的字段以及下面的默认上下文字段。

默认上下文字段（适用于每个事件/指标）

• auth_mode：swic | api | unknown。
• model：所使用模型的名称。
• app.version：Codex 版本。

指标目录

每个指标都包含必填字段以及上述默认上下文字段。下面的指标名称省略了 codex. 前缀。

大多数指标名称集中定义在 codex-rs/otel/src/metrics/names.rs 中；此处也包含在该文件之外发出的特定功能指标。

如果指标包含 tool 字段，它反映的是所使用的内部工具（例如 apply_patch 或 shell），不包含 Codex 尝试应用的实际 shell 命令或补丁。

运行时和模型传输

指标	类型	字段	描述
api_request	counter	status, success	按 HTTP 状态和成功/失败统计 API 请求数。
api_request.duration_ms	histogram	status, success	API 请求耗时（毫秒）。
sse_event	counter	kind, success	按事件类型和成功/失败统计 SSE 事件数。
sse_event.duration_ms	histogram	kind, success	SSE 事件处理耗时（毫秒）。
websocket.request	counter	success	按成功/失败统计 WebSocket 请求数。
websocket.request.duration_ms	histogram	success	WebSocket 请求耗时（毫秒）。
websocket.event	counter	kind, success	按类型和成功/失败统计 WebSocket 消息/事件数。
websocket.event.duration_ms	histogram	kind, success	WebSocket 消息/事件处理耗时（毫秒）。
responses_api_overhead.duration_ms	histogram		WebSocket 响应中的 Responses API 额外开销耗时。
responses_api_inference_time.duration_ms	histogram		WebSocket 响应中的 Responses API 推理耗时。
responses_api_engine_iapi_ttft.duration_ms	histogram		Responses API 引擎 IAPI 首 token 时间。
responses_api_engine_service_ttft.duration_ms	histogram		Responses API 引擎服务首 token 时间。
responses_api_engine_iapi_tbt.duration_ms	histogram		Responses API 引擎 IAPI token 间隔时间。
responses_api_engine_service_tbt.duration_ms	histogram		Responses API 引擎服务 token 间隔时间。
transport.fallback_to_http	counter	from_wire_api	WebSocket 回退到 HTTP 的次数。
remote_models.fetch_update.duration_ms	histogram		获取远程模型定义所需的时间。
remote_models.load_cache.duration_ms	histogram		加载远程模型缓存所需的时间。
startup_prewarm.duration_ms	histogram	status	按结果统计启动预热耗时。
startup_prewarm.age_at_first_turn_ms	histogram	status	第一个实际回合解析启动预热时的预热存续时间。
cloud_requirements.fetch.duration_ms	histogram		工作区管理的云端要求获取耗时。
cloud_requirements.fetch_attempt	counter	参见注释	工作区管理的云端要求获取尝试次数。
cloud_requirements.fetch_final	counter	参见注释	工作区管理的云端要求最终获取结果。
cloud_requirements.load	counter	trigger, outcome	工作区管理的云端要求加载结果。

cloud_requirements.fetch_attempt 指标包含 trigger、attempt、outcome 和 status_code 字段。cloud_requirements.fetch_final 指标包含 trigger、outcome、reason、attempt_count 和 status_code 字段。

回合与工具活动

指标	类型	字段	描述
turn.e2e_duration_ms	histogram		完整回合的端到端耗时。
turn.ttft.duration_ms	histogram		一个回合的首 token 时间。
turn.ttfm.duration_ms	histogram		一个回合首次模型输出项的时间。
turn.network_proxy	counter	active, tmp_mem_enabled	该回合是否启用了受管理的网络代理。
turn.memory	counter	read_allowed, feature_enabled, config_use_memories, has_citations	每回合的记忆读取可用性和记忆引用使用情况。
turn.tool.call	histogram	tmp_mem_enabled	一个回合中的工具调用次数。
turn.token_usage	histogram	token_type, tmp_mem_enabled	按 token 类型统计每回合的 token 使用量（total、input、cached_input、output 或 reasoning_output）。
tool.call	counter	tool, success	按工具名称和成功/失败统计工具调用次数。
tool.call.duration_ms	histogram	tool, success	按工具名称和结果统计工具执行耗时。
tool.unified_exec	counter	tty	按 TTY 模式统计 Unified exec 工具调用次数。
approval.requested	counter	tool, approved	工具审批请求结果（approved、approved_with_amendment、approved_for_session、denied、abort）。
mcp.call	counter	参见注释	MCP 工具调用结果。
mcp.call.duration_ms	histogram	参见注释	MCP 工具调用耗时。
mcp.tools.list.duration_ms	histogram	cache	MCP 工具列表耗时，包括缓存命中/未命中状态。
mcp.tools.fetch_uncached.duration_ms	histogram		未命中缓存的 MCP 工具获取耗时。
mcp.tools.cache_write.duration_ms	histogram		Codex Apps MCP 工具缓存写入耗时。
hooks.run	counter	hook_name, source, status	按钩子名称、来源和状态统计钩子运行次数。
hooks.run.duration_ms	histogram	hook_name, source, status	钩子运行耗时。

mcp.call 和 mcp.call.duration_ms 指标包含 status；正常的工具调用记录还包含 tool，并在可用时包含 connector_id 和 connector_name。被阻止的 Codex Apps MCP 调用可能只记录包含 status 的 mcp.call。

线程、任务与功能

指标	类型	字段	描述
feature.state	counter	feature, value	与默认值不同的功能值（每个非默认值记录一行）。
status_line	counter		以配置的状态行启动会话。
model_warning	counter		向模型发送的警告。
thread.started	counter	is_git	创建新线程，并根据工作目录是否位于 Git 仓库中进行标记。
conversation.turn.count	counter		每个线程中的用户/助手回合数，在​​线程结束时记录。
thread.fork	counter	source	通过分叉现有线程创建的新线程。
thread.rename	counter		重命名线程。
thread.side	counter	source	创建旁支对话。
thread.skills.enabled_total	histogram		为新线程启用的技能数量。
thread.skills.kept_total	histogram		提示渲染后保留的已启用技能数量。
thread.skills.truncated	histogram		技能渲染是否截断了已启用技能列表（1 或 0）。
task.compact	counter	type	按类型统计压缩次数（remote 或 local），包括手动和自动压缩。
task.review	counter		触发的审查次数。
task.undo	counter		触发的撤销操作次数。
task.user_shell	counter		用户 shell 操作次数（例如 TUI 中的 !）。
shell_snapshot	counter	参见注释	创建 shell 快照是否成功。
shell_snapshot.duration_ms	histogram	success	创建 shell 快照所需的时间。
skill.injected	counter	status, skill	按技能统计技能注入结果。
plugins.startup_sync	counter	transport, status	精选插件启动同步尝试次数。
plugins.startup_sync.final	counter	transport, status	精选插件启动同步最终结果。
multi_agent.spawn	counter	role	按角色统计 Agent 启动次数。
multi_agent.resume	counter		Agent 恢复次数。
multi_agent.nickname_pool_reset	counter		Agent 昵称池重置次数。

shell_snapshot 指标包含 success，失败时还包含 failure_reason。

记忆与本地状态

指标	类型	字段	描述
memory.phase1	counter	status	按状态统计记忆阶段 1 作业数量。
memory.phase1.e2e_ms	histogram		记忆阶段 1 的端到端耗时。
memory.phase1.output	counter		写入的记忆阶段 1 输出数量。
memory.phase1.token_usage	histogram	token_type	按 token 类型统计记忆阶段 1 的 token 使用量。
memory.phase2	counter	status	按状态统计记忆阶段 2 作业数量。
memory.phase2.e2e_ms	histogram		记忆阶段 2 的端到端耗时。
memory.phase2.input	counter		记忆阶段 2 的输入数量。
memory.phase2.token_usage	histogram	token_type	按 token 类型统计记忆阶段 2 的 token 使用量。
memories.usage	counter	kind, tool, success	按类型、工具和成功/失败统计记忆使用情况。
external_agent_config.detect	counter	参见注释	按迁移项目类型统计外部 Agent 配置检测次数。
external_agent_config.import	counter	参见注释	按迁移项目类型统计外部 Agent 配置导入次数。
db.backfill	counter	status	初始状态数据库回填结果（upserted、failed）。
db.backfill.duration_ms	histogram	status	初始状态数据库回填耗时。
db.error	counter	stage	状态数据库操作期间发生的错误。

external_agent_config.detect 和 external_agent_config.import 指标包含 migration_type；技能迁移还包含 skills_count。

Windows 沙箱

指标	类型	字段	描述
windows_sandbox.setup_success	counter	originator, mode	Windows 沙箱设置成功次数。
windows_sandbox.setup_failure	counter	originator, mode	Windows 沙箱设置失败次数。
windows_sandbox.setup_duration_ms	histogram	result, originator, mode	Windows 沙箱设置耗时。
windows_sandbox.elevated_setup_success	counter		提权 Windows 沙箱设置成功次数。
windows_sandbox.elevated_setup_failure	counter	参见注释	提权 Windows 沙箱设置失败次数。
windows_sandbox.elevated_setup_canceled	counter	参见注释	已取消的提权 Windows 沙箱设置尝试次数。
windows_sandbox.elevated_setup_duration_ms	histogram	result	提权 Windows 沙箱设置耗时。
windows_sandbox.elevated_prompt_shown	counter		已显示提权沙箱设置提示。
windows_sandbox.elevated_prompt_accept	counter		已接受提权沙箱设置提示。
windows_sandbox.elevated_prompt_use_legacy	counter		用户从提权提示中选择了旧版沙箱。
windows_sandbox.elevated_prompt_quit	counter		用户从提权提示中退出。
windows_sandbox.fallback_prompt_shown	counter		已显示回退沙箱提示。
windows_sandbox.fallback_retry_elevated	counter		用户从回退提示中重试提权设置。
windows_sandbox.fallback_use_legacy	counter		用户从回退提示中选择了旧版沙箱。
windows_sandbox.fallback_prompt_quit	counter		用户从回退提示中退出。
windows_sandbox.legacy_setup_preflight_failed	counter	参见注释	旧版 Windows 沙箱设置预检失败。
windows_sandbox.setup_elevated_sandbox_command	counter		已调用提权沙箱设置命令。
windows_sandbox.createprocessasuserw_failed	counter	error_code, path_kind, exe, level	Windows CreateProcessAsUserW 失败次数。

当有 Windows 设置失败详细信息时，提权设置失败指标会包含 code 和 message；如果指标从共享设置路径发出，还可能包含 originator。如果 windows_sandbox.legacy_setup_preflight_failed 指标从共享设置路径发出，则会包含 originator，但从回退提示触发的预检失败可能不包含任何字段。

反馈控件

默认情况下，本地客户端允许用户从 /feedback 发送反馈。要在一台设备上同时对 ChatGPT 桌面应用、Codex CLI 和 Codex IDE extension 禁用反馈收集，请更新配置：

[feedback]
enabled = false

禁用后，/feedback 会显示禁用消息，Codex 会拒绝反馈提交。

隐藏或显示推理事件

如果你想减少嘈杂的“推理”输出（例如在 CI 日志中），可以将其隐藏：

hide_agent_reasoning = true

如果你希望在模型生成原始推理内容时将其显示出来：

show_raw_agent_reasoning = true

只有在你的工作流可以接受的情况下，才启用原始推理。某些模型或提供商（例如 gpt-oss）不会生成原始推理；在这种情况下，此设置不会产生可见效果。

通知

使用 notify 可在 Codex 发出受支持的事件时触发外部程序（目前仅支持 agent-turn-complete）。这对于桌面通知、聊天 webhook、CI 更新或内置 TUI 通知无法覆盖的其他旁路提醒非常有用。

notify = ["python3", "/path/to/notify.py"]

下面是一个对 agent-turn-complete 作出响应的 notify.py 示例（已截断）：

#!/usr/bin/env python3
import json, subprocess, sys

def main() -> int:
    notification = json.loads(sys.argv[1])
    if notification.get("type") != "agent-turn-complete":
        return 0
    title = f"Codex: {notification.get('last-assistant-message', 'Turn Complete!')}"
    message = " ".join(notification.get("input-messages", []))
    subprocess.check_output([
        "terminal-notifier",
        "-title", title,
        "-message", message,
        "-group", "codex-" + notification.get("thread-id", ""),
        "-activate", "com.googlecode.iterm2",
    ])
    return 0

if __name__ == "__main__":
    sys.exit(main())

该脚本接收一个 JSON 参数。常见字段包括：

• type（目前为 agent-turn-complete）
• thread-id（会话标识符）
• turn-id（回合标识符）
• cwd（工作目录）
• input-messages（促成该回合的用户消息）
• last-assistant-message（上一条助手消息文本）

将脚本放置在磁盘上的某个位置，然后将 notify 指向该脚本。

notify 与 tui.notifications 的区别

• notify 运行外部程序（适用于 webhook、桌面通知程序和 CI 钩子）。
• tui.notifications 内置于 TUI，可选择按事件类型进行筛选（例如 agent-turn-complete 和 approval-requested）。
• tui.notification_method 控制 TUI 发出终端通知的方式（auto、osc9 或 bel）。
• tui.notification_condition 控制 TUI 通知仅在终端处于 unfocused 状态时触发，还是始终触发（always）。

在 auto 模式下，Codex 优先使用 OSC 9 通知（一种某些终端会解释为桌面通知的终端转义序列）；否则回退到 BEL（\x07）。

有关确切的键，请参阅配置参考。

历史记录持久化

默认情况下，Codex 会将本地会话记录保存到 CODEX_HOME 下（例如 ~/.codex/history.jsonl）。要禁用本地历史记录持久化：

[history]
persistence = "none"

要限制历史记录文件的大小，请设置 history.max_bytes。当文件超过上限时，Codex 会删除最早的条目并压缩文件，同时保留最新记录。

[history]
max_bytes = 104857600 # 100 MiB

可点击的引用

如果你使用支持此功能的终端/编辑器集成，Codex 可以将文件引用呈现为可点击链接。配置 file_opener 以选择 Codex 使用的 URI scheme：

file_opener = "vscode" # 或 cursor、windsurf、vscode-insiders、none

例如，类似 /home/user/project/main.py:42 的引用可以重写为可点击的 vscode://file/...:42 链接。

项目指令发现

Codex 会读取 AGENTS.md（及相关文件），并在会话的第一轮中包含有限的项目指导信息。以下两个配置项控制这一过程：

• project_doc_max_bytes：从每个 AGENTS.md 文件中读取的内容量
• project_doc_fallback_filenames：当某个目录层级缺少 AGENTS.md 时，尝试使用的其他文件名

详细操作说明请参阅使用 AGENTS.md 编写自定义指令。

桌面应用

本节中的选项仅适用于 ChatGPT 桌面应用。

添加自定义文件处理程序

在用户级别的 ~/.codex/config.toml 中，在 desktop.custom_file_handlers 下添加条目，以便在 ChatGPT 桌面应用默认不支持的编辑器或内部启动器中打开文件。每个条目都会向应用的“打开方式”菜单添加一个编辑器目标。当 command 是现有的绝对路径，或可从应用的 PATH 中解析时，应用才会列出该目标。

以下示例展示了向处理程序传递文件的三种方式：

# 将打开的路径直接追加到命令之后。
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# 将固定参数放在打开的路径之前。
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# 追加一个包含路径和编辑器上下文的 JSON 参数。
[desktop.custom_file_handlers.company_editor]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"
input = "json_argument"

保存 config.toml，然后重启 ChatGPT 桌面应用。

处理程序 ID 是 TOML 表头的最后一段。它必须包含 1–64 个字符，以 ASCII 字母或数字开头，其余部分只能包含 ASCII 字母、数字、句点、下划线或连字符。应用会为该 ID 添加 custom: 前缀；例如，company_editor 会变为 custom:company_editor。如果 ID 包含句点，请将其加引号，以免 TOML 将其解释为嵌套表。例如：

[desktop.custom_file_handlers."company.editor"]
label = "Company Editor"
icon = "/opt/company/editor/icon.png"
command = "/opt/company/bin/editor"

每个处理程序支持以下字段：

字段	必填	描述
label	是	应用中的显示名称。
icon	是	内置应用图标，例如 apps/vscode.png、base64 data:image/... URL、file: URI 或本地绝对图像路径。不受支持的来源会使用默认的 VS Code 图标。
command	是	用于检测和启动的可执行文件路径或命令名称。
args	否	插入 command 与文件输入之间的字符串数组。默认为 []。
input	否	应用发送文件输入的方式：path、json_argument 或 json_stdin。默认为 path。
supports_ssh	否	是否为 SSH 工作区中的文件提供此处理程序。默认为 false。当处理程序需要远程主机和路径详细信息时，请使用 json_stdin。

input 值控制 args 后面的内容：

• path 将路径作为最后一个命令参数追加。
• json_argument 追加一个包含 target、path、appPath 和 location 的 JSON 对象。location 值是一个包含从 1 开始计数的 line 和 column 值的对象，或 null。
• json_stdin 将 JSON 对象写入标准输入，而不是添加参数。它还包含 hostConfig、remoteWorkspaceRoot 和 remotePath；当这些字段不适用时，其值为 null。

例如，当用户打开特定源代码位置时，company_editor 可以接收以下参数：

{
  "target": "custom:company_editor",
  "path": "/repo/src/index.ts",
  "appPath": null,
  "location": { "line": 12, "column": 3 }
}

选择自定义处理程序作为首选编辑器后，选择会以与选择内置编辑器相同的方式持久化，包括按项目保存的偏好设置。

TUI 选项

不带子命令运行 codex 会启动交互式终端 UI（TUI）。Codex 在 [tui] 下提供了一些 TUI 专用配置，包括：

• tui.notifications：启用/禁用通知（或限制为特定类型）
• tui.notification_method：为终端通知选择 auto、osc9 或 bel
• tui.notification_condition：选择通知在 unfocused 或 always 状态下触发
• tui.animations：启用/禁用 ASCII 动画和 shimmer 效果
• tui.alternate_screen：控制备用屏幕的使用（设置为 never 可保留终端滚动历史）
• tui.show_tooltips：在欢迎屏幕上显示或隐藏入门工具提示

tui.notification_method 默认为 auto。在 auto 模式下，当终端看起来支持 OSC 9 通知时，Codex 会优先使用 OSC 9 通知（一种某些终端会解释为桌面通知的终端转义序列）；否则回退到 BEL（\x07）。

完整的键列表请参阅配置参考。