OpenAI 兼容编程工具设置指南：Cursor、Claude Code、Codex 和 Zed 接入自定义 LLM 路由

编程工具出厂时都带着默认的 API 地址。个人开发者用起来没问题，但团队一旦需要控制开销、记录审计日志、设置 provider 回退，或者想换模型时不用挨个改每台开发机，就得在工具和 provider 之间加一层路由。一个 OpenAI 兼容的 LLM 路由可以替你处理这些事。

OpenAI 兼容指供应商提供一个 chat-completions 接口，其请求与响应结构与 OpenAI API 契约足够接近——只需替换三个值（API key、base URL、模型名），原来的 OpenAI SDK 调用即可直接工作。最小实践面是POST /v1/chat/completions 带 messages、model， 并返回 OpenAI 形式的流式响应。

这篇文章覆盖五个主流编程工具的具体配置方法，分别是 Cursor、Claude Code、OpenAI Codex CLI、Zed 和 Devin Desktop。每个章节独立成篇，直接跳到你用的那个就行。

速查表

为什么要让编程工具走网关

编程工具的 API 开销可以很大。一次 Codex 会话就可能消耗数千 token。把流量统一走网关能带来几个实际好处。

• 成本可见。 在一个仪表板里看到每个开发者、每个模型、每个项目的花费，不用分别登录五个 provider 后台。
• Provider 回退。 OpenAI 返回 429 或 503 时，路由自动切到备用 provider。我们的路由在已上线的产品路径上支持 provider/model 路由和回退。
• 统一计费。 一张账单取代分散在 OpenAI、Anthropic、DeepSeek 等平台的多个账户。我们在已实现的范围内提供统一的计费/结算界面。
• 管控。 限速、模型白名单、支出上限都在网关层执行。开发者不接触原始 provider 密钥。
• 审计。 每条请求都记录用户身份、模型、token 数和延迟，SOC 2 和企业合规流程需要这些信息。

Cursor

Cursor 的设置界面提供了两个字段，用来把所有 OpenAI 格式的流量重定向到你的路由。

操作步骤

1. 打开 Cursor Settings（macOS 按 Cmd+,，Windows/Linux 按 Ctrl+,）。
2. 进入 Models → API Keys。
3. 在 OpenAI API Key 字段中输入路由的 API Key。
4. 勾选 Override OpenAI Base URL。
5. 输入路由地址（例如 https://api.therouter.ai/v1）。
6. 在 Models 列表中添加路由暴露的模型 ID（例如 gpt-6-astra、claude-sonnet-4、deepseek-v4-pro）。

验证

在 Cursor 的聊天或内联助手中发一条提示。打开路由仪表板查看是否收到请求。如果没有收到，检查以下几点。

• 确认 base URL 以 /v1 结尾。Cursor 会自动追加 /chat/completions。
• 确认 API Key 是路由的密钥，而不是 OpenAI 的原始密钥。
• 确认选中的模型 ID 和路由端的模型列表一致。

常见问题

• Cursor 自带的模型仍然走 Cursor 自己的基础设施。 Override 只影响你选择自定义模型列表中的模型时。cursor-fast 等默认模型会绕过 base URL 设置。
• API Key 字段对所有自定义模型生效。 GUI 里无法按模型设置不同的 Key。如果需要按模型区分认证，在路由层处理。
• 需要流式响应。 Cursor 要求 SSE streaming。你的路由必须支持 /v1/chat/completions 上的 stream: true。

Claude Code

Claude Code 通过环境变量指向自定义网关。关键变量是 ANTHROPIC_BASE_URL，它告诉 Claude Code 把 /v1/messages 请求发到哪里。

操作步骤

方案 A，Shell 环境变量（快速测试用）

export ANTHROPIC_BASE_URL=https://api.therouter.ai/api/anthropic
export ANTHROPIC_API_KEY=sk-your-router-key
claude

方案 B，Settings 文件（持久化，推荐团队使用）

创建或编辑 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.therouter.ai/api/anthropic",
    "ANTHROPIC_API_KEY": "sk-your-router-key"
  }
}

组织级部署时，管理员可以通过 managed settings 文件统一分发配置，每台开发机上的 Claude Code 启动时自动读取。

验证

1. 运行 claude 启动会话。
2. 输入 /status，查看 Anthropic base URL 一行是否显示你的路由地址。
3. 发一条测试提示。正常收到回复说明路由已生效。

常见问题

• ANTHROPIC_BASE_URL 必须指向 Anthropic 格式的路径，不是 OpenAI 兼容路径。如果路由在 /api/anthropic 提供 Anthropic 格式的服务，就填这个路径。端点必须能响应 /v1/messages。
• ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 的区别。网关期望 Authorization 头中的 bearer token 时用前者，期望 x-api-key 时用后者。拿不准就先用 ANTHROPIC_AUTH_TOKEN。
• 后台 agent 和 supervisor 可能读不到 shell export 的变量。使用 settings 文件方式可以确保 VS Code 插件和后台会话也正确路由。
• 只设 ANTHROPIC_BASE_URL 而不设凭证 并不会替换 claude.ai 订阅。请求会走你的路由地址，但计费和限制仍来自订阅。

OpenAI Codex CLI

Codex CLI 的配置文件是 ~/.codex/config.toml。最简单的方式是为内置 OpenAI provider 设置 openai_base_url。

操作步骤

方案 A，内置 provider 重定向

编辑 ~/.codex/config.toml。

[model]
openai_base_url = "https://api.therouter.ai/v1"

设置 API Key。

export OPENAI_API_KEY=sk-your-router-key

方案 B，自定义 model provider（适合通过路由使用非 OpenAI 模型）

[[model_provider]]
name = "therouter"
base_url = "https://api.therouter.ai/v1"
env_key = "THEROUTER_API_KEY"
wire_format = "openai"

[model_provider.models]
"deepseek-v4-pro" = { max_tokens = 131072 }
"claude-sonnet-4" = { max_tokens = 200000 }

设置环境变量：

export THEROUTER_API_KEY=sk-your-router-key

启动时选择模型：

codex --model therouter/deepseek-v4-pro

验证

运行 codex 并发送一个测试任务。在路由日志中确认收到请求。Codex 默认使用 Responses API (/v1/responses)，验证你的路由是否支持，否则需要配置 Codex 使用 Chat Completions API。

常见问题

• CODEX_HOME 会覆盖配置目录。 如果设了这个变量，Codex 会从 $CODEX_HOME/config.toml 读取配置，而不是 ~/.codex/config.toml。
• Codex 默认使用 Responses API，而非 Chat Completions。如果路由只支持 /v1/chat/completions，查看你的 Codex 版本是否提供 wire_format 或 API 模式切换选项。
• 自定义 provider 名称必须唯一。 定义了 therouter 这个 provider 后，在 --model 参数中用 therouter/model-name 引用它。

Zed

Zed 通过 Agent Settings 支持 OpenAI 兼容的 provider。配置写在 settings.json 文件中。

操作步骤

1. 打开 Agent Settings：在命令面板中运行 agent: open settings。
2. 在 language_models 下添加 OpenAI 兼容的 provider 条目：

{
  "language_models": {
    "therouter": {
      "type": "openai",
      "api_url": "https://api.therouter.ai/v1",
      "available_models": [
        {
          "name": "gpt-6-astra",
          "display_name": "GPT-6 Astra (via TheRouter)",
          "max_tokens": 200000
        },
        {
          "name": "deepseek-v4-pro",
          "display_name": "DeepSeek V4 Pro (via TheRouter)",
          "max_tokens": 131072
        },
        {
          "name": "claude-sonnet-4",
          "display_name": "Claude Sonnet 4 (via TheRouter)",
          "max_tokens": 200000
        }
      ]
    }
  }
}

3. 设置 API Key。Zed 根据 provider ID 生成环境变量名，provider therouter 对应 THEROUTER_API_KEY。

export THEROUTER_API_KEY=sk-your-router-key

也可以在 Settings → AI → LLM Providers 的 GUI 中输入密钥，Zed 会把它存到系统钥匙串。

验证

开一个新的 Zed Agent 线程，在模型选择器中选择自定义模型，发送测试提示。如果模型没有出现，保存 settings.json 后重启 Zed。

常见问题

• Provider ID 决定环境变量名。 ID my-gateway 对应 MY_GATEWAY_API_KEY。建议用简洁的 ID。
• available_models 是必填项。 OpenAI 兼容 provider 无法自动发现模型列表，必须手动声明。
• Zed Agent、Inline Assistant 和 commit 消息生成共用同一套 LLM provider 配置。Claude Code 等外部 agent 在 Zed 终端里运行时，走各自的端点配置，与这里无关。
• 自定义 header 可以通过 custom_headers 字段添加，适合路由要求额外认证头的场景。

Devin Desktop

Devin Desktop（前身为 Windsurf）通过 HTTP 代理设置转发所有 LLM 流量。

操作步骤

1. 打开 Devin Desktop Settings（macOS 按 Cmd+,，Windows/Linux 按 Ctrl+,）。
2. 搜索 Http Proxy。
3. 输入路由地址，填 https://api.therouter.ai。
4. 保存并重启 Devin Desktop。

验证

打开 Devin Desktop 聊天面板，发送一条测试消息。在路由仪表板中确认收到请求。

常见问题

• Devin Desktop 走代理模式，不是 base URL 覆盖。根据配置情况，编辑器中的所有 HTTP 流量（不限于 LLM 调用）都可能经过代理。
• 认证走代理。 路由需要能处理 Devin Desktop 发给上游 provider 的认证头。
• Cascade 已经停用。 如果你从 Windsurf 迁移过来，旧的 Cascade agent 已不再工作，请使用 Devin 内置 agent。

回退链配置

所有工具都接入网关之后，配置模型回退可以让编程任务在 provider 故障时继续运行。

主力模型：    deepseek-v4-pro（编程任务成本最低）
回退 1：     claude-sonnet-4（编程能力强，成本更高）
回退 2：     gpt-6-astra（覆盖面最广，成本最高）

路由自动处理故障转移。主力模型返回错误时，下一个模型接手处理请求。开发者的使用体验不受影响。我们的路由在已上线的产品路径上支持 provider/model 路由和回退。

关于模型回退的具体配置方法，可以在路由的仪表板或配置文件中设定回退链。每个编程工具都向同一个端点发请求，由路由决定哪个 provider 来处理。

成本监控

流量统一走网关后，你有了一个集中查看编程工具开销的地方。

• 按开发者拆分。 找出谁消耗了最多 token，用的是哪些模型。
• 按模型对比。 对比 deepseek-v4-pro（$0.70/M input）、claude-sonnet-4（$3/M input）和 gpt-6-astra 的花费，找到性价比最优的组合。
• 预算告警。 设定每日或每月的支出上限（按团队或按个人）。预算耗尽时路由返回 429，避免费用失控。

我们在已实现的范围内提供统一的计费/结算界面，让你用一张账单和一个仪表板取代分别核对五个 provider 账单的麻烦。

常见故障排查

FAQ

不同的编程工具可以走不同的路由吗？

可以。每个工具有独立的配置。你可以让 Cursor 走一个网关、Claude Code 走另一个。但统一走一个路由更便于计费和监控。

走网关会增加延迟吗？

部署位置合理的网关通常增加 5-20ms。对编程工具的工作负载来说，模型推理本身就要 500ms 到 5 秒，这点延迟可以忽略。自动故障转移带来的可靠性提升远超这点开销。

路由接入后，工具自带的模型还能用吗？

大多数工具可以。Cursor 的内置模型、Claude Code 的订阅访问、Zed 的托管模型都和自定义端点配置互不干扰。你可以按对话切换内置模型和路由模型。

路由挂了怎么办？

没有备用配置的话，编程工具会连接失败。为了降低风险，在支持多 provider 的工具中配置备选（比如 Codex 的多个 model_provider 块），或者搭建高可用的路由。

每个开发者需要单独的路由 API Key 吗？

建议这样做，但不是必须的。按人分配 Key 可以追踪用量并支持单独撤销。有些路由也支持团队级 Key 配合自定义 header 识别用户身份。

自托管模型也能接入吗？

可以。如果你在本地跑了一个 OpenAI 兼容的模型服务（vLLM、Ollama、TGI），把它作为 provider 接入路由，再让编程工具指向路由。工具本身不需要知道模型是自托管的。

相关资源

• OpenAI 兼容 API 提供商，所有兼容此方案的 provider 完整列表
• Cursor 自定义 API 端点指南，Cursor 配置的深入讲解
• AI 编程工具 API 路由对比，各工具路由方式的横向比较
• 2026 秋季编程工具模型路由，编程任务的最新模型推荐
• 模型回退配置，回退链设置详解
• OpenAI Provider，OpenAI 路由细节
• Anthropic Provider，Anthropic 路由细节