Tutoriels et astuces

【常青】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;演示用独立项目与配额。

相关阅读

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

核验与来源

Cet article n'est pas encore traduit ; le texte original chinois est affiché.

En bref

Publié
Source
Orange News Editorial / vendor docs
Catégorie
Tutoriels et astuces
Sujet
Actualité du secteurTutoriels et pratique
Pourquoi c'est important

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

Sujets

Entités associées

Comment citer

Pour citer cet article, conservez le titre, la date et le lien permanent, et indiquez Orange News comme source.

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

Tout voir →