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

پیکربندی QCode.cc به‌عنوان ارائه‌دهندگان مدل برای OpenClaw: بلوک models.providers در openclaw.json، ویزارد راه‌اندازی ارائه‌دهنده سفارشی، و نحوه تأیید اتصال

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

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

در یک نگاه¶

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 مراجعه کنید).
• یک کلید cr_ از QCode.cc (یکی را در داشبورد ایجاد کنید). نیازی به حساب کاربری جداگانه نزد ارائه‌دهنده مدل نیست.
• خود OpenClaw به حساب کاربری اختصاصی نیاز ندارد؛ هر مدل از ارائه‌دهندگانی می‌آید که شما پیکربندی می‌کنید.

راه‌اندازی¶

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

یک بلوک models.providers به ~/.openclaw/openclaw.json اضافه کنید. فایل 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" },
        ],
      },
    },
  },
}

سه نکته (همگی از مستند ارائه‌دهندگان سفارشی رسمی):

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

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

openclaw onboard --install-daemon

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

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

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 مراجعه کنید).

بررسی کارکرد¶

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

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

1. هر درخواست (از جمله درخواست‌های OpenClaw) در probe.qcode.cc ثبت می‌شود — کلید خود را وارد کنید تا مدل و وضعیت درخواست‌های واقعی را ببینید. هنوز ناموفق است؟ فهرست بررسی موجود در عیب‌یابی را دنبال کنید.

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

• هشدار شکل 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).
• در نقاط پایانی غیرمستقیم anthropic-messages، OpenClaw سرآیندهای بتای Anthropic را پیش از ارسال درخواست سرکوب می‌کند (رفتار مستندشده) — این برای درگاه‌های شخص ثالث مفید است. اگر ابزار دیگری با خطاهای 400 مربوط به anthropic-beta مواجه شود، این مشکل OpenClaw نیست.
• آداپتور Gemini (google-generative-ai) در فهرست رسمی وجود دارد، اما QCode در حال حاضر مدل‌های Gemini را ارائه نمی‌دهد، بنابراین هیچ نمونه‌ای ارائه نشده است.
• مستندات رسمی روی شاخه main در GitHub قرار دارند؛ ممکن است docs.openclaw.ai کمی عقب‌تر باشد.

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

• نقاط پایانی و مسیرهای API — پروتکل‌ها و نحوه پر کردن Base URLها
• مرور سازگاری ابزارها — پشتیبانی پروتکل در تمام ابزارها
• راه‌اندازی CC Switch — تغییر ارائه‌دهنده از طریق رابط گرافیکی برای Claude Code / Codex
• مدل‌های چینی — شناسه‌های فعلی GLM / Kimi / DeepSeek / Qwen که عرضه می‌شوند
• عیب‌یابی
• راه‌اندازی LobsterAI — کلاینت دسکتاپ NetEase Youdao که بر پایه OpenClaw ساخته شده است؛ مدل‌های سفارشی آن آدرس‌های Anthropic Compatible و OpenAI Compatible را می‌پذیرند
• راه‌اندازی AutoClaw — اپلیکیشن محلی OpenClaw از Zhipu؛ مدل‌های سفارشی آن از پروتکل OpenAI Chat استفاده می‌کنند

سازمانی ←