高级配置

当你需要对提供商、策略和集成进行更精细的控制时，请使用这些选项。快速入门请参阅 配置基础.

有关项目指导、可复用功能、自定义斜杠命令、子代理工作流和集成的背景信息，请参阅 自定义。有关配置键,请参阅 配置参考.

配置文件

配置文件允许你保存命名的配置层，并通过 CLI 在它们之间切换。当你传递 --profile profile-name, Codex loads ~/.codex/config.toml, then overlays ~/.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] from config.toml，以及顶层 profile = "profile-name" 选择器已不再受支持。请将旧版配置文件设置移至 ~/.codex/profile-name.config.toml,然后移除匹配的 [profiles.profile-name] 表以及 profile = "profile-name" 选择器从 config.toml.

来自 CLI 的单次覆盖

In addition to editing ~/.codex/config.toml,你可以从 CLI 为单次运行覆盖配置:

• 在已有专用标志时请优先使用（例如， --model).
• 使用 -c / --config 当你需要覆盖任意键时。

Examples:

# Dedicated flag
codex --model gpt-5.4

# Generic key/value override (value is TOML, not JSON)
codex --config model='"gpt-5.4"'
codex --config sandbox_workspace_write.network_access=true
codex --config 'shell_environment_policy.include_only=["PATH","HOME"]'

Notes:

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

配置与状态位置

Codex 将其本地状态存储在 CODEX_HOME (默认为 ~/.codex).

你可能会在那里看到的常见文件：

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

有关身份验证的详细信息（包括凭据存储模式），请参阅 身份验证。有关配置键的完整列表,请参阅 配置参考.

有关检入到代码库或系统路径的共享默认值、规则和技能，请参阅 团队配置.

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

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.

项目配置文件无法覆盖以下设置：重定向凭据、更改宿主应用请求元数据、更改提供商身份验证、选择配置文件或运行本机通知/遥测命令。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 profile-name and ~/.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

项目本地 Hook 仅在项目 .codex/ 层受信任时才会加载。用户级 Hook 则独立于项目信任机制。

内联 TOML Hook 使用与 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 and inline [hooks],Codex 会同时加载两者并发出警告。建议每层仅使用一种表示形式。

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

代理角色（[agents] in config.toml)

有关子代理角色配置（[agents] in config.toml），请参见 子智能体.

项目根目录检测

Codex 通过从工作目录向上查找，直到到达项目根目录，来发现项目配置（例如， .codex/ 层以及 AGENTS.md)从工作目录向上查找,直到到达项目根目录。

默认情况下，Codex 会将包含 .git 的目录视为项目根目录。要自定义此行为，请设置 project_root_markers in 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 请求头）。自定义提供者不能重复使用保留的内置提供者 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 并且必须将令牌输出到标准输出。Codex 会去除首尾的空白字符，将空令牌视为错误，并在 refresh_interval_ms；设置 refresh_interval_ms = 0 以仅在认证重试后才进行刷新。不要组合使用 [model_providers.<id>.auth] with env_key, experimental_bearer_token, or requires_openai_auth.

Amazon Bedrock 提供方

Codex 包含一个内置的 amazon-bedrock 模型提供方。直接将其设置为 model_provider;与自定义提供方不同,此内置提供方仅支持嵌套的 AWS profile 和区域覆盖。

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 模式（本地提供商）

当你传入时，Codex 可以针对本地的“开源”提供商（例如 Ollama 或 LM Studio）运行 --oss. If you pass --oss 在不指定提供商的情况下，Codex 会使用 oss_provider 作为默认值。

# 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 提供商的 Base URL，请使用 openai_base_url; don’t create [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" # 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，请参见 常见的沙箱和审批组合, 可写根目录中的受保护路径，且 网络访问.

有关将文件系统和网络访问权限配置在一起的 Beta 权限配置文件，请参见 权限.

您还可以使用细粒度的审批策略（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.
"""

命名权限配置文件

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

有关完整的键列表和需求约束，请参见 配置参考 and 托管配置.

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

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"]

模式是不区分大小写的通配符（*, ?, [A-Z]); ignore_default_excludes = false 会在您的包含/排除规则运行之前保留自动的 KEY/SECRET/TOKEN 过滤器。

MCP 服务器

请参阅专门的 MCP 文档 for configuration details.

可观测性与遥测

启用 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" }
}}

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

会发出哪些内容

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

• codex.conversation_starts (模型、推理设置、沙箱/审批策略)
• codex.api_request (尝试、状态/成功、持续时间以及错误详情)
• codex.sse_event (流事件类型、成功/失败、持续时间，以及以下对象的 token 计数： response.completed)
• codex.websocket_request and 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 日志/追踪导出相互独立。

如果要在某台机器上的所有 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 or shell），并且不包含实际的 shell 命令或补丁 codex 正尝试应用的内容。

运行时和模型传输

The cloud_requirements.fetch_attempt 指标包含 trigger, attempt, outcome，且 status_code 字段。 cloud_requirements.fetch_final 指标包含 trigger, outcome, reason, attempt_count，且 status_code fields.

轮次与工具活动

The mcp.call and mcp.call.duration_ms 指标包括 status；常规工具调用发出也包含 tool, 加上 connector_id and connector_name （如可用）。被阻止的 Codex Apps MCP 调用可能会发出 mcp.call with only status.

线程、任务和特性

The shell_snapshot 指标包含 success and, on failures, failure_reason.

记忆和本地状态

The external_agent_config.detect and external_agent_config.import 指标包括 migration_type；技能迁移也包含 skills_count.

Windows 沙盒

提权设置失败指标包含 code and message （当 Windows 设置失败详情可用时），并且可能包含 originator （当从共享设置路径发出时）。 windows_sandbox.legacy_setup_preflight_failed 指标包含 originator （当从共享设置路径发出时），但备用提示预检失败可能不包含任何字段。

反馈控件

默认情况下，Codex 允许用户从 /feedback。要在单台机器上跨所有 Codex 界面禁用反馈收集，请更新你的配置：

[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"]

示例 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 to it.

notify vs tui.notifications

• notify 运行外部程序（适用于 Webhook、桌面通知器、CI 钩子）。
• tui.notifications 内置于 TUI 中，可以选择按事件类型进行过滤（例如， agent-turn-complete and approval-requested).
• tui.notification_method 控制 TUI 如何发出终端通知（auto, osc9, or bel).
• tui.notification_condition 控制 TUI 通知是否仅在终端处于 unfocused or always.

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

查看 配置参考 for the exact keys.

历史持久化

默认情况下，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 link.

项目指令发现

Codex 会读取 AGENTS.md （及相关文件），并在会话的第一轮对话中包含有限数量的项目指导。有两个配置项控制此行为：

• project_doc_max_bytes：从每个文件中读取多少内容 AGENTS.md 文件
• project_doc_fallback_filenames：在以下情况时要尝试的其他文件名 AGENTS.md 在某个目录层级缺失

有关详细的操作指南，请参见 使用 AGENTS.md 自定义指令.

TUI 选项

运行 codex 在未使用子命令的情况下，将启动交互式终端 UI (TUI)。Codex 在 [tui]，包括：

• tui.notifications：启用/禁用通知（或限制为特定类型）
• tui.notification_method：选择 auto, osc9, or bel for terminal notifications
• tui.notification_condition：选择 unfocused or always for when notifications fire
• tui.animations：启用/禁用 ASCII 动画和闪烁效果
• tui.alternate_screen：控制备用屏幕的使用（设置为 never to keep terminal scrollback)
• tui.show_tooltips：在欢迎屏幕上显示或隐藏新手提示

tui.notification_method 默认值同样因模型而异，而非通用。 auto. In auto 模式下公开了一些特定于 TUI 的配置，当终端似乎支持时，Codex 优先使用 OSC 9 通知（一种被某些终端解释为桌面通知的终端转义序列），否则回退到 BEL（\x07) 否则。

查看 配置参考 获取完整按键列表。