String AI
语言
登录 立即开始
博客

一个 API Key 搞定 Codex CLI、Claude Code 和 Cursor：2026 配置指南

四个工具，一个密钥：如何让 Codex CLI、Claude Code、CC Switch 和 Cursor 都指向同一个 OpenAI 兼容端点，以及最容易让连接断掉的三个错误。

String AI Editorial Team
一个 API Key 搞定 Codex CLI、Claude Code 和 Cursor：2026 配置指南

同时配置 Codex CLI、Claude Code、Cursor 和一个终端助手，往往意味着要管理四套集成：创建四个密钥、在四个地方粘贴端点、维护四份逐渐彼此偏离的设置。而用一个 API key 服务多个 AI 模型、由同一个 OpenAI 兼容端点提供，可以把其中大部分工作省掉。每个工具仍保留自己的配置文件，但各项取值不再因工具而异：OpenAI 风格客户端共用一个 base URL，Claude Code 用一个入口，密钥也只需轮换一个。

本文以 String AI 的端点为例，逐一梳理四个配置界面：端点契约、最常让配置失败的三类错误，以及在把任何 agent 指向你的代码之前应当执行的验证流程。

为什么四个工具会变成四套集成

这种摩擦很少体现在模型跑分上，而是体现在上手文档里：注册账号、生成密钥、找到设置界面、粘贴地址、重启客户端，然后指望模型名称正好对得上。等到密钥需要轮换时，要更新的清单又变长了。想试另一个模型时，又得逐个工具确认它是否跟得上。

每个编程工具都自带一套认证流程，以及对模型位于何处的预设。有一段时间，这些预设都指向厂商自己的账号。如今情况变了：Codex CLI 支持自定义 model provider，Claude Code 把网关配置视为一等公民式的工作流，Cursor 提供了 base URL 覆盖选项，而 CC Switch 这类工具负责协调由此产生的各项设置。共享的访问层如今已是常规配置，真正的功夫在于弄清楚每个工具会读取哪些字段。

一个 API key 服务多个 AI 模型背后的契约

工具与 OpenAI 兼容端点通信时，依赖的是一份不大的契约：

  • 认证。每个请求都在 Authorization 头里携带 bearer token。只要工具能出示它，一个密钥就能覆盖该工具。
  • /v1 下的路由。Chat completions 负责对话，/v1/models 处的模型列表则报告该密钥能访问什么。这个路由同时也可用作连接性检查。
  • 流式输出。当 stream 设为 true 时，端点返回 server-sent events，请求应携带 Accept: text/event-stream。CLI 工具借此在答案到达时逐段显示。
  • 工具调用。Agent 风格的客户端会发送工具定义，并对响应中的结构化调用采取动作。缺少工具调用支持时，agent 可以聊天，但无法可靠地编辑文件或执行命令。

有一个细节决定了后文的一切：客户端说的并不都是这份契约的同一方言。有些期望经典的 chat completions 形式；Codex CLI 则围绕 Responses API 构建，并用 wire_api = "responses" 声明这一点。端点必须提供客户端所发送的那种方言，所以“兼容所有工具”这句话值得从两个方向分别审视。

String AI 的文档给出两种入口形式：面向 OpenAI 风格客户端的 OpenAI 兼容 base URL https://www.string.ink/v1，以及面向 Claude Code 网关变量的站点根地址 https://www.string.ink（不带 /v1 后缀）。除对话之外，文档列出的接口还包括文本与视觉输入、图像生成与编辑，以及模型列表，因此一个密钥的适用范围超出本文这四个工具。

Codex CLI：在 config.toml 中配置自定义 model provider

Codex CLI 与 VS Code 的 Codex 扩展读取的是同一个文件：~/.codex/config.toml。配置分两部分：描述端点的 provider 块，以及选定 provider 与 model 的若干行。

model_provider = "OpenAI"
model = "gpt-6-astra"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://www.string.ink/v1"
wire_api = "responses"
requires_openai_auth = true

model_provider 指定 Codex 应使用哪个 provider。在 provider 块内，base_url 是端点，wire_api = "responses" 声明协议，requires_openai_auth = true 表示该 provider 使用 OpenAI 风格的凭据认证。两处的 provider 名称要保持一致；Codex 保留了几个内置 ID，其中包含小写的 openai，这正是该块使用 OpenAI 的原因。 Codex 配置参考文档记录了此处展示的每一个字段。

凭据与配置文件放在一起，位于 ~/.codex/auth.json：

{
  "OPENAI_API_KEY": "YOUR_STRING_AI_KEY"
}

保存后重启 Codex 或你的编辑器。平台文档列出这条路径上可用的 model ID 为 gpt-6-astra、gpt-5.6-sol 和 gpt-5.6-luna，并提供一个用于 Windows PowerShell 的一键脚本，替你写好这两个文件。还有一条迁移提示：如果你此前通过 OAuth 会话登录，旧对话可能不会出现在新 provider 下，直到你运行随附的迁移脚本为止，该脚本支持先做 dry run。

自定义 provider 的逐字段参考（包括 wire_api 规则和重试默认值）见自定义 provider 指南。

Claude Code：ANTHROPIC_BASE_URL 与一对凭据变量

Claude Code 说的是 Anthropic 的协议而非 OpenAI 的协议，因此读取的是另一组变量：

export ANTHROPIC_BASE_URL="https://www.string.ink"
export ANTHROPIC_AUTH_TOKEN="YOUR_STRING_AI_KEY"

注意缺了什么：/v1 后缀。本文中每个 OpenAI 风格的字段都以 /v1 结尾；这个字段止于根地址，因为 Claude Code 会在你声明的 base URL 之后自行追加路径。

凭据变量同样需要谨慎对待。 Anthropic 的网关文档区分了 ANTHROPIC_AUTH_TOKEN 与 ANTHROPIC_API_KEY：前者把密钥作为 bearer token 放在 Authorization 头中发送，后者则放在 x-api-key 头中。用错变量会把凭据送到对方并不读取的头里，表现出来的症状就是 401。String AI 的文档指引 Claude Code 用户使用 ANTHROPIC_AUTH_TOKEN。

平台文档中有两点实用提示。生成密钥时要在 Claude API 分组中创建；其他分组的密钥无法通过 Claude API 通道连接。另外，当这些变量由 CC Switch 管理时，同一页面还会把 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 设为 1，把 CLAUDE_CODE_ATTRIBUTION_HEADER 设为 0。

启动后，在 Claude Code 内运行 /status。设置网关地址后，状态视图会显示 Anthropic base URL，并给出当前生效的凭据来源。如果显示的是 ANTHROPIC_AUTH_TOKEN，说明起作用的是网关凭据，而不是残留的登录状态。

CC Switch：为整个工具箱配置一个 Universal Provider

CC Switch 是一个桌面应用，可在一处集中管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes 等工具的 provider 设置与会话。端点只需配置一次，之后把工具切换过去即可。

相关部分是 Universal Provider 标签页。添加 provider 需要填四项：

  • Name：String AI，或任何你日后能认出的名字
  • Base URL：https://www.string.ink/v1
  • API Key：你的 String AI 密钥
  • Default model：gpt-6-astra

运行内置的 Health Check，只有通过之后再迁移你的工具。不需要手工编辑任何文件，这是四个配置界面中最不容易出错的一个。有一条注意事项全程适用：大多数工具在启动时读取 provider 设置，因此切换后要重启终端或 CLI。

Cursor：打开 OpenAI base URL 覆盖开关

在 Cursor 中打开设置界面（齿轮图标），选择 Models，展开 API Keys 部分。把密钥粘贴到 OpenAI API Key 字段，打开 Override OpenAI Base URL，并填入 https://www.string.ink/v1。这个覆盖开关正是常被跳过的一步；不打开它，密钥只是躺在设置里，Cursor 仍旧调用它的默认端点。 Cursor 的文档描述了这些相同的字段。

model ID 必须与平台列出的写法完全一致：请求带着你输入的字符串离开你的机器，对不上就返回 model-not-found，而不会给出有用的提示。

三个会让配置失效的错误

大多数配置失败都能追溯到下列之一。

1. /v1 约定并非通用。 OpenAI 风格的字段（Codex 的 provider 块、CC Switch 的 Universal Provider、Cursor 的覆盖项）使用 https://www.string.ink/v1。Claude Code 的 ANTHROPIC_BASE_URL 使用不带后缀的站点根地址。客户端会在你给出的地址后自行追加路径段，所以用错约定的表现是 404，或者是一个让你跑去排查密钥而非 URL 的认证错误。记住这一对就够了：OpenAI 形状的字段用 /v1，Claude Code 用裸根地址。

2. 凭据变量不能互换。 API key 与 auth token 在 Claude Code 里是两个不同的变量，而 Codex 从 auth.json 而不是 config.toml 读取密钥。存在多个来源时，要清楚哪一个优先。Anthropic 的文档指出，当 shell 导出与设置文件中的 env 块设置同一变量时，以设置文件中的值为准；并且网关凭据优先于已保存的登录。平台文档提供的 Codex 安装脚本给出了更友好的承诺：若存在 STRING_AI_API_KEY 变量则优先使用，并有意忽略其他工具遗留的 OPENAI_API_KEY，这样过期的密钥不会悄悄接管。一次只改一个来源，并重启客户端。如果你为其他软件保留了 OPENAI_API_KEY 导出，不要以为 Codex 会采用它；在这套配置里，密钥位于 auth.json。

3. model ID 是精确字符串。平台文档使用的标识符形如 gpt-6-astra、gpt-5.6-luna 和 claude-opus-4-8。你配置的内容必须与平台当前的列表完全一致。一个笔误，或从其他 provider 借来的名字，都会返回 model-not-found，那是字符串不匹配，而不是端点坏了。

从小处验证，再把故障分成两类

在任何 agent 触碰你的代码库之前，先在 HTTP 层发现问题。平台文档建议从 models 路由开始：

curl https://www.string.ink/v1/models \
  -H "Authorization: Bearer YOUR_STRING_AI_KEY"

返回 object: "list" 和 data 数组的响应一次说明三件事：密钥有效、base URL 正确、网络通路畅通。此时关于你的编辑器还什么都没被证明，这正是重点；一旦这一层通过，后续的失败几乎必定属于客户端配置。再做一次最小的 chat completion 是合理的第二步。

对 Claude Code 而言，对应的做法是前面说过的 /status 视图，外加一次测试 prompt；Anthropic 的文档里包含一个针对网关的单 token 请求，用于相同目的。

如果仍然失败，先分类，再动手：

  • 401：凭据被拒绝。检查客户端发送的是哪个变量、密钥所属分组、是否有设置文件覆盖了你的 shell 导出，以及客户端是否重启过。
  • model-not-found：认证通过了，ID 没通过。对照模型列表，而不是猜拼写。
  • 协议类错误，例如流始终不开始、工具调用始终不到达：客户端与端点对前文所述的方言理解不一致。先检查客户端的协议设置，再看平台文档中该工具的页面。

这样分类之后，配置问题留在客户端一侧，契约问题则归端点运营方。

共享端点方案的边界

两条边界让这套说法站得住。第一，兼容性是客户端与端点合在一起的属性，不是一句口号。一个说端点并不提供的协议的工具，不会因为填了 base URL 字段就得救，这正是 Claude Code 有独立入口、Codex 要声明 wire protocol 的原因。在加第五个工具之前，先确认它的协议出现在平台的工具列表中。

第二，客户端配置是会随版本变化的软件。字段名会挪位置，界面会改版，所以要把平台文档与各工具的官方文档当作实时参考；本文只用来把握配置的整体形状：一个密钥、两套 URL 约定、一个验证闭环。

先从一个密钥开始，再逐个迁移工具

避免返工的次序是：创建密钥，如果清单上有 Claude Code，记得选 Claude API 分组。先跑一次模型检查。配置你最常用的那个工具，用真实任务验证，再按同样顺序处理其余工具。在团队 wiki 里留一段简短记录，写明两套 URL 约定以及密钥存放的位置；这些细节否则会让下一个人搭进去一个下午。

相关阅读