Codex 配置深度解析：远端压缩、鉴权机制与历史数据管理

背景

随着 AI 编程助手（如 Codex、Claude Code）的普及，开发者越来越倾向于通过第三方 API 中转站（Proxy）或自建反代服务来接入模型，以获取更低的成本、更高的稳定性或访问受限模型。然而，这种非官方直连的方式引入了配置复杂性。

许多用户在配置 config.toml 和 auth.json 时遇到困惑，主要集中在以下三个痛点：

1. 远端压缩（Remote Compression）无法开启：不清楚触发条件及服务商配置要求。
2. API Key 鉴权失败：不理解 sk- 前缀的作用及匹配机制。
3. 切换供应商后对话历史丢失：误以为更换 URL 或 Key 会导致历史数据永久删除，实则是因为 Provider ID 变更。

本文基于 LINUX DO 社区的技术分享，深入解析 Codex 在第三方 API 场景下的配置逻辑、底层机制及最佳实践。

核心内容

1. 前置知识：智能体接入第三方 API 的必要条件

在 Codex 等智能体中接入第三方模型，必须满足以下两个核心要素：

• API Key：用于身份验证和计费。通常以 sk- 开头，但这仅是命名惯例，并非魔法前缀。
• Base URL：指向中转站或反代服务器的地址。

接口规范差异：

• Codex (OpenAI 格式)：接口版本号位于 URL 路径中（如 /v1）。因此，Base URL 通常需包含 /v1 后缀。
• Claude Code (Anthropic 格式)：接口版本号位于请求 Header 中。因此，Base URL 仅需填写根地址，无需包含版本号。

关键约束：Responses API Codex 仅支持 Responses API（端点为 /v1/responses），不支持老式的 Chat Completions API。

• 验证方法：主流的反代平台（如 CPA、Sub2API）均支持 Responses API。若商家明确声明仅支持 Chat Completions，则无法在 Codex 中使用。

2. 配置文件详解：auth.json 与 config.toml

Codex 的配置分为两个文件，各司其职：

auth.json：鉴权文件

该文件仅负责存储 API Key，格式固定：

{
  "OPENAI_API_KEY": "your_api_key_here",
  "auth_mode": "apikey"
}

关于 sk- 前缀的误区：

• sk- 代表 Secret Key，是 OpenAI 起的头，被各中转站沿用。
• 匹配机制：服务器将用户输入的完整字符串与数据库中的真值进行精确比对。
• 常见错误：若中转站后台存储的 Key 不带 sk-，而用户填写了 sk-xxx，会导致比对失败。
• 解决方案：以实际能调通的 Key 格式为准。若不确定，可尝试带前缀和不带前缀各测试一次。

config.toml：基础配置

该文件定义模型提供商（Provider）的行为。最短且必须的基础配置如下：

model_provider = "a"

[model_providers.a]
name = "b"
base_url = "..."

• model_provider：指定当前使用的 Provider ID（此处为 "a"）。
• [model_providers.a]：定义 ID 为 "a" 的 Provider 配置。
• name：Provider 在 Codex 内部显示的名称。注意：此字段不仅用于显示，还直接决定压缩策略（见下文）。
• base_url：服务器请求地址。
• 一致性要求：model_provider 的值与 [model_providers.xxx] 中的 ID 必须完全一致，否则报错。

合法性验证：若配置非法，Codex 将无法设置沙盒，点击“使用备份沙盒”无反应，且无法发起对话。

3. 远端压缩（Remote Compression）机制

概念区分

• 本地压缩：客户端调用配置的模型，让模型对上下文进行总结，生成一段文字保存。
• 远端压缩：客户端调用服务器端点 /v1/responses/compact，由服务器端将历史压缩为加密块（blob）返回。客户端无法查看或修改该块，下一轮对话时原样回传，由服务器解密还原。

开启条件

远端压缩的触发条件极其严格：

1. Provider Name 必须严格为 "OpenAI"：
   • 区分大小写，必须是大写 O 和 AI。
   • 只要 name 字段不是 "OpenAI"，Codex 将默认使用本地压缩。
2. 服务商支持：
   • 中转站必须支持模型映射（Alias）功能，并暴露 /v1/responses/compact 端点。
   • 若服务商未配置映射，用户无法使用远端压缩，只能回退到本地压缩。

服务商配置示例（以 CPA + New API 为例）

若使用 CPA 作为上游，New API 作为中转，需进行如下映射配置：

CPA 侧配置 (oauth-model-alias):

oauth-model-alias:
  codex:
    - name: "gpt-5.5"          # 真实上游模型
      alias: "gpt-5.5-openai-compact" # 客户端请求的模型名
      fork: true               # 保留原模型，额外暴露 alias

New API 侧配置: 在渠道管理中，需同时保留 gpt-5.5 和 gpt-5.5-openai-compact 两个模型条目，确保客户端请求 alias 时能正确路由。

4. 对话历史丢失问题解析

现象

用户更换中转站（修改 URL 或 API Key）后，发现之前的对话记录全部消失。

根本原因

Codex 的对话历史绑定的是 Provider ID（即 config.toml 中 model_provider 指定的值，如 "a"），而非 URL 或 Key。

• 当用户修改 config.toml 时，若顺手将 Provider ID 从 "a" 改为 "b"，Codex 会认为这是一个全新的提供商，从而隐藏旧的历史记录（数据并未删除，只是被隔离）。
• 若将 ID 改回 "a"，历史记录将重新出现。

解决方案

在更换供应商时，仅修改 base_url 和 auth.json 中的 Key，务必保持 config.toml 中的 Provider ID（如 "a"）不变。

关键要点

• 接口规范：Codex 仅支持 OpenAI 格式的 Responses API (/v1/responses)，不支持 Chat Completions。接入前需确认服务商支持此端点。
• API Key 格式：sk- 仅为前缀装饰，无特殊魔法。服务器进行精确字符串匹配，若鉴权失败，尝试去除或添加 sk- 前缀以匹配服务商后台存储格式。
• 远端压缩触发条件：config.toml 中 [model_providers.xxx] 下的 name 字段必须严格等于 "OpenAI"（区分大小写）。
• 服务商配置要求：启用远端压缩要求中转站支持模型别名（Alias）映射，并正确暴露 compact 端点。若服务商不支持，只能使用本地压缩。
• 历史数据保护：对话历史绑定 Provider ID。更换 URL 或 Key 时，不要更改 model_provider 的值，否则会导致历史对话“消失”（实为被新 ID 隔离）。
• 配置验证：若 config.toml 配置错误，表现为无法设置沙盒、无