GoModel AI网关接入Claude Code、Codex与Cursor:AI编码助手集成完整教程

原创2026-10-13 14:48:121,936 阅读

GoModel AI网关接入Claude Code、Codex与Cursor:AI编码助手集成完整教程

GoModel 是一款用 Go 编写的生产级 AI 网关(AI Gateway),它为 Claude Code、Codex、Cursor 等 AI 编码助手提供统一的 OpenAI 兼容和 Anthropic 兼容 API,并附带可观测性、成本追踪、限流、故障转移和实时日志等能力。本教程将带你用最短路径,把这三款主流 AI 编码助手接入 GoModel 网关,实现流量统一管控与用量可视化。

为什么编码助手需要一个AI网关

直连各大模型供应商 API 时,你通常要面对这些问题:

痛点 GoModel 网关的解法
每个工具单独配 API Key,密钥散落各处 所有助手只认网关密钥,上游密钥集中保管
账单分散,看不清谁花了多少钱 用量分析按模型、用户路径聚合,成本一目了然
供应商故障时编码助手直接罢工 故障转移(failover)与弹性策略自动接管
请求黑盒,出问题无法排查 审计日志完整记录请求与响应轨迹
想给不同团队不同模型/预算 虚拟模型、预算、限流、标签一应俱全

接入后的流量路径非常直观:

Claude Code / Codex / Cursor  →  GoModel  →  Anthropic / OpenAI / DeepSeek / Ollama ...

下面按「安装网关 → 逐个接入 → 统一观测」的顺序展开。

20秒启动GoModel网关

三端接入共用同一个网关实例。最快的方式是用 Docker 一键启动(参考 quickstart.mdx):

docker run --rm -p 8080:8080 \
  -e GOMODEL_MASTER_KEY="change-me" \
  -e ANTHROPIC_API_KEY="sk-ant-..." \
  -e OPENAI_API_KEY="sk-..." \
  enterpilot/gomodel

启动后打开控制台 http://localhost:8080/admin/dashboard,即可在 Providers 页面用图形界面添加上游供应商(无需重启,见 configuration.mdx):

GoModel控制台Add Provider对话框:填写供应商类型、名称与API Key完成AI网关上游配置

💡 环境变量、config.yaml 和仪表盘三种配置方式任选其一;GOMODEL_MASTER_KEY 是网关管理密钥,后续会用到。

Claude Code接入:Anthropic透传与订阅令牌

Claude Code 支持标准的 LLM 网关模式,只需两个环境变量即可改道 GoModel(完整步骤见 claude-code.mdx)。

上游密钥两种来源:

  • Console API Key:在 Claude Console 账号设置中创建,按 API 用量计费;
  • Claude 订阅令牌:在已登录订阅的机器上运行 claude setup-token,得到 sk-ant-oat01-... 令牌。GoModel 会自动识别该前缀并走 OAuth Bearer 认证,用量消耗的是你的 Pro/Max 订阅额度而非 API 余额。

⚠️ 注意:Anthropic 订阅令牌仅限 Claude Code 流量使用,GoModel 作为中继转发 Claude Code 请求是合规的,但不要把它共享给其他客户端。

第 1 步:配置 Claude Code 指向网关

export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_AUTH_TOKEN=change-me
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

管理端点 http://localhost:8080 提供 /v1/messages 原生转发:凡是解析到 Anthropic 的请求会原样透传(保留 cache_control、thinking 签名和 beta 头),同时网关的限流、预算、审计照常生效;如果解析到其他供应商(比如通过模型别名或虚拟模型),Claude Code 就能被路由到别的模型上。

第 2 步:跑一条测试提示词验证

claude -p --output-format text --model claude-3-haiku-20240307 \
  'Reply with exactly ok and no punctuation.'

返回 ok 即接入成功。

Codex CLI接入:自定义Provider与Responses API

Codex 天然使用 OpenAI Responses API,与 GoModel 的 /v1/responses 端点完全契合,推荐走「自定义 Provider」路径(详见 codex.mdx)。

计费取决于上游选择:

GoModel 上游 实际扣费方
chatgpt(Codex 后端) 你的 ChatGPT 订阅额度
openai / deepseek / anthropic 等 对应供应商的 API 余额

若想让 Codex 走 ChatGPT 订阅额度,先登录一次把令牌交给网关:

codex login
export CHATGPT_API_KEY=$(jq -r .tokens.access_token ~/.codex/auth.json)

启动网关时加上 -e CHATGPT_API_KEY="$CHATGPT_API_KEY" 即可。

第 1 步:在 ~/.codex/config.toml 添加 GoModel 自定义 Provider

model_provider = "gomodel"
model = "gpt-5.6-sol"   # 换成你的GoModel提供的任意模型

[model_providers.gomodel]
name = "GoModel"
base_url = "http://localhost:8080/v1"
env_key = "GOMODEL_API_KEY"
wire_api = "responses"

第 2 步:导出网关密钥并测试

export GOMODEL_API_KEY=change-me
codex exec -m gpt-5.6-sol 'Reply with exactly ok and no punctuation.'

返回 ok 即完成接入。两个常见提示:

  • ⚠️ 即使已用 ChatGPT 登录,env_key 对应的环境变量也必须存在(里面装的是网关主密钥,不是 OpenAI Key),否则 Provider 启动失败;
  • 若用 DeepSeek 等 chat 系供应商,请配置 type: deepseek,网关会自动把 /responses 翻译成 /chat/completions。

Cursor接入:OpenAI BYOK与Base URL覆盖

Cursor 的接入路径是 OpenAI API Key + Override OpenAI Base URL(详见 cursor.mdx),但有一个硬约束:

⚠️ GoModel 必须部署在公网 HTTPS 地址上。 Cursor 会经由其官方后端构建最终提示词,http://localhost:8080/v1 这类本地地址不可靠。本地调试可用安全隧道临时测试,生产环境请在反向代理或负载均衡器上终结 TLS(参考 production.mdx)。

第 1 步:为 Cursor 创建专用托管密钥

在 GoModel 控制台 API Keys → Create API Key 中创建一把专属密钥,不要填写主密钥——因为 Cursor 会把 Key 随请求发给它的后端,专用密钥便于单独吊销与限权:

GoModel控制台API Keys管理页:为AI编码助手创建带标签的专属网关密钥

第 2 步:模型名与虚拟模型对齐

GoModel 默认列出 openai/gpt-4.1-mini 这类带供应商前缀的选择器,而 Cursor 转发的是裸模型名。用虚拟模型做一层短名映射即可(参考 virtual-models.mdx):

virtual_models:
  - source: gpt-4.1-mini
    target: openai/gpt-4.1-mini

GoModel虚拟模型配置:为Cursor创建短名称到供应商限定选择器的AI模型别名映射

第 3 步:在 Cursor 中完成配置

  1. 打开 Cursor Settings → Models;
  2. 找到 OpenAI API Key,启用并填入第 1 步创建的 GoModel 托管密钥;
  3. 启用 Override OpenAI Base URL,填入 https://gomodel.example.com/v1(保留 /v1,不要追加 /chat/completions 或 /responses);
  4. 点击 Save,新开对话选择 gpt-4.1-mini(自定义别名则先用 Add Model 添加)。

第 4 步:验证流量

先用纯文本提示词 Reply with exactly ok and no punctuation. 测试,再在一次性项目里让 Agent 模式创建测试文件;随后到 GoModel 审计日志确认请求命中了 POST /v1/chat/completions。

Cursor 的边界要清楚: 只有 OpenAI 系 BYOK 聊天流量走网关;Tab 补全、Auto、Cursor 原生模型和 Background Agents 仍走 Cursor 自有基础设施,且 BYOK 的 Agent/Edit 功能需要付费套餐。

统一观测:在网关看清每个编码助手的流量

三端接入完成后,所有流量都会汇总到同一个控制台。在 Audit Logs 中可以按模型、状态码、接口路径过滤,逐条展开查看完整的请求与响应轨迹——这是确认 Claude Code、Codex、Cursor 确实经过网关的最直接方式:

GoModel审计日志界面:按会话分组展示AI编码助手经网关的完整请求记录与响应轨迹

而 Usage Analytics 页面则回答「谁在花钱」:按模型和 user path 聚合 Token 用量与估算成本,配合预算(Budgets)和限流(Rate Limits),你可以给每个团队、每个编码助手划定清晰的开销边界。

常见故障排查清单

现象 原因与处理
Cursor 无法连通 Cursor 后端必须能访问公网 HTTPS 地址;本地地址、内网 IP、自签证书都不行
401 Unauthorized Cursor 里填的应是 GoModel 托管密钥而非上游供应商密钥,且密钥未被吊销
Model not found Cursor 原样转发模型名,从 /v1/models 复制精确选择器,或为 Cursor 建虚拟模型别名
Claude Code 401 检查 ANTHROPIC_AUTH_TOKEN 是否为网关主密钥,且网关上游 ANTHROPIC_API_KEY 有效
Codex 启动报 missing field "models" Codex 0.147.0 的已知表面日志,会自动回退,不影响会话
Cursor Agent 模式失败但聊天正常 先升级 Cursor,换标准非推理模型重试,并查看 GoModel 审计日志中的上游响应

总结:一张网关打通三大编码助手

回顾一下三端接入的核心差异:

助手 接入机制 关键点
Claude Code Anthropic 网关模式 ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN,支持订阅令牌
Codex 自定义 Responses Provider config.toml 中 wire_api = "responses",可选 ChatGPT 订阅计费
Cursor OpenAI BYOK 覆盖 必须公网 HTTPS;为 Cursor 建专用托管密钥 + 虚拟模型别名

配置入口汇总:快速上手见 quickstart.mdx,环境变量与配置文件参考 config.go,三端完整官方指南分别位于 claude-code.mdx、codex.mdx、cursor.mdx。把 Claude Code、Codex 和 Cursor 的流量都收敛到 GoModel 之后,你获得的不仅是一个统一入口,还有成本、审计、限流和故障转移这些生产级保障——这正是 AI 网关相比裸连 API 的核心价值。

登录后查看全文
GoModel