Codex CLI 配置参考

Codex 对大多数用户开箱即用。但有时你想根据自己的喜好配置 Codex 以更好地满足需求。为此提供了广泛的配置选项。

概述

配置文件位置：~/.codex/config.toml

要在使用 Codex IDE 扩展时访问配置文件，可以点击扩展右上角的齿轮图标，然后点击 Codex Settings > Open config.toml。

此配置文件在 CLI 和 IDE 扩展之间共享，可用于配置默认模型、审批策略、沙箱设置或 Codex 应访问的 MCP 服务器等。

注意事项：

在 TOML 格式中，根级别的键必须出现在表（tables）之前
默认为"未设置"的可选键以注释形式展示
MCP 服务器、配置文件和模型提供商部分为示例配置，请根据需要修改或删除

认证配置（auth.json）

认证文件位置：~/.codex/auth.json

此文件用于存储 API 密钥等认证信息。如果你使用 OpenAI API 密钥进行认证，可以在此文件中配置：

json

{
  "OPENAI_API_KEY": null
}

配置说明：

将 null 替换为你的实际 API 密钥，例如：

json

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx"
}

如果你使用其他认证方式（如 ChatGPT 登录），可以将值保持为 null
此文件会在首次运行 Codex 时自动创建

手动创建 auth.json：

bash

# 创建 .codex 目录（如果不存在）
mkdir -p ~/.codex

# 创建 auth.json 文件
echo '{"OPENAI_API_KEY": "你的API密钥"}' > ~/.codex/auth.json

注意： 请妥善保管你的 API 密钥，不要将其提交到版本控制系统中。

完整配置示例

以下是一个使用自定义模型提供商的完整配置示例：

toml

# 模型配置
model_provider = "aicodex"
model = "gpt-5.2-codex"

# /review 功能（代码审查）使用的模型
review_model = "gpt-5.2-codex"

# 推理配置
model_reasoning_effort = "medium"
show_raw_agent_reasoning = true
model_reasoning_summary = "detailed"

# 隐私设置
disable_response_storage = true

# 认证方式
preferred_auth_method = "apikey"

# 详细程度
model_verbosity = "high"

# 自定义模型提供商配置
[model_providers.aicodex]
name = "aicodex"
base_url = "https://api.leagsoft.ai/v1"
wire_api = "responses"
requires_openai_auth = true
env_key = "AICODEX_OAI_KEY"

# 功能开关
[features]
skills = true

使用此配置前，需要设置环境变量：

bash

export AICODEX_OAI_KEY="你的API密钥"

常用配置快速参考

以下是一些最常更改的设置：

默认模型

toml

model = "gpt-5"

CLI 参数：codex --model gpt-5

模型提供商

toml

model_provider = "ollama"

CLI 参数：codex --config model_provider="ollama"

审批提示

toml

approval_policy = "on-request"

CLI 参数：codex --ask-for-approval on-request

沙箱级别

toml

sandbox_mode = "workspace-write"

CLI 参数：codex --sandbox workspace-write

推理深度

toml

model_reasoning_effort = "high"

CLI 参数：codex --config model_reasoning_effort="high"

命令环境

toml

[shell_environment_policy]
include_only = ["PATH", "HOME"]

CLI 参数：codex --config shell_environment_policy.include_only='["PATH","HOME"]'

核心模型选择

toml

# Codex 使用的主模型。默认值："gpt-5.2"（所有平台）
model = "gpt-5.2"

# /review 功能（代码审查）使用的模型。默认值："gpt-5.2"
review_model = "gpt-5.2"

# 从 [model_providers] 中选择的提供商 ID。默认值："openai"
model_provider = "openai"

# 可选的手动模型元数据。未设置时，Codex 会自动从模型检测。
# 取消注释以强制设置值。
# model_context_window = 128000       # token 数；默认：根据模型自动设置
# model_auto_compact_token_limit = 0  # 禁用/覆盖自动压缩；默认：根据模型系列设置
# tool_output_token_limit = 10000     # 每个工具输出存储的 token 数；默认：gpt-5.2 为 10000

推理与详细程度

适用于支持 Responses API 的模型。

toml

# 推理努力程度：minimal | low | medium | high | xhigh
# 默认值：medium；gpt-5.2 和 gpt-5.2 默认为 xhigh
model_reasoning_effort = "medium"

# 推理摘要：auto | concise | detailed | none（默认值：auto）
model_reasoning_summary = "auto"

# GPT-5 系列（Responses API）的文本详细程度：low | medium | high（默认值：medium）
model_verbosity = "medium"

# 强制为当前模型启用推理摘要（默认值：false）
model_supports_reasoning_summaries = false

# 强制推理摘要格式：none | experimental（默认值：none）
model_reasoning_summary_format = "none"

指令覆盖

toml

# 附加在 AGENTS.md 之后的额外用户指令。默认值：未设置
# developer_instructions = ""

# 可选的旧版基础指令覆盖（推荐使用 AGENTS.md）。默认值：未设置
# instructions = ""

# 历史压缩提示的内联覆盖。默认值：未设置
# compact_prompt = ""

# 使用文件路径覆盖内置基础指令。默认值：未设置
# experimental_instructions_file = "/absolute/or/relative/path/to/instructions.txt"

# 从文件加载压缩提示覆盖。默认值：未设置
# experimental_compact_prompt_file = "/absolute/or/relative/path/to/compact_prompt.txt"

审批与沙箱

toml

# 何时请求命令审批：
# - untrusted：仅已知安全的只读命令自动运行；其他命令需要提示
# - on-failure：在沙箱中自动运行；仅在失败时提示升级权限
# - on-request：由模型决定何时询问（默认值）
# - never：从不提示（有风险）
approval_policy = "on-request"

# 工具调用的文件系统/网络沙箱策略：
# - read-only（默认值）
# - workspace-write
# - danger-full-access（无沙箱；极其危险）
sandbox_mode = "read-only"

# 仅在 sandbox_mode = "workspace-write" 时使用的额外设置
[sandbox_workspace_write]
# 除工作区（cwd）外的额外可写根目录。默认值：[]
writable_roots = []
# 允许沙箱内的出站网络访问。默认值：false
network_access = false
# 从可写根目录中排除 $TMPDIR。默认值：false
exclude_tmpdir_env_var = false
# 从可写根目录中排除 /tmp。默认值：false
exclude_slash_tmp = false

Shell 环境策略

控制生成进程的环境变量。

toml

[shell_environment_policy]
# 继承方式：all（默认值）| core | none
inherit = "all"
# 跳过包含 KEY/TOKEN 名称的默认排除项（不区分大小写）。默认值：false
ignore_default_excludes = false
# 要移除的不区分大小写的 glob 模式（例如 "AWS_*", "AZURE_*"）。默认值：[]
exclude = []
# 显式键/值覆盖（始终优先）。默认值：{}
set = {}
# 白名单；如果非空，仅保留匹配的变量。默认值：[]
include_only = []
# 实验性：通过用户 shell 配置文件运行。默认值：false
experimental_use_profile = false

历史记录与文件打开器

toml

[history]
# 持久化方式：save-all（默认值）| none
persistence = "save-all"
# 历史文件的最大字节数；超出时会修剪最旧的条目。示例：5242880
# max_bytes = 0

# 可点击引用的 URI 方案：vscode（默认值）| vscode-insiders | windsurf | cursor | none
file_opener = "vscode"

UI、通知和杂项

toml

[tui]
# TUI 的桌面通知：布尔值或过滤列表。默认值：true
# 示例：false | ["agent-turn-complete", "approval-requested"]
notifications = false

# 启用欢迎/状态/加载动画。默认值：true
animations = true

# 从输出中隐藏内部推理事件。默认值：false
hide_agent_reasoning = false

# 在可用时显示原始推理内容。默认值：false
show_raw_agent_reasoning = false

# 禁用 TUI 中的突发粘贴检测。默认值：false
disable_paste_burst = false

# 跟踪 Windows 入门确认（仅限 Windows）。默认值：false
windows_wsl_setup_acknowledged = false

# 外部通知程序（argv 数组）。未设置时：禁用
# 示例：notify = ["notify-send", "Codex"]
# notify = [ ]

# 产品内通知（大多由 Codex 自动设置）
[notice]
# hide_full_access_warning = true
# hide_rate_limit_model_nudge = true

认证与登录

toml

# CLI 登录凭据的存储位置：file（默认值）| keyring | auto
cli_auth_credentials_store = "file"

# ChatGPT 认证流程的基础 URL（非 OpenAI API）。默认值：
chatgpt_base_url = "https://chatgpt.com/backend-api/"

# 将 ChatGPT 登录限制到特定工作区 ID。默认值：未设置
# forced_chatgpt_workspace_id = ""

# 当 Codex 通常会自动选择时强制登录机制。默认值：未设置
# 允许的值：chatgpt | api
# forced_login_method = "chatgpt"

# MCP OAuth 凭据的首选存储：auto（默认值）| file | keyring
mcp_oauth_credentials_store = "auto"

项目文档控制

toml

# 嵌入到首轮指令中的 AGENTS.md 最大字节数。默认值：32768
project_doc_max_bytes = 32768

# 当目录级别缺少 AGENTS.md 时的有序回退文件名。默认值：[]
project_doc_fallback_filenames = []

工具配置

为兼容性保留的旧版开关。

toml

[tools]
# 启用网络搜索工具（别名：web_search_request）。默认值：false
web_search = false

# 启用 view_image 工具，使代理可以附加本地图片。默认值：true
view_image = true

# （也接受别名）你也可以写成：
# web_search_request = false

功能标志

集中式功能标志（推荐方式）。

toml

[features]
# 保持此表为空以接受默认值。设置显式布尔值以选择启用/禁用。
unified_exec = false
rmcp_client = false
apply_patch_freeform = false
view_image_tool = true
web_search_request = false
ghost_commit = false
enable_experimental_windows_sandbox = false
skills = false

实验性开关

旧版实验性开关（推荐使用 [features]）。

toml

# 通过自由格式编辑路径包含 apply_patch（影响默认工具集）。默认值：false
experimental_use_freeform_apply_patch = false

MCP 服务器

在此表下定义 MCP 服务器。留空以禁用。

toml

[mcp_servers]

# --- 示例：STDIO 传输 ---
# [mcp_servers.docs]
# command = "docs-server"                 # 必需
# args = ["--port", "4000"]               # 可选
# env = { "API_KEY" = "value" }           # 可选：按原样复制的键/值对
# env_vars = ["ANOTHER_SECRET"]           # 可选：从父环境转发这些变量
# cwd = "/path/to/server"                 # 可选：工作目录覆盖
# startup_timeout_sec = 10.0              # 可选；默认 10.0 秒
# # startup_timeout_ms = 10000            # 可选：启动超时的别名（毫秒）
# tool_timeout_sec = 60.0                 # 可选；默认 60.0 秒
# enabled_tools = ["search", "summarize"] # 可选：允许列表
# disabled_tools = ["slow-tool"]          # 可选：拒绝列表（在允许列表之后应用）

# --- 示例：可流式 HTTP 传输 ---
# [mcp_servers.github]
# url = "https://github-mcp.example.com/mcp"  # 必需
# bearer_token_env_var = "GITHUB_TOKEN"       # 可选；Authorization: Bearer <token>
# http_headers = { "X-Example" = "value" }    # 可选：静态头
# env_http_headers = { "X-Auth" = "AUTH_ENV" } # 可选：从环境变量填充的头
# startup_timeout_sec = 10.0                  # 可选
# tool_timeout_sec = 60.0                     # 可选
# enabled_tools = ["list_issues"]             # 可选：允许列表

模型提供商

扩展/覆盖内置提供商。

内置提供商包括：

openai：Responses API；需要登录或通过认证流程获取 OPENAI_API_KEY
oss：Chat Completions API；默认为 http://localhost:11434/v1

toml

[model_providers]

# --- 示例：使用显式基础 URL 或头覆盖 OpenAI ---
# [model_providers.openai]
# name = "OpenAI"
# base_url = "https://api.openai.com/v1"         # 未设置时的默认值
# wire_api = "responses"                         # "responses" | "chat"（默认值因情况而异）
# # requires_openai_auth = true                  # 内置 OpenAI 默认为 true
# # request_max_retries = 4                      # 默认 4；最大 100
# # stream_max_retries = 5                       # 默认 5；最大 100
# # stream_idle_timeout_ms = 300000              # 默认 300_000（5分钟）
# # experimental_bearer_token = "sk-example"    # 可选：仅开发用的直接 bearer token
# # http_headers = { "X-Example" = "value" }
# # env_http_headers = { "OpenAI-Organization" = "OPENAI_ORGANIZATION", "OpenAI-Project" = "OPENAI_PROJECT" }

# --- 示例：Azure（根据端点使用 Chat/Responses）---
# [model_providers.azure]
# name = "Azure"
# base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
# wire_api = "responses"                          # 或根据端点使用 "chat"
# query_params = { api-version = "2025-04-01-preview" }
# env_key = "AZURE_OPENAI_API_KEY"
# # env_key_instructions = "在环境中设置 AZURE_OPENAI_API_KEY"

# --- 示例：本地 OSS（例如 Ollama 兼容）---
# [model_providers.ollama]
# name = "Ollama"
# base_url = "http://localhost:11434/v1"
# wire_api = "chat"

配置文件（Profiles）

Profiles 将一组配置值打包在一起，这样你可以在不同设置之间切换而无需每次编辑 config.toml。它们目前适用于 Codex CLI。

在 config.toml 中的 [profiles.<name>] 下定义配置文件，并使用 codex --profile <name> 启动 CLI：

toml

model = "gpt-5-codex"
approval_policy = "on-request"

[profiles.deep-review]
model = "gpt-5-pro"
model_reasoning_effort = "high"
approval_policy = "never"

[profiles.lightweight]
model = "gpt-4.1"
approval_policy = "untrusted"

运行 codex --profile deep-review 将使用 gpt-5-pro 模型，高推理努力程度，无审批策略。运行 codex --profile lightweight 将使用 gpt-4.1 模型和 untrusted 审批策略。

要将某个配置文件设为默认，在 config.toml 顶层添加 profile = "deep-review"；CLI 将加载该配置文件，除非你在命令行覆盖它。

值的解析顺序：显式 CLI 标志（如 --model）覆盖一切，配置文件值次之，然后是 config.toml 中的根级别条目，最后是 CLI 的内置默认值。利用这个优先级在顶层设置通用设置，同时让每个配置文件只调整需要更改的字段。

toml

# 活动配置文件名称。未设置时，不应用任何配置文件。
# profile = "default"

[profiles]

# [profiles.default]
# model = "gpt-5.2"
# model_provider = "openai"
# approval_policy = "on-request"
# sandbox_mode = "read-only"
# model_reasoning_effort = "medium"
# model_reasoning_summary = "auto"
# model_verbosity = "medium"
# chatgpt_base_url = "https://chatgpt.com/backend-api/"
# experimental_compact_prompt_file = "./compact_prompt.txt"
# include_apply_patch_tool = false
# experimental_use_freeform_apply_patch = false
# tools_web_search = false
# tools_view_image = true
# features = { unified_exec = false }

项目信任级别

将特定工作树标记为受信任。仅识别 "trusted"。

toml

[projects]
# [projects."/absolute/path/to/project"]
# trust_level = "trusted"

OpenTelemetry (OTEL)

默认禁用。

toml

[otel]
# 在日志中包含用户提示文本。默认值：false
log_user_prompt = false
# 应用于遥测的环境标签。默认值："dev"
environment = "dev"
# 导出器：none（默认值）| otlp-http | otlp-grpc
exporter = "none"

# 示例：OTLP/HTTP 导出器配置
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs"
# protocol = "binary"                         # "binary" | "json"

# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"

# 示例：OTLP/gRPC 导出器配置
# [otel.exporter."otlp-grpc"]
# endpoint = "https://otel.example.com:4317"
# headers = { "x-otlp-meta" = "abc123" }

# 示例：带双向 TLS 的 OTLP 导出器
# [otel.exporter."otlp-http"]
# endpoint = "https://otel.example.com/v1/logs"
# protocol = "binary"

# [otel.exporter."otlp-http".headers]
# "x-otlp-api-key" = "${OTLP_TOKEN}"

# [otel.exporter."otlp-http".tls]
# ca-certificate = "certs/otel-ca.pem"
# client-certificate = "/etc/codex/certs/client.pem"
# client-private-key = "/etc/codex/certs/client-key.pem"

Rules（预览）

.rules 文件让你定义细粒度的规则来管理 Codex 的行为，例如识别 Codex 允许在沙箱外运行的命令。

例如，假设你创建了文件 ~/.codex/rules/default.rules，内容如下：

python

# 允许以 `gh pr view` 开头的命令在 Codex 的 "shell tool" 沙箱外运行的规则
prefix_rule(
    # 要匹配的前缀
    pattern = ["gh", "pr", "view"],

    # 当 Codex 请求运行匹配命令时采取的操作
    decision = "allow",

    # `match` 和 `not_match` 是可选的"内联单元测试"，你可以提供应该（或不应该）
    # 匹配此规则的命令示例。如果这些测试失败，.rules 文件将无法加载。
    match = [
      "gh pr view 7888",
      "gh pr view --repo openai/codex",
      "gh pr view 7888 --json title,body,comments",
    ],
    not_match = [
      # 不匹配，因为 `pattern` 必须是精确前缀
      "gh pr --repo openai/codex view 7888",
    ],
)

prefix_rule() 让你使用以下选项在 Codex 运行命令前预先批准、提示或阻止命令：

allow - 允许命令运行
prompt - 提示用户确认
block - 阻止命令运行

Codex 在启动时加载 ~/.codex/rules 下的每个 *.rules 文件；当你在 TUI 中将命令加入白名单时，它会将规则追加到 ~/.codex/rules/default.rules，这样未来的运行可以跳过提示。

注意 .rules 文件的输入语言是 Starlark。其语法类似于 Python，但它被设计为一种安全的、可嵌入的语言，可以在没有副作用（如触及文件系统）的情况下解释。Starlark 的功能如列表推导使得可以动态构建规则。

最后，要测试策略如何应用于命令而不编辑文件，可以使用 CLI 助手：

bash

$ codex execpolicy check --pretty --rules ~/.codex/rules/default.rules -- gh pr view 7888 --json title,body,comments
{
  "matchedRules": [
    {
      "prefixRuleMatch": {
        "matchedPrefix": [
          "gh",
          "pr",
          "view"
        ],
        "decision": "prompt"
      }
    }
  ],
  "decision": "prompt"
}

传递多个 --rules 标志以组合文件，添加 --pretty 获取格式化的 JSON。规则系统仍处于预览阶段，因此语法和默认值可能会更改。

通知

使用 notify 在 Codex 发出支持的事件（目前：agent-turn-complete）时触发外部程序。这对于桌面提示、聊天 webhook、CI 更新或内置 TUI 通知未涵盖的任何旁路警报很有用。

toml

notify = ["python3", "/path/to/notify.py"]

示例 notify.py（截断）响应 agent-turn-complete：

python

#!/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())

将脚本放在磁盘上的某个位置并将 notify 指向它。对于更轻量的终端内警报，改用 tui.notifications。

IDE 扩展配置

除了通过 config.toml 文件配置底层 Codex 代理外，你还可以配置使用 Codex IDE 扩展的方式。

要查看可用配置选项列表，点击扩展右上角的齿轮图标，然后点击 IDE settings。

要定义自己的键盘快捷键来触发 Codex 或向 Codex 上下文添加内容，点击扩展右上角的齿轮图标，然后点击 Keyboard shortcuts。

Codex CLI 配置参考 ​

概述 ​

认证配置（auth.json） ​

完整配置示例 ​

常用配置快速参考 ​

核心模型选择 ​

推理与详细程度 ​

指令覆盖 ​

审批与沙箱 ​

Shell 环境策略 ​

历史记录与文件打开器 ​

UI、通知和杂项 ​

认证与登录 ​

项目文档控制 ​

工具配置 ​

功能标志 ​

实验性开关 ​

MCP 服务器 ​

模型提供商 ​

配置文件（Profiles） ​

项目信任级别 ​

OpenTelemetry (OTEL) ​

Rules（预览） ​

通知 ​

IDE 扩展配置 ​

Codex CLI 配置参考

概述

认证配置（auth.json）

完整配置示例

常用配置快速参考

核心模型选择

推理与详细程度

指令覆盖

审批与沙箱

Shell 环境策略

历史记录与文件打开器

UI、通知和杂项

认证与登录

项目文档控制

工具配置

功能标志

实验性开关

MCP 服务器

模型提供商

配置文件（Profiles）

项目信任级别

OpenTelemetry (OTEL)

Rules（预览）

通知

IDE 扩展配置