外部模型接入 Codex

本文只介绍第三方在线模型，提供两种接入路线：

开始前必须理解一个关键限制：

本文适用于运行在本机的 Codex CLI、Codex IDE 扩展以及读取同一套 config.toml 的桌面客户端。Codex 云端会话目前不能通过本文方式切换为自定义模型。

开始之前

安装或更新 Codex CLI

npm install -g @openai/codex@latest
codex --version

首次安装后，至少运行一次：

codex

这样可以初始化 Codex 的用户配置目录。

Codex 配置文件位置

macOS 和 Linux：

~/.codex/config.toml

Windows：

%USERPROFILE%\.codex\config.toml

修改配置前建议备份。

macOS / Linux：

mkdir -p ~/.codex/backup
cp ~/.codex/config.toml \
  ~/.codex/backup/config.toml.$(date +%Y%m%d-%H%M%S) \
  2>/dev/null || true

PowerShell：

$codexDir = Join-Path $HOME ".codex"
$backupDir = Join-Path $codexDir "backup"
New-Item -ItemType Directory -Force -Path $backupDir | Out-Null

$configFile = Join-Path $codexDir "config.toml"
if (Test-Path $configFile) {
  $timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
  Copy-Item $configFile (Join-Path $backupDir "config.toml.$timestamp")
}

区分 provider、MCP 和模型网关

这三个概念解决的问题不同：

• model_provider：决定 Codex 把模型请求发送到哪里；
• MCP：给 Codex 增加浏览器、GitHub、数据库等工具与上下文；
• 模型网关：在 Codex 和模型服务之间完成协议转换、鉴权、路由、日志或限流。

因此，更换 Codex 的底层模型需要配置 provider，不是配置 MCP。

API Key 安全

不要把真实 API Key 提交到 Git 仓库，也不要把完整密钥放进公开截图、日志或工单。

手动配置 provider 时，优先使用环境变量：

[model_providers.example]
env_key = "EXAMPLE_API_KEY"

CC Switch 会在本机保存 provider 配置，并在切换时修改 Codex 的本地配置。它是第三方开源工具，不是 OpenAI 官方产品。应只从 CC Switch 官方网站或官方 GitHub 仓库安装，并保护好本机配置、数据库和备份文件。

1. 使用 CC Switch 接入第三方模型

对于大多数第三方模型，CC Switch 是更容易使用的接入方式。它可以管理 provider、API Key、模型列表和本地路由，并在上游协议不兼容时完成转换。

1.1 CC Switch 解决了什么问题

新版 Codex 按 Responses API 发送请求，但不少第三方服务提供的是：

• OpenAI Chat Completions；
• Anthropic Messages；
• 非 Codex 默认识别的模型 ID；
• 厂商自定义的推理参数和流式事件格式。

CC Switch 的本地路由可以把调用链转换为：

Codex
  │  Responses API
  ▼
CC Switch 本地路由
  │  根据 provider 配置转换协议和模型名称
  ▼
第三方模型 API
  │
  ▼
CC Switch 将响应、SSE、推理内容和工具调用转换回 Responses 格式
  │
  ▼
Codex

对于原生支持 Responses API 的 provider，CC Switch 可以不做 Chat 协议转换；对于 Chat Completions 或 Anthropic Messages provider，则必须启用本地路由。

1.2 安装 CC Switch

只从以下官方来源获取安装包：

• CC Switch 官方网站
• CC Switch GitHub 仓库
• CC Switch Releases

macOS 推荐使用 Homebrew：

brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

Windows 可以从 Releases 下载 .msi 安装包或便携版压缩包。

Linux 可以从 Releases 下载 .deb、.rpm 或 AppImage。不同版本的界面文字可能略有变化，建议始终使用最新稳定版本，并以应用内实际选项为准。

1.3 准备工作

接入前准备以下内容：

1. 已安装并运行过一次 Codex；
2. 已安装并能够正常启动 CC Switch；
3. 已获得目标模型服务的 API Key；
4. 已从供应商文档确认 Base URL、模型 ID 和上游 API 协议；
5. 如果需要保留 Codex 官方账号能力，先完成一次官方登录。

检查 Codex 登录状态：

codex login status

需要登录时可以运行：

codex login

也可以使用设备码登录：

codex login --device-auth

1.4 可选：切换第三方 provider 时保留官方登录

这一项主要适用于同时使用 Codex 桌面功能、官方插件或远程控制能力的用户。只使用 CLI 且不依赖官方登录能力时，可以跳过。

推荐顺序：

1. 在 CC Switch 的 Codex 页面切换到 OpenAI Official；
2. 启动 Codex，并完成官方账号登录；
3. 在 CC Switch 打开 Settings → General → Codex App Enhancements；
4. 开启 Keep official login when switching third-party providers；
5. 再添加或切换第三方 provider。

开启后，CC Switch 会尽量保持：

• ~/.codex/auth.json：继续保存官方登录状态；
• ~/.codex/config.toml：保存当前第三方 provider、模型、地址和认证配置。

auth.json 中包含敏感登录信息，不要复制给他人，也不要提交到版本控制系统。

1.5 添加第三方 provider

打开 CC Switch，切换到顶部的 Codex 页面，然后点击右上角的添加按钮。

优先使用预设

如果应用内已经有对应 provider 预设，优先选择预设，只填写 API Key 和必要参数。预设通常会自动配置：

• Base URL；
• 默认模型；
• 上游协议；
• 是否需要本地路由；
• 模型映射；
• 部分推理参数。

CC Switch 的预设列表会随着版本更新。文档中不应长期固定某个厂商的模型 ID，应以应用内列表和供应商官方文档为准。

使用自定义 provider

预设中没有目标服务时，选择自定义配置，并填写：

最关键的是正确选择 Upstream Format：

不要因为供应商宣传“兼容 OpenAI API”就默认选择 Responses。很多所谓 OpenAI 兼容接口只兼容 Chat Completions。

1.6 正确填写 Base URL

默认情况下，CC Switch 会在 Base URL 后拼接对应的 API 路径。因此，通常只填写供应商文档给出的 API 根地址，不要自行重复添加 /chat/completions 或 /responses。

例如，供应商要求：

POST https://api.example.com/v1/chat/completions

通常填写：

https://api.example.com

或者按照预设要求填写：

https://api.example.com/v1

具体是否包含 /v1，取决于 CC Switch 预设和供应商文档。保存前应使用 CC Switch 的连接检测或请求日志确认最终请求地址。

只有当供应商要求非标准完整路径时，才使用 CC Switch 的 Full URL Mode，并填写完整 endpoint。

1.7 配置 Needs Local Routing 和模型映射

当 provider 使用 Chat Completions、Anthropic Messages，或者模型名称不是 Codex 默认模型时，应启用 Needs Local Routing。

选择 Chat 类型预设时，CC Switch 通常会自动开启该选项；自定义 provider 需要自行确认。

启用后会出现模型映射配置。常见字段包括：

注意：

• Model ID 必须与供应商文档完全一致；
• 不要凭感觉填写上下文窗口；
• 模型列表变化后需要重启 Codex；
• CC Switch 会根据映射生成 Codex 使用的模型目录；
• 如果中转平台修改了模型名称或域名，自动推理能力识别可能不准确，应在高级设置中检查。

1.8 开启本地路由并接管 Codex

在 CC Switch 中打开：

Settings → Routing → Local Routing

完成以下操作：

1. 开启本地路由总开关；
2. 在 Routing Enabled 中开启 Codex；
3. 确认目标 provider 的 Needs Local Routing 状态正确；
4. 使用期间保持 CC Switch 正在运行。

本地路由默认地址通常是：

http://127.0.0.1:15721

接管生效后，Codex 的实时配置会指向 CC Switch 本地路由。CC Switch 再根据当前选中的 provider，把请求转发到真正的第三方 API。

如果上游是 Chat Completions，实际过程通常类似：

Codex POST /responses
  → CC Switch 转换为 POST /chat/completions
  → 第三方模型返回 JSON 或 SSE
  → CC Switch 转换回 Responses JSON 或 SSE
  → Codex 继续执行工具调用

1.9 切换 provider 并重启 Codex

返回 CC Switch 的 Codex provider 列表，选中刚刚配置的 provider，然后点击启用。

切换后建议完全退出并重新启动 Codex，原因包括：

• Codex 在启动时读取 config.toml；
• /model 菜单通常在启动时加载模型目录；
• IDE 扩展或桌面客户端可能缓存旧 provider；
• 已存在的会话可能仍保存旧模型信息。

CLI 用户可以重新运行：

codex

1.10 验证是否接入成功

进入 Codex 后运行：

/status

检查当前模型、provider、权限和上下文信息。

查看模型列表：

/model

检查配置层级：

/debug-config

同时检查：

• CC Switch 当前选中的 Codex provider；
• CC Switch 本地路由日志或统计；
• 第三方平台的请求记录和余额变化；
• ~/.codex/config.toml 是否暂时指向本地路由。

不要只发送“你好”来验证。至少完成一次智能体能力测试：

1. 让 Codex 列出当前项目文件；
2. 让 Codex 读取一个文件并总结内容；
3. 让 Codex 修改一个小文件；
4. 让 Codex 运行测试；
5. 故意保留一个简单错误，观察它能否根据测试结果继续修复。

只有文本对话成功，不代表工具调用和多轮智能体工作流已经兼容。

1.11 切回 OpenAI 官方 provider

在 CC Switch 中选择 OpenAI Official，然后重启 Codex。

检查登录状态：

codex login status

如果官方登录状态异常，重新执行：

codex login

如果你需要同时保留官方登录和第三方模型请求，检查 Keep official login when switching third-party providers 是否仍然开启。

1.12 CC Switch 的限制与注意事项

CC Switch 简化了配置，但仍有以下限制：

• 使用 Chat 或 Messages 协议时，CC Switch 必须持续运行；
• 协议转换不能保证还原所有供应商特有能力；
• 某些模型虽然能聊天，但工具调用质量不足；
• Web Search、图片输入、WebSocket、响应存储等高级功能可能不兼容；
• 供应商的限流、计费和数据保留政策仍然生效；
• 中转平台可能再次修改请求或响应；
• CC Switch、Codex 或供应商升级后，旧配置可能需要重新验证。

CC Switch 更适合本地桌面开发。服务器、CI 或无图形界面的长期自动化任务，优先使用原生 Responses API 或自建协议网关。

2. 手动接入第三方在线模型 API

只有当第三方服务原生支持 Codex 所需的 Responses API 时，才建议直接配置自定义 provider。

如果供应商只提供 /chat/completions 或 Anthropic Messages，请使用第一部分的 CC Switch 流程，不要尝试配置 wire_api = "chat"。

2.1 接口需要满足的条件

一个可以直接接入 Codex 的 provider，至少应支持：

• POST /responses；
• Responses JSON 结构；
• Responses SSE 流式事件；
• function/tool calling；
• JSON Schema 工具参数；
• 工具结果回传后的继续推理；
• 多轮请求或 previous_response_id 等连续对话机制；
• 足够的上下文窗口和稳定的长请求处理；
• 清晰的认证、限流和错误响应。

仅支持普通文本生成并不足以稳定运行 Codex 智能体。

2.2 通用配置

编辑用户级配置：

~/.codex/config.toml

添加：

model_provider = "third_party"
model = "provider-model-id"

# 仅在模型明确支持时设置。
model_reasoning_effort = "high"

# 可选：没有官方模型目录时，填写供应商公布的真实值。
# model_context_window = 131072

[model_providers.third_party]
name = "My Responses-compatible Provider"
base_url = "https://provider.example.com/v1"
env_key = "THIRD_PARTY_API_KEY"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 300000

不要使用以下保留 provider ID：

openai
ollama
lmstudio

可以使用 third_party、company_gateway 或其他自定义 ID。

2.3 配置字段说明

base_url 是否包含 /v1 必须以供应商文档为准。Codex 会在它后面访问 Responses 路径，常见最终地址是：

https://provider.example.com/v1/responses

2.4 设置 API Key

bash / zsh 当前会话：

export THIRD_PARTY_API_KEY="你的 API Key"

fish：

set -gx THIRD_PARTY_API_KEY "你的 API Key"

PowerShell 当前会话：

$env:THIRD_PARTY_API_KEY = "你的 API Key"

PowerShell 持久保存到当前用户：

[Environment]::SetEnvironmentVariable(
  "THIRD_PARTY_API_KEY",
  "你的 API Key",
  [EnvironmentVariableTarget]::User
)

持久设置后，需要重新启动终端、IDE 或桌面客户端。

2.5 先测试 Responses endpoint

在启动 Codex 前，先直接测试第三方接口：

export PROVIDER_BASE_URL="https://provider.example.com/v1"

curl "$PROVIDER_BASE_URL/responses" \
  -H "Authorization: Bearer $THIRD_PARTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "provider-model-id",
    "input": "Reply with exactly: PROVIDER_OK",
    "stream": false
  }'

至少检查：

• endpoint 不是 404；
• 返回的是 Responses 风格结构，不是只有 choices 的 Chat Completions 结构；
• 模型 ID 正确；
• 认证方式正确；
• 错误响应包含可排查的信息。

随后还应单独测试：

• stream: true；
• 工具调用；
• 工具结果回传；
• 多轮调用；
• 长上下文；
• 并发和限流。

2.6 验证 Codex 配置

严格模式启动：

codex --strict-config

--strict-config 会把不认识的配置项当作错误，适合发现旧教程中的废弃字段。

进入 Codex 后运行：

/status

需要检查配置来源时运行：

/debug-config

临时覆盖 provider 和模型，不修改默认配置：

codex \
  -c 'model_provider="third_party"' \
  -m 'provider-model-id'

2.7 模型目录与 Unknown model

Codex 的模型目录可以描述：

• 上下文窗口；
• 支持的推理等级；
• 输入模态；
• 工具调用能力；
• 截断策略；
• 客户端最低版本。

如果供应商提供 Codex 可用的模型目录文件，保存到本机后配置：

model_catalog_json = "~/.codex/provider-models.json"

如果没有模型目录，可以在确认真实值后设置：

model_context_window = 131072

不要复制另一模型的元数据来消除警告。错误的上下文窗口或工具能力声明，可能导致提前截断、超出限额或工具调用异常。

2.8 完整兼容性检查

正式使用前，建议逐项验证：

• /responses 非流式文本；
• Responses SSE 流式输出；
• 单个工具调用；
• 多个并行或连续工具调用；
• JSON Schema 参数；
• 工具结果回传；
• 长上下文与自动压缩；
• reasoning 参数；
• 图片或其他输入模态；
• 速率限制和重试；
• 代理是否缓冲 SSE；
• 供应商是否修改或丢弃工具字段；
• 数据保留、日志和隐私政策。

2.9 provider 配置应放在哪里

model_provider、model_providers 和 provider 认证配置应放在用户级文件：

~/.codex/config.toml

不要把它们放进项目仓库的：

<project>/.codex/config.toml

Codex 会忽略项目级配置中可能重定向模型请求或认证信息的相关字段。这可以防止克隆不可信仓库后，请求被项目配置悄悄转发到其他服务器。

3. 使用配置档案管理多个第三方 provider

如果使用 CC Switch，通常直接在图形界面切换 provider 即可，不必再配置 Codex 配置档案（Profile）。

配置档案更适合手动配置多个原生 Responses provider 的用户。可以把 provider 定义放在基础配置中，再用独立配置档案文件选择模型。

基础配置 ~/.codex/config.toml：

[model_providers.provider_a]
name = "Provider A"
base_url = "https://api.provider-a.example/v1"
env_key = "PROVIDER_A_API_KEY"
wire_api = "responses"

[model_providers.provider_b]
name = "Provider B"
base_url = "https://api.provider-b.example/v1"
env_key = "PROVIDER_B_API_KEY"
wire_api = "responses"

创建：

~/.codex/fast.config.toml

内容：

model_provider = "provider_a"
model = "provider-a-fast-model"
model_reasoning_effort = "medium"

再创建：

~/.codex/quality.config.toml

内容：

model_provider = "provider_b"
model = "provider-b-quality-model"
model_reasoning_effort = "high"

启动时选择：

codex --profile fast
codex --profile quality

非交互模式：

codex exec --profile quality "Review the current changes"

配置档案文件位于：

$CODEX_HOME/<profile-name>.config.toml

默认 CODEX_HOME 是 ~/.codex。

较新的 Codex 版本使用独立配置档案文件，不再读取旧式的 [profiles.<name>] 表。如果从旧配置迁移，应把每个配置档案拆分为单独的 <name>.config.toml。

4. 特殊认证 Header 与高级认证

4.1 标准 Bearer Token

大多数第三方服务可以直接使用：

[model_providers.third_party]
env_key = "THIRD_PARTY_API_KEY"

Codex 会从环境变量读取密钥，并使用 provider 要求的 Bearer 认证。

4.2 自定义 API Key Header

某些平台要求：

x-api-key: <key>

可以使用 env_http_headers：

model_provider = "custom_header_provider"
model = "provider-model-id"

[model_providers.custom_header_provider]
name = "Custom Header Provider"
base_url = "https://provider.example.com/v1"
wire_api = "responses"
env_http_headers = { "x-api-key" = "VENDOR_API_KEY" }

右侧的 VENDOR_API_KEY 是环境变量名称，不是真实密钥。

export VENDOR_API_KEY="你的 API Key"

4.3 固定 Header 和查询参数

添加不敏感的固定 Header：

http_headers = { "X-Client-Name" = "codex", "X-Environment" = "development" }

添加查询参数：

query_params = { "api-version" = "2026-08-01" }

不要把真实密钥直接写进 http_headers。

4.4 命令式动态认证

企业环境中可能需要从系统密钥链、云凭证工具或内部命令获取短期 Token：

[model_providers.corporate]
name = "Corporate Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"

[model_providers.corporate.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

认证命令必须把 Token 输出到标准输出，并且不要输出额外日志。

以下认证方式不要混用：

• [model_providers.<id>.auth]；
• env_key；
• experimental_bearer_token；
• requires_openai_auth。

4.5 通过代理继续使用 OpenAI 认证

只有当代理后面仍然访问 OpenAI 模型，并且希望 Codex 使用 OpenAI 官方认证时，才配置：

requires_openai_auth = true

这不适用于普通第三方模型 API Key。开启后，Codex 会忽略该 provider 的 env_key。

5. 常见错误与排查

5.1 CC Switch 已切换，但 Codex 仍使用旧模型

依次检查：

1. CC Switch 中当前启用的是目标 Codex provider；
2. 本地路由总开关是否开启；
3. Routing Enabled 中是否开启 Codex；
4. Chat 或 Messages provider 是否启用了 Needs Local Routing；
5. CC Switch 是否仍在运行；
6. 是否完全重启了 Codex、IDE 或桌面客户端；
7. /debug-config 是否显示了预期配置来源。

模型映射变更后，通常必须重启 Codex 才能刷新 /model 列表。

5.2 返回 404、400 或找不到 /responses

常见原因：

• 把 Chat Completions provider 当成 Responses provider；
• Base URL 多写或少写了一层 /v1；
• 重复拼接了 /chat/completions；
• 非标准地址没有开启 Full URL Mode；
• CC Switch 本地路由没有接管 Codex；
• 第三方网关没有实现完整 Responses API。

CC Switch 用户应检查 Upstream Format 和路由日志。手动 provider 用户应直接用 curl 测试 <base_url>/responses。

5.3 返回 401 Unauthorized 或 403 Forbidden

检查：

• API Key 是否有效；
• Key 是否属于正确区域、项目或套餐；
• 余额和权限是否充足；
• 服务要求 Bearer Token 还是 x-api-key；
• 环境变量名称是否与 env_key 完全一致；
• CC Switch 中是否保存了正确密钥；
• 代理是否删除了认证 Header。

检查环境变量时不要在共享日志中打印完整密钥。

bash / zsh：

printenv THIRD_PARTY_API_KEY

PowerShell：

$env:THIRD_PARTY_API_KEY

5.4 第三方模型没有出现在 /model 中

检查：

• CC Switch 的 Model Mapping 是否包含真实模型 ID；
• provider 是否已经保存并启用；
• 是否重启了 Codex；
• 手动配置是否提供了正确的 model_catalog_json；
• 模型目录 JSON 是否有效；
• 模型 ID 是否已被供应商下线或重命名。

5.5 可以聊天，但不能读写文件或运行命令

常见原因：

• 模型本身不擅长工具调用；
• 上游不支持 function calling；
• 中转层丢失了 tool call ID；
• SSE 分片没有被正确重组；
• JSON Schema 被修改；
• 工具结果没有正确回传到下一轮；
• 模型上下文过短；
• 模型目录错误声明了能力。

应使用真实项目测试“读取 → 修改 → 运行测试 → 根据失败继续修复”的完整循环。

5.6 流式响应频繁中断

CC Switch 用户先查看本地路由日志和上游响应。常见原因包括：

• 上游排队或推理时间过长；
• 第三方网关没有及时发送 SSE；
• CDN、反向代理或公司网络缓冲了流；
• 上游发送了非标准事件；
• CC Switch 或 provider 版本存在兼容问题。

手动 provider 可以适当增加：

request_max_retries = 4
stream_max_retries = 5
stream_idle_timeout_ms = 600000

增加超时只能缓解网络或长推理问题，不能修复错误的协议实现。

5.7 wire_api = "chat" 无法启动

这是旧教程中常见的配置。当前 Codex 只支持：

wire_api = "responses"

如果上游只有 Chat Completions，改用 CC Switch，不要继续尝试 wire_api = "chat"。

运行以下命令检查其他过时字段：

codex --strict-config

5.8 修改项目内配置后 provider 没有变化

以下配置必须放在用户级文件中：

~/.codex/config.toml

项目内 .codex/config.toml 不能覆盖会重定向请求或改变 provider 认证的字段，包括 model_provider 和 model_providers。

5.9 终端可用，但 IDE 扩展提示缺少 API Key

GUI 应用通常不会继承刚刚在某个终端中临时设置的环境变量。

可以：

• 从已经设置变量的终端启动 IDE；
• 将变量持久保存到系统用户环境；
• 完全退出并重新打开 IDE；
• 改用 CC Switch 管理本地 provider 配置。

5.10 切换后官方登录状态或官方功能异常

检查：

• 是否先切回 OpenAI Official；
• Keep official login when switching third-party providers 是否开启；
• ~/.codex/auth.json 是否被旧配置覆盖；
• codex login status 是否正常。

必要时重新执行：

codex login

不要手动分享或编辑包含 Access Token 的 auth.json。

5.11 Web Search、图片或其他高级功能不可用

第三方 provider 能完成文本和工具调用，不代表支持 Codex 的全部能力。

自定义 provider 默认不会声明 standalone Web Search。只有 provider、模型和 endpoint 都真实兼容时，才应配置：

supports_standalone_web_search = true

错误开启只会让 Codex发送上游无法处理的请求。图片输入、WebSocket、响应存储和其他高级能力也应分别验证。

6. 如何选择接入方式

推荐按三个层级验收：

1. 连接测试：可以稳定返回文本；
2. 工具测试：可以读取文件、调用命令并正确回传结果；
3. 任务测试：可以连续完成修改、测试和修复。

最后还要确认：

• 第三方计费方式；
• 速率限制；
• 请求和代码是否被记录；
• 数据保存地区；
• 团队或企业合规要求；
• 模型升级后是否需要重新测试。

使用第三方 API Key 时，费用由第三方服务或中转平台单独结算，不会自动使用或共享 ChatGPT Plus、Pro 或 Codex 订阅中的额度。

参考资料

• Codex Config Basics
• Codex Advanced Configuration
• Codex Configuration Reference
• Codex Authentication
• Codex Developer Commands
• Codex Models
• CC Switch GitHub
• CC Switch User Manual
• CC Switch: Add Provider
• CC Switch: Preserve Codex Official Login