# یکپارچه‌سازی OpenClaw

> **آخرین بازبینی**: 2026-09-18 · 📄 بر اساس مستندات رسمی (OpenClaw v2026.9.4، منتشرشده در 2026-09-11)

## در یک نگاه

| مورد | جزئیات |
|---|---|
| مدل‌های قابل استفاده | Claude ✅ (پروتکل Anthropic) · GPT ✅ · مدل‌های چینی ✅ · Gemini ❌ (QCode در حال حاضر مدل‌های Gemini را ارائه نمی‌دهد) |
| پروتکل و Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| محل پیکربندی | `~/.openclaw/openclaw.json` (JSON5، با بارگذاری مجدد خودکار) یا ویزارد `openclaw onboard` |
| مستندات رسمی | [ارائه‌دهندگان سفارشی](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md) · [docs.openclaw.ai](https://docs.openclaw.ai) |

OpenClaw یک **دستیار هوش مصنوعی متن‌باز است که روی دستگاه‌های خودتان اجرا می‌شود**: یک فرایند دروازه خودمیزبان به Discord، Telegram، Slack، iMessage و دیگر کانال‌های چت متصل می‌شود، با اپلیکیشن‌های بومی برای macOS / Windows / Linux. **این یک ویرایشگر کد نیست** — در این بخش قرار دارد زیرا اغلب به‌عنوان «دروازه دستیار شخصی روی چند مدل» استفاده می‌شود، و زیرا به‌صورت بومی از هر نقطه پایانی سازگار با OpenAI / Anthropic پشتیبانی می‌کند.

## پیش‌نیازها

- OpenClaw نصب شده باشد (نصب‌کننده رسمی `curl -fsSL https://openclaw.ai/install.sh | bash`؛ نصب مستقیم با npm به Node 24.16+ نیاز دارد، توصیه رسمی 26+ است، به [README](https://github.com/openclaw/openclaw#readme) مراجعه کنید).
- یک کلید `cr_` از QCode.cc (یکی را در [داشبورد](https://qcode.cc/dashboard) ایجاد کنید). **نیازی** به حساب کاربری جداگانه نزد ارائه‌دهنده مدل نیست.
- خود OpenClaw به حساب کاربری اختصاصی نیاز ندارد؛ هر مدل از ارائه‌دهندگانی می‌آید که شما پیکربندی می‌کنید.

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

### مسیر A: ویرایش مستقیم فایل پیکربندی (توصیه‌شده)

یک بلوک `models.providers` به `~/.openclaw/openclaw.json` اضافه کنید. فایل JSON5 است (کامنت‌ها و ویرگول‌های انتهایی مجاز هستند) و دروازه آن را به‌صورت خودکار بارگذاری مجدد می‌کند — نیازی به راه‌اندازی مجدد نیست:

```json5
{
  models: {
    mode: "merge", // keep built-in providers, append QCode
    providers: {
      qcode: {
        baseUrl: "https://api.qcode.cc/api",
        apiKey: "${QCODE_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-sonnet-5", name: "Claude Sonnet 5", input: ["text", "image"] },
        ],
      },
      qcode_openai: {
        baseUrl: "https://api.qcode.cc/openai/v1",
        apiKey: "${QCODE_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.6", name: "GPT-5.6" },
          { id: "glm-5.3", name: "GLM-5.3" },
        ],
      },
    },
  },
}
```

سه نکته (همگی از [مستند ارائه‌دهندگان سفارشی](https://github.com/openclaw/openclaw/blob/main/docs/concepts/model-providers/custom-providers.md) رسمی):

- `apiKey` از جایگزینی `${ENV_VAR}` پشتیبانی می‌کند؛ مستندات OpenClaw برای کلید، ارجاع‌های محرمانه / متغیرهای محیطی را به‌جای کلید متنی توصیه می‌کند.
- `api` آداپتور درخواست است: پروتکل Anthropic برابر `anthropic-messages` و پروتکل OpenAI برابر `openai-completions` است. تنظیم فقط `baseUrl` بدون `api` به‌صورت پیش‌فرض `openai-completions` می‌شود.
- یک مدل فقط زمانی تصاویر را (به‌صورت بینایی) دریافت می‌کند که صریحاً `input: ["text", "image"]` را تنظیم کنید؛ در غیر این صورت تصاویر به‌صورت ارجاع متنی ارسال می‌شوند.

### مسیر B: گزینه ارائه‌دهنده سفارشی در ویزارد onboard

```bash
openclaw onboard --install-daemon
```

در فهرست ارائه‌دهندگان، **Custom Provider** را انتخاب کنید (زیر **More…** وقتی مستقیماً فهرست نشده است)، سپس Base URL، کلید API، سازگاری و شناسه مدل را وارد کنید. ویزارد پیش از ذخیره یک تکمیل واقعی را بررسی می‌کند (عبارت رسمی: *یک پاسخ واقعی را پیش از ذخیره بررسی می‌کند*)، که فوراً غلط‌های تایپی در URL را شناسایی می‌کند.

معادل غیرتعاملی، برای یک مدل Claude:

```bash
openclaw onboard --non-interactive --accept-risk \
  --auth-choice custom-api-key \
  --custom-base-url "https://api.qcode.cc/api" \
  --custom-model-id "claude-sonnet-5" \
  --custom-api-key "$QCODE_API_KEY" \
  --custom-compatibility anthropic
```

🔴 دو املا متفاوت وجود دارد: فلگ ویزارد `--custom-compatibility` مقدار `anthropic` را می‌پذیرد، در حالی که `api` در فایل پیکربندی مقدار `anthropic-messages` را می‌پذیرد (به [مستندات onboard](https://github.com/openclaw/openclaw/blob/main/docs/cli/onboard.md) مراجعه کنید).
## بررسی کارکرد

1. اگر از مسیر B استفاده کردید، ویزارد پیش‌تر یک بررسی زنده برای شما اجرا کرده است (یک درخواست واقعی پیش از ذخیره).
2. پس از مسیر A، از عامل چیزی ساده مانند `ping` بپرسید. اگر ناموفق بود، ابتدا نحو JSON5 فایل `~/.openclaw/openclaw.json` را بررسی کنید — کامنت‌ها و ویرگول‌های نابجا آن را خراب می‌کنند.
3. برای اینکه فقط بررسی کنید که مسیر وجود دارد و کلید می‌رسد:

```bash
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $QCODE_API_KEY"
# → 401 = key invalid; any code other than a JSON error = path reachable
```

4. هر درخواست (از جمله درخواست‌های OpenClaw) در [probe.qcode.cc](https://probe.qcode.cc) ثبت می‌شود — کلید خود را وارد کنید تا مدل و وضعیت درخواست‌های واقعی را ببینید. هنوز ناموفق است؟ فهرست بررسی موجود در [عیب‌یابی](/docs/reference/troubleshooting) را دنبال کنید.

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

- **هشدار شکل Base URL**: هر دو نمونه رسمی `anthropic-messages` (Synthetic، MiniMax) از `baseUrl` **بدون `/v1`** استفاده می‌کنند (مثلاً `https://api.minimax.io/anthropic`)، بنابراین این صفحه از `https://api.qcode.cc/api` استفاده می‌کند. مسیر دقیقی که OpenClaw اضافه می‌کند به‌صورت واژه‌به‌واژه مستند نشده و در اینجا به‌صورت زنده آزمایش نشده است. اگر درخواست‌ها 404 برگردانند، `baseUrl` را به مسیر کامل `https://api.qcode.cc/api/v1/messages` تغییر دهید.
- آداپتور `openai-responses` فقط برای بک‌اندهایی مستند شده است که از `/v1/responses` پشتیبانی می‌کنند. در QCode، نقطه پایانی Responses به مدل‌های GPT سرویس می‌دهد؛ مدل‌های چینی را از طریق `openai-completions` مسیریابی کنید (ماتریس پروتکل: [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths)).
- در نقاط پایانی غیرمستقیم `anthropic-messages`، OpenClaw سرآیندهای بتای Anthropic را پیش از ارسال درخواست سرکوب می‌کند (رفتار مستندشده) — این برای درگاه‌های شخص ثالث مفید است. اگر ابزار دیگری با خطاهای 400 مربوط به `anthropic-beta` مواجه شود، این مشکل OpenClaw نیست.
- آداپتور Gemini (`google-generative-ai`) در فهرست رسمی وجود دارد، اما QCode در حال حاضر مدل‌های Gemini را ارائه نمی‌دهد، بنابراین هیچ نمونه‌ای ارائه نشده است.
- مستندات رسمی روی شاخه `main` در GitHub قرار دارند؛ ممکن است docs.openclaw.ai کمی عقب‌تر باشد.

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

- [نقاط پایانی و مسیرهای API](/docs/getting-started/endpoints-and-api-paths) — پروتکل‌ها و نحوه پر کردن Base URLها
- [مرور سازگاری ابزارها](/docs/ide/tool-compatibility) — پشتیبانی پروتکل در تمام ابزارها
- [راه‌اندازی CC Switch](/docs/ide/cc-switch) — تغییر ارائه‌دهنده از طریق رابط گرافیکی برای Claude Code / Codex
- [مدل‌های چینی](/docs/usage/cn-models) — شناسه‌های فعلی GLM / Kimi / DeepSeek / Qwen که عرضه می‌شوند
- [عیب‌یابی](/docs/reference/troubleshooting)
- [راه‌اندازی LobsterAI](/docs/ide/lobsterai) — کلاینت دسکتاپ NetEase Youdao که بر پایه OpenClaw ساخته شده است؛ مدل‌های سفارشی آن آدرس‌های Anthropic Compatible و OpenAI Compatible را می‌پذیرند
- [راه‌اندازی AutoClaw](/docs/ide/autoclaw) — اپلیکیشن محلی OpenClaw از Zhipu؛ مدل‌های سفارشی آن از پروتکل OpenAI Chat استفاده می‌کنند