Cursor、Claude Code、Codex 自定义 API Endpoint 配置完全指南

2026 年的主流 AI 编程工具都支持自定义 API endpoint。这意味着你可以把 Cursor、Claude Code、OpenAI Codex 和 Zed 指向自己的网关——不管是自建代理、商业 LLM 路由，还是统一 API 层——让所有请求经过一个 base URL。这给了你 provider 故障转移、费用追踪、模型级权限控制，以及全团队只需管理一个 API key。

本指南覆盖每个工具的精确配置步骤、首次配置时常见的坑，以及团队规模部署自定义 endpoint 的生产清单。

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

为什么要用自定义 API Endpoint

在进入配置之前，先说明团队将默认 provider URL 替换为自定义 endpoint 的理由：

• 多 provider 故障转移。 如果 OpenAI 返回 429 或 503，你的路由可以自动重试到 Anthropic、DeepSeek 或 DashScope——无需改代码。详见我们的 模型 fallback 路由指南。
• 统一账单。 一张发票代替五张，一套 API key 代替每个 provider 一个。
• 模型级权限控制。 决定每个团队或项目可以使用哪些模型，设置预算上限，审计每个请求。
• 成本优化。 将简单任务路由到便宜模型、复杂任务路由到前沿模型——通过同一个 base_url。我们的 成本优化策略指南 有深入介绍。
• 可观测性。 在一个 dashboard 中查看每个请求的延迟、token 数和错误，而不是分别登录五个 provider 控制台。

如果你只用一个 provider 且不需要路由，自定义 endpoint 只会增加复杂度。但当你使用两个或以上 provider 时——或者需要团队级管控——网关很快就能回本。

第一步：Cursor 自定义 API Endpoint 配置

Cursor 通过内置设置 UI 支持自定义 OpenAI 兼容 endpoint。配置入口在 Cursor Settings → Models。

配置步骤

1. 打开 Cursor，按 Cmd+Shift+J（macOS）或 Ctrl+Shift+J（Windows/Linux）打开 Cursor Settings。
2. 找到 Models 部分。
3. 打开 OpenAI API Key 开关，输入你的网关 API key。
4. 打开 Override OpenAI Base URL 开关。
5. 输入你的自定义 endpoint URL，例如 https://your-gateway.example.com/v1。
6. 在模型列表中添加自定义模型名。点击 + Add Model，输入网关期望的 model ID（如 gpt-5.6-terra、claude-opus-4、deepseek-v4-flash）。
7. 点击 Verify 确认连接正常。

Cursor 特有的坑

HTTP/2 兼容性。 如果设置 base URL 后出现连接错误，请到 Cursor Settings → Network → HTTP Compatibility Mode 切换为 HTTP/1.1。很多反向代理和网关不支持 HTTP/2，而 Cursor 默认使用它。这是 Cursor 社区论坛 上报告最多的故障点。

部分功能不走你的 key。 即使启用了自定义 API key，Cursor 的一些功能——包括 Tab Completion 和 Apply from Chat——仍然使用 Cursor 自己的后端模型。你的自定义 endpoint 只处理你显式添加的模型的 chat 和 agent 请求。

Model ID 映射。 Cursor 发送的 model ID 就是你在模型列表中输入的原文。如果网关期望 openai/gpt-5.6-terra 但你填了 gpt-5.6-terra，请求会失败。确保 ID 与网关期望的格式一致。

Subagent 限制。 通过 base URL 覆盖配置的自定义模型可能无法在 Cursor 的 subagent 流程中使用。如果你发现后台 agent 静默回退到 Cursor 管理的模型，这是 2026 年中的一个已知限制。

第二步：Claude Code 自定义 Endpoint 配置

Claude Code 通过环境变量支持自定义 endpoint。两个关键变量：

配置步骤

方式 A：Shell 环境变量（快速开始）

export ANTHROPIC_BASE_URL="https://your-gateway.example.com/v1"
export ANTHROPIC_API_KEY="your-gateway-key"
claude

方式 B：Claude Code 配置文件（持久化）

将变量添加到 ~/.claude/settings.json：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com/v1",
    "ANTHROPIC_API_KEY": "your-gateway-key"
  }
}

方式 C：团队托管配置

企业部署场景下，可以通过配置管理系统分发托管配置文件，将网关 URL 预置其中。Claude Code 的 LLM 网关文档 描述了如何推送配置，让每个开发者自动获得相同的 endpoint。

Claude Code 的坑

原生 Anthropic 格式 vs OpenAI 兼容。 Claude Code 默认使用 Anthropic Messages API 格式，而非 OpenAI 的 chat completions 格式。如果你的网关只处理 OpenAI 兼容请求，你需要一个能在两种格式之间转换的网关——或直接使用 Anthropic provider。

OPENAI_BASE_URL 用于 OpenAI 模型。 如果你想让 Claude Code 调用 OpenAI 模型（通过 --model 指定 OpenAI model ID），需要设置 OPENAI_BASE_URL。Claude Code 根据模型所属 provider 使用对应的 base URL 变量。

AWS Bedrock 和 Google Vertex。 Claude Code 还支持 CLAUDE_CODE_USE_BEDROCK=1 和 CLAUDE_CODE_USE_VERTEX=1 环境变量，用于云托管的 Claude。如果你通过 AWS 或 Google 路由，使用这些变量而非 ANTHROPIC_BASE_URL。

第三步：OpenAI Codex CLI 自定义 Endpoint 配置

OpenAI 的 Codex CLI 从 ~/.codex/config.toml 读取配置。自定义 endpoint 通过命名的 model provider 配置块设置。

配置步骤

1. 安装 Codex CLI：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

2. 创建或编辑 ~/.codex/config.toml：

model = "gpt-5.6-terra"
model_provider = "my-gateway"

[model_providers.my-gateway]
name = "my-gateway"
base_url = "https://your-gateway.example.com/v1"
env_key = "MY_GATEWAY_API_KEY"
wire_api = "responses"

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

3. 设置 API key：

export MY_GATEWAY_API_KEY="your-gateway-key"

4. 运行 Codex：

codex

Codex 的坑

wire_api 设置。 Codex 支持两种线格式："responses"（OpenAI 较新的 Responses API）和 "chat_completions"（标准的 /v1/chat/completions）。如果你的网关只处理 chat completions，将 wire_api 设为 "chat_completions"。设错了会产生难以理解的 404 错误，因为 Codex 会尝试 POST 到 /v1/responses。

Profiles 切换多个 endpoint。 Codex 在 config.toml 中支持命名 profiles。你可以定义多个 [model_providers.*] 块，用 codex --profile <name> 切换。这在 dev 和 production 有不同网关时非常有用。

Stream idle timeout。 对于长时间推理请求，增加 provider 配置中的 stream_idle_timeout_ms。默认值可能不够用于思考 30 秒以上才回复的模型：

[model_providers.my-gateway]
stream_idle_timeout_ms = 120000
stream_max_retries = 5

第四步：Zed 编辑器自定义 Endpoint 配置

Zed 通过其设置 JSON 支持自定义 OpenAI 兼容 provider。

配置步骤

1. 打开 Zed Settings（macOS 上按 Cmd+,）。
2. 进入 Agent Settings 并添加自定义 OpenAI 兼容 provider。
3. 或直接编辑 ~/.config/zed/settings.json：

{
  "language_models": {
    "openai": {
      "api_url": "https://your-gateway.example.com/v1",
      "available_models": [
        {
          "name": "gpt-5.6-terra",
          "display_name": "GPT-5.6 Terra (via Gateway)",
          "max_tokens": 128000
        }
      ]
    }
  }
}

4. 通过 OPENAI_API_KEY 环境变量或 Zed 的凭据存储设置 API key。

Zed 的坑

Provider 配置块。 Zed 对不同 provider 有独立的配置块（openai、anthropic、google）。如果你的网关通过一个 base URL 处理多个 provider，将其配置在 openai 块下——因为这是支持自定义 api_url 的那个。

模型可用性。 你必须在 available_models 数组中显式列出可用模型。Zed 不会自动从网关发现模型列表。

所有工具的通用问题

认证头格式

大多数编程工具将 API key 作为 Bearer token 放在 Authorization 头中发送：

Authorization: Bearer sk-your-key-here

如果你的网关需要不同的认证方式（如自定义头 X-Api-Key），你需要在前面加一层薄代理来转换头。大多数商业网关和路由接受标准 Bearer token。

Model ID 映射

工具发送的 model ID 必须与网关期望的完全匹配。常见不匹配情况：

Streaming 兼容性

四个工具默认都使用 streaming 响应（stream: true）。你的网关必须支持 Server-Sent Events（SSE）streaming。如果只支持非 streaming，你会看到超时错误或空响应。检查网关文档确认 streaming 支持。

Rate Limit 与重试

通过网关路由时，你得到的是网关的 rate limit，而非底层 provider 的。如果你的网关限制 60 RPM，而 Cursor agent 每分钟发了 80 个请求，即使 provider 允许也会触发 429 错误。配置网关的 rate limit 以匹配预期用量。详见我们的 rate limit 对比。

团队生产部署清单

在向团队推广自定义 endpoint 前，逐项验证：

• 网关可达 —— 所有开发者的机器都能访问（VPN、防火墙规则、DNS）。
• SSL 证书 有效且受信。自签名证书在大多数工具中会导致静默失败。
• API key 轮换 可行，无需更新每个开发者的本地配置。使用环境变量或密钥管理器。
• Model ID 有文档。发布可用 model ID 列表及其背后的 provider。
• Fallback 行为 已测试。模拟 provider 故障，确认网关路由到备份。
• Streaming 端到端正常。发送长 prompt，验证 token 是增量到达的。
• HTTP/1.1 模式 已在 Cursor 中启用（如果网关不支持 HTTP/2）。
• 费用监控 已就位。确认网关 dashboard 显示按模型、按用户的 token 用量。
• Rate limit 已按团队规模和使用模式配置。
• 超时值 适合推理模型（可能思考 60 秒以上）。

TheRouter 集成说明

TheRouter 路由 OpenAI 兼容请求到已配置的 provider，并支持 provider/模型路由和 fallback。将上述任意编程工具指向 TheRouter 的步骤：

1. 使用 TheRouter base URL 作为自定义 endpoint（如 https://api.therouter.ai/v1）。
2. 使用 TheRouter API key 作为 API key。
3. 使用 TheRouter 模型目录 中的 model ID——这些会自动映射到底层 provider。

TheRouter 处理 model 到 provider 的解析，你不需要担心 provider 前缀。一个 base_url 就能访问 OpenAI、Anthropic、DeepSeek、DashScope 等 provider。完整迁移步骤详见我们的 OpenAI 到 TheRouter 迁移指南。

FAQ

所有四个工具能用同一个自定义 endpoint 吗？

可以，如果你的网关支持 OpenAI 兼容的 chat completions 格式。Cursor、Codex 和 Zed 都使用 OpenAI 线格式。Claude Code 默认使用 Anthropic 格式，所以网关需要同时处理两种——或者你为 Claude Code 配置 OPENAI_BASE_URL 来使用 OpenAI 兼容模型。

网关会看到我所有的代码吗？

会。编程工具发送的每个 prompt——包括文件内容、指令和上下文——都经过你的网关。选择你信任的网关。安全方面的考量详见我们的 编程 agent 治理指南。

网关挂了怎么办？

大多数工具会显示连接错误并停止工作，直到网关恢复。它们不会自动回退到 provider 的直接 endpoint。一些网关支持健康检查和自动故障转移到备份 endpoint——在网关层配置这些，而非在编程工具中。

这能用于本地模型吗（Ollama、vLLM）？

可以。任何兼容 OpenAI chat completions 格式的 endpoint 都可以。将 base URL 指向 Ollama 的 http://localhost:11434/v1 或你的 vLLM 服务器 URL。Model ID 需要与本地服务器提供的一致。

---

来源：Cursor 设置与自定义 API Key（2026-07-29 检索）、Claude Code 环境变量（2026-07-29 检索）、Claude Code LLM 网关文档（2026-07-29 检索）、OpenAI Codex CLI 高级配置（2026-07-29 检索）、LiteLLM Codex 教程（2026-07-29 检索）、Zed API 访问文档（2026-07-29 检索）、Cursor 论坛：Override Base URL 问题（2026-07-29 检索）、Cursor 论坛：Subagent 限制（2026-07-29 检索）