很多开发者第一次接入 Claude API 中转服务，并不是因为 API Key 错了，也不是模型名填错了，而是 Base URL 配置错误。

我们最近统计了数百个用户工单后发现，超过 60% 的配置失败，都和 Base URL 有关。

有人少写了 /v1，返回 404。有人多写了 /v1，Claude Desktop 一直报错。还有人直接把 /chat/completions 整个复制进去，结果所有请求全部失败。实际上，不同的软件使用的是不同 SDK。

同样都是 Claude API，有的软件走 OpenAI Compatible 协议，有的软件走 Anthropic 原生协议，因此 Base URL 的填写方式完全不同。

为了避免大家继续踩坑，我们把目前开发者最常用的七款工具全部重新测试了一遍，包括：

• Cursor

• Cline

• Dify

• ChatBox

• Cherry Studio

• Open WebUI

• Claude Desktop

所有配置全部重新验证，并整理出这份可以直接照着填写的完整教程。如果你第一次接触 Claude API，看完这篇文章，基本 30 分钟以内就可以完成全部配置。

---

一张表先看懂：不同工具 Base URL 应该怎么填

很多人其实不用看完整篇。先找到自己的软件即可。

工具	Base URL	是否需要 /v1
Cursor	https://gw.claudeapi.com/v1	✅ 需要
Cline	https://gw.claudeapi.com/v1	✅ 需要
Dify	https://gw.claudeapi.com/v1	✅ 需要
ChatBox	https://gw.claudeapi.com/v1	✅ 需要
Cherry Studio	https://gw.claudeapi.com/v1	✅ 需要
Open WebUI	https://gw.claudeapi.com/v1	✅ 需要
Claude Desktop	https://gw.claudeapi.com	❌ 不需要

记住一句话即可：

所有使用 OpenAI Compatible SDK 的工具，Base URL 都填写 /v1。

只有 Claude Desktop 使用 Anthropic SDK，不需要 /v1。

很多人的问题，到这里其实已经解决了。

---

为什么 Base URL 经常配错？

很多开发者觉得：

Base URL 不就是网址吗？

其实不是。真正决定填写方式的是 SDK。目前主流只有两种协议：

第一种：OpenAI Compatible

例如：

• Cursor

• Cline

• Dify

• ChatBox

• Cherry Studio

• Open WebUI

它们内部都会自动拼接：

/chat/completions

因此 Base URL 只需要填写：

https://gw.claudeapi.com/v1

SDK 最终请求：

https://gw.claudeapi.com/v1/chat/completions

完全正确。

---

第二种：Anthropic SDK

目前只有：Claude Desktop它自己会自动请求：

/v1/messages

所以 Base URL 必须填写：

https://gw.claudeapi.com

最终实际请求：

https://gw.claudeapi.com/v1/messages

如果这里再加一个 /v1

最后请求会变成：

https://gw.claudeapi.com/v1/v1/messages

直接返回：

404 Not Found

这也是很多人配置 Claude Desktop 一直失败的真正原因。

---

Cursor 配置教程（最详细）

Cursor 是目前使用最多的 Claude Code IDE。整个配置只需要一分钟。

第一步

打开：

File

↓

Preferences

↓

Cursor Settings

进入：

Models

页面。

---

第二步

API Provider选择：

OpenAI Compatible

注意：

不要选择 Anthropic。

否则不会出现 Base URL。

---

第三步

填写如下：

字段	内容
Base URL	https://gw.claudeapi.com/v1
API Key	sk-xxxxxxxx
Model	claude-haiku-4-5-20251001

---

第四步

点击：

Verify

如果右边出现：

✓ Verified

说明连接成功。

---

Terminal 验证

如果 Verify 一直失败，可以直接 Terminal 测试：

curl https://gw.claudeapi.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"

如果返回：

{
  "object":"list",
  "data":[
      {
          "id":"claude-haiku-4-5-20251001"
      }
  ]
}

说明接口完全正常。问题就是 Cursor 配置。

---

常见错误

① 401 Unauthorized

原因：API Key 错误。

重新复制。不要复制到空格。

---

② 404 Not Found

99% 是：

https://gw.claudeapi.com

少写了：

/v1

改成：

https://gw.claudeapi.com/v1

即可。

---

Cline 配置教程

Cline 和 Cursor 基本一致。进入：

VSCode

↓

Cline

↓

Settings

填写：

字段	内容
API Provider	OpenAI Compatible
Base URL	https://gw.claudeapi.com/v1
API Key	sk-xxxx
Model	claude-haiku-4-5-20251001

保存即可。

---

注意：Model 一定要自己输入。不是下拉选择。

例如：

claude-haiku-4-5-20251001

不要少一个字符。

---

Terminal 测试

可以直接：

curl https://gw.claudeapi.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model":"claude-haiku-4-5-20251001",
"messages":[
{
"role":"user",
"content":"Hello"
}
]
}'

如果返回：

choices

说明配置没有问题。

---

Dify 配置教程

很多企业都在使用 Dify。这里最容易填错的是：API Base URL。很多人喜欢写：

https://gw.claudeapi.com/v1/chat/completions

这是错误的。应该写：

https://gw.claudeapi.com/v1

Dify 自己会拼接。

---

配置如下：

字段	内容
Provider	OpenAI Compatible
API Base URL	https://gw.claudeapi.com/v1
API Key	sk-xxxx

保存。然后新增模型：

claude-haiku-4-5-20251001

即可。

---

Terminal 测试

建议直接：

curl https://gw.claudeapi.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"

如果模型能够返回：说明 Dify 配置一定可以成功。

---

Claude Desktop 配置教程（最容易踩坑）

这是所有工具里面最特殊的。因为：不能加 /v1

配置文件位置：

Windows：

%APPDATA%\Claude\claude_desktop_config.json

Mac：

~/Library/Application Support/Claude/

配置如下：

{
  "apiSettings": {
    "baseUrl": "https://gw.claudeapi.com",
    "apiKey": "你的API Key"
  },
  "mcpServers": {}
}

注意这里千万不要写：

https://gw.claudeapi.com/v1

否则Claude Desktop 会一直提示：

404 API Error

---

Terminal 测试

Claude Desktop 使用Anthropic 协议。

验证命令：

curl https://gw.claudeapi.com/v1/messages \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model":"claude-haiku-4-5-20251001",
"max_tokens":100,
"messages":[
{
"role":"user",
"content":"Hello"
}
]
}'

如果返回：

content

说明配置成功。

---

ChatBox 配置教程

ChatBox 最大的问题不是 Base URL。

而是：

很多人 Provider 选错。

必须选择：

OpenAI API

不要选：

Claude API

然后填写：

字段	内容
API Host	https://gw.claudeapi.com/v1
API Key	sk-xxxx
Model	claude-haiku-4-5-20251001

点击：

Check Connection

看到：

Connection successful

即可。

---

Cherry Studio 配置教程

Cherry Studio 配置方式基本一致。新增 Provider：

OpenAI Compatible

填写：

API Address

↓

https://gw.claudeapi.com/v1

API Key：

sk-xxxx

新增模型：

claude-haiku-4-5-20251001

即可。

---

Open WebUI 配置教程

管理员后台：

Admin Panel

↓

Connections

↓

OpenAI

填写：

https://gw.claudeapi.com/v1

保存即可。随后执行：

curl https://gw.claudeapi.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"

如果可以列出：

data

说明Open WebUI 可以正常调用。

---

一分钟排查所有配置错误

如果一直连接失败，可以按下面顺序排查。

第一项

先验证接口：

curl https://gw.claudeapi.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"

如果失败，不是软件问题。

先检查：

• API Key

• 网络

• Base URL

---

第二项

确认模型名称。推荐：

claude-haiku-4-5-20251001

不要：

haiku

Claude

Sonnet

必须完整名称。

---

第三项

确认 URL。不要：

https://gw.claudeapi.com

（OpenAI Compatible）也不要：

https://gw.claudeapi.com/v1/

（末尾不要斜杠）正确：

https://gw.claudeapi.com/v1

---

最终验证（建议每个人都执行一次）

获取模型：

curl https://gw.claudeapi.com/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"

发送测试：

curl https://gw.claudeapi.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model":"claude-haiku-4-5-20251001",
  "messages":[
    {
      "role":"user",
      "content":"请用一句话介绍你自己。"
    }
  ]
}'

如果返回：

{
  "choices":[
    {
      "message":{
        "content":"你好，我是 Claude ..."
      }
    }
  ],
  "usage":{
    "prompt_tokens":...,
    "completion_tokens":...
  }
}

说明：

• Base URL 正确

• API Key 正确

• 模型正确

• 网络正常

• 接口可以正式投入使用

常见问题（FAQ）

Q1：为什么 Cursor 要加 /v1？

因为 Cursor 使用 OpenAI Compatible SDK，SDK 会自动拼接 /chat/completions，所以 Base URL 必须包含 /v1。

Q2：为什么 Claude Desktop 不加 /v1？

Claude Desktop 使用 Anthropic 原生 SDK，内部请求的是 /v1/messages，如果 Base URL 再写 /v1，最终会变成 /v1/v1/messages，直接返回 404。

Q3：Base URL 后面需要加 /chat/completions 吗？

不需要。所有 OpenAI Compatible 工具只填写：

https://gw.claudeapi.com/v1

具体接口路径由 SDK 自动拼接。

Q4：可以多个工具共用同一个 API Key 吗？

可以。同一个 API Key 可以同时在 Cursor、Cline、Dify、ChatBox、Cherry Studio、Open WebUI 等多个客户端使用，请求会统一计费。

Q5：为什么提示连接成功，但发送消息失败？

连接成功通常只代表 API Key 验证通过，仍需确认模型名称填写正确、账号已启用对应模型，并检查账户余额是否充足。

---

总结

实际上，七款工具的配置逻辑并不复杂，只需要记住一条核心规则即可：

• OpenAI Compatible SDK（Cursor、Cline、Dify、ChatBox、Cherry Studio、Open WebUI）统一填写：https://gw.claudeapi.com/v1

• Anthropic 原生 SDK（Claude Desktop）填写：https://gw.claudeapi.com（不要添加 /v1）

在实际排查过程中，建议优先使用本文提供的 curl 命令验证接口是否连通，再检查 Base URL、API Key 和模型名称，这样往往几分钟内就能定位绝大多数配置问题，大大减少调试时间。