# راه‌اندازی LobsterAI با QCode (مدل سفارشی)

> **آخرین بازبینی**: 2026-11-13 · 📄 طبق مستندات رسمی (LobsterAI 2026.11.6، منتشرشده در 2026-11-06: README، راهنمای کاربر، سورس مخزن؛ نمونه‌های شناسه مدل در 2026-11-13 دوباره با qcode.cc/models بررسی شد)

آیا LobsterAI می‌تواند از کلید API خودتان استفاده کند؟ بله. تا 2026-11-10، بر اساس README رسمی، سورس مخزن و پاسخ یکی از نگه‌دارندگان: **Settings → Custom Model** را باز کنید، در پایین فهرست ارائه‌دهنده‌ها روی **+ Add Custom** کلیک کنید، زیر **API Format** گزینه **Anthropic Compatible (Messages)** یا **OpenAI Compatible (Chat Completions)** را انتخاب کنید، Base URL مربوط به QCode و کلید `cr_` خود را وارد کنید، یک شناسه مدل اضافه کنید و سپس روی **Test Connection** کلیک کنید.

## یک نگاه کلی

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (Anthropic Compatible) · GPT ✅ (OpenAI Compatible) · GLM / Kimi / DeepSeek / Qwen ✅ (هرکدام) · Gemini ❌ (QCode فعلاً آن را ارائه نمی‌دهد) |
| Base URL | Anthropic Compatible (Messages): `https://api.qcode.cc/api` · OpenAI Compatible (Chat Completions): `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | درون برنامه: **Settings → Custom Model → + Add Custom** |
| مستندات رسمی | [راهنمای پیکربندی مدل](https://lobsterai.youdao.com/en/docs/lobsterai_model_config_guide) · [راهنمای کاربر](https://lobsterai.youdao.com/en/docs/lobsterai_user_manual) · [مخزن GitHub](https://github.com/netease-youdao/LobsterAI) |

پرسش‌های متداول رسمی، LobsterAI (نام چینی: Youdao Lobster) را یک عامل هوش مصنوعی رومیزی متن‌باز از NetEase Youdao معرفی می‌کند که به‌عنوان دستیار اداری همه‌سناریویی ساخته شده است. این نرم‌افزار بر پایه OpenClaw، چارچوب عامل متن‌باز، ساخته شده است، روی macOS (Apple Silicon و Intel) و Windows اجرا می‌شود و تحت مجوز MIT در GitHub (netease-youdao/LobsterAI) منتشر شده است. این محصولی متفاوت از [OpenClaw](/docs/ide/openclaw) است: OpenClaw چارچوب زمان اجرا است و LobsterAI یک کلاینت رومیزی با رابط کاربری اختصاصی خود است.

نسخه: تا 2026-11-10، انتشاری که GitHub آن را **Latest** علامت می‌زند `LobsterAI 2026.11.6` است (منتشرشده در 2026-11-06)؛ صفحه اصلی وب‌سایت رسمی در همان روز هنوز 2026.10.30 را نشان می‌دهد. برچسب‌های رابط کاربری زیر با سورس 2026.11.6 بررسی شده‌اند.
## از کدام پروتکل استفاده کنیم

یک ارائه‌دهنده سفارشی چندین قالب API ارائه می‌دهد. دو مورد از آن‌ها استفاده روزمره با QCode را پوشش می‌دهند:

- **Anthropic Compatible (Messages)** + `https://api.qcode.cc/api`: مدل‌های Claude و همچنین GLM / Kimi / DeepSeek / Qwen.
- **OpenAI Compatible (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 Compatible (Responses)** در بخش اختیاری زیر پوشش داده شده است.

## نصب

README رسمی به [صفحه دانلود](https://lobsterai.youdao.com/#/download-list) (macOS Apple Silicon، macOS Intel، Windows x64) یا به آخرین نصب‌کننده‌ها در GitHub Releases اشاره می‌کند. شما به حساب کاربری نزد هیچ ارائه‌دهنده مدلی نیاز ندارید: یک کلید `cr_` در [داشبورد](https://qcode.cc/dashboard) بسازید و آن را در دسترس نگه دارید.

## پیکربندی

منابع رسمی مسیر منو را با عبارت‌هایی کمی متفاوت توصیف می‌کنند:

- README: کلید API خود را زیر **تنظیمات → مدل سفارشی** اضافه کنید.
- پاسخ یکی از نگه‌دارندگان مخزن در issue #362 (2026-10-06): «یک ارائه‌دهنده سفارشی زیر تنظیمات → مدل‌های سفارشی اضافه کنید … گزینه سازگار با OpenAI را با Base URL … و کلید … انتخاب کنید، یک شناسه مدل اضافه کنید … و آزمایش اتصال را اجرا کنید». همان پاسخ می‌گوید پس از آزمایش موفق، ارائه‌دهنده به‌طور خودکار فعال می‌شود و می‌توان آن را از انتخاب‌گر مدل در کادر ورودی برگزید؛ قالب سازگار با Anthropic گزینه دیگر است.
- راهنمای کاربر و راهنمای پیکربندی مدل، همان صفحه را **تنظیمات → مدل‌ها** می‌نامند (همان‌جایی که ارائه‌دهندگان توکار مانند DeepSeek، Moonshot، Zhipu، MiniMax و Qwen تنظیم می‌شوند). این صفحه دوم نیست: در سورس 2026.11.6، این صفحه تنظیمات با برچسب **مدل سفارشی** آمده است و ارائه‌دهندگان توکار و **+ افزودن سفارشی** در همان فهرست قرار دارند.

### مرحله 1: افزودن ارائه‌دهنده سفارشی

1. تنظیمات را باز کنید و به **مدل سفارشی** بروید.
2. در پایین فهرست ارائه‌دهندگان روی **+ افزودن سفارشی** کلیک کنید.
3. فیلدهای زیر را پر کنید (برچسب‌ها مطابق رشته‌های رابط کاربری انگلیسی سورس 2026.11.6 هستند).

| فیلد | مدل‌های Claude و چینی | مدل‌های GPT و چینی |
|---|---|---|
| نام نمایشی | `QCode` (هر نامی) | `QCode OpenAI` (هر نامی) |
| قالب API | `Anthropic Compatible (Messages)` | `OpenAI Compatible (Chat Completions)` |
| Base URL API | `https://api.qcode.cc/api` | `https://api.qcode.cc/openai/v1` |
| کلید API | `cr_xxx` | `cr_xxx` |

برای استفاده از هر دو قالب، دو ارائه‌دهنده سفارشی اضافه کنید. تاریخچه تغییرات رسمی می‌گوید چندین ارائه‌دهنده سفارشی را می‌توان هم‌زمان متصل کرد، با محدودیت 30.

### مرحله 2: آیا Base URL به `/v1` نیاز دارد؟

سه منبع رسمی به آن پاسخ می‌دهند:

1. راهنمای زیر **قالب API**: «باید با پروتکل پشت Base URL شما مطابقت داشته باشد؛ URLهای سازگار با OpenAI معمولاً با /v1 تمام می‌شوند».
2. مثال‌های زیر فیلد Base URL («Examples (SiliconFlow, click to fill)») **OpenAI Compatible** را با `https://api.siliconflow.cn/v1` و **Anthropic Compatible** را با `https://api.siliconflow.cn` جفت می‌کنند که `/v1` ندارد (سورس مخزن).
3. **آزمایش اتصال** خودش مسیر درخواست را می‌سازد (سورس مخزن، 2026.11.6). قالب Anthropic به Base URL + `/v1/messages` ارسال می‌کند، یا وقتی Base URL از قبل به `/v1` ختم می‌شود فقط به `/messages`. قالب OpenAI Chat Completions وقتی Base URL به نسخه‌ای مانند `/v1` ختم می‌شود به Base URL + `/chat/completions` ارسال می‌کند و در غیر این صورت ابتدا `/v1` را اضافه می‌کند. قالب Responses به Base URL + `/responses` ارسال می‌کند و همچنین وقتی `/v1` وجود ندارد ابتدا آن را اضافه می‌کند.

پس برای Anthropic Compatible عبارت `https://api.qcode.cc/api` را وارد کنید (آزمایش سپس `/api/v1/messages` را فراخوانی می‌کند) و برای OpenAI Compatible عبارت `https://api.qcode.cc/openai/v1` را وارد کنید (آزمایش `/openai/v1/chat/completions` را فراخوانی می‌کند). خودتان `/v1/messages` یا `/chat/completions` را به فیلد اضافه نکنید. این پیکربندی در سمت ما روی نصب LobsterAI اجرا نشده است، بنابراین نتیجه **آزمایش اتصال** حرف آخر را می‌زند. در شبکه ناپایدار می‌توانید میزبان را با `asia.qcode.cc` (آسیا) یا `us.qcode.cc` (آمریکای شمالی) عوض کنید؛ مسیر ثابت می‌ماند.

### مرحله 3: افزودن مدل و آزمایش اتصال

1. در ارائه‌دهنده جدید روی **افزودن مدل** کلیک کنید و **نام مدل** (برچسبی که در فهرست نمایش داده می‌شود) و **شناسه مدل** را پر کنید.
2. **شناسه مدل** باید کاراکتربه‌کاراکتر با مدلی که در [qcode.cc/models](https://qcode.cc/models) عرضه می‌شود مطابقت داشته باشد، برای مثال:

| قالب API | نمونه‌های شناسه مدل |
|---|---|
| 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. روی **آزمایش اتصال** کلیک کنید. طبق پاسخ نگه‌دارنده در issue #362، پس از موفقیت ارائه‌دهنده به‌طور خودکار فعال می‌شود و می‌توانید آن را از انتخاب‌گر مدل در کادر ورودی انتخاب کنید. نرخ‌های هر مدل در https://qcode.cc/models است.

### اختیاری: OpenAI Compatible (Responses)

یادداشت‌های انتشار رسمی 2026.10.23 می‌گویند: «ارائه‌دهندگان سفارشی اکنون از OpenAI Responses و APIهای بومی Gemini پشتیبانی می‌کنند.» گزینه **OpenAI Compatible (Responses)** است، با این راهنما: «نیازمند آن است که ارائه‌دهنده از OpenAI Responses API پشتیبانی کند. درخواست‌ها به Base URL + /responses می‌روند.» در QCode، Responses به مدل‌های GPT سرویس می‌دهد؛ با Base URL `https://api.qcode.cc/openai/v1` درخواست روی `/openai/v1/responses` فرود می‌آید که صفحه نقاط پایانی آن را معادل `/openai/responses` فهرست می‌کند. برای استفاده روزمره **OpenAI Compatible (Chat Completions)** کافی است. QCode فعلاً مدل‌های Gemini را ارائه نمی‌دهد، بنابراین گزینه **Gemini (generateContent)** بلااستفاده می‌ماند.
## بررسی

1. روی **آزمایش اتصال** کلیک کنید؛ «Connection successful» یعنی مسیر و کلید هر دو درست کار می‌کنند.
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 = path and key fine; 401 = bad key; 404 = wrong path prefix
```

هر درخواست در [probe.qcode.cc](https://probe.qcode.cc) نمایش داده می‌شود؛ کلید خود را وارد کنید تا مدل و کد وضعیت هر فراخوانی را ببینید.

## محدودیت‌های شناخته‌شده و خطاهای رایج

بر اساس دفترچه راهنمای رسمی، تاریخچه تغییرات، سورس مخزن و موضوع‌ها:

- **پاسخ‌ها روی ارائه‌دهنده‌های سفارشی (موضوع #185)**: موضوع #185 (بازشده در 2026-02-28) درخواست پشتیبانی از قالب جدیدتر API شرکت OpenAI روی ارائه‌دهنده‌های سفارشی را داشت؛ پاسخ نگه‌دارنده در آن زمان این بود که زبان برنامه را به انگلیسی تغییر دهید و از ارائه‌دهنده داخلی OpenAI استفاده کنید. وضعیت فعلی: از 2026.10.23 ارائه‌دهنده‌های سفارشی از OpenAI Responses پشتیبانی می‌کنند (بخش اختیاری بالا را ببینید).
- **زبان برنامه فهرست ارائه‌دهنده‌های داخلی را تغییر می‌دهد**: در موضوع‌های #87 و #185 نگه‌دارنده توضیح می‌دهد که رابط کاربری انگلیسی ارائه‌دهنده‌های داخلی بیشتری مانند OpenAI و Gemini را فهرست می‌کند. وضعیت فعلی: سورس 2026.11.6 هنوز فهرست داخلی را بر اساس زبان رابط کاربری انتخاب می‌کند و ارائه‌دهنده‌های سفارشی را در هر دو زبان نشان می‌دهد، بنابراین تنظیم QCode در رابط کاربری چینی و انگلیسی یکسان است.
- **شناسه Claude در قالب OpenAI**: QCode پاسخ `model_not_available_on_endpoint` را می‌دهد. **قالب API** آن ارائه‌دهنده را به **Anthropic Compatible (Messages)** با `https://api.qcode.cc/api` تغییر دهید؛ این یک ناسازگاری پروتکل است، نه مشکل کلید.
- **شناسه مدل ناشناخته**: در موضوع #87 سرویس دیگری پاسخ `invalid param model:claude-haiku-4-5-20251001` (کد 400) را داد چون آن شناسه را نمی‌شناخت. با QCode فقط از شناسه‌هایی استفاده کنید که در [qcode.cc/models](https://qcode.cc/models) عرضه می‌شوند.
- راهنمای رسمی پیکربندی مدل چهار پیام خطا را فهرست می‌کند: «API Key Invalid»، «Insufficient Balance»، «Network Error» و «Service Unavailable». در QCode: کلید کامل `cr_` را دوباره کپی کنید، موجودی QCode خود را بررسی کنید، شبکه را بررسی کنید، سپس وضعیت سرویس را بررسی کنید.
- ذخیره‌سازی کلید: دفترچه راهنمای رسمی بیان می‌کند که کلید API فقط روی دستگاه محلی شما ذخیره می‌شود و به هیچ سروری بارگذاری نمی‌شود.

## مستندات مرتبط

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — پروتکل‌ها و نحوه پر کردن Base URLها
- [نمای کلی سازگاری ابزارها](/docs/ide/tool-compatibility) — پشتیبانی پروتکل در همه ابزارها
- [یکپارچه‌سازی OpenClaw](/docs/ide/openclaw) — چارچوب OpenClaw که LobsterAI بر آن ساخته شده است
- [AutoClaw](/docs/ide/autoclaw) — برنامه محلی OpenClaw از Zhipu (مدل‌های سفارشی از پروتکل OpenAI استفاده می‌کنند)
- [Qoder](/docs/ide/qoder) — یک عامل دسکتاپ دیگر که مدل‌های سفارشی آن هم نقاط پایانی Anthropic و هم OpenAI را می‌پذیرند
- [مدل‌های چینی](/docs/usage/cn-models) — شناسه‌های فعلی GLM / Kimi / DeepSeek / Qwen که عرضه می‌شوند
- [راهنمای عیب‌یابی](/docs/reference/troubleshooting)