# 有道龙虾LobsterAI接入

> **最后核实**：2026-11-10 · 📄 依据官方文档（LobsterAI 2026.11.6，2026-11-06 发布：README、用户手册、仓库源码）

LobsterAI（有道龙虾）能不能用自己的 API key？能。截至 2026-11-10，按官方 README、仓库源码与维护者答复：打开 设置 →「自定义模型」，在服务商列表底部点「+ 添加自定义」，「API 格式」选「Anthropic 兼容（Messages）」或「OpenAI 兼容（Chat Completions）」，填上 QCode 的 Base URL 和 `cr_` 密钥，添加模型 ID 后点「测试连接」即可。

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ✅（Anthropic 兼容）· GPT ✅（OpenAI 兼容）· GLM / Kimi / DeepSeek / Qwen ✅（两种都可）· Gemini ❌（QCode 暂不提供） |
| Base URL | Anthropic 兼容（Messages）：`https://api.qcode.cc/api` · OpenAI 兼容（Chat Completions）：`https://api.qcode.cc/openai/v1` |
| 配置位置 | 应用内：设置 →「自定义模型」→「+ 添加自定义」 |
| 官方资料 | [模型配置指南](https://lobsterai.youdao.com/docs/lobsterai_model_config_guide) · [用户手册](https://lobsterai.youdao.com/docs/lobsterai_user_manual) · [GitHub 仓库](https://github.com/netease-youdao/LobsterAI) |

官网 FAQ 对它的介绍是：LobsterAI（中文名有道龙虾）是网易有道推出的开源桌面 AI Agent，定位全场景办公助手；基于开源 Agent 框架 OpenClaw 构建，支持 macOS（Apple 芯片与 Intel 芯片）和 Windows，代码以 MIT 协议发布在 GitHub（netease-youdao/LobsterAI）。它和 [OpenClaw](/docs/ide/openclaw) 是两个不同的产品：OpenClaw 是运行时框架，LobsterAI 是带界面的桌面客户端。

版本：截至 2026-11-10，GitHub Releases 标为 Latest 的是 `LobsterAI 2026.11.6`（2026-11-06 发布）；官网首页同日仍显示最新版本 2026.10.30。下面的界面文字按 2026.11.6 版源码核对。

## 用哪条协议

自定义服务商提供几种 API 格式，日常接 QCode 用其中两种：

- 「Anthropic 兼容（Messages）」+ `https://api.qcode.cc/api`：可调 Claude 型号，也可调 GLM / Kimi / DeepSeek / Qwen。
- 「OpenAI 兼容（Chat Completions）」+ `https://api.qcode.cc/openai/v1`：可调 GPT 型号，也可调 GLM / Kimi / DeepSeek / Qwen。

同一把 `cr_` 密钥两个地址通用；Claude 型号只走 Anthropic 端点，GPT 型号只走 OpenAI 端点，完整对照见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。「OpenAI 兼容（Responses）」格式见下文「可选」一节。

## 安装

官方 README 给出的下载方式：从 [官网下载页](https://lobsterai.youdao.com/#/download-list) 选择 macOS（Apple 芯片）、macOS（Intel）或 Windows x64 安装包，也可直接取 GitHub Releases 的最新安装包。QCode 不需要你另外注册模型厂商的账号，准备一把控制台里创建的 `cr_` 密钥即可（[控制台](https://qcode.cc/dashboard)）。

## 配置步骤

官方资料对菜单路径的写法略有差异：

- README：在 **设置 → 自定义模型** 中填入自己的 API Key。
- 仓库维护者在 issue #362 的答复（2026-10-06）：「打开 设置 →「自定义模型」，在提供商列表底部点「+ 添加自定义」，API 格式选「OpenAI 兼容」…再点「添加模型」…然后点「测试连接」，成功后该提供商会自动启用，即可在输入框的模型选择器中选用。也可以选「Anthropic 兼容」」。
- 用户手册与模型配置指南写的是 设置 →「模型」，用于内置的 DeepSeek、Moonshot、智谱、MiniMax、通义千问等；QCode 走上面的「自定义模型」。

### 第一步：添加自定义服务商

1. 打开设置，进入「自定义模型」。
2. 在服务商列表底部点「+ 添加自定义」。
3. 按下表填写（字段名取自 2026.11.6 版源码的中文界面文案）。

| 字段 | Claude 与国产模型 | GPT 与国产模型 |
|---|---|---|
| 显示名称 | `QCode`（自取） | `QCode OpenAI`（自取） |
| API 格式 | `Anthropic 兼容（Messages）` | `OpenAI 兼容（Chat Completions）` |
| API Base URL | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` |
| API Key | `cr_xxx` | `cr_xxx` |

两种格式想都用，就各添加一个自定义条目（官方更新日志写明可同时接入多个自定义服务商，数量上限 30 个）。

### 第二步：Base URL 要不要带 `/v1`

三处官方原文可以回答：

1. 「API 格式」下方的提示：「需与 Base URL 的接口协议一致，OpenAI 兼容地址通常以 /v1 结尾」。
2. Base URL 下方的示例（「示例（以硅基流动为例，点击填入）」）：「OpenAI 兼容」对应 `https://api.siliconflow.cn/v1`，「Anthropic 兼容」对应 `https://api.siliconflow.cn`，后者不带 `/v1`（仓库源码）。
3. 「测试连接」自己拼请求路径（仓库源码，2026.11.6）：Anthropic 格式发到 Base URL + `/v1/messages`，Base URL 已以 `/v1` 结尾时只补 `/messages`；OpenAI Chat Completions 格式在 Base URL 以 `/v1` 这类版本号结尾时补 `/chat/completions`，否则先补 `/v1`；Responses 格式补 `/responses`，缺 `/v1` 时同样先补上。

所以 Anthropic 兼容填 `https://api.qcode.cc/api`（测试连接实际请求 `/api/v1/messages`），OpenAI 兼容填 `https://api.qcode.cc/openai/v1`（实际请求 `/openai/v1/chat/completions`），不要自己再加 `/v1/messages` 或 `/chat/completions`。这套填法我们没有在 LobsterAI 安装包上实测，最终以「测试连接」的结果为准。网络不稳定时可把域名换成 `asia.qcode.cc`（亚洲）或 `us.qcode.cc`（北美），路径不变。

### 第三步：添加模型并测试连接

1. 在刚建的条目里点「添加模型」，填「模型名称」（列表里显示的名字）与「模型ID」。
2. 「模型ID」必须逐字等于 [qcode.cc/models](https://qcode.cc/models) 在售的型号，例如：

| API 格式 | 模型ID 示例 |
|---|---|
| Anthropic 兼容（Messages） | `claude-sonnet-5-5`、`claude-opus-5-5`、`claude-haiku-5-5`、`glm-5.3`、`deepseek-v4.1-flash`、`kimi-k3`、`qwen3.8-max` |
| OpenAI 兼容（Chat Completions） | `gpt-6.1-sol`、`gpt-6.1-terra`、`glm-5.3`、`deepseek-v4.1-flash`、`kimi-k3`、`qwen3.8-max` |

3. 点「测试连接」。按维护者在 issue #362 的答复，成功后该服务商会自动启用，随后即可在输入框的模型选择器中选用它。各模型单价见 https://qcode.cc/models。

### 可选：OpenAI 兼容（Responses）

官方 2026.10.23 更新日志写明「自定义模型支持 OpenAI Responses 与 Gemini 原生接口」。对应的选项是「OpenAI 兼容（Responses）」，提示为「需服务商支持 OpenAI Responses 接口，请求地址为 Base URL + /responses」。QCode 的 Responses 接口服务 GPT 型号；Base URL 填 `https://api.qcode.cc/openai/v1` 时请求落在 `/openai/v1/responses`，端点页写明它与 `/openai/responses` 等价。日常使用选「OpenAI 兼容（Chat Completions）」就够了。QCode 暂不提供 Gemini 型号，「Gemini（generateContent）」这一项用不上。

## 验证是否接通

1. 点「测试连接」，出现「连接成功」即路径与密钥都已送达。
2. 回到输入框，在模型选择器里选中刚添加的模型，发一句 `ping`。
3. 想先在命令行验证网络与密钥（空请求体返回 400 就是路径与密钥正常）：

```bash
KEY="cr_your_key"
curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  https://api.qcode.cc/api/v1/messages -H "x-api-key: $KEY"
curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY"
# 400 = 路径与密钥正常；401 = 密钥无效；404 = 路径前缀错
```

每次请求都会出现在 [probe.qcode.cc](https://probe.qcode.cc)，输入密钥即可看到实际请求的型号与返回码。

## 已知限制与常见报错

依据官方手册、更新日志、仓库源码与 issue：

- **自定义服务商与 Responses（issue #185）**：issue #185（2026-02-28 提出）希望自定义服务商支持 OpenAI 的新接口格式，维护者当时的答复是把应用语言切到英文，使用内置的 OpenAI 模型提供商。现状：2026.10.23 起自定义模型已支持 OpenAI Responses，见上文「可选」一节。
- **界面语言决定内置服务商列表**：维护者在 issue #87 与 #185 里说明，英文界面会多出 OpenAI、Gemini 等内置条目。现状：2026.11.6 版源码仍按界面语言决定内置列表，自定义条目在中英文界面都会显示，所以接 QCode 的步骤在两种语言下相同。
- **Claude 型号加在了 OpenAI 格式下**：QCode 返回 `model_not_available_on_endpoint`。把该条目的「API 格式」改成「Anthropic 兼容（Messages）」、地址改成 `https://api.qcode.cc/api`；这是协议选错，不是密钥问题。
- **型号 ID 不认**：issue #87 里另一家服务返回 `invalid param model:claude-haiku-4-5-20251001`（400），原因是服务端不认这个 ID。接 QCode 时只填 [qcode.cc/models](https://qcode.cc/models) 在售的型号。
- 官方模型配置指南的错误表有四类提示：「API Key无效」「余额不足」「网络错误」「服务不可用」。对应处理：重新复制完整的 `cr_` 密钥、检查 QCode 余额、检查网络、查看服务状态。
- 密钥存放：官方手册写明 API Key 仅存储在本机，不会上传到服务器。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) —— 协议对照与 Base URL 填法
- [工具兼容总览](/docs/ide/tool-compatibility) —— 各工具协议支持一览
- [OpenClaw 接入](/docs/ide/openclaw) —— LobsterAI 所基于的 OpenClaw 框架本身的配置
- [AutoClaw 接入](/docs/ide/autoclaw) —— 智谱的本地 OpenClaw 应用（自定义模型走 OpenAI 协议）
- [Qoder 接入](/docs/ide/qoder) —— 同样能在自定义模型里填 Anthropic 与 OpenAI 两种端点的桌面 Agent
- [国产模型接入](/docs/usage/cn-models) —— GLM / Kimi / DeepSeek / Qwen 的在售 ID
- [故障排查指南](/docs/reference/troubleshooting)