本文为非官方中文翻译，内容以 OpenAI 官方英文文档为准。
官方来源：https://developers.openai.com/codex/config-advanced
高级配置
适用于 Codex 本地客户端的更多高级配置选项
当你需要更精细地控制 provider、策略和集成时，请使用这些选项。快速开始请参见 配置基础。
有关项目指导、可复用能力、自定义斜杠命令、subagent 工作流和集成的背景信息，请参见 自定义。有关配置键，请参见 配置参考。
Profiles
Profiles 允许你保存带名称的一组配置值，并从 CLI 在它们之间切换。
Profiles 是实验性的，未来版本中可能会更改或移除。
Codex IDE 扩展当前不支持 Profiles。
请在 config.toml 的 [profiles.] 下定义 profiles，然后运行 codex --profile ：
model = "gpt-5.4"
approval_policy = "on-request"
model_catalog_json = "/Users/me/.codex/model-catalogs/default.json"
[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"
model_catalog_json = "/Users/me/.codex/model-catalogs/deep-review.json"
[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"
要将某个 profile 设为默认值，请在 config.toml 顶层添加 profile = "deep-review"。除非你在命令行中覆盖它，否则 Codex 会加载该 profile。
Profiles 也可以覆盖 model_catalog_json。当顶层和所选 profile 都设置了 model_catalog_json 时，Codex 会优先使用 profile 的值。
来自 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（如果你使用基于文件的凭据存储）或你的操作系统 keychain/keyringhistory.jsonl（如果启用了历史记录持久化）- 其他按用户区分的状态，例如日志和缓存
有关身份验证的详细信息（包括凭据存储模式），请参见 身份验证。有关完整的配置键列表，请参见 配置参考。
有关签入到仓库或系统路径中的共享默认值、规则和 Skills，请参见 Team Config。
如果你只是需要让内置的 OpenAI provider 指向某个 LLM 代理、路由器或启用了数据驻留的项目，请在 config.toml 中设置 openai_base_url，而不是定义新的 provider。这样会更改内置 openai provider 的基础 URL，而无需单独的 model_providers. 条目。
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、项目本地 hooks 和项目本地规则。用户层和系统层保持独立，并且仍会加载。
项目配置中的相对路径（例如 model_instructions_file）会相对于包含该 config.toml 的 .codex/ 文件夹解析。
项目配置文件不能覆盖那些会重定向凭据、更改
provider 身份验证或运行机器本地通知/遥测命令的设置。
Codex 会忽略项目本地 .codex/config.toml 中的以下键，并且
在看到它们时打印启动警告：openai_base_url，
chatgpt_base_url、model_provider、model_providers、notify、profile、
profiles、experimental_realtime_ws_base_url 和 otel。请改为在
你的用户级 ~/.codex/config.toml 中设置这些键。
Hooks
Codex 还可以从 hooks.json 文件或与活动配置层相邻的 config.toml 文件中的内联
[hooks] 表加载生命周期 hooks。
在实际使用中，四个最有用的位置是：
~/.codex/hooks.json~/.codex/config.toml/.codex/hooks.json/.codex/config.toml
项目本地 hooks 仅在项目 .codex/ 层受信任时才会加载。
用户级 hooks 不受项目信任状态影响。
内联 TOML hooks 使用与 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 会同时加载
两者并给出警告。每个层请优先只使用一种表示方式。
有关当前事件列表、输入字段、输出行为和限制，请参见 Hooks。
Agent 角色（config.toml 中的 [agents]）
有关 subagent 角色配置（config.toml 中的 [agents]），请参见 Subagents。
项目根目录检测
Codex 会通过从工作目录向上遍历直到到达项目根目录，来发现项目配置（例如 .codex/ 层和 AGENTS.md）。
默认情况下，Codex 将包含 .git 的目录视为项目根目录。要自定义此行为，请在 config.toml 中设置 project_root_markers：
# 当目录包含以下任意标记时，将其视为项目根目录。
project_root_markers = [".git", ".hg", ".sl"]
将 project_root_markers = [] 设为空数组可跳过搜索父目录，并将当前工作目录视为项目根目录。
自定义 model provider
model provider 定义了 Codex 如何连接到模型（基础 URL、wire API、身份验证以及可选的 HTTP 标头）。自定义 provider 不能复用保留的内置 provider ID：openai、ollama 和 lmstudio。
定义额外的 providers，并让 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" }
当 provider 需要 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，并且必须将 token 打印到 stdout。Codex 会去除两端空白，将空 token 视为错误，并按 refresh_interval_ms 主动刷新；将 refresh_interval_ms = 0 设为仅在身份验证重试后刷新。不要将 [model_providers..auth] 与 env_key、experimental_bearer_token 或 requires_openai_auth 组合使用。
Amazon Bedrock provider
Codex 包含一个内置的 amazon-bedrock model provider。请直接将它设置为
model_provider；与自定义 provider 不同，这个内置 provider 仅支持
嵌套的 AWS profile 和 region 覆盖。
model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"
[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"
如果你省略 profile，Codex 会使用标准 AWS 凭据链。请将
region 设置为应处理请求的受支持 Bedrock 区域。
OSS 模式（本地 provider）
当你传入 --oss 时，Codex 可以针对本地“开源”provider 运行（例如 Ollama 或 LM Studio）。如果你传入 --oss 但未指定 provider，Codex 会默认使用 oss_provider。
# 与 `--oss` 一起使用的默认本地 provider
oss_provider = "ollama" # 或 "lmstudio"
Azure provider 和按 provider 调优
[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 provider 的 base URL，请使用 openai_base_url；不要创建 [model_providers.openai]，因为你不能覆盖内置 provider ID。
使用数据驻留的 ChatGPT 客户
启用了 data residency 创建的项目，可以创建一个 model provider，通过使用正确的前缀来更新 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 的 provider。Chat Completions provider 会忽略此设置。
审批策略和沙箱模式
选择审批严格程度（影响 Codex 何时暂停）和沙箱级别（影响文件/网络访问）。
关于编辑 config.toml 时需要注意的操作细节，请参见 常见沙箱与审批组合、可写根中的受保护路径 和 网络访问。
关于同时配置文件系统和网络访问的 beta 权限配置文件，请参见 Permissions。
你还可以使用细粒度审批策略（approval_policy = { granular = { ... } }）来允许或自动拒绝单个提示类别。当你希望某些情况使用正常的交互式审批，但希望其他情况（例如 request_permissions 或 skill-script 提示）自动以失败关闭时，这会很有用。
将 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 工具使用 login 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 = """
使用你组织的自动审核策略。
"""
命名权限配置文件
关于内置配置文件、自定义配置文件语法以及完整的文件系统和网络配置模型，请参见 Permissions。
关于完整的键列表，包括作用域于配置文件的覆盖项和 requirements 约束，请参见 Configuration Reference 和 Managed configuration。
在 workspace-write 模式下，一些环境会让 .git/ 和 .codex/
保持只读，即使工作区其余部分是可写的也是如此。这就是为什么
像 git commit 这样的命令在沙箱外运行时仍然可能需要审批。如果你希望 Codex 跳过特定命令（例如，阻止在沙箱外执行 git commit），请使用
rules。
完全禁用沙箱（仅当你的环境已经隔离进程时才使用）：
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 会在你的 includes/excludes 生效之前保留自动的 KEY/SECRET/TOKEN 过滤器。
MCP 服务器
配置细节请参见专门的 MCP 文档。
可观测性和遥测
启用 OpenTelemetry (OTel) 日志导出以跟踪 Codex 运行（API 请求、SSE/events、prompts、工具审批/结果）。默认禁用；通过 [otel] 选择启用：
[otel]
environment = "staging" # 默认为 "dev"
exporter = "none" # 设置为 otlp-http 或 otlp-grpc 以发送事件
log_user_prompt = false # 默认对用户 prompts 打码，除非显式启用
选择一个 exporter：
[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 会记录事件但不发送任何内容。exporter 会异步批处理，并在关闭时刷新。事件元数据包括服务名、CLI 版本、env 标签、conversation id、模型、sandbox/approval 设置以及每个事件的字段（参见 Config Reference）。
会发出什么
Codex 会为运行和工具使用发出结构化日志事件。代表性的事件类型包括：
codex.conversation_starts（模型、推理设置、sandbox/approval 策略）codex.api_request（尝试次数、状态/成功、时长和错误详情）codex.sse_event（流事件种类、成功/失败、时长，以及response.completed上的 token 计数）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。
| Metric | Type | Fields | Description |
|---|---|---|---|
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 | 按工具名称和结果划分的工具执行时长（毫秒）。 |
有关 telemetry 的更多安全与隐私指导，请参阅安全。
指标
默认情况下，Codex 会定期向 OpenAI 发送少量匿名使用情况和健康数据。这有助于检测 Codex 何时未正常工作，并显示正在使用哪些功能和配置选项，以便 Codex 团队专注于最重要的事项。这些指标不包含任何个人身份信息（PII）。指标收集独立于 OTel 日志/追踪导出。
如果你想在一台机器上的所有 Codex 表面中完全禁用指标收集，请在配置中设置 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 | 启动预热在第一次真实 turn 解决时的存在时长。 |
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 与工具活动
| 指标 | 类型 | 字段 | 描述 |
|---|---|---|---|
turn.e2e_duration_ms | histogram | 完整 turn 的端到端耗时。 | |
turn.ttft.duration_ms | histogram | 一个 turn 的首个 token 时间。 | |
turn.ttfm.duration_ms | histogram | 一个 turn 的首个模型输出项时间。 | |
turn.network_proxy | counter | active, tmp_mem_enabled | 该 turn 是否启用了受管理的网络代理。 |
turn.memory | counter | read_allowed, feature_enabled, config_use_memories, has_citations | 每个 turn 的内存读取可用性和内存引用使用情况。 |
turn.tool.call | histogram | tmp_mem_enabled | 该 turn 中的工具调用数量。 |
turn.token_usage | histogram | token_type, tmp_mem_enabled | 每个 turn 按 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 模式统计的统一 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 | 按 hook 名称、来源和状态统计的 hook 运行次数。 |
hooks.run.duration_ms | histogram | hook_name, source, status | hook 运行耗时（毫秒）。 |
mcp.call 和 mcp.call.duration_ms 指标包含 status；常规工具调用发射还包含 tool，以及在可用时包含 connector_id 和 connector_name。被阻止的 Codex Apps MCP 调用可能会发射仅包含 status 的 mcp.call。
线程、任务和功能
| Metric | Type | Fields | Description |
|---|---|---|---|
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 | 为新线程启用的 skills 数量。 | |
thread.skills.kept_total | histogram | 在提示渲染后保留下来的已启用 skills 数量。 | |
thread.skills.truncated | histogram | skill 渲染是否截断了已启用 skills 列表（1 或 0）。 | |
task.compact | counter | type | 每种类型（remote 或 local）的压缩次数，包括手动和自动。 |
task.review | counter | 触发的 review 次数。 | |
task.undo | counter | 触发的撤销操作次数。 | |
task.user_shell | counter | 用户 shell 操作次数（例如 TUI 中的 !）。 | |
shell_snapshot | counter | See note | 获取 shell 快照是否成功。 |
shell_snapshot.duration_ms | histogram | success | 获取 shell 快照所需时间。 |
skill.injected | counter | status, skill | 按 skill 统计的 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。
内存和本地状态
| Metric | Type | Fields | Description |
|---|---|---|---|
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 | 按 kind、tool 和成功/失败统计的内存使用情况。 |
external_agent_config.detect | counter | See note | 按迁移项类型统计的外部 agent 配置检测。 |
external_agent_config.import | counter | See note | 按迁移项类型统计的外部 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 迁移还包含 skills_count。
Windows 沙箱
| Metric | Type | Fields | Description |
|---|---|---|---|
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 | See note | 提权 Windows 沙箱设置失败次数。 |
windows_sandbox.elevated_setup_canceled | counter | See note | 已取消的提权 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 | See note | 旧版 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，但 fallback-prompt 预检失败可能不包含任何字段。
反馈控制
默认情况下，Codex 允许用户通过 /feedback 发送反馈。要在一台机器上禁用 Codex 各界面的反馈收集，请更新你的配置：
[feedback]
enabled = false
禁用后，/feedback 会显示一条已禁用消息，并且 Codex 会拒绝提交反馈。
隐藏或显示 reasoning 事件
如果你想减少嘈杂的 “reasoning” 输出（例如在 CI 日志中），你可以抑制它：
hide_agent_reasoning = true
如果你想在模型发出原始 reasoning 内容时将其显示出来：
show_raw_agent_reasoning = true
仅在你的工作流可以接受的情况下启用原始 reasoning。某些模型/提供方（例如 gpt-oss）不会发出原始 reasoning；在这种情况下，此设置不会产生可见效果。
通知
使用 notify 可以在 Codex 发出受支持事件时触发一个外部程序（当前仅支持 agent-turn-complete）。这对于桌面通知、聊天 webhook、CI 更新，或任何内置 TUI 通知未覆盖的侧边通道告警都很方便。
notify = ["python3", "/path/to/notify.py"]
响应 agent-turn-complete 的 notify.py 示例（节选）：
#!/usr/bin/env python3
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（最后一条 assistant 消息文本）
将脚本放在磁盘上的某个位置，并将 notify 指向它。
notify 与 tui.notifications
notify会运行一个外部程序（适合用于 webhook、桌面通知器、CI hooks）。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" # 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 的自定义说明。
TUI 选项
运行不带子命令的 codex 会启动交互式终端 UI（TUI）。Codex 在 [tui] 下暴露了一些 TUI 专用配置，包括：
tui.notifications：启用/禁用通知（或限制为特定类型）tui.notification_method：为终端通知选择auto、osc9或beltui.notification_condition：选择在何时 触发通知：unfocused或alwaystui.animations：启用/禁用 ASCII 动画和 shimmer 效果tui.alternate_screen：控制备用屏幕的使用（设为never以保留终端滚动缓冲区）tui.show_tooltips：在欢迎界面显示或隐藏引导 tooltip
tui.notification_method 默认为 auto。在 auto 模式下，当终端看起来支持时，Codex 会优先使用 OSC 9 通知（一种某些终端会解释为桌面通知的终端转义序列），否则回退到 BEL（\x07）。
完整键列表请参见配置参考。