高级配置

身份 非官方简体中文镜像

翻译状态 AI 翻译

来源版本 官方未提供

同步日期 2026-07-31

官方原文 learn.chatgpt.com

如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加 .md 来获取 URL。

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

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

配置文件配置

配置文件让你保存命名的配置层，并从 该 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 不再从 [profiles.profile-name] 读取 config.toml，并且顶层 profile = "profile-name" 选择器也不再 受支持。将旧版配置文件设置移到 ~/.codex/profile-name.config.toml，然后从 [profiles.profile-name] 中移除匹配的 profile = "profile-name" 表和 config.toml选择器。

来自 CLI 的单次覆盖

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

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

示例：

# Dedicated flag
codex --model gpt-5.6-terra

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.6-terra"'
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 （如果你使用基于文件的凭据存储）或你的 OS keychain/keyring
• history.jsonl （如果启用了历史记录持久化）
• 其他按用户保存的状态，例如日志和缓存

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

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

如果你只是需要将内置的 OpenAI 提供商指向一个 LLM 代理、路由器或启用了数据驻留的项目，请在 openai_base_url 中设置 config.toml ，而不是定义新的提供商。这会更改内置 URL 提供商的基础 openai ，而无需单独的 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）会相对于 .codex/ 所在的 config.toml文件夹解析。

项目配置文件不能覆盖会重定向凭据、修改 主机拥有的应用请求元数据、更改提供商身份验证、选择配置文件 或运行机器本地 notification/telemetry 命令的设置。 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 文件或 [hooks] 文件中与活动配置层相邻的内联 config.toml 表加载生命周期钩子。

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

• ~/.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 会同时加载 并发出警告。每个层最好只使用一种表示方式。

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

Agent 角色（[agents] 位于 config.toml中）

有关子 Agent 角色配置（[agents] 位于 config.toml中），请参阅 子 Agent。

项目根目录检测

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

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

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

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

自定义模型提供商

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

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

model = "gpt-5.6-terra"
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 模式（本地提供商）

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

# Default local provider used with `--oss`
oss_provider = "ollama" # or "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

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

ChatGPT 使用数据驻留的客户

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

model_provider = "openaidr"
[model_providers.openaidr]
name = "OpenAI Data Residency"
base_url = "https://us.api.openai.com/v1" # Replace 'us' with domain prefix

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

model_reasoning_summary = "none"          # Disable summaries
model_verbosity = "low"                   # Shorten responses
model_supports_reasoning_summaries = true # Force reasoning
model_context_window = 128000             # Context window size

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

审批策略和沙箱模式

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

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

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

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

设置 approvals_reviewer = "auto_review" 以通过自动审查路由符合条件的交互式审批 请求。这会更改审查者，而不是沙箱 边界。

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

approval_policy = "untrusted"   # Other options: on-request, never, or { granular = { ... } }
approvals_reviewer = "user"     # Or "auto_review" for automatic review
sandbox_mode = "workspace-write"
allow_login_shell = false       # Optional hardening: disallow login shells for shell tools

# Example granular approval policy:
# 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  # Allow $TMPDIR
exclude_slash_tmp = false       # Allow /tmp
writable_roots = ["/Users/YOU/.pyenv/shims"]
network_access = false          # Opt in to outbound network

[auto_review]
policy = """
Use your organization's automatic 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 运行前保留自动 includes/excludes 过滤器。

MCP 服务器

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

可观测性和遥测

启用 OpenTelemetry （OTel）日志导出以跟踪 Codex 运行（API 请求、 SSE/events、提示词、工具 approvals/results）。默认禁用；通过 [otel]选择启用：

[otel]
environment = "staging"   # defaults to "dev"
exporter = "none"         # set to otlp-http or otlp-grpc to send events
log_user_prompt = false   # redact user prompts unless explicitly enabled

选择导出器：

[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、模型、 sandbox/approval 设置，以及每个事件字段（参见 配置参考）。

导出的内容

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

• codex.conversation_starts （模型、推理设置、 sandbox/approval 策略）
• codex.api_request （尝试次数、 status/success、持续时间和错误详细信息）
• codex.sse_event （流事件类型、 success/failure、持续时间，以及 response.completed上的 token 计数）
• codex.websocket_request 和 codex.websocket_event （请求持续时间以及每条消息的 kind/success/error）
• codex.user_prompt （长度；除非明确启用，否则内容会被遮盖）
• codex.tool_decision （approved/denied 以及决策是否来自配置而非用户）
• codex.tool_result （持续时间、成功状态、输出片段）

OTel 发出的指标

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

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

指标	类型	字段	说明
codex.api_request	计数器	status、 success	API 按 HTTP 状态和 success/failure统计的请求计数。
codex.api_request.duration_ms	直方图	status、 success	API 请求持续时间（毫秒）。
codex.sse_event	计数器	kind、 success	SSE 按事件类型和 success/failure统计的事件计数。
codex.sse_event.duration_ms	直方图	kind、 success	SSE 事件处理持续时间（毫秒）。
codex.websocket.request	计数器	success	WebSocket 按 success/failure统计的请求计数。
codex.websocket.request.duration_ms	直方图	success	WebSocket 请求持续时间（毫秒）。
codex.websocket.event	计数器	kind、 success	WebSocket message/event 按类型和 success/failure统计的计数。
codex.websocket.event.duration_ms	直方图	kind、 success	WebSocket message/event 处理持续时间（毫秒）。
codex.tool.call	计数器	tool、 success	按工具名称和 success/failure统计的工具调用计数。
codex.tool.call.duration_ms	直方图	tool、 success	按工具名称和结果统计的工具执行持续时间（毫秒）。

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

指标

默认情况下， Codex 会定期向 OpenAI发送少量匿名使用情况和健康数据。这有助于检测 Codex 何时无法正常工作，并显示正在使用哪些功能和配置选项，以便 Codex 团队能够专注于最重要的事项。这些指标不包含任何个人身份信息（PII）。指标收集独立于 OTel log/trace 导出。

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

[analytics]
enabled = false

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

默认上下文字段（适用于每个 event/metric）

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

指标目录

每个指标都包含必需字段以及上面的默认上下文字段。下面的指标名称省略了 codex. 前缀。 大多数指标名称集中在 codex-rs/otel/src/metrics/names.rs中；在该文件之外发出的功能特定指标也包含在这里。 如果指标包含 tool 字段，它反映的是所使用的内部工具（例如 apply_patch 或 shell），并不包含实际 shell 命令或 codex 正在尝试应用的补丁。

运行时和模型传输

指标	类型	字段	说明
api_request	计数器	status、 success	API 按 HTTP 状态和 success/failure统计的请求计数。
api_request.duration_ms	直方图	status、 success	API 请求持续时间（毫秒）。
sse_event	计数器	kind、 success	SSE 按事件类型和 success/failure统计的事件计数。
sse_event.duration_ms	直方图	kind、 success	SSE 事件处理持续时间（毫秒）。
websocket.request	计数器	success	WebSocket 按 success/failure统计的请求计数。
websocket.request.duration_ms	直方图	success	WebSocket 请求持续时间（毫秒）。
websocket.event	计数器	kind、 success	WebSocket message/event 按类型和 success/failure统计的计数。
websocket.event.duration_ms	直方图	kind、 success	WebSocket message/event 处理持续时间（毫秒）。
responses_api_overhead.duration_ms	直方图		Responses API 来自 WebSocket 响应的开销计时。
responses_api_inference_time.duration_ms	直方图		Responses API 来自 WebSocket 响应的推理计时。
responses_api_engine_iapi_ttft.duration_ms	直方图		Responses API 引擎 IAPI 首个 token 时间计时。
responses_api_engine_service_ttft.duration_ms	直方图		Responses API 引擎服务首个 token 时间计时。
responses_api_engine_iapi_tbt.duration_ms	直方图		Responses API 引擎 IAPI token 间隔时间计时。
responses_api_engine_service_tbt.duration_ms	直方图		Responses API 引擎服务 token 间隔时间计时。
transport.fallback_to_http	计数器	from_wire_api	WebSocket到HTTP 的回退计数。
remote_models.fetch_update.duration_ms	直方图		获取远程模型定义的时间。
remote_models.load_cache.duration_ms	直方图		加载远程模型缓存的时间。
startup_prewarm.duration_ms	直方图	status	按结果统计的启动预热持续时间。
startup_prewarm.age_at_first_turn_ms	直方图	status	首次真实轮次解析启动预热时的预热时长。
cloud_requirements.fetch.duration_ms	直方图		获取工作区托管云要求的持续时间。
cloud_requirements.fetch_attempt	计数器	见注释	获取工作区托管云要求的尝试次数。
cloud_requirements.fetch_final	计数器	见注释	获取工作区托管云要求的最终结果。
cloud_requirements.load	计数器	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	直方图		完整轮次的端到端时间。
turn.ttft.duration_ms	直方图		某一轮次到首个令牌的时间。
turn.ttfm.duration_ms	直方图		某一轮次到首个模型输出项的时间。
turn.network_proxy	计数器	active, tmp_mem_enabled	托管网络代理在该轮次中是否处于活动状态。
turn.memory	计数器	read_allowed, feature_enabled, config_use_memories, has_citations	每轮次的内存读取可用性和内存引用使用情况。
turn.tool.call	直方图	tmp_mem_enabled	该轮次中的工具调用次数。
turn.token_usage	直方图	token_type, tmp_mem_enabled	按令牌类型统计的每轮次令牌用量（total, input, cached_input, output，或 reasoning_output）。
tool.call	计数器	tool, success	按工具名称和 success/failure统计的工具调用次数。
tool.call.duration_ms	直方图	tool, success	按工具名称和结果统计的工具执行时长（毫秒）。
tool.unified_exec	计数器	tty	统一 exec 工具调用，按 TTY 模式统计。
approval.requested	计数器	tool, approved	工具审批请求结果（approved, approved_with_amendment, approved_for_session, denied, abort）。
mcp.call	计数器	见注释	MCP 工具调用结果。
mcp.call.duration_ms	直方图	见注释	MCP 工具调用时长。
mcp.tools.list.duration_ms	直方图	cache	MCP 工具列表时长，包括缓存 hit/miss 状态。
mcp.tools.fetch_uncached.duration_ms	直方图		耗时： MCP 未命中缓存的工具获取。
mcp.tools.cache_write.duration_ms	直方图		耗时： Codex Apps MCP 工具缓存写入。
hooks.run	计数器	hook_name, source, status	按 hook 名称、来源和状态统计的 hook 运行次数。
hooks.run.duration_ms	直方图	hook_name, source, status	Hook 运行时长（毫秒）。

这些 mcp.call 和 mcp.call.duration_ms 指标包含 status；普通工具调用的发射还包含 tool，以及在可用时包含 connector_id 和 connector_name 。被阻止的 Codex Apps MCP 调用可能只带 mcp.call 发射 status。

线程、任务与功能

指标	类型	字段	描述
feature.state	counter	feature, value	不同于默认值的功能值（每个非默认值发射一行）。
status_line	counter		会话以已配置的状态行启动。
model_warning	counter		发送给模型的警告。
thread.started	counter	is_git	创建新线程，并标记工作目录是否位于 Git 仓库中。
conversation.turn.count	counter		User/assistant 每个线程的轮次数，在线程结束时记录。
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	按类别、工具和 success/failure统计的内存使用情况。
external_agent_config.detect	counter	见注释	按迁移项类型统计的外部 Agent 配置检测。
external_agent_config.import	counter	见注释	按迁移项类型统计的外部 Agent 配置导入。
db.backfill	counter	status	初始状态 DB 回填结果（upserted, failed）。
db.backfill.duration_ms	histogram	status	初始状态 DB 回填的耗时。
db.error	counter	stage	状态 DB 操作期间的错误。

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 和 IDE extension 禁用反馈收集，请更新配置：

[feedback]
enabled = false

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

隐藏或显示推理事件

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

hide_agent_reasoning = true

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

show_raw_agent_reasoning = true

仅在你的工作流可接受时启用原始推理。某些 models/providers （例如 gpt-oss）不会发射原始推理；这种情况下，此设置没有可见效果。

通知

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

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

响应 notify.py 的示例 agent-turn-complete（已截断）：

#!/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

可点击的引用

如果你使用支持它的 terminal/editor 集成， Codex 可以将文件引用渲染为可点击链接。配置 file_opener 以选择 URI 使用的 Codex 方案：

file_opener = "vscode" # or 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解析时，应用会列出该目标。

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

# Append the opened path directly after the command.
[desktop.custom_file_handlers.vscodium]
label = "VSCodium"
icon = "/Users/you/.codex/icons/vscodium.png"
command = "codium"

# Place fixed arguments before the opened path.
[desktop.custom_file_handlers.textedit]
label = "TextEdit"
icon = "/Users/you/.codex/icons/textedit.png"
command = "/usr/bin/open"
args = ["-a", "TextEdit"]

# Append one JSON argument with the path and editor context.
[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 追加一个 JSON 对象，其中包含 target， path， appPath，以及 location。 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： enable/disable 通知（或限制为特定类型）
• tui.notification_method：选择 auto， osc9，或 bel 用于终端通知
• tui.notification_condition：选择 unfocused 或 always 以控制 通知触发的时机
• tui.animations： enable/disable ASCII 动画和微光效果
• tui.alternate_screen：控制备用屏幕的使用（设为 never 以保留终端回滚）
• tui.show_tooltips：在欢迎屏幕上显示或隐藏入门提示

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

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