# LobsterAI Setup with QCode (Custom Model)

> **Last verified**: 2026-11-10 · 📄 Per official docs (LobsterAI 2026.11.6, released 2026-11-06: README, user manual, repository source)

Can LobsterAI use your own API key? Yes. As of 2026-11-10, per the official README, the repository source and a maintainer's reply: open **Settings → Custom Model**, click **+ Add Custom** at the bottom of the provider list, pick **Anthropic Compatible (Messages)** or **OpenAI Compatible (Chat Completions)** under **API Format**, enter the QCode Base URL and your `cr_` key, add a model ID, then click **Test Connection**.

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (Anthropic Compatible) · GPT ✅ (OpenAI Compatible) · GLM / Kimi / DeepSeek / Qwen ✅ (either) · Gemini ❌ (QCode does not offer it for now) |
| Base URL | Anthropic Compatible (Messages): `https://api.qcode.cc/api` · OpenAI Compatible (Chat Completions): `https://api.qcode.cc/openai/v1` |
| Where to configure | In-app: **Settings → Custom Model → + Add Custom** |
| Official docs | [Model configuration guide](https://lobsterai.youdao.com/en/docs/lobsterai_model_config_guide) · [User manual](https://lobsterai.youdao.com/en/docs/lobsterai_user_manual) · [GitHub repository](https://github.com/netease-youdao/LobsterAI) |

The official FAQ describes LobsterAI (Chinese name: Youdao Lobster) as an open-source desktop AI agent from NetEase Youdao, built as an all-scenario office assistant. It is built on OpenClaw, the open-source agent framework, runs on macOS (Apple Silicon and Intel) and Windows, and is released under the MIT License on GitHub (netease-youdao/LobsterAI). It is a different product from [OpenClaw](/docs/ide/openclaw): OpenClaw is the runtime framework, LobsterAI is a desktop client with its own UI.

Version: as of 2026-11-10 the release GitHub marks **Latest** is `LobsterAI 2026.11.6` (published 2026-11-06); the official website's home page still shows 2026.10.30 on the same day. The UI labels below were checked against the 2026.11.6 source.

## Which protocol to use

A custom provider offers several API formats. Two of them cover everyday use with QCode:

- **Anthropic Compatible (Messages)** + `https://api.qcode.cc/api`: Claude models, and also GLM / Kimi / DeepSeek / Qwen.
- **OpenAI Compatible (Chat Completions)** + `https://api.qcode.cc/openai/v1`: GPT models, and also GLM / Kimi / DeepSeek / Qwen.

One `cr_` key works for both. Claude models are served only on the Anthropic endpoint and GPT models only on the OpenAI endpoints; the full matrix is in [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths). The **OpenAI Compatible (Responses)** format is covered in an optional section below.

## Install

The official README points to the [download page](https://lobsterai.youdao.com/#/download-list) (macOS Apple Silicon, macOS Intel, Windows x64), or to the latest installers on GitHub Releases. You do not need an account with any model vendor: create a `cr_` key in the [dashboard](https://qcode.cc/dashboard) and keep it handy.

## Configure

The official sources describe the menu path in slightly different words:

- README: add your own API key under **Settings → Custom Model**.
- A repository maintainer's reply in issue #362 (2026-10-06): "add a custom provider under Settings → Custom Models … choose OpenAI-compatible with base URL … and the … key, add a model ID … and run Test Connection". The same reply says that after a successful test the provider is enabled automatically and can be picked in the model selector of the input box; the Anthropic-compatible format is the other choice.
- The user manual and model configuration guide use **Settings → Models** for the built-in providers (DeepSeek, Moonshot, Zhipu, MiniMax, Qwen and others). QCode goes under **Custom Model**.

### Step 1: add a custom provider

1. Open Settings and go to **Custom Model**.
2. Click **+ Add Custom** at the bottom of the provider list.
3. Fill the fields below (labels as in the English UI strings of the 2026.11.6 source).

| Field | Claude and Chinese models | GPT and Chinese models |
|---|---|---|
| Display Name | `QCode` (any name) | `QCode OpenAI` (any name) |
| API Format | `Anthropic Compatible (Messages)` | `OpenAI Compatible (Chat Completions)` |
| API Base URL | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` |
| API Key | `cr_xxx` | `cr_xxx` |

To use both formats, add two custom providers. The official changelog says several custom providers can be connected at once, with a limit of 30.

### Step 2: does the Base URL need `/v1`?

Three official sources answer it:

1. The hint under **API Format**: "Must match the protocol behind your Base URL; OpenAI-compatible URLs usually end with /v1".
2. The examples under the Base URL field ("Examples (SiliconFlow, click to fill)") pair **OpenAI Compatible** with `https://api.siliconflow.cn/v1` and **Anthropic Compatible** with `https://api.siliconflow.cn`, which has no `/v1` (repository source).
3. **Test Connection** builds the request path itself (repository source, 2026.11.6). The Anthropic format sends to Base URL + `/v1/messages`, or only `/messages` when the Base URL already ends in `/v1`. The OpenAI Chat Completions format sends to Base URL + `/chat/completions` when the Base URL ends in a version such as `/v1`, and adds `/v1` first otherwise. The Responses format sends to Base URL + `/responses`, also adding `/v1` first when it is missing.

So enter `https://api.qcode.cc/api` for Anthropic Compatible (the test then calls `/api/v1/messages`) and `https://api.qcode.cc/openai/v1` for OpenAI Compatible (the test calls `/openai/v1/chat/completions`). Do not add `/v1/messages` or `/chat/completions` to the field yourself. This setup has not been run on a LobsterAI install on our side, so the **Test Connection** result is the final word. On an unstable network you can swap the host for `asia.qcode.cc` (Asia) or `us.qcode.cc` (North America); the path stays the same.

### Step 3: add a model and test the connection

1. In the new provider click **Add Model** and fill **Model Name** (the label shown in the list) and **Model ID**.
2. **Model ID** must match a model on sale at [qcode.cc/models](https://qcode.cc/models) character for character, for example:

| API Format | Model ID examples |
|---|---|
| Anthropic Compatible (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 Compatible (Chat Completions) | `gpt-6.1-sol`, `gpt-6.1-terra`, `glm-5.3`, `deepseek-v4.1-flash`, `kimi-k3`, `qwen3.8-max` |

3. Click **Test Connection**. Per the maintainer's reply in issue #362, after success the provider is enabled automatically and you can pick it from the model selector in the input box. Per-model rates are at https://qcode.cc/models.

### Optional: OpenAI Compatible (Responses)

The official 2026.10.23 release notes say: "Custom providers now support OpenAI Responses and Gemini native APIs." The option is **OpenAI Compatible (Responses)**, with the hint "Requires the provider to support the OpenAI Responses API. Requests go to Base URL + /responses." On QCode, Responses serves GPT models; with Base URL `https://api.qcode.cc/openai/v1` the request lands on `/openai/v1/responses`, which the endpoints page lists as equivalent to `/openai/responses`. For everyday use **OpenAI Compatible (Chat Completions)** is enough. QCode does not offer Gemini models for now, so the **Gemini (generateContent)** option stays unused.

## Verify

1. Click **Test Connection**; "Connection successful" means the path and key both work.
2. Back in the input box, pick the new model in the model selector and send `ping`.
3. To check the network and key from a terminal first (a 400 on an empty body means path and key are fine):

```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 = path and key fine; 401 = bad key; 404 = wrong path prefix
```

Every request shows up at [probe.qcode.cc](https://probe.qcode.cc); enter your key to see the model and status code of each call.

## Known limits and common errors

From the official manual, changelog, repository source and issues:

- **Responses on custom providers (issue #185)**: issue #185 (opened 2026-02-28) asked for OpenAI's newer API format on custom providers; the maintainer's answer at the time was to switch the app language to English and use the built-in OpenAI provider. Current status: since 2026.10.23 custom providers support OpenAI Responses (see the optional section above).
- **The app language changes the built-in provider list**: in issues #87 and #185 the maintainer explains that the English UI lists extra built-in providers such as OpenAI and Gemini. Current status: the 2026.11.6 source still picks the built-in list by UI language and shows custom providers in both languages, so the QCode setup is the same in the Chinese and English UI.
- **Claude ID under an OpenAI format**: QCode answers `model_not_available_on_endpoint`. Switch that provider's **API Format** to **Anthropic Compatible (Messages)** with `https://api.qcode.cc/api`; it is a protocol mismatch, not a key problem.
- **Unknown model ID**: in issue #87 another service answered `invalid param model:claude-haiku-4-5-20251001` (a 400) because it did not know that ID. With QCode, use only IDs on sale at [qcode.cc/models](https://qcode.cc/models).
- The official model configuration guide lists four error messages: "API Key Invalid", "Insufficient Balance", "Network Error" and "Service Unavailable". On QCode: copy the full `cr_` key again, check your QCode balance, check the network, then check the service status.
- Key storage: the official manual states the API key is stored only on your local device and is not uploaded to any server.

## Related docs

- [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths) — protocols and how to fill Base URLs
- [Tool Compatibility Overview](/docs/ide/tool-compatibility) — protocol support across all tools
- [OpenClaw Integration](/docs/ide/openclaw) — the OpenClaw framework LobsterAI is built on
- [AutoClaw](/docs/ide/autoclaw) — Zhipu's local OpenClaw app (custom models speak the OpenAI protocol)
- [Qoder](/docs/ide/qoder) — another desktop agent whose custom models take both Anthropic and OpenAI endpoints
- [Chinese Models](/docs/usage/cn-models) — current GLM / Kimi / DeepSeek / Qwen IDs on sale
- [Troubleshooting Guide](/docs/reference/troubleshooting)