Cursor 等 OpenAI 兼容客户端通常填 https://主机/v1;Claude Code 的 ANTHROPIC_BASE_URL 一般填根地址、由客户端再拼 /v1/messages——两者不能互相照抄。配错最常见的是 404、「找不到资源」或「模型不存在」,看起来像密钥坏了,其实往往是路径多拼或少拼了一层。
适用边界: 只讲 Base URL 要不要带 /v1,以及 OpenAI 兼容与 Anthropic Messages 别混用。设置页文案以官方现行文档或本机为准。示例用占位主机,不绑定未核实第三方中转站。
1. 先分协议,再填地址
| 协议 | 典型客户端 | Base 怎么填 | 客户端还会拼什么 |
|---|---|---|---|
| OpenAI 兼容(Chat Completions / Responses) | Cursor(Override OpenAI Base URL)、Codex CLI | 通常带 /v1,如 https://api.example.com/v1 | /chat/completions 或 /responses |
| Anthropic Messages | Claude Code(ANTHROPIC_BASE_URL) | 通常只填根地址,如 https://api.example.com | /v1/messages |
依据:OpenAI REST 根是 https://api.openai.com/v1,兼容端 Base URL 习惯停在 /v1。Claude Code 官方网关示例 ANTHROPIC_BASE_URL=https://llm-gateway.example.com(无 /v1),验证却 POST $ANTHROPIC_BASE_URL/v1/messages——再手写一层会变成 …/v1/v1/messages。统一网关也要按客户端分协议取根,不能把 Cursor 地址原样粘到 Claude Code。
2. 对照表:Cursor / Claude Code / Codex
| 客户端 | 配置项(以官方现行文案为准) | 是否带 /v1 | 占位示例 |
|---|---|---|---|
| Cursor | Settings → Models → API Keys;开启 Override OpenAI Base URL;密钥填该端点签发的 Key;需要时再 Add Custom Model | 通常要带 | https://api.example.com/v1 |
| Claude Code | ANTHROPIC_BASE_URL;凭证用 ANTHROPIC_AUTH_TOKEN(Bearer)或 ANTHROPIC_API_KEY(x-api-key) | 通常不带(根地址) | https://api.example.com |
| Codex CLI | ~/.codex/config.toml 里 [model_providers.xxx] 的 base_url,并设 model_provider | 通常要带 | https://api.example.com/v1;Azure:https://YOUR_RESOURCE.openai.azure.com/openai/v1 |
能力边界:
- Cursor: Override 主要服务本地 Chat / Agent;Tab、Auto、Cloud/CLI 等仍可能走 Cursor 自身路由。无 Override 开关时可能是版本或套餐不支持。Agent 有时走 Responses,Chat 常走 Chat Completions。
- Claude Code: 改请求终点,不是换模型名。可用
/status看 base URL 与凭证来源;Bearer 与x-api-key选错常见持续401。 - Codex: Microsoft Learn / NVIDIA NIM 要求
base_url含/v1;env_key只能写环境变量名;Responses 场景常用wire_api = "responses"。漏/v1常见连不上或超时。
不要把 …/v1/chat/completions 或 …/v1/messages 整段填进 Base URL——客户端还会再拼,双路径是 404 高发原因。
3. 验证三步
- 最小请求: OpenAI 兼容对
…/v1/models做带授权 GET;Claude Code 对$ANTHROPIC_BASE_URL/v1/messages发max_tokens: 1的 POST。返回msg_类 JSON 说明链路通;「未知模型」多半改模型 ID;401先换凭证变量种类。 - 流式: 开流式对话。长时间无输出或半截断开,查网关缓冲、超时与空闲探测。
- 工具调用: 让 Agent 读本地文件或跑无害命令。Codex 依赖 Responses + tools;未通时常见「只描述命令不执行」。
三步都过再谈复杂任务;勿用第一次长任务同时调试路径、模型和权限。
4. 排查五步(401 / 404)
- 重复或缺失
/v1:Claude Code 多写会变成…/v1/v1/messages;Cursor / Codex 漏写会打错路径。对照表改完后重做最小请求。 - 模型 ID:展示名≠请求体
model;从/v1/models或控制台抄确切 ID。 - Key 来源:Cursor 填该兼容端点签发的 Key;Claude Code 分清 Bearer /
x-api-key;Codex 的env_key与已 export 变量名一致。 - 未加载新配置:新开终端或重启 IDE;Claude Code 看
/status;Codex 确认~/.codex/config.toml且model_provider指向新段。桌面启动的编辑器可能读不到终端 export。 - 协议混用:Anthropic 根填进 Cursor Override,或 OpenAI
…/v1填进ANTHROPIC_BASE_URL,常见持续 404/400——按表换协议。
5. 安全边界
- 联调用测试 Key,设额度与告警;勿用生产主密钥。
- 密钥放环境变量或本机密钥管理;勿进仓库、截图、公开 Issue。
- 勿把登录 Cookie、主密码或未脱敏客户数据塞进网关测试。
- Cursor 自定义 Base URL 时请求仍可能经其服务端转发;内网网关需确认可达与合规。
- 测完轮换测试 Key;演示用独立项目与配额。
相关阅读
核验与来源
- 核验日期: 2026-11-07(Asia/Shanghai)
- Claude Code env-vars · gateway connect · gateway protocol
- Cloudflare Cursor Override · OpenAI Help / Cursor
- OpenAI API Overview · Microsoft Codex
/v1· NVIDIA NIM Codex