GoModel AI网关接入Claude Code、Codex与Cursor:AI编码助手集成完整教程
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):
💡 环境变量、
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 随请求发给它的后端,专用密钥便于单独吊销与限权:
第 2 步:模型名与虚拟模型对齐
GoModel 默认列出 openai/gpt-4.1-mini 这类带供应商前缀的选择器,而 Cursor 转发的是裸模型名。用虚拟模型做一层短名映射即可(参考 virtual-models.mdx):
virtual_models:
- source: gpt-4.1-mini
target: openai/gpt-4.1-mini
第 3 步:在 Cursor 中完成配置
- 打开 Cursor Settings → Models;
- 找到 OpenAI API Key,启用并填入第 1 步创建的 GoModel 托管密钥;
- 启用 Override OpenAI Base URL,填入
https://gomodel.example.com/v1(保留/v1,不要追加/chat/completions或/responses); - 点击 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 确实经过网关的最直接方式:
而 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 的核心价值。



