# راه‌اندازی LobeChat

> **آخرین بازبینی**: 2026-11-12 · 📄 بر اساس مستندات رسمی (LobeHub v2.2.19؛ بخش مدل Claude و قیمت‌گذاری رسمی در 2026-11-12 دوباره با صفحه‌های نمای کلی مدل و قیمت‌گذاری Anthropic بازبینی شد)

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | 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 ارائه‌دهنده انتخاب‌شده، کنترل‌های **Proxy URL** و **Check** |
| مسیر میزبانی روی سرور خود | متغیرهای محیطی `ANTHROPIC_PROXY_URL` و `OPENAI_PROXY_URL` به‌جای رابط کاربری برنامه |
| مستندات رسمی | [ارائه‌دهندگان مدل AI](https://lobehub.com/docs/usage/providers) |

این برنامه امروز با نام **LobeHub** منتشر می‌شود — متن نمای کلی خودش هنوز می‌گوید ایده چندمدلی «با پشتیبانی چندمدلی LobeChat آغاز شد» — بنابراین سایت مستندات، نسخه‌های دسکتاپ، ایمیج `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` |

🔴 **هرگز Claude را از طریق ارائه‌دهنده OpenAI فراخوانی نکنید.** QCode فقط Claude را روی نقطه پایانی Anthropic ارائه می‌دهد؛ شناسه `claude-*` روی نقطه پایانی سازگار با OpenAI رد می‌شود، و شناسه‌های `gpt-*` هم روی نقطه پایانی Anthropic ارائه نمی‌شوند. یک کلید QCode (`cr_…`) هر دو ورودی را پوشش می‌دهد.

Proxy URL را دقیقاً مطابق جدول وارد کنید: **بدون اسلش پایانی**، و مسیر کامل درخواست مانند `/v1/chat/completions` را در آن فیلد جای‌گذاری نکنید — LobeHub آن را «Base URL ارائه‌دهنده API یا یک نقطه پایانی سازگار» تعریف می‌کند. اینکه فیلد Anthropic انتظار بخش مسیر اضافه‌ای دارد یا نه مستند نشده است، بنابراین آدرسی را که QCode به شما می‌دهد همان‌طور که هست وارد کنید. به [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) مراجعه کنید.
## نصب

ابتدا مشخص کنید برنامه را چگونه اجرا می‌کنید؛ محل نگهداری کلید از همان‌جا تعیین می‌شود.

- **دسکتاپ یا وب** — «برنامه macOS، Windows یا Linux را از صفحه دانلود رسمی دریافت کنید»؛ نسخه دسکتاپ مبتنی بر Electron است و در مرورگر کافی است «LobeHub را در یک مرورگر مدرن باز کنید». پیکربندی را از طریق رابط کاربری برنامه در ادامه انجام دهید.
- **میزبانی شخصی، تک‌ایمیج 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
```

برای اینکه برنامه دسکتاپ بتواند نمونه‌ای را که خودتان میزبانی می‌کنید هدایت کند، مستندات دسکتاپ الزام می‌کند که «نسخه نمونه میزبانی‌شده شخصی شما 1.83.6 یا بالاتر باشد تا از قابلیت‌های اتصال دسکتاپ پشتیبانی کند»: روی آیکون Wi-Fi در گوشه بالا سمت راست کلیک کنید، آدرس نمونه خود را وارد کنید و سپس متصل شوید. همان مستند همچنین الزام می‌کند که نمونه پیش از اتصال «به‌درستی با متغیرهای محیطی مرتبط با OIDC پیکربندی شده باشد». نسخه سروری که این صفحه بر اساس آن بررسی شده v2.2.19 (2026-10-07) است؛ 1.83.6 عددی است که آن مستند برای دسکتاپ ذکر کرده و همان عدد نیست.

بنابراین در این صفحه دو مسیر وجود دارد: **ابر و دسکتاپ از فیلدهای رابط کاربری استفاده می‌کنند**، **میزبانی شخصی می‌تواند از متغیرهای محیطی استفاده کند**.

## پیکربندی

LobeHub صریحاً می‌گوید که فیلدها به ارائه‌دهنده بستگی دارند: «App Settings → AI Providers را باز کنید، سپس ارائه‌دهنده‌ای را که می‌خواهید پیکربندی کنید انتخاب کنید. فیلدهای موجود به ارائه‌دهنده بستگی دارند». ترتیب مستندشده چنین است: «یک ارائه‌دهنده را از فهرست انتخاب کنید و سوئیچ آن را روشن کنید»، سپس «اطلاعات ورود نمایش‌داده‌شده در صفحه را وارد کنید. بیشتر ارائه‌دهندگان ابری از کلید API استفاده می‌کنند»، سپس «اگر Proxy URL در دسترس است، Base URL API ارائه‌دهنده یا یک نقطه پایانی سازگار را وارد کنید»، سپس «برای آزمایش اتصال، Check را انتخاب کنید»، سپس «یک مدل را در فهرست مدل‌ها فعال کنید. هر جا این عملیات در دسترس باشد می‌توانید مدل‌ها را واکشی یا اضافه کنید.» این راهنما می‌افزاید: «تغییرات شما به‌طور خودکار ذخیره می‌شوند. سپس می‌توانید ارائه‌دهنده و مدل را در Agent settings انتخاب کنید.»

دو محدودیت را باید صریح گفت. نخست، عبارت شرطی است — *If Proxy URL is available* — پس این صفحه ادعا نمی‌کند که هر ارائه‌دهنده‌ای آن فیلد را در معرض دید می‌گذارد، و LobeHub هیچ جدول مقایسه‌ای ابر در برابر دسکتاپ درباره اینکه کدام ارائه‌دهنده چنین فیلدی دارد منتشر نکرده است. اگر نسخه شما برای Anthropic یا OpenAI ورودی Proxy URL را نشان نمی‌دهد، این راهنما نمی‌تواند آن را تغییر مسیر دهد. دوم، ابر و دسکتاپ متضاد یکدیگر نیستند: «برنامه دسکتاپ می‌تواند از سرویس‌های ابری و مدل‌های ابری استفاده کند.»

### پیکربندی Claude (ارائه‌دهنده Anthropic)

راهنمای رسمی Anthropic، با همان ترتیب خودش:

1. «App Settings → AI Providers را باز کنید، Anthropic را انتخاب کنید و ارائه‌دهنده را فعال کنید»
2. «کلید API را وارد کنید. اگر از یک پروکسی استفاده می‌کنید، Proxy URL آن را وارد کنید» — کلید `cr_…` QCode شما، و Proxy URL برابر `https://api.qcode.cc/api`
3. «برای آزمایش اتصال، Check را انتخاب کنید»
4. «مدل‌های Claude موردنیاز را فعال کنید، سپس یکی را در Agent settings انتخاب کنید»

شناسه‌ها را از فهرست QCode انتخاب کنید: `claude-sonnet-5` برای کارهای روزمره، `claude-sonnet-5-5`، `claude-opus-5` یا `claude-opus-5-5` برای کارهای دشوار، `claude-haiku-5-5` برای کارهای سبک؛ `claude-sonnet-4-6`، `claude-fable-5` و `claude-fable-5-1` نیز در دسترس هستند. جدیدترین Fable همان `claude-fable-5-2` است: Anthropic آن را در 2026-11-09 با پنجره زمینه 1M توکن و حداکثر 128K توکن خروجی در هر درخواست، با قیمت رسمی $8 به‌ازای هر یک میلیون توکن ورودی و $40 به‌ازای هر یک میلیون توکن خروجی منتشر کرد (بررسی‌شده با صفحه‌های نمای کلی مدل‌ها و قیمت‌گذاری Anthropic در 2026-11-12)؛ `claude-fable-5-1` پیشین نیز همچنان روی QCode با قیمت رسمی $10 ورودی و $50 خروجی در دسترس است. این صفحه فقط ورودی‌های داخلی Anthropic و OpenAI را پوشش می‌دهد؛ LobeHub راهنماهای زیادی برای ارائه‌دهندگان دیگر مستند کرده است و هیچ‌چیز در اینجا با آن‌ها بررسی نشده است.

### پیکربندی GPT و مدل‌های چینی (ارائه‌دهنده OpenAI)

همان شکل، با گام‌های خود راهنمای OpenAI:

1. «App Settings → AI Providers را باز کنید، OpenAI را انتخاب کنید و ارائه‌دهنده را فعال کنید»
2. «کلید API را وارد کنید. اگر از پروکسی یا نقطه پایانی سازگار استفاده می‌کنید، Proxy URL آن را وارد کنید» — همان کلید `cr_…`، و Proxy URL برابر `https://api.qcode.cc/openai/v1`
3. «برای آزمایش اتصال، Check را انتخاب کنید»
4. «مدل‌های OpenAI موردنیاز را فعال کنید، سپس یکی را در Agent settings انتخاب کنید»

شناسه‌های خانواده چینی از همین ارائه‌دهنده و همین 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 کل فهرست را پوشش می‌دهد. اگر شناسه شما در انتخابگر داخلی نیست، آن را همان‌جایی اضافه کنید که مستندات اجازه واکشی یا افزودن مدل را می‌دهد.

### متغیرهای محیطی میزبانی شخصی

در استقرار Docker یا Compose، همان دو نقطه پایانی برای هر ارائه‌دهنده در فایل env پیکربندی می‌شوند. مرجع، `ANTHROPIC_PROXY_URL` را به‌عنوان موردی مستند می‌کند که «Base URL پیش‌فرض درخواست API Anthropic را بازنویسی می‌کند» و `OPENAI_PROXY_URL` را به‌عنوان موردی که «Base URL پیش‌فرض درخواست API OpenAI را بازنویسی می‌کند»، که آن‌ها را به همتای میزبانی شخصی فیلد Proxy URL در رابط کاربری تبدیل می‌کند:

| متغیر | مقدار پیش‌فرض مستندشده | مقداری که باید تنظیم کنید |
|---|---|---|
| `ANTHROPIC_API_KEY` | – | کلید `cr_…` QCode شما |
| `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` «برای کنترل فهرست مدل‌ها استفاده می‌شود»: `+` یک مدل اضافه می‌کند، `-` یکی را پنهان می‌کند و `-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` در مقدار بیاید یا نه، ویژگی نقطه پایانی است نه LobeChat — مستندات به شما می‌گوید «پسوند درخواست ارائه‌دهنده سرویس پروکسی خود را بررسی کنید» و اگر پاسخ خالی برگشت پیشنهاد می‌کنند پسوند `/v1` را اضافه کنید و دوباره تلاش کنید. برای QCode: مقدار OpenAI پسوند `/openai/v1` را نگه می‌دارد و مقدار Anthropic در `/api` متوقف می‌شود. مرجع همچنین مواردی به‌ازای هر ارائه‌دهنده برای سرویس‌های چینی مستند می‌کند (`DEEPSEEK_PROXY_URL`، `QWEN_PROXY_URL`، `MOONSHOT_PROXY_URL`)؛ یکی را فقط زمانی به QCode اشاره دهید که آگاهانه می‌خواهید پشت ورودی آن ارائه‌دهنده قرار گیرد.
## بررسی

بررسی مستندشده در برنامه قرار دارد: «Select Check to test the connection» در کارت ارائه‌دهنده. **این صفحه کلید آزمایشی ندارد، بنابراین هیچ نتیجه HTTP برای هیچ‌یک از تنظیمات بالا ادعا نمی‌شود.** اگر **Check** شکست بخورد، پیش از دست زدن به هر چیز دیگری، Proxy URL و کلید را اصلاح کنید.

برای جدا کردن مشکل دروازه از مشکل برنامه، نقاط پایانی را مستقیم فراخوانی کنید:

```bash
KEY="cr_your_qcode_key"

# Anthropic endpoint — Claude ids only
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 compatible endpoint — GPT and Chinese ids, never 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) باشد یعنی سمت نقطه پایانی پاسخ داده است و مشکل باقی‌مانده در تنظیمات برنامه است. مصرف بر اساس توکن محاسبه می‌شود؛ نرخ‌های هر مدل در [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)») | `https://api.qcode.cc/openai/v1` را دقیقاً نگه دارید، بدون اسلش انتهایی |
| شناسه `claude-*` رد می‌شود | — | QCode خانواده Claude را روی آدرس سازگار با OpenAI ارائه نمی‌دهد (`model_not_available_on_endpoint`)؛ آن را با `https://api.qcode.cc/api` به ارائه‌دهنده Anthropic منتقل کنید |
| فراخوانی‌های طولانی Anthropic قطع می‌شوند | `ANTHROPIC_CLIENT_TIMEOUT`، پیش‌فرض `295000`، و آن مهلت زمانی «is also used by Anthropic-compatible providers that rely on the Anthropic SDK» | آن را در میزبانی شخصی افزایش دهید، فقط برای تولیدهای طولانی |
| روی Vercel مستقر شده است | یک «محدودیت زمانی 10 ثانیه‌ای برای توابع serverless» | در برداشت ما: پاسخ‌های طولانی‌تر از آن سقف به Docker یا میزبان دیگری نیاز دارند |
| یک ارائه‌دهنده از دسترس خارج می‌شود | «This does not guarantee automatic failover» | ارائه‌دهنده دوم را خودتان پیکربندی کنید و دستی تغییر دهید |
| خطای اتصال، رد شدن کلید | «Check your API key for extra spaces. Check that the key type matches the provider» | کلید `cr_…` را دوباره جای‌گذاری کنید، ارائه‌دهنده را تأیید کنید |
| شناسه مدل شما در فهرست نیست | «Your account tier can exclude a model, or the provider can retire it» | برای QCode، شناسه را خودتان اضافه کنید — انتخابگر داخلی کاتالوگ 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 یا یک مدل چینی استفاده کنید. اگر آدرس اصلی Anthropic برای شما در دسترس نیست، همان کلید روی `https://asia.qcode.cc/api` و `https://us.qcode.cc/api` هم کار می‌کند. اینکه کدام نسخه LobeChat فیلد Proxy URL را برای کدام ارائه‌دهنده نشان می‌دهد، توسط LobeHub مستند نشده است؛ بنابراین آن تفاوت در اینجا خارج از محدوده است.

## مرتبط

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — پروتکل در برابر خانواده مدل
- [سازگاری ابزارها](/docs/ide/tool-compatibility) — هر ابزار با چه چیزی صحبت می‌کند
- [یکپارچه‌سازی Cherry Studio](/docs/ide/cherry-studio) — همان نقاط پایانی، فیلدهای برنامه دسکتاپ
- [راه‌اندازی API شخص ثالث در Claude Desktop](/docs/ide/claude-desktop)
- [مدل‌های چینی](/docs/usage/cn-models)
- [راهنمای انتخاب مدل](/docs/usage/model-selection)
- [عیب‌یابی](/docs/reference/troubleshooting)