Tutoriales y consejos

【常青】Cursor / Claude Code / Codex:Base URL 该不该带 /v1?一张表说清

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 MessagesClaude 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占位示例
CursorSettings → Models → API Keys;开启 Override OpenAI Base URL;密钥填该端点签发的 Key;需要时再 Add Custom Model通常要带https://api.example.com/v1
Claude CodeANTHROPIC_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. 验证三步

  1. 最小请求: OpenAI 兼容对 …/v1/models 做带授权 GET;Claude Code 对 $ANTHROPIC_BASE_URL/v1/messages 发 max_tokens: 1 的 POST。返回 msg_ 类 JSON 说明链路通;「未知模型」多半改模型 ID;401 先换凭证变量种类。
  2. 流式: 开流式对话。长时间无输出或半截断开,查网关缓冲、超时与空闲探测。
  3. 工具调用: 让 Agent 读本地文件或跑无害命令。Codex 依赖 Responses + tools;未通时常见「只描述命令不执行」。

三步都过再谈复杂任务;勿用第一次长任务同时调试路径、模型和权限。

4. 排查五步(401 / 404)

  1. 重复或缺失 /v1:Claude Code 多写会变成 …/v1/v1/messages;Cursor / Codex 漏写会打错路径。对照表改完后重做最小请求。
  2. 模型 ID:展示名≠请求体 model;从 /v1/models 或控制台抄确切 ID。
  3. Key 来源:Cursor 填该兼容端点签发的 Key;Claude Code 分清 Bearer / x-api-key;Codex 的 env_key 与已 export 变量名一致。
  4. 未加载新配置:新开终端或重启 IDE;Claude Code 看 /status;Codex 确认 ~/.codex/config.toml 且 model_provider 指向新段。桌面启动的编辑器可能读不到终端 export。
  5. 协议混用:Anthropic 根填进 Cursor Override,或 OpenAI …/v1 填进 ANTHROPIC_BASE_URL,常见持续 404/400——按表换协议。

5. 安全边界

  • 联调用测试 Key,设额度与告警;勿用生产主密钥。
  • 密钥放环境变量或本机密钥管理;勿进仓库、截图、公开 Issue。
  • 勿把登录 Cookie、主密码或未脱敏客户数据塞进网关测试。
  • Cursor 自定义 Base URL 时请求仍可能经其服务端转发;内网网关需确认可达与合规。
  • 测完轮换测试 Key;演示用独立项目与配额。

相关阅读

怎么选大模型?按任务做同题测试

核验与来源

Este artículo aún no está traducido; se muestra el texto original en chino.

Resumen rápido

Publicado
Fuente
Orange News Editorial / vendor docs
Categoría
Tutoriales y consejos
Tema
Actualidad del sectorTutoriales y práctica
Por qué importa

对照三类客户端的 Base URL 配置,分清协议与路径,再按最小请求、流式和工具调用逐步排查。

Temas

Entidades relacionadas

Cómo citar

Al citar este artículo, conserva el título, la fecha y el enlace permanente, e indica que la fuente es Orange News.

Orange News: 【常青】Cursor / Claude Code / Codex:Base URL 该不该带 /v1?一张表说清. 7. noviembre 2026. https://new.nat6.net/es/news/custom-e410786ad6764d07/

Ver todo →