高级配置

当您需要更精细地控制提供商、策略和集成时，请使用这些选项。如需快速上手，请参阅基础配置。

如需了解项目指导、可复用能力、自定义斜杠命令、子智能体工作流和集成的相关背景，请参阅自定义。有关配置键，请参阅配置参考资料。

配置方案

配置方案可让您保存带名称的配置层，并通过 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.6-sol"
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。

示例：

# 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（如果您使用基于文件的凭据存储）或操作系统的钥匙串/密钥环
• 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：

# 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 标头）。自定义提供商不能使用保留的内置提供商 ID：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.proxy]
name = "OpenAI using LLM proxy"
base_url = "https://proxy.example.com/v1"
env_key = "OPENAI_API_KEY"
supports_standalone_web_search = true

对于自定义提供商，此设置默认为 false。独立网页搜索仍在 开发中，默认关闭。将提供商能力设置为 true 并不会启用它：提供商必须支持兼容的端点， 且所选模型和运行时必须支持独立搜索。 已配置的 web_search 模式和 受管理的搜索限制仍然适用。

根据需要添加请求标头：

[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 输入，并且必须将 Token 输出到 stdout。Codex 会去除首尾空白，将空 Token 视为错误，并按 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 区域。

有关完整的设置流程、身份验证选项、支持的模型及功能可用性， 请参阅通过 Amazon Bedrock 使用 ChatGPT Work 和 Codex。

OSS 模式（本地提供商）

传入 --oss 时，Codex 可以连接 Ollama 或 LM Studio 等 本地“开源”提供商运行。您可以使用 --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

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

使用数据驻留的 API 组织

对于创建时启用了数据驻留的项目，可以创建模型提供商，以使用正确的前缀更新 base_url。对于启用了数据驻留的 ChatGPT 工作空间，无需自定义提供商；当您使用 ChatGPT 登录时，Codex 会遵循工作空间的数据驻留设置。

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 何时暂停）和沙盒级别（影响文件和网络访问）。

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

Codex 和 ChatGPT Work 已不再支持 approval_policy = "untrusted"。请参阅 从已停用的 untrusted 审批策略迁移， 了解受支持的设置以及针对源自项目的操作的更严格审批。

有关可同时配置文件系统和网络访问的测试版权限配置方案，请参阅权限。

您还可以使用细粒度审批策略（approval_policy = { granular = { ... } }），允许或自动拒绝特定类别的审批提示。如果您希望在某些情况下使用常规交互式审批，而在其他情况下（例如 request_permissions 或技能脚本审批提示）自动拒绝并阻止操作，这种策略会很有用。

设置 approvals_reviewer = "auto_review"，将符合条件的交互式审批请求 交由自动审查处理。这会更改审查方， 但不会改变沙盒边界。

使用 [auto_review].policy 设置本地审查方的策略指令。 托管的 guardian_policy_config 优先级更高。

approval_policy = "on-request"  # Other options: 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.
"""

命名权限配置方案

有关内置配置方案、自定义配置方案语法，以及完整的文件系统和 网络配置模型，请参阅权限。

有关完整的配置键列表和要求约束，请参阅 配置参考和 托管配置。

完全禁用沙盒（仅当您的环境已提供进程隔离时使用）：

sandbox_mode = "danger-full-access"

Shell 环境策略

shell_environment_policy 控制 Codex 将哪些环境变量传递给 启动的命令。使用 inherit = "none" 从空环境开始，或 使用 inherit = "core" 继承一组精简的环境变量。添加明确指定的值和按键配置的 过滤规则，避免向启动的命令传递不必要的机密信息。

[shell_environment_policy]
inherit = "core"
set = { MY_FLAG = "1" }
ignore_default_excludes = false

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

过滤模式不区分大小写，并支持 * 和 ?。使用 "exclude" 移除匹配的变量。当任一模式使用 "include" 时，Codex 仅保留与包含模式匹配的变量。包含规则不会恢复 已被排除的变量。不同配置层中的过滤键会以不区分大小写的方式 合并。

ignore_default_excludes 默认为 true，因此 Codex 不会自动 移除名称中包含 KEY、SECRET 或 TOKEN 的变量。将其设为 false， 即可在您明确指定的过滤规则运行之前应用这些自动排除规则。

Codex 首先应用自动排除规则，然后应用自定义排除规则、 set 中的值，最后应用包含模式允许列表。由于 set 在排除规则之后 运行，因此可以恢复已被排除的变量。包含模式允许列表 仍可移除恢复后的值。

现有配置仍支持旧版的 exclude 和 include_only 数组。 请勿在同一配置层中将这两个数组中的任意一个与 [shell_environment_policy.filters] 一起使用；Codex 会拒绝这种组合。

MCP 服务器

有关配置详情，请参阅专门的 MCP 文档。

可观测性和遥测

启用 OpenTelemetry（OTel）日志导出，以跟踪 Codex 运行情况（API 请求、SSE/事件、提示、工具审批及结果）。此功能默认禁用，可通过 [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、模型、沙盒与审批设置，以及各事件专属的字段（请参阅配置参考）。

输出的内容

Codex 会针对运行和工具使用情况输出结构化日志事件。典型事件类型包括：

• codex.conversation_starts（模型、推理设置、沙盒与审批策略）
• 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。

有关遥测的更多安全和隐私指导，请参阅安全。

指标

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

如果您想在某台计算机上的 ChatGPT 桌面应用、Codex CLI 和 IDE 扩展中全面禁用指标收集，请在配置中设置分析开关：

[analytics]
enabled = false

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

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

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

指标目录

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

运行时和模型传输

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

轮次与工具活动

mcp.call 和 mcp.call.duration_ms 指标包含 status；正常工具调用上报的数据还包含 tool，以及可用时的 connector_id 和 connector_name。被阻止的 Codex 应用 MCP 调用可能会上报仅包含 status 的 mcp.call。

对话线程、任务和功能

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

记忆和本地状态

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

Windows 沙盒

如果有 Windows 设置失败的详细信息，提权设置失败指标会包含 code 和 message；如果由共享设置流程发出，还可能包含 originator。由共享设置流程发出的 windows_sandbox.legacy_setup_preflight_failed 指标会包含 originator，但备用沙盒提示中的预检失败可能不包含任何字段。

反馈控制

默认情况下，本地客户端允许用户通过 /feedback 发送反馈。要在一台计算机上的 ChatGPT 桌面应用、Codex CLI 和 IDE 扩展中禁用反馈收集，请更新您的配置：

[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 方案：

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"

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

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 动画和微光效果
• tui.alternate_screen：控制备用屏幕的使用（设为 never 可保留终端回滚历史）
• tui.show_tooltips：显示或隐藏欢迎屏幕上的入门提示

tui.notification_method 默认为 auto。在 auto 模式下，如果终端看起来支持 OSC 9 通知，Codex 会优先使用该通知方式（这是一种终端转义序列，部分终端会将其解释为桌面通知）；否则会回退到 BEL（\x07）。

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