# LobeChat 接入

> **最后核实**：2026-10-13 · 📄 依据官方文档（LobeHub v2.2.19）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（Anthropic 服务商 + Proxy URL）· GPT ✅ · 国产模型 ✅（OpenAI 服务商 + Proxy URL）· Gemini ❌（QCode 暂不提供 Gemini 系列，请使用 Claude、GPT 或国产模型） |
| 协议与 Proxy URL | Anthropic Messages：`https://api.qcode.cc/api` · OpenAI 兼容：`https://api.qcode.cc/openai/v1` |
| 配置入口 | App Settings → AI Providers，选中服务商后填 API Key、**Proxy URL**，再点 **Check** |
| 自部署路径 | 不走界面，改用环境变量 `ANTHROPIC_PROXY_URL` 与 `OPENAI_PROXY_URL` |
| 官方文档 | [AI Model Providers](https://lobehub.com/docs/usage/providers) |

这个应用如今以 **LobeHub** 名义发布，官方概览页仍写着多模型的起点是 "began with LobeChat's multi-model support"；文档站、桌面安装包、`lobehub/lobehub` 镜像与开源 Community Edition 都在这个名字下，搜 LobeChat 落到的也是 LobeHub。

## 用哪条协议

| 想用的模型 | 启用的服务商 | Proxy URL |
|---|---|---|
| Claude（`claude-sonnet-5`、`claude-opus-5`、`claude-haiku-5-5`） | **Anthropic** | `https://api.qcode.cc/api` |
| GPT（`gpt-6-sol`、`gpt-5.6-terra`） | **OpenAI** | `https://api.qcode.cc/openai/v1` |
| 国产模型（`deepseek-v4.1-flash`、`glm-5.3`、`qwen3.8-max`、`kimi-k3`） | **OpenAI** | `https://api.qcode.cc/openai/v1` |

🔴 **绝不要用 OpenAI 服务商调用 Claude。** QCode 只在 Anthropic 端点上提供 Claude；`claude-*` 写进 OpenAI 兼容端点会被拒绝，反过来 `gpt-*` 也走不了 Anthropic 端点。一把 QCode 密钥（`cr_` 开头）两边通用。

Proxy URL 照上表逐字填：**结尾不要斜杠**，也不要把 `/v1/chat/completions` 这类完整请求路径填进输入框——官方对这个字段的定义是 "the provider API base URL or a compatible endpoint"。Anthropic 侧是否还需要额外路径段，官方未说明，因此按 QCode 给出的地址原样填。详见 [接入点与 API 路径](/docs/getting-started/endpoints-and-api-paths)。

## 安装

先决定用哪种形态，密钥填在哪里随之确定。

- **桌面端 / 网页端**——官方说法是 "Download the macOS, Windows, or Linux app from the official download page"，桌面端基于 Electron；网页端 "Open LobeHub in a modern browser" 即可。密钥与 Proxy URL 走下面小节的界面字段。
- **自部署，单个 Docker 镜像**（官方命令，环境变量放在 env 文件里）：

```bash
docker run -it -d -p 3210:3210 --network pg --env-file lobehub.env --name lobehub lobehub/lobehub
```

- **自部署，Docker Compose**（官方脚本 + compose）：

```bash
mkdir lobehub && cd lobehub
bash <(curl -fsSL https://lobe.li/setup.sh) -l en
docker compose up -d
```

如果要让桌面端连你自己的实例，桌面文档要求 "your self-hosted instance version is 1.83.6 or higher to support desktop" 连接功能：点右上角的 Wi-Fi 图标，填实例地址，再连接。同一篇文档还要求：连接之前，自部署实例要 "correctly configured with the OIDC-related environment variables"。本页核对的服务端版本是 v2.2.19（2026-10-07 发布）；1.83.6 只是桌面文档引用的数字，两者不是同一个版本号。

于是本页有两条路径：**云端与桌面端用界面字段**，**自部署用环境变量**。

## 配置

官方明确字段随服务商而变："Open App Settings → AI Providers, then select the provider you want to configure. The available fields depend on the provider"。文档给出的顺序是 "Select a provider from the list and turn on its switch"，接着 "Enter the credentials shown on the page. Most cloud providers use an API key"，再 "If Proxy URL is available, enter the provider API base URL or a compatible endpoint"，然后 "Select Check to test the connection"，最后 "Enable a model in the model list. You can also fetch or add models when those actions are available."，并补一句 "Your changes are saved automatically. You can then select the provider and model in the Agent settings."

两点要说清楚。第一，官方措辞是条件式的——*If Proxy URL is available*——所以本页不断言每个服务商都有这个字段，官方也没有云端与桌面端的字段可用对照表；如果你的版本里 Anthropic 或 OpenAI 卡片下看不到 Proxy URL 输入框，这一页无法替你改地址。第二，云端与桌面端并不对立："The desktop app can use Cloud services and cloud models."

### 配置 Claude（Anthropic 服务商）

按官方 Anthropic 页的步骤顺序：

1. "Open App Settings → AI Providers, select Anthropic, and enable the provider"
2. "Enter the API key. If you use a proxy, enter its proxy URL"——填 QCode 的 `cr_` 密钥，Proxy URL 填 `https://api.qcode.cc/api`
3. "Select Check to test the connection"
4. "Enable the Claude models you need, then select one in the Agent settings"

模型 ID 从 QCode 在售名单里挑：日常用 `claude-sonnet-5`，也可用 `claude-sonnet-5-5`，重活用 `claude-opus-5` 或 `claude-opus-5-5`，轻量用 `claude-haiku-5-5`；`claude-sonnet-4-6`、`claude-haiku-4-5-20251001`、`claude-fable-5`、`claude-fable-5-1` 同样可调。本页只覆盖内置的 Anthropic 与 OpenAI 两个服务商；官方还写了别的厂商指引，这里没有逐条核对过。

### 配置 GPT 与国产模型（OpenAI 服务商）

同样的形状，照 OpenAI 官方页的步骤：

1. "Open App Settings → AI Providers, select OpenAI, and enable the provider"
2. "Enter the API key. If you use a proxy or compatible endpoint, enter its proxy URL"——同一把 `cr_` 密钥，Proxy URL 填 `https://api.qcode.cc/openai/v1`
3. "Select Check to test the connection"
4. "Enable the OpenAI models you need, then select one in the Agent settings"

国产模型 ID 走同一个服务商、同一个 Proxy URL：`deepseek-v4.1-flash`、`deepseek-v4-pro`、`glm-5.3`、`qwen3.8-max`、`kimi-k3`，见 [国产模型接入](/docs/usage/cn-models)。为这个目的不必再去配 DeepSeek、Qwen、Moonshot 那些单独指引——一条 OpenAI 兼容地址就能覆盖整张名单。如果内置下拉里没有你要的 ID，就按官方允许的「获取或添加模型」入口自己加。

### 自部署的环境变量

Docker 或 Compose 部署时，同样两个地址按服务商写在 env 文件里。参考页把 `ANTHROPIC_PROXY_URL` 描述为用于 "override the default Anthropic API request base URL"，把 `OPENAI_PROXY_URL` 描述为用于 "override the default OpenAI API request base URL"，正好是界面 Proxy URL 字段的自部署对应物：

| 变量 | 官方默认值 | 填什么 |
|---|---|---|
| `ANTHROPIC_API_KEY` | – | QCode 的 `cr_` 密钥 |
| `ANTHROPIC_PROXY_URL` | `https://api.anthropic.com` | `https://api.qcode.cc/api` |
| `OPENAI_API_KEY` | – | 同一把密钥 |
| `OPENAI_PROXY_URL` | `https://api.openai.com/v1` | `https://api.qcode.cc/openai/v1` |
| `OPENAI_MODEL_LIST` | – | 见下 |
| `ANTHROPIC_CLIENT_TIMEOUT` | `295000` | 除非长请求被截断，否则不动 |

`OPENAI_MODEL_LIST` 的官方说明是 "Used to control the model list"：`+` 添加、`-` 隐藏、`-all` 先隐藏内置全集——端点只服务你点名的模型时用这种写法：

```bash
ANTHROPIC_API_KEY=cr_your_qcode_key
ANTHROPIC_PROXY_URL=https://api.qcode.cc/api
OPENAI_API_KEY=cr_your_qcode_key
OPENAI_PROXY_URL=https://api.qcode.cc/openai/v1
OPENAI_MODEL_LIST=-all,+gpt-6-sol,+gpt-5.6-terra,+glm-5.3,+deepseek-v4.1-flash
```

`/v1` 该不该写在值里取决于端点本身，官方原话是让你 "check the request suffix of your proxy service provider"，并说空回复时试着加上 `/v1` 再试。对 QCode 而言：OpenAI 侧保留 `/openai/v1`，Anthropic 侧只写到 `/api`。参考页还为国产服务列了各自的环境变量（`DEEPSEEK_PROXY_URL`、`QWEN_PROXY_URL`、`MOONSHOT_PROXY_URL`），只有当你故意要让 QCode 挂在那个服务商下时才把它们指向 QCode。

## 验证

界面里的官方检查就是 "Select Check to test the connection"。**本页没有测试密钥，因此不为上面任何一种写法声明 HTTP 结果。** Check 失败时，先修 Proxy URL 与密钥，再动别的东西。

要区分是网关问题还是应用问题，直接请求端点：

```bash
KEY="cr_your_qcode_key"

# Anthropic 端点——只填 Claude ID
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'

# OpenAI 兼容端点——只填 GPT 与国产模型 ID，绝不填 claude-*
curl -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"model":"gpt-6-sol","messages":[{"role":"user","content":"ping"}]}'
```

返回的 JSON 里有 `content`（Anthropic）或 `choices`（OpenAI），说明端点侧已响应，剩下的问题在应用设置里。按 token 计费，各模型单价见 [qcode.cc/models](https://qcode.cc/models)。

## 排查与已知限制

| 现象 | 官方原话 | 怎么做 |
|---|---|---|
| 设了 `OPENAI_PROXY_URL` 后回复为空 | "may encounter a situation where the AI returns an empty message"；官方要求复核变量、确认 `/v1` "suffix is added correctly (if required)" | Proxy URL 逐字用 `https://api.qcode.cc/openai/v1`，结尾不加斜杠 |
| `claude-*` 被拒绝 | — | QCode 的 OpenAI 兼容地址不提供 Claude 家族（`model_not_available_on_endpoint`）；换到 Anthropic 服务商，Proxy URL 用 `https://api.qcode.cc/api` |
| Anthropic 长请求被截断 | `ANTHROPIC_CLIENT_TIMEOUT` 默认 `295000`，且该超时 "is also used by Anthropic-compatible providers that rely on the Anthropic SDK" | 自部署时只为长生成调大 |
| 部署在 Vercel | 有 "10-second serverless function timeout limit" | 按本页的理解：超过这个上限的长回答要改用 Docker 或其它宿主 |
| 某个服务商不可用 | "This does not guarantee automatic failover" | 自己配好第二个服务商，手动切换 |
| 连接报错、密钥被判无效 | "Check your API key for extra spaces. Check that the key type matches the provider" | 重新粘贴 `cr_` 密钥，确认服务商类型 |
| 模型列表里没有你的 ID | "Your account tier can exclude a model, or the provider can retire it" | 对 QCode 而言自己加 ID——内置下拉不等于 QCode 的在售清单 |
| 触发限流 | "You reached the provider's request rate limit" | 降低请求频率，或换服务商 |

QCode 不提供的项目：**gpt-6-luna** 与 **gpt-5.6-luna** 请改用其它 GPT 模型（`gpt-6.1-sol` / `gpt-6-sol` / `gpt-5.6-terra`）；**Gemini 系列**同样暂不提供，请使用 Claude、GPT 或国产模型。若主地址在你的网络里不通，同一把密钥也可用 `https://asia.qcode.cc/api` 与 `https://us.qcode.cc/api`。哪个版本在哪个服务商下会显示 Proxy URL 字段，官方没有说明，这一点不在本页范围内。

## 相关文档

- [接入点与 API 路径](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型族对照
- [工具兼容总览](/docs/ide/tool-compatibility) — 各工具说哪种协议
- [Cherry Studio 接入](/docs/ide/cherry-studio) — 同样两个端点，桌面应用的填法
- [Claude Desktop 接入](/docs/ide/claude-desktop)
- [国产模型接入](/docs/usage/cn-models)
- [模型选型指南](/docs/usage/model-selection)
- [故障排查指南](/docs/reference/troubleshooting)