الوثائقDocumentationAppsOpenClaw model provider setup

إعداد موفر النماذج في OpenClaw

اضبط OpenClaw باستخدام مفتاح API لأي موفر نماذج بعد التثبيت.

يُثبَّت OpenClaw في Appbox من دون الحاجة إلى مفتاح API للنماذج.

الطريقة الموصى بها لإكمال الإعداد هي الاتصال بتطبيق OpenClaw عبر SSH وتشغيل معالج openclaw onboard المدمج. هذا المعالج أكثر أماناً من تعديل ملف الإعداد الكامل يدوياً، لأنه يحافظ على إعدادات بوابة Appbox أثناء إرشادك خلال موفري النماذج ومفاتيح API والقنوات وفحوصات الصحة والمهارات.

إذا لم تكن تستطيع استخدام SSH أو لا ترغب في ذلك، فاستخدم طريقة لوحة التحكم الاحتياطية بدلاً من ذلك.

الطريقة الموصى بها: الدخول إلى OpenClaw عبر SSH وتشغيل الإعداد الأولي

استخدم هذه الطريقة للتثبيتات الجديدة، وللتثبيتات الحالية التي تحتاج إلى إضافة بيانات اعتماد موفر النماذج أو تغييرها.

ما تحتاجه أولاً

  • صفحة تفاصيل تطبيق OpenClaw في Appbox.
  • SSH Command المعروض في قسم Configuration.
  • Gateway Token / SSH Password. هذا هو السر نفسه المُولَّد لتسجيل الدخول إلى لوحة OpenClaw.
  • حساب لدى موفر نماذج أو مفتاح API. إذا لم يكن لديك واحد بعد، فراجع الحصول على مفاتيح API.

تعرض صفحة تفاصيل التطبيق أمر SSH جاهزاً للنسخ:

Appbox OpenClaw app details page with the SSH command highlighted

الاتصال من macOS

  1. افتح Terminal أو iTerm2.
  2. انسخ SSH Command من صفحة تفاصيل تطبيق OpenClaw.
  3. الصقه وشغّله. سيبدو مشابهاً لما يلي:
ssh node@your-openclaw-domain.example -p 12345
  1. إذا سألك macOS هل تثق بالمضيف، فاكتب yes واضغط Enter.
  2. عند طلب كلمة المرور، الصق Gateway Token / SSH Password واضغط Enter. لن يعرض Terminal أي أحرف أثناء كتابة كلمة المرور أو لصقها.

الاتصال من Windows

يتضمن Windows 10 وWindows 11 عميل OpenSSH افتراضياً.

  1. افتح Windows Terminal أو PowerShell.
  2. انسخ SSH Command من صفحة تفاصيل تطبيق OpenClaw.
  3. الصقه وشغّله:
ssh node@your-openclaw-domain.example -p 12345
  1. إذا سألك Windows هل تثق بالمضيف، فاكتب yes واضغط Enter.
  2. عند طلب كلمة المرور، الصق Gateway Token / SSH Password واضغط Enter. لن يعرض PowerShell كلمة المرور الملصقة.

إذا أبلغ Windows بأن ssh غير معروف، فثبّت OpenSSH Client من Settings > System > Optional features، ثم أعد فتح Windows Terminal وحاول مرة أخرى.

تشغيل معالج إعداد OpenClaw الأولي

بعد نجاح اتصال SSH، شغّل:

openclaw onboard
iTerm2 on macOS connected to OpenClaw over SSH and running the openclaw onboard command

المعالج تفاعلي. استخدم هذه الخيارات الخاصة بـ Appbox:

  1. Existing config: اختر خيار مراجعة الإعداد الحالي أو تعديله. لا تختر إعادة ضبط كاملة إلا إذا كنت تقصد عمداً إعادة بناء إعداد OpenClaw من الصفر.
  2. Model and auth: اختر موفرك، مثل OpenRouter أو OpenAI أو Anthropic أو Google أو xAI أو موفر مخصص متوافق مع OpenAI. الصق مفتاح API عندما يطلبه المعالج. يُعد OpenRouter الخيار الافتراضي الأسهل لمعظم المستخدمين، لأن مفتاحاً واحداً يمكنه التوجيه إلى نماذج كثيرة. إذا كانت لديك اشتراك OpenAI Codex، فاختر OpenAI Codex في قائمة الموفرين، وليس خياراً اسمه codex فقط.
  3. Default model: اختر النموذج الذي يوصي به المعالج لذلك الموفر، أو أدخل قيمة provider/model يدوياً، مثل openrouter/auto.
  4. Workspace: أبقِ مساحة العمل الافتراضية ما لم يكن لديك سبب محدد لتغييرها.
  5. Gateway settings: أبقِ إعدادات بوابة Appbox الحالية. وبوجه خاص، أبقِ مصادقة الرمز مفعّلة، وأبقِ إعدادات منفذ/ربط البوابة الحالية.
  6. Channels: اضبط WhatsApp أو Telegram أو Discord أو Signal أو iMessage أو القنوات الأخرى الآن، أو تخطَّها وأضفها لاحقاً باستخدام openclaw configure.
  7. Web search: اختر موفر بحث إذا كان لديك واحد، أو تخطَّ هذه الخطوة حالياً.
  8. Daemon/service install: يشرف Appbox بالفعل على OpenClaw داخل الحاوية، لذلك تخطَّ تثبيت daemon إذا عرضه المعالج.
  9. Health check: اسمح للمعالج بتشغيل فحص الصحة.
  10. Skills: اسمح للمعالج بفحص المهارات المضمّنة. عندما يسألك عن Preferred node manager for skill installs، اختر npm.

عند انتهاء الإعداد الأولي، عُد إلى لوحة OpenClaw. إذا كانت اللوحة مفتوحة بالفعل، فحدّثها واختبر مطالبة دردشة قصيرة.

أوامر متابعة مفيدة عبر SSH:

openclaw configure
openclaw status --deep
openclaw health

الحصول على مفاتيح API (مع روابط لوحات التحكم)

استخدم لوحات الموفرين هذه لإنشاء المفاتيح. مع طريقة SSH الموصى بها، الصق المفتاح عندما يطلبه openclaw onboard. ومع طريقة لوحة التحكم الاحتياطية، ادمج المفتاح في Config > Secrets > Raw.

الموصى به أولاً: OpenRouter (أفضل خيار افتراضي لمعظم المستخدمين)

لماذا نوصي به:

  • يمنحك مفتاحاً واحداً للعديد من مورّدي النماذج.
  • يمكنك استخدام openrouter/auto، الذي يستطيع تبديل النماذج بناءً على صعوبة المهمة.
  • يمكن أن يقلل auto التكلفة عبر توجيه المهام الأبسط إلى نماذج أرخص.

كيفية الحصول على مفتاح:

  1. انتقل إلى OpenRouter وسجّل الدخول.
  2. افتح إعدادات API Keys.
  3. انقر Create وانسخ المفتاح (يظهر مرة واحدة).
  4. استخدمه عندما يطلب معالج OpenClaw مفتاح OpenRouter API. أما في طريقة لوحة التحكم الاحتياطية، فمفتاح الإعداد هو models.providers.openrouter.apiKey.
OpenRouter API keys page screenshot from a public tutorial

الدليل المصدر: How to Get an OpenRouter API Key

OpenAI

كيفية الحصول على مفتاح:

  1. سجّل الدخول إلى OpenAI Platform.
  2. افتح API Keys.
  3. انقر Create new secret key.
  4. انسخه فوراً (تعرض OpenAI القيمة الكاملة مرة واحدة فقط).
OpenAI API key settings screenshot from a public tutorial

الدليل المصدر: How to Get an OpenAI API Key

Anthropic

كيفية الحصول على مفتاح:

  1. سجّل الدخول إلى Anthropic Console.
  2. افتح API Keys.
  3. انقر Create Key.
  4. انسخ المفتاح فوراً (يظهر مرة واحدة).
Anthropic API key creation screenshot from a public tutorial

الدليل المصدر: How to get your Claude API key

Google (Gemini عبر AI Studio)

كيفية الحصول على مفتاح:

  1. افتح Google AI Studio.
  2. انتقل إلى API Keys.
  3. انقر Create API key (لمشروع جديد أو موجود).
  4. انسخ المفتاح واحفظه.
Google AI Studio API key creation screenshot from a public tutorial

الدليل المصدر: Get Google AI API Key

ملاحظة: يمكن أن تتغير لوحات الموفرين كثيراً وقد تعرض مطالبة تسجيل دخول بحسب حالة جلستك.

طريقة احتياطية: ضبط مصادقة الموفر في لوحة التحكم

استخدم هذه الطريقة فقط إذا لم يكن SSH متاحاً أو كنت تفضّل الإعداد اليدوي. يعمل محرر Raw في لوحة التحكم، لكنه يحرر كائن إعداد OpenClaw بالكامل مرة واحدة. احرص على دمج إعدادات الموفر داخل الملف الحالي بدلاً من استبدال إعدادات البوابة والمهارات الافتراضية الخاصة بـ Appbox.

  1. افتح رابط لوحة OpenClaw من صفحة تفاصيل التطبيق المثبت.
  2. انتقل إلى Config > Secrets.
  3. اختر Raw بدلاً من Form.
  4. انقر زر إظهار القيم الحساسة (الذي يبدو كعين مشطوبة).
  5. ادمج إعدادات الموفر من الأمثلة أدناه داخل إعدادك الحالي (راجع كيف يتناسب إعداد الموفر اليدوي مع الملف الكامل) — لا تستبدل الملف كله إلا إذا كنت تقصد إعادة ضبط البوابة والمهارات وإعدادات Appbox الافتراضية الأخرى.
  6. احفظ وطبّق تغييرات الإعداد.

كيف يتناسب إعداد الموفر اليدوي مع الملف الكامل

يقوم Config > Secrets > Raw بتحرير إعداد OpenClaw بالكامل في كائن واحد. على Appbox، يتضمن هذا الملف مسبقاً أشياء مثل gateway (bind ومصادقة token وControl UI)، وskills.load.extraDirs (المهارات المضمّنة)، وcommands، وأحياناً meta. لا تعرض المقتطفات في قسم أمثلة الموفرين الرئيسيين إلا الأجزاء التي تحتاجها للنماذج: شجرة models وagents.defaults.model.primary.

ما الذي يجب فعله: أبقِ مفاتيح المستوى الأعلى الحالية (gateway وskills وcommands وغيرها) وأضف أو حدّث هذين القسمين:

  • models.providers — أضف الموفر (مثل openrouter) وapiKey الخاص به وbaseUrl عند الحاجة وقائمة models.
  • agents.defaults.model.primary — اضبط سلسلة النموذج الافتراضي (مثل openrouter/auto) حتى يستخدم الوكيل ذلك الموفر.

إذا كان models أو agents موجودين بالفعل، فادمج المفاتيح الجديدة داخل تلك الكائنات بدلاً من تكرارها.

فيما يلي مثال على شكل ملف Raw كامل واحد بصيغة JSON (قد يقبل المحرر عملياً علامات اقتباس بنمط JSON5 أيضاً). قد يتضمن ملفك الحقيقي حقولاً أكثر (مثل بيانات وصفية أغنى للنماذج أو meta). كتل الموفرين في الأمثلة التالية هي الأجزاء التي توائمها مع models وagents هنا.

{
  "models": {
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "YOUR_OPENROUTER_KEY",
        "models": [
          {
            "id": "auto",
            "name": "Auto (OpenRouter)",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 200000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/auto"
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "gateway": {
    "bind": "lan",
    "controlUi": {
      "dangerouslyAllowHostHeaderOriginFallback": true,
      "dangerouslyDisableDeviceAuth": true
    },
    "auth": {
      "mode": "token",
      "token": "YOUR_GATEWAY_TOKEN"
    }
  },
  "skills": {
    "load": {
      "extraDirs": ["/app/skills"]
    }
  }
}

رمز البوابة مقابل مفتاح API للموفر: يُستخدم gateway.auth.token فقط لتسجيل الدخول إلى OpenClaw Control UI / gateway. أما models.providers.*.apiKey فهو مفتاح مورّد LLM لديك (OpenRouter أو OpenAI أو غيرهما) — وهما إعدادان مختلفان.

أمثلة الموفرين الرئيسيين

استخدم كتلة موفر واحدة في البداية، وتأكد أنها تعمل، ثم أضف موفرين آخرين. كل مثال أدناه هو مقتطف دمج: تم حذف ... من الإعداد (أسطر أعلى أو أسفل)، و}, قبل "models" هو إغلاق أي مفتاح يقع فوق models في ملفك (مثل skills أو commands). المقتطفات ليست JSON صالحاً بذاتها — ادمج قسمي models وagents داخل كائن الجذر.

OpenRouter

...
  },
  "models": {
    "providers": {
      "openrouter": {
        "baseUrl": "https://openrouter.ai/api/v1",
        "apiKey": "sk-or-...",
        "models": [
          {
            "id": "auto",
            "name": "Auto (OpenRouter)"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/auto"
      }
    }
  },
...

OpenAI

...
  },
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-...",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT-5.4"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai/gpt-5.4"
      }
    }
  },
...

Anthropic

...
  },
  "models": {
    "providers": {
      "anthropic": {
        "baseUrl": "https://api.anthropic.com/v1",
        "apiKey": "sk-ant-...",
        "models": [
          {
            "id": "claude-opus-4-6",
            "name": "Claude Opus 4.6"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-opus-4-6"
      }
    }
  },
...

Google (Gemini)

...
  },
  "models": {
    "providers": {
      "google": {
        "apiKey": "AIza...",
        "models": [
          {
            "id": "gemini-3.1-pro-preview",
            "name": "Gemini 3.1 Pro Preview"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-3.1-pro-preview"
      }
    }
  },
...

xAI (Grok)

...
  },
  "models": {
    "providers": {
      "xai": {
        "apiKey": "xai-...",
        "models": [
          {
            "id": "grok-4",
            "name": "Grok 4"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "xai/grok-4"
      }
    }
  },
...

Mistral

...
  },
  "models": {
    "providers": {
      "mistral": {
        "baseUrl": "https://api.mistral.ai/v1",
        "apiKey": "sk-...",
        "models": [
          {
            "id": "mistral-large-latest",
            "name": "Mistral Large Latest"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "mistral/mistral-large-latest"
      }
    }
  },
...

Together AI

...
  },
  "models": {
    "providers": {
      "together": {
        "baseUrl": "https://api.together.xyz/v1",
        "apiKey": "together-...",
        "models": [
          {
            "id": "moonshotai/Kimi-K2.5",
            "name": "Kimi K2.5"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "together/moonshotai/Kimi-K2.5"
      }
    }
  },
...

ملاحظة Bedrock (بلا مفتاح API)

يستخدم Amazon Bedrock بيانات اعتماد AWS (مثل AWS_ACCESS_KEY_ID وAWS_SECRET_ACCESS_KEY وAWS_REGION) بدلاً من مفتاح API. يبدو إدخال موفر بسيط كما يلي:

...
  },
  "models": {
    "providers": {
      "amazon-bedrock": {
        "baseUrl": "https://bedrock-runtime.us-east-1.amazonaws.com",
        "api": "bedrock-converse-stream",
        "auth": "aws-sdk",
        "models": [
          {
            "id": "us.anthropic.claude-opus-4-6-v1:0",
            "name": "Claude Opus 4.6 (Bedrock)"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0"
      }
    }
  },
...

ملاحظات

  • رمز مصادقة البوابة ومفاتيح API لموفري النماذج إعدادات مختلفة.
  • إذا حصلت على خطأ من موفر (مثل نقص مفتاح Anthropic)، فحدّث النموذج الافتراضي إلى موفر أعددته بالفعل.
  • إذا فشل تحقق موفر، فتأكد أولاً من وجود حقول الموفر المطلوبة (baseUrl وmodels وapiKey عند الحاجة).

وثائق الموفرين الرسمية

Introduction