آموزش اتصال AvalAI به OpenClaw؛ استفاده از مدل‌های هوش مصنوعی بدون تحریم

نکته: ابزار Clawdbot اخیراً تغییر نام داده و اکنون با نام OpenClaw شناخته می‌شود (وب‌سایت: openclaw.ai). این راهنما برای تمام نسخه‌ها کاربرد دارد، اما دستورات بر اساس نام جدید یعنی openclaw نوشته شده‌اند. اگر هنوز آن را نصب نکرده‌اید، با دستور npm install -g openclaw شروع کنید.

ابزار OpenClaw به طور پیش‌فرض از غول‌هایی مثل OpenAI و Anthropic پشتیبانی می‌کند. اما قابلیت طلایی آن، امکان اتصال هر سرویس‌دهنده‌ی سازگار با OpenAI (OpenAI-compatible) است. در این راهنما یاد می‌گیریم چطور سرویس ایرانی AvalAI را به OpenClaw متصل کنیم.

چرا از AvalAI در OpenClaw استفاده کنیم؟

برای کاربران ایرانی، استفاده از سرویس‌دهنده‌های داخلی مثل AvalAI مزایای مشخصی دارد:

1. پرداخت ریالی: نیازی به کارت‌های اعتباری بین‌المللی ندارید.

2. رفع تحریم: بدون نیاز به تغییر IP و نگرانی از مسدود شدن اکانت، به مدل‌های روز دنیا (مثل GPT-4o یا Claude 3.5 Sonnet) دسترسی دارید.

3. مدیریت هزینه: تعرفه‌های رقابتی برای کارهای پرحجم

روش اول: روش خودکار (سریع و آسان)

اگر OpenClaw در حال اجراست، نیازی نیست درگیر فایل‌های کانفیگ شوید. کافیست دستور زیر را به خودِ چت‌بات OpenClaw بدهید تا تنظیمات را برایتان انجام دهد.

ابتدا کلید API خود را از سایت AvalAI کپی کنید و سپس پرامپت زیر را در محیط چت OpenClaw وارد کنید:

Add AvalAI as a custom provider to my OpenClaw config. Use these details:
- Provider name: avalai
- Base URL: https://api.avalai.ir/v1
- API key: [کلید API خود را اینجا جایگذاری کنید]
- API type: openai-completions

Add these models:
1. gpt-4o-mini (reasoning: false, context: 128000, max tokens: 4096)
2. gpt-4o (reasoning: true, context: 128000, max tokens: 4096)

Create aliases "4o-mini" and "4o" for easy switching. Apply the config when done.

OpenClaw به طور خودکار فایل کانفیگ شما را آپدیت کرده و Gateway را ریستارت می‌کند. برای اطمینان از صحت کار، دستور /models را بزنید و نام مدل‌های جدید را چک کنید.

روش دوم: تنظیم دستی (برای حرفه‌ای‌ها)

اگر می‌خواهید دقیقاً بدانید چه اتفاقی در حال رخ دادن است یا نیاز به عیب‌یابی دارید، مراحل زیر را طی کنید.

گام اول: پیدا کردن فایل کانفیگ

فایل تنظیمات در مسیر ~/.openclaw/openclaw.json قرار دارد (در ویندوز معمولاً در C:\Users\YourUser\.openclaw).

گام دوم: تعریف Provider

فایل JSON را باز کنید و در بخش models.providers، تنظیمات AvalAI را اضافه کنید:

{
  "models": {
    "mode": "merge",
    "providers": {
      "avalai": {
        "baseUrl": "https://api.avalai.ir/v1",
        "apiKey": "YOUR_AVALAI_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-4o-mini",
            "name": "gpt-4o-mini",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0.00015,
              "output": 0.0006,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 128000,
            "maxTokens": 4096
          }
        ]
      }
    }
  }
}

نکات مهم:

• baseUrl: حتماً باید https://api.avalai.ir/v1 باشد.

• api: باید روی openai-completions تنظیم شود.

• id: باید دقیقاً نام مدلی باشد که در مستندات AvalAI آمده است (مثلاً gpt-4o-mini یا llama-3-70b).

گام سوم: اضافه کردن به لیست مجاز (Allowlist)

بسیاری از کاربران اینجا به مشکل می‌خورند. تعریف کردن Provider کافی نیست؛ شما باید به OpenClaw اجازه دهید که از این مدل‌ها استفاده کند. در بخش agents.defaults.models کد زیر را اضافه کنید:

{
  "agents": {
    "defaults": {
      "models": {
        "avalai/gpt-4o-mini": {
          "alias": "4o-mini"
        }
      }
    }
  }
}

نکته کلیدی: فرمت کلید باید به صورت provider-name/model-name باشد (در اینجا avalai/gpt-4o-mini).

گام چهارم: اعمال تغییرات

پس از ذخیره فایل، دستور زیر را در ترمینال اجرا کنید تا تنظیمات اعمال شود:

openclaw gateway config.apply --file ~/.openclaw/openclaw.json

تست نهایی

برای اطمینان از اتصال صحیح:

1. دستتور /models را اجرا کنید تا لیست مدل‌ها را ببینید.

2. با دستور /model 4o-mini روی مدل AvalAI سوییچ کنید.

3. یک پیام آزمایشی ارسال کنید (مثلاً: “سلام، حالت چطوره؟”).

عیب‌یابی مشکلات رایج

خطای “model not allowed: avalai/gpt-4o-mini”

این یعنی مدل در لیست مجاز (Allowlist) نیست. به گام سوم برگردید و مطمئن شوید که نام مدل را به صورت کامل (ترکیب نام سرویس‌دهنده و نام مدل) وارد کرده‌اید.

مدل در لیست /models دیده نمی‌شود چک کنید که آیا مدل را در آرایه models در گام دوم تعریف کرده‌اید یا خیر. صرفاً اضافه کردن به Allowlist کافی نیست.

خطای اتصال (Connection Errors)

آدرس baseUrl و apiKey را چک کنید. می‌توانید با یک دستور curl ساده اتصال خود به AvalAI را تست کنید:

curl https://api.avalai.ir/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "test"}]}'

اگر این دستور کار کرد اما OpenClaw کار نکرد، مشکل از فایل JSON شماست. اگر این دستور هم کار نکرد، مشکل از اینترنت یا کلید API شماست.