配置

Codex 支持几种设置配置值的机制：

• 特定于配置的命令行标志，如 --model o3（优先级最高）。
• 通用的 -c/--config 标志，接受 key=value 对，如 --config model="o3"。
• 键可以包含点，以设置比根更深的值，例如 --config model_providers.openai.wire_api="chat"。
• 为了与 config.toml 保持一致，值是 TOML 格式的字符串而不是 JSON 格式，因此使用 key='{a = 1, b = 2}' 而不是 key='{"a": 1, "b": 2}'。
  • 值周围的引号是必要的，因为如果没有它们，你的 shell 会在空格上拆分配置参数，导致 codex 接收 -c key={a 和（无效的）额外参数 =、1,、b、=、2}。
• 值可以包含任何 TOML 对象，如 --config shell_environment_policy.include_only='["PATH", "HOME", "USER"]'。
• 如果 value 无法解析为有效的 TOML 值，它将被视为字符串值。这意味着 -c model='"o3"' 和 -c model=o3 是等效的。
  • 在第一种情况下，值是 TOML 字符串 "o3"，而在第二种情况下，值是 o3，它不是有效的 TOML，因此被视为 TOML 字符串 "o3"。
  • 因为引号被 shell 解释，-c key="true" 将在 TOML 中正确解释为 key = true（布尔值）而不是 key = "true"（字符串）。如果出于某种原因你需要字符串 "true"，你需要使用 -c key='"true"'（注意两组引号）。
• $CODEX_HOME/config.toml 配置文件，其中 CODEX_HOME 环境值默认为 ~/.codex。（注意 CODEX_HOME 也是存储日志和其他 Codex 相关信息的地方。）

--config 标志和 config.toml 文件都支持以下选项：

model

Codex 应该使用的模型。

model = "o3"  # 覆盖默认的 "gpt-5-codex"

model_providers

此选项允许你覆盖和补充 Codex 捆绑的默认模型提供商集。此值是一个映射，其中键是与 model_provider 一起使用以选择相应提供商的值。

例如，如果你想添加一个通过聊天补全 API 使用 OpenAI 4o 模型的提供商，那么你可以添加以下配置：

# 回想在 TOML 中，根键必须在表之前列出。
model = "gpt-4o"
model_provider = "openai-chat-completions"

[model_providers.openai-chat-completions]
# 将在 Codex UI 中显示的提供商名称。
name = "使用聊天补全的 OpenAI"
# 路径 `/chat/completions` 将被附加到此 URL 以发出聊天补全的 POST 请求。
base_url = "https://api.openai.com/v1"
# 如果设置了 `env_key`，标识在使用此提供商的 Codex 时必须设置的环境变量。
# 环境变量的值必须非空，并将用于 POST 请求的 `Bearer TOKEN` HTTP 头。
env_key = "OPENAI_API_KEY"
# wire_api 的有效值是 "chat" 和 "responses"。如果省略，默认为 "chat"。
wire_api = "chat"
# 如有必要，需要添加到 URL 的额外查询参数。
# 请参阅下面的 Azure 示例。
query_params = {}

注意这使得可以将 Codex CLI 与非 OpenAI 模型一起使用，只要它们使用与 OpenAI 聊天补全 API 兼容的线协议 API。例如，你可以定义以下提供商来使用 Codex CLI 与本地运行的 Ollama：

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

或者第三方提供商（使用不同的环境变量来存储 API 密钥）：

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

还可以配置提供商以在请求中包含额外的 HTTP 头。这些可以是硬编码的值（http_headers）或从环境变量读取的值（env_http_headers）：

[model_providers.example]
# name, base_url, ...

# 这将添加 HTTP 头 `X-Example-Header`，值为 `example-value`
# 到对模型提供商的每个请求。
http_headers = { "X-Example-Header" = "example-value" }

# 这将添加 HTTP 头 `X-Example-Features`，值为
# `EXAMPLE_FEATURES` 环境变量的值，到对模型提供商的每个请求
# _如果_ 设置了环境变量且其值非空。
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

Azure 模型提供商示例

注意 Azure 要求将 api-version 作为查询参数传递，因此在定义 Azure 提供商时，请确保将其指定为 query_params 的一部分：

[model_providers.azure]
name = "Azure"
# 确保为此 URL 设置适当的子域。
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"  # 或 "OPENAI_API_KEY"，无论你使用哪个。
query_params = { api-version = "2025-04-01-preview" }
wire_api = "responses"

在启动 Codex 之前导出你的密钥：export AZURE_OPENAI_API_KEY=…

每个提供商的网络调优

以下可选设置控制重试行为和流式空闲超时，按模型提供商。它们必须在 config.toml 中相应的 [model_providers.<id>] 块内指定。（旧版本接受顶级键；这些现在被忽略。）

示例：

[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
# 网络调优覆盖（都是可选的；回退到内置默认值）
request_max_retries = 4            # 重试失败的 HTTP 请求
stream_max_retries = 10            # 重试丢失的 SSE 流
stream_idle_timeout_ms = 300000    # 5分钟空闲超时

request_max_retries

Codex 将重试对模型提供商的失败 HTTP 请求的次数。默认为 4。

stream_max_retries

当流式响应中断时，Codex 将尝试重新连接的次数。默认为 5。

stream_idle_timeout_ms

Codex 在将连接视为丢失之前将等待流式响应上的活动的时间。默认为 300_000（5 分钟）。

model_provider

标识从 model_providers 映射中使用哪个提供商。默认为 "openai"。你可以通过 OPENAI_BASE_URL 环境变量覆盖内置 openai 提供商的 base_url。

注意，如果你覆盖了 model_provider，那么你可能也想覆盖 model。例如，如果你在本地使用 Mistral 运行 ollama，那么除了在 model_providers 映射中的新条目外，你还需要在配置中添加以下内容：

model_provider = "ollama"
model = "mistral"

approval_policy

确定何时应该提示用户批准 Codex 是否可以执行命令：

# Codex 有硬编码逻辑定义了一组"受信任"的命令。
# 将 approval_policy 设置为 `untrusted` 意味着 Codex 将在运行不在"受信任"集中的命令之前提示用户。
#
# 请参阅 https://github.com/openai/codex/issues/1260 了解启用最终用户定义自己受信任命令的计划。
approval_policy = "untrusted"

如果你希望在命令失败时收到通知，请使用 "on-failure"：

# 如果命令在沙盒中运行失败，Codex 会请求许可在沙盒外重试该命令。
approval_policy = "on-failure"

如果你希望模型运行直到它认为需要你提升权限，请使用 "on-request"：

# 模型决定何时提升
approval_policy = "on-request"

或者，你可以让模型运行直到完成，并且从不请求运行具有提升权限的命令：

# 永远不提示用户：如果命令失败，Codex 将自动尝试其他方法。
# 注意 `exec` 子命令始终使用此模式。
approval_policy = "never"

profiles

配置文件 是可以一起设置的一组配置值。可以在 config.toml 中定义多个配置文件，你可以通过 --profile 标志在运行时指定要使用的配置文件。

以下是定义多个配置文件的 config.toml 示例：

model = "o3"
approval_policy = "untrusted"

# 设置 `profile` 相当于在命令行上指定 `--profile o3`，
# 不过 `--profile` 标志仍然可以用来覆盖这个值。
profile = "o3"

[model_providers.openai-chat-completions]
name = "使用聊天补全的 OpenAI"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "chat"

[profiles.o3]
model = "o3"
model_provider = "openai"
approval_policy = "never"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"

[profiles.gpt3]
model = "gpt-3.5-turbo"
model_provider = "openai-chat-completions"

[profiles.zdr]
model = "o3"
model_provider = "openai"
approval_policy = "on-failure"

用户可以在多个级别指定配置值。优先级顺序如下：

1. 自定义命令行参数，例如，--model o3
2. 作为配置文件的一部分，其中 --profile 通过 CLI（或在配置文件本身中）指定
3. 作为 config.toml 中的条目，例如，model = "o3"
4. Codex CLI 附带的默认值（即，Codex CLI 默认为 gpt-5-codex）

model_reasoning_effort

如果所选模型已知支持推理（例如：o3、o4-mini、codex-*、gpt-5、gpt-5-codex），则在使用 Responses API 时默认启用推理。如 OpenAI Platform 文档 中所述，可以将其设置为：

• "minimal"
• "low"
• "medium"（默认）
• "high"

注意：要最小化推理，请选择 "minimal"。

model_reasoning_summary

如果模型名称以 "o" 开头（如 "o3" 或 "o4-mini"）或 "codex"，则在使用 Responses API 时默认启用推理。如 OpenAI Platform 文档 中所述，可以将其设置为：

• "auto"（默认）
• "concise"
• "detailed"

要禁用推理摘要，请在你的配置中设置 model_reasoning_summary 为 "none"：

model_reasoning_summary = "none"  # 禁用推理摘要

model_verbosity

控制在使用 Responses API 时 GPT‑5 系列模型的输出长度/细节。支持的值：

• "low"
• "medium"（省略时的默认值）
• "high"

设置时，Codex 在请求负载中包含一个具有配置的详细程度的 text 对象，例如："text": { "verbosity": "low" }。

示例：

model = "gpt-5"
model_verbosity = "low"

注意：这仅适用于使用 Responses API 的提供商。聊天补全提供商不受影响。

model_supports_reasoning_summaries

默认情况下，reasoning 仅在对已知支持它的 OpenAI 模型的请求上设置。要强制在当前模型的请求上设置 reasoning，你可以通过在 config.toml 中设置以下内容来强制此行为：

model_supports_reasoning_summaries = true

sandbox_mode

Codex 在操作系统级别的沙盒内执行模型生成的 shell 命令。

在大多数情况下，你可以通过单个选项选择所需的行为：

# 与 `--sandbox read-only` 相同
sandbox_mode = "read-only"

默认策略是 read-only，这意味着命令可以读取磁盘上的任何文件，但尝试写入文件或访问网络将被阻止。

更宽松的策略是 workspace-write。指定时，Codex 任务当前的工作目录将是可写的（以及 macOS 上的 $TMPDIR）。注意，CLI 默认使用它被生成的目录作为 cwd，尽管这可以使用 --cwd/-C 覆盖。

在 macOS（以及很快的 Linux）上，所有包含 .git/ 文件夹作为直接子级的可写根目录（包括 cwd）将把 .git/ 文件夹配置为只读，而 Git 存储库的其余部分将是可写的。这意味着像 git commit 这样的命令默认将失败（因为它涉及写入 .git/），并且需要 Codex 请求许可。

# 与 `--sandbox workspace-write` 相同
sandbox_mode = "workspace-write"

# 仅在 `sandbox = "workspace-write"` 时适用的额外设置。
[sandbox_workspace_write]
# 默认情况下，Codex 会话的 cwd 以及 $TMPDIR（如果设置）和 /tmp（如果存在）将是可写的。
# 将相应选项设置为 `true` 将覆盖这些默认值。
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

# $TMPDIR 和 /tmp 之外的 _额外_ 可写根的可选列表。
writable_roots = ["/Users/YOU/.pyenv/shims"]

# 允许在沙盒内运行的命令发出出站网络请求。
# 默认禁用。
network_access = false

要完全禁用沙盒，请指定 danger-full-access，如下所示：

# 与 `--sandbox danger-full-access` 相同
sandbox_mode = "danger-full-access"

如果 Codex 在提供自己沙盒的环境中运行（例如 Docker 容器），从而不需要进一步沙盒化，那么使用此选项是合理的。

虽然如果你尝试在不支持其本机沙盒机制的环境中使用 Codex，例如旧版 Linux 内核或 Windows 上，也可能需要使用此选项。

批准预设

Codex 提供三个主要的批准预设：

• 只读：Codex 可以读取文件并回答问题；编辑、运行命令和网络访问需要批准。
• 自动：Codex 可以读取文件、进行编辑并在工作区中运行命令而无需批准；在工作区外或网络访问需要批准。
• 完全访问：完全的磁盘和网络访问而无提示；极其危险。

你可以使用 --ask-for-approval 和 --sandbox 选项进一步自定义 Codex 在命令行上的运行方式。

MCP 服务器

你可以配置 Codex 使用 MCP 服务器 来访问外部应用程序、资源或服务，如 Playwright、Figma、文档 和 更多。

服务器传输配置

STDIO

# 顶级表名必须是 `mcp_servers`
# 子表名（本例中为 `server-name`）可以是任何你想要的名称。
[mcp_servers.server-name]
command = "npx"
# 可选
args = ["-y", "mcp-server"]
# 可选：将额外的环境变量传播到 MVP 服务器。
# 默认的环境变量白名单将传播到 MCP 服务器。
# https://github.com/openai/codex/blob/main/codex-rs/rmcp-client/src/utils.rs#L82
env = { "API_KEY" = "value" }

可流式 HTTP

# 可流式 HTTP 需要实验性 rmcp 客户端
experimental_use_rmcp_client = true
[mcp_servers.figma]
url = "http://127.0.0.1:3845/mcp"
# 可选的 bearer 令牌，将被传递到 `Authorization: Bearer <token>` 头中
# 谨慎使用，因为令牌是明文的。
bearer_token = "<token>"

请参阅 MCP CLI 命令进行 oauth 登录

其他配置选项

# 可选：覆盖默认的 10 秒启动超时
startup_timeout_sec = 20
# 可选：覆盖默认的每工具 60 秒超时
tool_timeout_sec = 30

实验性 RMCP 客户端

Codex 正在过渡到 官方 Rust MCP SDK，像可流式 http 服务器这样的新功能只能与新客户端一起工作。

请尝试报告新客户端的问题。要启用它，请将此添加到 config.toml 的顶级

experimental_use_rmcp_client = true

MCP CLI 命令

# 添加服务器（env 可以重复；`--` 分隔启动器命令）
codex mcp add docs -- docs-server --port 4000

# 列出配置的服务器（漂亮表格或 JSON）
codex mcp list
codex mcp list --json

# 显示一个服务器（表格或 JSON）
codex mcp get docs
codex mcp get docs --json

# 移除服务器
codex mcp remove docs

# 登录到支持 oauth 的可流式 HTTP 服务器
codex mcp login SERVER_NAME

# 从支持 oauth 的可流式 HTTP 服务器登出
codex mcp logout SERVER_NAME

shell_environment_policy

Codex 生成子进程（例如，在执行助手建议的 local_shell 工具调用时）。默认情况下，它现在将你的完整环境传递给这些子进程。你可以通过 config.toml 中的 shell_environment_policy 块来调整此行为：

[shell_environment_policy]
# inherit 可以是 "all"（默认）、"core" 或 "none"
inherit = "core"
# 设置为 true 以*跳过*对 `"*KEY*"` 和 `"*TOKEN*"` 的过滤
ignore_default_excludes = false
# 排除模式（不区分大小写的 glob）
exclude = ["AWS_*", "AZURE_*"]
# 强制设置/覆盖值
set = { CI = "1" }
# 如果提供，*仅*保留匹配这些模式的变量
include_only = ["PATH", "HOME"]

模式是 glob 风格的，不是完整的正则表达式：* 匹配任意数量的字符，? 正好匹配一个，字符类如 [A-Z]/[^0-9] 受支持。匹配总是不区分大小写的。此语法在代码中记录为 EnvironmentVariablePattern（参见 core/src/config_types.rs）。

如果你只需要一个带有一些自定义条目的干净状态，你可以写：

[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin", MY_FLAG = "1" }

目前，假设网络被禁用，CODEX_SANDBOX_NETWORK_DISABLED=1 也会被添加到环境中。这是不可配置的。

otel

Codex 可以发出 OpenTelemetry 日志事件，描述每次运行：出站 API 请求、流式响应、用户输入、工具批准决策以及每次工具调用的结果。导出默认禁用，因此本地运行保持自包含。通过添加 [otel] 表并选择导出器来选择加入。

[otel]
environment = "staging"   # 默认为 "dev"
exporter = "none"          # 默认为 "none"；设置为 otlp-http 或 otlp-grpc 以发送事件
log_user_prompt = false    # 默认为 false；除非明确启用，否则编辑提示文本

Codex 为每个导出的事件标记 service.name = $ORIGINATOR（与在 originator 头中发送的值相同，默认为 codex_cli_rs）、CLI 版本和一个 env 属性，以便下游收集器可以区分开发/暂存/生产流量。只有 codex_otel crate 内产生的遥测——下面列出的事件——被转发到导出器。

事件目录

每个事件共享一组常见的元数据字段：event.timestamp、conversation.id、app.version、auth_mode（可用时）、user.account_id（可用时）、terminal.type、model 和 slug。

启用 OTEL 后，Codex 发出以下事件类型（除了上述元数据）：

• codex.conversation_starts
• provider_name
• reasoning_effort（可选）
• reasoning_summary
• context_window（可选）
• max_output_tokens（可选）
• auto_compact_token_limit（可选）
• approval_policy
• sandbox_policy
• mcp_servers（逗号分隔的列表）
• active_profile（可选）
• codex.api_request
• attempt
• duration_ms
• http.response.status_code（可选）
• error.message（失败）
• codex.sse_event
• event.kind
• duration_ms
• error.message（失败）
• input_token_count（仅响应）
• output_token_count（仅响应）
• cached_token_count（仅响应，可选）
• reasoning_token_count（仅响应，可选）
• tool_token_count（仅响应）
• codex.user_prompt
• prompt_length
• prompt（除非 log_user_prompt = true 否则编辑）
• codex.tool_decision
• tool_name
• call_id
• decision（approved、approved_for_session、denied 或 abort）
• source（config 或 user）
• codex.tool_result
• tool_name
• call_id（可选）
• arguments（可选）
• duration_ms（工具的执行时间）
• success（"true" 或 "false"）
• output

这些事件形状可能会在我们迭代时改变。

选择导出器

设置 otel.exporter 来控制事件的去向：

• none – 保持检测活动但跳过导出。这是默认设置。
• otlp-http – 将 OTLP 日志记录发布到 OTLP/HTTP 收集器。指定你的收集器期望的端点、协议和头：

toml [otel] exporter = { otlp-http = { endpoint = "https://otel.example.com/v1/logs", protocol = "binary", headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" } }}

• otlp-grpc – 通过 gRPC 流式传输 OTLP 日志记录。提供端点和任何元数据头：

toml [otel] exporter = { otlp-grpc = { endpoint = "https://otel.example.com:4317", headers = { "x-otlp-meta" = "abc123" } }}

如果导出器是 none，则不会在任何地方写入任何内容；否则你必须运行或指向你自己的收集器。所有导出器都在后台批处理工作程序上运行，该程序在关闭时刷新。

如果你从源代码构建 Codex，OTEL crate 仍然在 otel 功能标志后面；官方预构建的二进制文件启用了该功能。当功能被禁用时，遥测钩子变为无操作，因此 CLI 继续在没有额外依赖项的情况下运行。

notify

指定一个将执行以获取有关 Codex 生成的事件通知的程序。请注意，该程序将接收作为 JSON 字符串的通知参数，例如：

{
  "type": "agent-turn-complete",
  "turn-id": "12345",
  "input-messages": ["将 `foo` 重命名为 `bar` 并更新调用点。"],
  "last-assistant-message": "重命名完成并验证 `cargo build` 成功。"
}

"type" 属性将始终被设置。目前，"agent-turn-complete" 是唯一支持的通知类型。

例如，这是一个 Python 脚本，它解析 JSON 并决定是否使用 macOS 上的 terminal-notifier 显示桌面推送通知：

#!/usr/bin/env python3

import json
import subprocess
import sys


def main() -> int:
    if len(sys.argv) != 2:
        print("用法: notify.py <NOTIFICATION_JSON>")
        return 1

    try:
        notification = json.loads(sys.argv[1])
    except json.JSONDecodeError:
        return 1

    match notification_type := notification.get("type"):
        case "agent-turn-complete":
            assistant_message = notification.get("last-assistant-message")
            if assistant_message:
                title = f"Codex: {assistant_message}"
            else:
                title = "Codex: 回合完成!"
            input_messages = notification.get("input_messages", [])
            message = " ".join(input_messages)
            title += message
        case _:
            print(f"不为以下内容发送推送通知: {notification_type}")
            return 0

    subprocess.check_output(
        [
            "terminal-notifier",
            "-title",
            title,
            "-message",
            message,
            "-group",
            "codex",
            "-ignoreDnD",
            "-activate",
            "com.googlecode.iterm2",
        ]
    )

    return 0


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

要让 Codex 使用此脚本进行通知，你可以通过 ~/.codex/config.toml 中的 notify 配置它，使用计算机上 notify.py 的适当路径：

notify = ["python3", "/Users/mbolin/.codex/notify.py"]

[!NOTE] 使用 notify 进行自动化和集成：Codex 为每个事件调用你的外部程序，传递单个 JSON 参数，独立于 TUI。如果你只想要在使用 TUI 时的轻量级桌面通知，更喜欢 tui.notifications，它使用终端转义码并且不需要外部程序。你可以同时启用两者；tui.notifications 覆盖 TUI 内警报（例如，批准提示），而 notify 最适合系统级钩子或自定义通知程序。目前，notify 只发出 agent-turn-complete，而 tui.notifications 支持 agent-turn-complete 和 approval-requested 并具有可选过滤。

history

默认情况下，Codex CLI 在 $CODEX_HOME/history.jsonl 中记录发送给模型的的消息。请注意，在 UNIX 上，文件权限设置为 o600，因此它应该只能由所有者读写。

要禁用此行为，请按如下方式配置 [history]：

[history]
persistence = "none"  # "save-all" 是默认值

file_opener

标识用于在模型输出中超链接引用的编辑器/URI 方案。如果设置，模型输出中对文件的引用将使用指定的 URI 方案进行超链接，以便可以从终端 ctrl/cmd 单击它们来打开。

例如，如果模型输出包含诸如 【F:/home/user/project/main.py†L42-L50】 之类的引用，那么这将被重写为链接到 URI vscode://file/home/user/project/main.py:42。

注意这不是一般的编辑器设置（如 $EDITOR），因为它只接受固定的一组值：

• "vscode"（默认）
• "vscode-insiders"
• "windsurf"
• "cursor"
• "none" 明确禁用此功能

目前，"vscode" 是默认值，尽管 Codex 不验证 VS Code 是否已安装。因此，file_opener 在未来可能默认为 "none" 或其他内容。

hide_agent_reasoning

Codex 间歇性地发出"推理"事件，显示模型在产生最终答案之前的内部"思考"。一些用户可能会觉得这些事件分散注意力，特别是在 CI 日志或最小终端输出中。

将 hide_agent_reasoning 设置为 true 会在 TUI 和无头 exec 子命令中都抑制这些事件：

hide_agent_reasoning = true   # 默认为 false

show_raw_agent_reasoning

在可用时显示模型的原始思维链（"原始推理内容"）。

注意：

• 仅在所选模型/提供商实际发出原始推理内容时才生效。许多模型不这样做。当不受支持时，此选项没有可见效果。
• 原始推理可能包括中间思想或敏感上下境。仅在你的工作流可接受时启用。

示例：

show_raw_agent_reasoning = true  # 默认为 false

model_context_window

模型的上下文窗口大小，以令牌为单位。

一般来说，Codex 知道最常见的 OpenAI 模型的上下文窗口，但如果你将新模型与旧版本的 Codex CLI 一起使用，那么你可以使用 model_context_window 告诉 Codex 在对话期间使用什么值来确定剩余多少上下文。

model_max_output_tokens

这类似于 model_context_window，但是用于模型的输出令牌最大数量。

project_doc_max_bytes

从 AGENTS.md 文件读取以包含在会话第一轮发送的指令中的最大字节数。默认为 32 KiB。

project_doc_fallback_filenames

当在给定目录级别缺少 AGENTS.md 时要查找的其他文件名的有序列表。CLI 总是首先检查 AGENTS.md；配置的回退按提供的顺序尝试。这让已经使用替代指令文件（例如，CLAUDE.md）的单一代码库可以在你逐步迁移到 AGENTS.md 时开箱即用。

project_doc_fallback_filenames = ["CLAUDE.md", ".exampleagentrules.md"]

我们建议将指令迁移到 AGENTS.md；其他文件名可能会降低模型性能。

tui

特定于 TUI 的选项。

[tui]
# 当需要批准或回合完成时发送桌面通知。
# 默认为 false。
notifications = true

# 你可以选择性地过滤到特定的通知类型。
# 可用类型是 "agent-turn-complete" 和 "approval-requested"。
notifications = [ "agent-turn-complete", "approval-requested" ]

[!NOTE] Codex 使用终端转义码发出桌面通知。并非所有终端都支持这些（值得注意的是，macOS Terminal.app 和 VS Code 的终端不支持自定义通知。iTerm2、Ghostty 和 WezTerm 支持这些通知）。

[!NOTE] > tui.notifications 是内置的，仅限于 TUI 会话。对于程序化或跨环境通知——或与操作系统特定的通知程序集成——使用顶级 notify 选项来运行接收事件 JSON 的外部程序。这两个设置是独立的，可以一起使用。

配置参考