配置高级能力

当你需要更细地控制 providers（模型供应商）、policies（策略）和 integrations（集成）时，使用高级配置。

如果只是快速上手，先看配置基础：

https://developers.openai.com/codex/config-basic

如果你想理解 project guidance（项目指引）、reusable capabilities（可复用能力）、custom slash commands、自定义 subagent workflows 和 integrations 的整体关系，看 Customization：

https://developers.openai.com/codex/concepts/customization

完整配置键列表见 Configuration Reference：

https://developers.openai.com/codex/config-reference

Profiles

Profiles 让你把一组配置值保存成 named set（命名配置组），并在 CLI 中快速切换。

注意：Profiles 仍是 experimental（实验性能力），未来版本可能变化或移除。Codex IDE extension 目前不支持 profiles。

在 config.toml 中用 [profiles.<name>] 定义 profile，然后运行：

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"

如果要让某个 profile 成为默认值，在 config.toml 顶层加入：

profile = "deep-review"

之后，除非你在命令行覆盖，Codex 会默认加载这个 profile。

Profiles 也可以覆盖 model_catalog_json。如果顶层和选中的 profile 都设置了 model_catalog_json，Codex 优先使用 profile 中的值。

One-off overrides from the CLI

除了编辑 ~/.codex/config.toml，你也可以在单次运行时从 CLI 覆盖配置。

原则：

• 有专用 flag 时优先用专用 flag，例如 --model。
• 需要覆盖任意 key 时，用 -c 或 --config。

示例：

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

注意：

• 可以用 dot notation 设置 nested values，例如 mcp_servers.context7.enabled=false。
• --config 的值按 TOML 解析。拿不准时，把值加引号，避免 shell 按空格拆开。
• 如果值无法按 TOML 解析，Codex 会把它当作 string。

Config and state locations

Codex 把本地状态放在 CODEX_HOME 下，默认是：

~/.codex

常见文件：

• config.toml：本地配置。
• auth.json：使用 file-based credential storage 时的认证文件；也可能使用 OS keychain / keyring。
• history.jsonl：开启 history persistence 后的历史记录。
• 其他 per-user state，例如 logs 和 caches。

认证细节见：

https://developers.openai.com/codex/auth

完整配置键见：

https://developers.openai.com/codex/config-reference

如果要把 shared defaults、rules 和 skills 放进 repo 或 system paths，看 Team Config：

https://developers.openai.com/codex/enterprise/admin-setup#team-config

如果你只是想把内置 OpenAI provider 指向 LLM proxy、router 或启用 data residency 的 project，设置 openai_base_url 即可，不需要定义新的 model_providers.<id>：

openai_base_url = "https://us.api.openai.com/v1"

这会修改内置 openai provider 的 base URL。

Project config files

除了 user config，Codex 也会读取 repo 内的 project-scoped overrides：

.codex/config.toml

Codex 会从 project root 走到 current working directory，并加载路径上找到的每一个 .codex/config.toml。如果多个文件定义同一个 key，离当前 working directory 最近的文件优先。

出于安全考虑，Codex 只在 project trusted（项目受信任）时加载 project-scoped config files。

如果 project untrusted，Codex 会忽略 project .codex/ layers，包括：

• .codex/config.toml
• project-local hooks
• project-local rules

User 和 system layers 仍然独立加载。

Project config 中的 relative paths，例如 model_instructions_file，会相对于包含该 config.toml 的 .codex/ 文件夹解析。

Hooks 事件

Codex 可以从两种位置加载 lifecycle hooks（生命周期 Hook）：

• hooks.json
• config.toml 中的 inline [hooks] tables

最常用位置：

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

Project-local hooks 只在 project .codex/ layer trusted 时加载。User-level hooks 不受 project trust 影响。

启用 hooks：

[features]
codex_hooks = true

Inline TOML hooks 使用和 hooks.json 一样的 event structure：

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

如果同一个 layer 同时包含 hooks.json 和 inline [hooks]，Codex 会两者都加载，并发出 warning。建议每个 layer 只使用一种表示方式。

当前 event list、input fields、output behavior 和限制见 Hooks：

https://developers.openai.com/codex/hooks

Agent roles

Subagent role configuration 使用 config.toml 中的 [agents]。

说明见：

https://developers.openai.com/codex/subagents

Project root detection

Codex 会从 working directory 向上查找 project root，以发现 project configuration，例如 .codex/ layers 和 AGENTS.md。

默认情况下，包含 .git 的目录会被视为 project root。

你可以通过 project_root_markers 自定义：

# Treat a directory as the project root when it contains any of these markers.
project_root_markers = [".git", ".hg", ".sl"]

如果想跳过 parent directories 搜索，把当前 working directory 当作 project root：

project_root_markers = []

Custom model providers

Model provider 定义 Codex 如何连接模型，包括：

• base URL
• wire API
• authentication
• optional HTTP headers

自定义 providers 不能复用内置保留 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"

需要时添加 request headers：

[model_providers.example]
http_headers = { "X-Example-Header" = "example-value" }
env_http_headers = { "X-Example-Features" = "EXAMPLE_FEATURES" }

当 provider 需要 Codex 从外部 credential helper 获取 bearer token 时，使用 command-backed authentication：

[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

Auth command 不接收 stdin，必须把 token 打印到 stdout。Codex 会 trim 周围空白，把空 token 视为错误，并按 refresh_interval_ms 主动刷新。

如果设置：

refresh_interval_ms = 0

Codex 只会在 authentication retry 后刷新。

不要把 [model_providers.<id>.auth] 与以下选项组合：

• env_key
• experimental_bearer_token
• requires_openai_auth

Amazon Bedrock provider

Codex 内置 amazon-bedrock model provider。你可以直接把它设为 model_provider。

和 custom providers 不同，这个内置 provider 只支持 nested AWS profile 和 region overrides：

model_provider = "amazon-bedrock"
model = "<bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "eu-central-1"

如果省略 profile，Codex 使用标准 AWS credential chain。region 应设置为处理请求的 Bedrock supported region。

OSS mode

传入 --oss 时，Codex 可以运行在本地 open source provider 上，例如 Ollama 或 LM Studio。

如果传入 --oss 但不指定 provider，Codex 使用 oss_provider 作为默认值：

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Azure provider and per-provider tuning

Azure 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 IDs 不能被覆盖。

ChatGPT customers using data residency

启用 data residency 的 projects 可以创建 model provider，并用正确 prefix 更新 base_url。

Data residency 说明：

https://help.openai.com/en/articles/9903489-data-residency-and-inference-residency-for-chatgpt

可用 prefix 说明：

https://platform.openai.com/docs/guides/your-data#which-models-and-features-are-eligible-for-data-residency

示例：

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, verbosity, and limits

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 的 providers 生效。Chat Completions providers 会忽略这个设置。

Approval policies and sandbox modes

Approval strictness 决定 Codex 什么时候暂停；sandbox level 决定文件和网络访问边界。

编辑 config.toml 前，建议同时看：

• Common sandbox and approval combinations： https://developers.openai.com/codex/agent-approvals-security#common-sandbox-and-approval-combinations
• Protected paths in writable roots： https://developers.openai.com/codex/agent-approvals-security#protected-paths-in-writable-roots
• Network access： https://developers.openai.com/codex/agent-approvals-security#network-access

你也可以使用 granular approval policy：

approval_policy = { granular = { ... } }

它可以允许或自动拒绝单独 prompt categories。适合你希望某些情况继续正常交互审批，但希望另一些情况 fail closed，例如 request_permissions 或 skill-script prompts。

把 approvals_reviewer 设为 auto_review，可以把符合条件的 interactive approval requests 路由到 automatic review。它改变的是 reviewer，不改变 sandbox boundary。

[auto_review].policy 用于本地 reviewer policy instructions。Managed 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 = """
使用你所在组织的自动 review policy。
"""

Named permission profiles

default_permissions 可以复用 named sandbox profile。

Codex 内置 profiles：

• :read-only
• :workspace
• :danger-no-sandbox

示例：

default_permissions = ":workspace"

如果使用 custom profile，把 default_permissions 指向你在 [permissions.<name>] 下定义的名字：

default_permissions = "workspace"

[permissions.workspace.filesystem]
":project_roots" = { "." = "write", "**/*.env" = "none" }
glob_scan_max_depth = 3

[permissions.workspace.network]
enabled = true
mode = "limited"

[permissions.workspace.network.domains]
"api.openai.com" = "allow"

内置 names 带 leading colon。自定义 names 不带 leading colon，并且必须有匹配的 permissions tables。

完整 key list，包括 profile-scoped overrides 和 requirements constraints，见：

• Configuration Reference： https://developers.openai.com/codex/config-reference
• Managed configuration： https://developers.openai.com/codex/enterprise/managed-configuration

在 workspace-write 模式中，一些环境会让 .git/ 和 .codex/ 保持 read-only，即使 workspace 其他部分可写。这就是为什么 git commit 这类命令仍可能需要 approval 才能在 sandbox 外运行。

如果你希望 Codex 跳过特定命令，例如阻止 sandbox 外的 git commit，使用 rules：

https://developers.openai.com/codex/rules

完全关闭 sandboxing：

sandbox_mode = "danger-full-access"

只在你的环境已经隔离 processes 时使用。

Shell environment policy

shell_environment_policy 控制 Codex 启动 subprocess 时传入哪些 environment variables，例如运行模型提出的 tool-command。

建议从干净起点或裁剪集开始，再逐层添加 excludes、includes 和 overrides，避免泄露 secrets，同时保留任务需要的 paths、keys 或 flags。

示例：

[shell_environment_policy]
inherit = "none"
set = { PATH = "/usr/bin", MY_FLAG = "1" }
ignore_default_excludes = false
exclude = ["AWS_*", "AZURE_*"]
include_only = ["PATH", "HOME"]

Patterns 是 case-insensitive globs，支持 *、?、[A-Z]。

ignore_default_excludes = false 会保留自动 KEY / SECRET / TOKEN 过滤，然后才执行你的 includes / excludes。

MCP servers 配置

MCP 配置见专门文档：

https://developers.openai.com/codex/mcp

Observability and telemetry

可以启用 OpenTelemetry (OTel) log export，跟踪 Codex runs，包括 API requests、SSE / events、prompts、tool approvals / results。

默认关闭。通过 [otel] 显式 opt in：

[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

OTLP HTTP exporter 示例：

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

OTLP gRPC exporter 示例：

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

如果 exporter = "none"，Codex 记录 events，但不发送。Exporters 会异步 batch，并在 shutdown 时 flush。

Event metadata 包括 service name、CLI version、env tag、conversation id、model、sandbox / approval settings 和 per-event fields。

字段说明见：

https://developers.openai.com/codex/config-reference

What gets emitted

Codex 会为 runs 和 tool usage 产生 structured log events。代表性 event types 包括：

• codex.conversation_starts：model、reasoning settings、sandbox / approval policy。
• codex.api_request：attempt、status / success、duration 和 error details。
• codex.sse_event：stream event kind、success / failure、duration，以及 response.completed 上的 token counts。
• codex.websocket_request 和 codex.websocket_event：request duration、每条 message 的 kind / success / error。
• codex.user_prompt：长度；除非显式启用，否则内容会 redacted。
• codex.tool_decision：approved / denied，以及 decision 来自 config 还是 user。
• codex.tool_result：duration、success、output snippet。

输出的 OTel 指标

启用 OTel metrics pipeline 后，Codex 会为 API、stream 和 tool activity 发出 counters 和 duration histograms。

下面每个 metric 都包含默认 metadata tags：

• auth_mode
• originator
• session_source
• model
• app.version

Telemetry 安全和隐私说明见：

https://developers.openai.com/codex/agent-approvals-security#monitoring-and-telemetry

Metrics

默认情况下，Codex 会定期向 OpenAI 发送少量 anonymous usage and health data（匿名使用与健康数据）。这帮助团队发现 Codex 是否工作正常，以及哪些 features 和 configuration options 正在被使用。

这些 metrics 不包含 personally identifiable information (PII)。Metrics collection 与 OTel log / trace export 独立。

如果想在一台机器上完全关闭 Codex surfaces 的 metrics collection：

[analytics]
enabled = false

每个 metric 都包含自己的 fields 和以下 default context fields。

Default context fields

• auth_mode: swic / api / unknown
• model: 使用的模型名称
• app.version: Codex 版本

指标目录

下面 metric names 省略 codex. prefix。

大多数 metric names 集中在 codex-rs/otel/src/metrics/names.rs；feature-specific metrics 如果在其他位置产生，也列在这里。

如果 metric 包含 tool 字段，它反映内部 tool，例如 apply_patch 或 shell，不包含 Codex 正在执行的实际 shell command 或 patch 内容。

Runtime and model transport

cloud_requirements.fetch_attempt 包含 trigger、attempt、outcome、status_code。

cloud_requirements.fetch_final 包含 trigger、outcome、reason、attempt_count、status_code。

Turn and tool activity

mcp.call 和 mcp.call.duration_ms 包含 status。普通 tool-call emissions 也包含 tool，并在可用时包含 connector_id 和 connector_name。Blocked Codex Apps MCP calls 可能只带 status。

线程, tasks, and features

shell_snapshot 包含 success；失败时包含 failure_reason。

Memory and local state

external_agent_config.detect 和 external_agent_config.import 包含 migration_type；skills migrations 也包含 skills_count。

Windows sandbox

Elevated setup failure metrics 在可用时包含 code 和 message，从 shared setup path 发出时也可能包含 originator。

windows_sandbox.legacy_setup_preflight_failed 从 shared setup path 发出时包含 originator，但 fallback-prompt preflight failures 可能不包含字段。

Feedback controls

默认情况下，Codex 允许用户通过 /feedback 发送反馈。要在一台机器上关闭所有 Codex surfaces 的 feedback collection：

[feedback]
enabled = false

关闭后，/feedback 会显示 disabled message，Codex 会拒绝 feedback submissions。

Hide or surface reasoning events

如果想减少 noisy reasoning output，例如 CI logs 中，可以 suppress：

hide_agent_reasoning = true

如果希望在模型发出 raw reasoning content 时显示它：

show_raw_agent_reasoning = true

只有当你的 workflow 可以接受 raw reasoning 时才启用。某些 models / providers，例如 gpt-oss，不会发出 raw reasoning；这种情况下设置没有可见效果。

通知

notify 可以在 Codex 发出 supported events 时触发 external program。目前支持 agent-turn-complete。

适合 desktop toasts、chat webhooks、CI updates，或任何内置 TUI notifications 覆盖不到的 side-channel alerting。

示例：

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 argument。常见字段：

• type：当前是 agent-turn-complete
• thread-id：session identifier
• turn-id：turn identifier
• cwd：working directory
• input-messages：触发该 turn 的 user messages
• last-assistant-message：last assistant message text

把脚本放到磁盘上，然后让 notify 指向它。

notify vs tui.notifications

• notify：运行 external program，适合 webhooks、desktop notifiers、CI hooks。
• tui.notifications：TUI 内置，可按 event type 过滤，例如 agent-turn-complete 和 approval-requested。
• tui.notification_method：控制 TUI 如何发出 terminal notifications，选项是 auto、osc9、bel。
• tui.notification_condition：控制 TUI notifications 只在 terminal unfocused 时触发，还是 always 触发。

在 auto mode 中，Codex 优先使用 OSC 9 notifications；如果终端不支持，就退回 BEL (\x07)。

完整 keys 见：

https://developers.openai.com/codex/config-reference

History persistence

默认情况下，Codex 会把本地 session transcripts 保存到 CODEX_HOME，例如：

~/.codex/history.jsonl

关闭本地 history persistence：

[history]
persistence = "none"

限制 history file size：

[history]
max_bytes = 104857600 # 100 MiB

当文件超过 cap，Codex 会丢弃 oldest entries 并 compact 文件，同时保留 newest records。

Clickable citations

如果你的 terminal / editor integration 支持，Codex 可以把 file citations 渲染成 clickable links。

通过 file_opener 配置 URI scheme：

file_opener = "vscode" # or cursor, windsurf, vscode-insiders, none

例如 /home/user/project/main.py:42 可以改写成 clickable vscode://file/...:42 link。

Project instructions discovery

Codex 会读取 AGENTS.md 及相关文件，并在 session 第一轮中加入有限数量的 project guidance。

两个关键开关：

• project_doc_max_bytes：从每个 AGENTS.md 读取多少内容。
• project_doc_fallback_filenames：当某一层级缺少 AGENTS.md 时，额外尝试哪些文件名。

详细说明：

https://developers.openai.com/codex/guides/agents-md

TUI options

不带 subcommand 运行 codex 会启动 interactive terminal UI (TUI)。

TUI 专属配置位于 [tui]，包括：

• tui.notifications：启用或禁用 notifications，也可以限制为特定 types。
• tui.notification_method：选择 terminal notifications 的方式：auto、osc9、bel。
• tui.notification_condition：选择 notifications 何时触发：unfocused 或 always。
• tui.animations：启用或禁用 ASCII animations 和 shimmer effects。
• tui.alternate_screen：控制 alternate screen usage，设为 never 可保留 terminal scrollback。
• tui.show_tooltips：显示或隐藏 welcome screen 上的 onboarding tooltips。

tui.notification_method 默认是 auto。在 auto mode 中，Codex 会优先使用 OSC 9 notifications；如果不支持，就退回 BEL (\x07)。

完整 key list：

https://developers.openai.com/codex/config-reference