高级配置

当你需要更细粒度地控制提供方、策略和集成时，请使用这些配置项。若你只需要快速入门，先看 配置基础。

如果你想了解项目指导、可复用能力、自定义斜杠命令、子智能体工作流和集成能力的背景概念，参见 自定义。如果你想查具体键名，参见 配置参考。

配置档案（Profiles）

配置档案允许你保存一组带名字的配置值，并在 CLI 中按名称切换。

在 config.toml 中通过 [profiles.<name>] 定义配置档案，然后运行 codex --profile <name>：

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"

如果你想让某个配置档案成为默认值，可以在 config.toml 顶层加上 profile = "deep-review"。这样除非你在命令行里显式覆盖，Codex 启动时就会自动加载该配置档案。

配置档案也可以覆盖 model_catalog_json。如果顶层和所选配置档案同时设置了 model_catalog_json，Codex 会优先使用配置档案中的值。

通过 CLI 做一次性覆盖

除了直接编辑 ~/.codex/config.toml 之外，你还可以在 CLI 中只对单次运行做配置覆盖：

• 优先使用专用 flag，例如 --model
• 当你需要覆盖任意配置键时，使用 -c / --config

示例：

# 专用 flag
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"]'

补充说明：

• --config 里的值使用的是 TOML 语法，而不是 JSON。
• 你可以覆盖嵌套键，例如 mcp_servers.context7.enabled=false。
• 如果拿不准，请给值加上引号，避免 shell 因为空格把它拆开。
• 如果某个值无法被解析成 TOML，Codex 会把它当作普通字符串处理。

配置与状态文件位置

Codex 会把本地状态保存在 CODEX_HOME 下，默认路径是 ~/.codex。

你在其中最常见到的文件包括：

• config.toml（你的本地配置）
• auth.json（如果你使用基于文件的凭据存储；否则会使用操作系统的 keychain / keyring）
• 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/ 目录来解析。

项目配置文件不能覆盖会重定向凭据、改变 provider 认证，或运行机器本地通知 / telemetry 命令的设置。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 中。

生命周期钩子

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 会同时加载并给出警告。建议每个配置层只使用其中一种表示方式。

关于当前支持的事件列表、输入字段、输出行为和限制，请参见 Hooks。

智能体角色（config.toml 中的 [agents]）

关于子智能体角色配置，也就是 config.toml 中的 [agents]，参见 子智能体。

项目根目录检测

Codex 会从当前工作目录向上查找项目根，从而发现项目配置，例如 .codex/ 配置层和 AGENTS.md。

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

# 当目录中包含以下任一标记时，将其视为项目根目录。
project_root_markers = [".git", ".hg", ".sl"]

如果你设置 project_root_markers = []，Codex 就不会再向父目录搜索，而是直接把当前工作目录视为项目根。

自定义模型提供方

模型提供方定义了 Codex 如何连接到某个模型，例如基础 URL、wire_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 令牌，可以使用命令式认证：

[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 主动刷新；如果设为 0，则只会在认证重试后刷新。不要把 [model_providers.<id>.auth] 与 env_key、experimental_bearer_token 或 requires_openai_auth 混用。

Amazon Bedrock 提供方

Codex 内建了 amazon-bedrock 模型提供方。可以直接把它设为 model_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 模式（本地提供方）

当你传入 --oss 时，Codex 可以运行在本地“开源”提供方上，例如 Ollama 或 LM Studio。如果你传了 --oss 但没有指定提供方，Codex 会把 oss_provider 作为默认值。

# `--oss` 默认使用的本地提供方
oss_provider = "ollama" # 或 "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 不能被覆盖。

启用了数据驻留的 ChatGPT 客户

如果你的项目启用了 数据驻留，可以创建一个模型提供方，把 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 的提供方生效。基于 Chat Completions 的提供方会忽略这个设置。

审批策略与沙箱模式

你可以同时配置审批严格程度（控制 Codex 何时暂停）和沙箱级别（控制文件 / 网络访问范围）。

在编辑 config.toml 时，和这些设置相关的运行时行为细节可参考 常见的沙箱与审批组合、可写根目录中的受保护路径 和 网络访问。

如果要使用同时配置文件系统和网络访问的 beta 权限配置档案，请参见权限。

你也可以使用细粒度审批策略，也就是 approval_policy = { granular = { ... } }，按类别允许或自动拒绝单独的提示。这适合你希望某些情形仍保留交互式批准，而另一些情形，例如 request_permissions 或技能脚本提示，则默认直接拒绝的场景。

如果你希望把符合条件的交互式审批请求交给自动评审，可以设置 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 = """
Use your organization's automatic review policy.
"""

命名权限配置档案

关于内建配置档案、自定义配置档案语法，以及完整的文件系统与网络配置模型，请参见权限。

如果你需要完整键列表，包括配置档案级覆盖值和 requirements 强制规则，参见 配置参考 与 托管配置。

如果你想彻底关闭沙箱（仅当你的运行环境本身已经提供进程隔离时才建议这样做）：

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 自动过滤会先于你自己的包含 / 排除规则生效。

MCP server

关于 MCP server 的配置细节，参见独立的 MCP 文档。

可观测性与遥测

你可以启用 OpenTelemetry（OTel）日志导出，用来追踪 Codex 运行过程，包括 API 请求、SSE 事件、提示词、工具审批和工具结果。该功能默认关闭；如需启用，请在 [otel] 中配置：

[otel]
environment = "staging"   # 默认为 "dev"
exporter = "none"         # 设为 otlp-http 或 otlp-grpc 以发送事件
log_user_prompt = false   # 默认脱敏用户提示词，除非显式开启

你可以选择导出器：

[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 何时工作不正常，也帮助团队了解哪些功能和配置正在被实际使用，从而把精力投入到最重要的问题上。这些指标不包含任何个人身份信息（PII）。需要注意的是，指标收集与 OTel 日志 / trace 导出是独立的。

如果你想在某台机器上的所有 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 命令或 patch 内容。

运行时与模型传输

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

Turn 与工具活动

mcp.call 和 mcp.call.duration_ms 指标包含 status。常规工具调用还会包含 tool，并在可用时包含 connector_id 和 connector_name。被阻止的 Codex Apps 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，但回退提示中的预检失败可能不包含字段。

反馈控制

默认情况下，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"]

下面是一个会响应 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：assistant 最近一条消息的文本内容

把脚本放到磁盘上的任意位置，然后让 notify 指向它即可。

notify 与 tui.notifications

• notify 用于运行外部程序，适合接 webhook、桌面通知程序或 CI hook。
• 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 编写自定义说明。

TUI 选项

直接运行 codex 而不带子命令时，会启动交互式终端界面（TUI）。Codex 在 [tui] 下提供了一些 TUI 专属配置项，包括：

• tui.notifications：启用或关闭通知，也可以限制只接收特定类型的通知
• tui.notification_method：选择终端通知方式，可用值为 auto、osc9 或 bel
• tui.notification_condition：选择通知只在终端失焦时触发，还是始终触发；可用值为 unfocused 或 always
• tui.animations：启用或关闭 ASCII 动画与闪光效果
• tui.alternate_screen：控制是否使用备用屏幕（alternate screen）；设为 never 时会保留终端滚动历史
• tui.show_tooltips：控制欢迎页是否显示引导提示

tui.notification_method 默认值为 auto。在 auto 模式下，如果 Codex 判断当前终端支持，它会优先使用 OSC 9 通知。OSC 9 是一种终端转义序列，有些终端会把它解释为桌面通知；如果不可用，则会退回到 BEL（\x07）。

完整键列表请参见 配置参考。