Claude Code、Cursor 接入自定义 API 网关时，Base URL 应该怎么填？

故乡de云

17人浏览 · 2026-06-24 17:45:18

故乡de云 · 2026-06-24 17:45:18 发布

在配置 Claude Code、Cursor、ChatGPT 客户端、Codex、LangChain、OpenAI SDK，或者各种 OpenAI-compatible API 网关时，很多开发者都会卡在同一个字段上：

Base URL

它看起来只是一个接口地址，但一旦填错，问题会非常分散：可能是 401 Unauthorized，也可能是 403 Forbidden、404 Not Found、429 Too Many Requests，还可能提示“模型不存在”“请求失败”“无法连接服务”。

更麻烦的是，不同工具对 Base URL 的要求并不完全一致。有的要求只填域名，有的要求带 /v1，有的配置项看起来像 Base URL，实际却要求完整 Endpoint。

这篇文章重点解决一个实际问题：

在 Claude Code、Cursor、OpenAI SDK、Anthropic API 网关或 OpenAI-compatible 服务里，Base URL 到底应该填到哪一层？

1. Base URL 是什么？

Base URL 可以理解为 API 请求的“基础地址”。

客户端不会只依赖 Base URL 发请求，它通常会在 Base URL 后面继续拼接具体接口路径，例如：

/chat/completions
/models
/embeddings
/messages
/v1/messages
/v1/chat/completions

以 OpenAI-compatible 风格接口为例，一个完整请求大概长这样：

https://api.example.com/v1/chat/completions

可以拆成三部分：

https://api.example.com      /v1        /chat/completions
        域名                 版本号          具体接口路径

所以，Base URL 不一定等于完整请求地址。

常见可能填写的形式有三种：

https://api.example.com

https://api.example.com/v1

https://api.example.com/v1/chat/completions

真正要判断的是：

当前工具会不会自动补 /v1？
当前工具会不会自动补 /chat/completions、/models、/messages 这类具体路径？

2. Base URL、Endpoint、Model、API Key 的区别

在配置 Claude Code、Cursor 或 SDK 时，通常会遇到几个容易混淆的字段。

字段	作用	示例
Base URL	API 请求的基础地址	`https://api.example.com/v1`
Endpoint	完整接口地址	`https://api.example.com/v1/chat/completions`
API Key	鉴权密钥	`sk-xxx` 或平台生成的密钥
Model	调用的模型名称	`gpt-xxx`、`claude-xxx` 或服务商模型名

最常见的错误是：

把完整 Endpoint 填进 Base URL
把 API Key 填进 Base URL
Base URL 对了，但模型名填错
工具已经自动补 /v1，用户又手动写了一次 /v1

3. 三种常见填写方式

3.1 只填域名

有些工具或平台已经封装好了 API 版本和具体路径，只要求你填写服务域名。

示例：

https://api.example.com

如果工具内部会自动拼接 /v1/chat/completions，那么最终请求会变成：

https://api.example.com/v1/chat/completions

这是正常的。

但如果你手动写成：

https://api.example.com/v1

工具又自动补一次 /v1，最终可能变成：

https://api.example.com/v1/v1/chat/completions

这种情况通常会导致 404 Not Found。

比较容易只填域名的场景：

场景	示例	注意点
文档明确写“服务域名”	`https://api.example.com`	不要自行追加 `/v1`
配置项叫 `Host` 或 `Domain`	`https://api.example.com`	通常不是完整接口路径
本地代理已经映射好路径	`http://localhost:3000`	要确认代理内部如何转发

3.2 填到 `/v1`

很多 OpenAI-compatible 工具和 SDK 更常见的写法，是把 Base URL 填到版本层级。

示例：

https://api.example.com/v1

然后 SDK 或工具会继续拼接具体接口：

/chat/completions
/models
/embeddings

最终请求变成：

https://api.example.com/v1/chat/completions

OpenAI SDK 中也常见这种写法：

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.example.com/v1"
)

这里不要把 base_url 写成：

https://api.example.com/v1/chat/completions

因为 SDK 会根据你调用的方法自动拼接接口路径。

例如：

client.chat.completions.create(...)

SDK 会自己请求类似：

/v1/chat/completions

如果你提前把 /chat/completions 写进 base_url，就可能变成：

https://api.example.com/v1/chat/completions/chat/completions

3.3 填完整 Endpoint

完整 Endpoint 通常长这样：

https://api.example.com/v1/chat/completions

这种地址一般不应该填进 Base URL，除非配置项明确写的是：

Endpoint
Request URL
接口地址
完整请求地址

例如某些低代码工具、Webhook 工具、HTTP 请求组件，可能确实要求你填完整接口地址。

判断规则可以简单记成：

配置项名称	更可能填写	示例
`Base URL` / `API Base` / `base_url`	基础地址	`https://api.example.com/v1`
`Endpoint` / `Request URL` / `接口地址`	完整路径	`https://api.example.com/v1/chat/completions`
`Host` / `Domain` / `服务域名`	域名	`https://api.example.com`

4. Claude Code、Cursor、SDK 为什么填法不一样？

很多人会直接复制别人截图里的配置，但同一个服务，在不同工具里的填写方式可能不一样。

原因是：

不同工具自动拼接路径的程度不同。

一个 AI 工具发起请求时，至少需要这些信息：

Base URL
API Key
Model

其中：

Base URL 决定请求发到哪里
API Key 决定是否有权限
Model 决定调用哪个模型
Endpoint 决定实际访问哪个接口

有些工具内部已经写死了 OpenAI 风格路径，只让你替换前面的服务地址。

有些工具更底层，需要你填写带版本号的 API Base。

还有一些工具为了兼容 OpenAI、Anthropic、本地模型网关，会在不同模式下使用不同的路径规则。

所以同一个 API 服务，可能在 A 工具里填：

https://api.example.com

在 B 工具里填：

https://api.example.com/v1

这并不一定是谁错了，而是两个工具的路径拼接规则不同。

5. OpenAI-compatible 和 Anthropic API 网关的差异

OpenAI-compatible 通常表示请求格式尽量兼容 OpenAI API，例如：

/v1/chat/completions
/v1/models

Anthropic API 或 Claude Code 相关配置中，则可能涉及另一类路径，例如：

/v1/messages

或者工具内部封装后的 Anthropic-compatible 接口。

需要注意：

项目	OpenAI-compatible	Anthropic / Claude 相关接口
常见聊天接口	`/v1/chat/completions`	`/v1/messages`
常见模型名	`gpt-xxx` 或服务商模型名	`claude-xxx` 或服务商模型名
SDK 参数	常见 `base_url`	取决于工具或 SDK
鉴权方式	常见 Bearer Key	通常也需要 Key，但以文档为准

第三方兼容网关不等于官方服务。实际 Base URL、模型名、额度、线路、鉴权方式，都应该以服务商文档或控制台为准。

不要只看“兼容 OpenAI”或“兼容 Claude”这几个字，就默认路径、模型名、权限完全一致。

6. 推荐的配置顺序

为了减少排错成本，建议不要一开始就把所有参数都填上。

更稳的顺序是：

先确认接口类型
再确认 Base URL 层级
再验证 API Key
再确认模型名
最后配置高级参数

也就是：

1. 判断是 OpenAI 官方、OpenAI-compatible，还是 Anthropic-compatible
2. 判断工具要求域名、/v1，还是完整 Endpoint
3. 用最小请求测试接口连通性
4. 再填入 Cursor、Claude Code、Codex 或 SDK
5. 最后调整温度、上下文、代理、并发等参数

很多配置失败并不是 Base URL 本身复杂，而是所有参数一起改，最后无法判断到底是哪一项出错。

7. 用 curl 验证 OpenAI-compatible 接口

如果使用 OpenAI-compatible 服务，可以先测试模型列表接口。

curl https://api.example.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

如果接口正常，通常会返回模型列表。

如果模型列表接口不可用，也可以直接发一个最小聊天请求：

curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "messages": [
      {
        "role": "user",
        "content": "ping"
      }
    ]
  }'

这里需要替换三项：

https://api.example.com/v1
YOUR_API_KEY
YOUR_MODEL_NAME

如果这个请求能正常返回结果，说明：

Base URL 大概率正确
API Key 可以通过鉴权
模型名基本可用
服务本身可访问

然后再把配置迁移到 Cursor、Claude Code、Codex 或其他客户端里，会更容易定位问题。

8. 用 curl 验证 Anthropic-compatible 接口

如果你配置的是 Claude Code 或 Anthropic-compatible 网关，需要特别注意接口路径和请求格式。

常见 Anthropic Messages API 风格可能类似：

curl https://api.example.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "max_tokens": 128,
    "messages": [
      {
        "role": "user",
        "content": "ping"
      }
    ]
  }'

但不同兼容网关的鉴权 Header、版本字段、路径规则可能不同。

所以这里不要机械照抄，要重点确认服务商文档中的几项：

Base URL
Endpoint
鉴权 Header
模型名
是否需要版本 Header

如果服务商提供的是 OpenAI-compatible Claude 接入方式，那也可能继续使用：

/v1/chat/completions

而不是：

/v1/messages

最终以服务商文档为准。

9. 环境变量配置示例

很多命令行工具和 SDK 支持通过环境变量读取配置。

常见 OpenAI-compatible 配置形式：

export OPENAI_API_KEY="YOUR_API_KEY"
export OPENAI_BASE_URL="https://api.example.com/v1"

有些工具使用的是：

export OPENAI_API_BASE="https://api.example.com/v1"

或者：

export BASE_URL="https://api.example.com/v1"

Claude 或 Anthropic 相关工具可能使用：

export ANTHROPIC_API_KEY="YOUR_API_KEY"
export ANTHROPIC_BASE_URL="https://api.example.com"

具体变量名要看工具文档。

需要重点确认两件事：

1. 工具实际读取的是哪个环境变量名
2. 该变量要求填写域名、/v1，还是完整 Endpoint

如果配置了多个环境变量，还要注意优先级。例如：

export OPENAI_BASE_URL="https://api.a.com/v1"
export OPENAI_API_BASE="https://api.b.com/v1"

不同工具可能读取不同变量，导致你以为改了配置，实际请求还是发到了旧地址。

10. 常见报错与排查方法

Base URL 配错时，错误信息不一定直接提示“URL 错误”。可以先根据状态码排查。

报错	优先检查	常见原因	修正方向
`401 Unauthorized`	API Key	Key 错误、没填、格式不对	重新生成 Key，确认工具是否自动加 Bearer
`403 Forbidden`	权限	服务未开通、账号无权限、区域或策略限制	检查账号状态、模型权限、服务权限
`404 Not Found`	Base URL / Endpoint / Model	多写 `/v1`、少写 `/v1`、路径写太长、模型名不存在	对照工具规则和服务商文档
`429 Too Many Requests`	频率和额度	请求太快、并发过高、额度不足	降低频率，检查额度和限流规则

其中 404 最容易误判。

它可能是 Base URL 错了，例如：

https://api.example.com/v1/v1/chat/completions

也可能是 Endpoint 拼重复了：

https://api.example.com/v1/chat/completions/chat/completions

还可能是模型名不支持。

例如你配置：

Base URL: https://api.example.com/v1
Model: gpt-4o-mini

如果第三方服务并不支持 gpt-4o-mini 这个模型名，即使 Base URL 完全正确，也可能返回模型不存在或 404。

所以排查 404 时，不要只看 URL，也要同时检查模型名。

11. 五个高频误区

11.1 重复写 `/v1`

错误情况：

工具自动补 /v1
用户又填写 https://api.example.com/v1
最终变成 https://api.example.com/v1/v1/...

如果文档要求填写服务域名，应填写：

https://api.example.com

而不是：

https://api.example.com/v1

11.2 把完整接口路径当成 Base URL

错误示例：

https://api.example.com/v1/chat/completions

如果配置项叫 Base URL，多数情况下应填写：

https://api.example.com/v1

具体的 /chat/completions 通常由 SDK 或工具自动拼接。

11.3 只改 Base URL，不改模型名

第三方 OpenAI-compatible 或 Anthropic-compatible 服务不一定支持官方模型名。

有些服务会使用自定义模型名或模型别名。

Base URL 对了，但模型名错了，请求仍然会失败。

建议直接到服务商控制台或文档确认可用模型名，不要凭经验填写。

11.4 把 API Key 当成 Base URL

Base URL 是网址，通常以：

https://

开头。

API Key 是密钥，通常是一串字符，例如：

sk-...

两者不能混用。

11.5 把一个工具的配置套到所有工具

同一个 API 服务，在不同工具里可能有不同填法：

工具类型	可能要求
SDK	通常填 `.../v1`
桌面客户端	可能填域名或 `/v1`
浏览器插件	可能填完整 Endpoint
命令行工具	可能通过环境变量读取
本地代理	取决于代理如何映射路径

不要只复制别人的配置截图，关键要看当前工具如何拼接路径。

12. 不同场景下怎么填

场景	填写建议	容易犯错点
OpenAI 官方 API + SDK	通常使用 `https://api.openai.com/v1`	不要写完整 `/chat/completions`
OpenAI-compatible 第三方接口 + SDK	通常使用服务商提供的 `.../v1` 地址	模型名不一定等于 OpenAI 官方模型名
Cursor 等可视化工具要求 OpenAI Base URL	优先看是否要求带 `/v1`	重复 `/v1` 很常见
工具要求 API Host 或服务域名	通常只填域名	不要自行追加版本号
工具要求 Endpoint URL	可能需要完整接口路径	不要把 Endpoint 和 Base URL 混用
Claude Code 接入自定义网关	按网关文档确认 Base URL、Endpoint、模型名和鉴权方式	不要默认等同于 Anthropic 官方接口
本地代理或自建网关	按网关暴露的路径填写	注意网关是否已经映射 `/v1`

一个实用判断规则是：

如果工具会拼具体接口路径，Base URL 就不要写到 /chat/completions。
如果工具会自动补 /v1，Base URL 就不要再写 /v1。
如果工具什么都不补，才需要填写更完整的 Endpoint。

13. 最小自检清单

配置前可以按这个清单检查：

1. 当前接口是 OpenAI 官方、OpenAI-compatible，还是 Anthropic-compatible？
2. 工具配置项叫 Base URL、Endpoint，还是 Host？
3. 工具是否自动补 /v1？
4. 工具是否自动补 /chat/completions 或 /messages？
5. API Key 是否正确？
6. 鉴权 Header 是否符合要求？
7. 模型名是否是服务商支持的模型名？
8. 当前账号是否有该模型权限？
9. 是否触发额度或频率限制？

建议先用 curl 跑通最小请求，再填入工具。

不要一开始就同时配置代理、插件、函数调用、上下文长度、并发、温度等高级参数。

14. 总结

Base URL 不是越完整越好，而是要填到工具期望的层级。

配置 Claude Code、Cursor、Codex、OpenAI SDK 或自定义 API 网关时，可以按这个顺序判断：

先看接口类型：OpenAI-compatible 还是 Anthropic-compatible
再看配置项名称：Base URL、Endpoint 还是 Host
再看工具规则：是否自动补 /v1 和具体接口路径
然后验证：API Key、模型名、权限、额度和限流

如果只记一句话：

Base URL 的正确写法，取决于工具会帮你自动拼接多少路径。

如果需要了解 ClaudeAPI 这类第三方 Claude API 兼容接入服务，可看作者主页，具体配置与可用能力以官网最新说明为准。

https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

Anthropic 重磅发布 Claude Tag，AI 不再只是助手，而是你的 Slack 团队队友

AI编程社区

别再做通用AI面试工具！个人求职数据资产，才是面试产品真正的护城河

市面上绝大多数AI模拟面试产品，本质只是套壳大模型对话工具：不管是谁打开，问的都是千篇一律的八股、通用项目问题。用户换个ChatGPT、豆包、通义千问照样能实现同类功能，完全没有差异化壁垒。真正能锁住用户、形成长期留存的核心竞争力，从来不是“AI能模拟面试官”，而是沉淀用户专属求职数据资产，基于个人独有资产生成千人千面的定制化面试。下文结合Java后端求职赛道产品「码上面试」，完整拆解资产驱动型A