OpenRouter

يوجّه OpenRouter الطلبات إلى نماذج عديدة من خلال واجهة API واحدة ومفتاح واحد. وهو متوافق مع OpenAI، لذلك يتواصل OpenClaw معه عبر آلية النقل نفسها بنمط openai-completions المستخدمة مع موفّري الوكيل الآخرين.

بدء الاستخدام

OAuth
مفتاح API

تشغيل الإعداد الأولي لـ OAuth

openclaw onboard --auth-choice openrouter-oauth

يفتح OpenClaw مسار تسجيل الدخول عبر المتصفح الخاص بـ OpenRouter ‏(PKCE)، ويستبدل الرمز بمفتاح API لـ OpenRouter، ثم يخزّنه في ملف تعريف المصادقة الافتراضي لـ OpenRouter. على المضيفين البعيدين أو غير المزودين بواجهة رسومية، يطبع OpenClaw عنوان URL لتسجيل الدخول ويطلب منك لصق عنوان URL لإعادة التوجيه بعد تسجيل الدخول.

(اختياري) التبديل إلى نموذج محدد

يستخدم الإعداد الأولي openrouter/auto افتراضيًا. اختر نموذجًا محددًا لاحقًا:

openclaw models set openrouter/<provider>/<model>

الحصول على مفتاح API

أنشئ مفتاح API على openrouter.ai/keys.

تشغيل الإعداد الأولي باستخدام مفتاح API

openclaw onboard --auth-choice openrouter-api-key

(اختياري) التبديل إلى نموذج محدد

يستخدم الإعداد الأولي openrouter/auto افتراضيًا. اختر نموذجًا محددًا لاحقًا:

openclaw models set openrouter/<provider>/<model>

مثال على الإعداد

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/auto" },
    },
  },
}

مراجع النماذج

تتبع مراجع النماذج النمط openrouter/<provider>/<model>. للاطلاع على القائمة الكاملة للموفّرين والنماذج المتاحة، راجع /concepts/model-providers.

نماذج الرجوع الاحتياطية المضمّنة، والمستخدمة عند تعذّر الاكتشاف المباشر للكتالوج:

مرجع النموذج	ملاحظات
`openrouter/auto`	التوجيه التلقائي من OpenRouter
`openrouter/moonshotai/kimi-k2.6`	Kimi K2.6 عبر MoonshotAI
`openrouter/moonshotai/kimi-k2.5`	Kimi K2.5 عبر MoonshotAI

يُحلّ أي مرجع آخر بصيغة openrouter/<provider>/<model>، بما في ذلك openrouter/openrouter/fusion (راجع موجّه Fusion)، ديناميكيًا بالاستناد إلى كتالوج النماذج المباشر في OpenRouter.

توليد الصور

يمكن لـ OpenRouter دعم أداة image_generate. عيّن نموذج صور من OpenRouter ضمن agents.defaults.imageGenerationModel:

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
        timeoutMs: 180_000,
      },
    },
  },
}

يرسل OpenClaw طلبات الصور إلى واجهة API للصور القائمة على إكمالات المحادثة في OpenRouter مع modalities: ["image", "text"]. تتلقى نماذج صور Gemini أيضًا تلميحات aspectRatio وresolution عبر image_config الخاص بـ OpenRouter؛ أما نماذج الصور الأخرى فلا تتلقاها. استخدم agents.defaults.imageGenerationModel.timeoutMs للنماذج الأبطأ؛ وتظل قيمة timeoutMs الخاصة بكل استدعاء لأداة image_generate هي المقدَّمة.

توليد الفيديو

يمكن لـ OpenRouter دعم أداة video_generate عبر واجهة API غير المتزامنة /videos. عيّن نموذج فيديو من OpenRouter ضمن agents.defaults.videoGenerationModel:

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "openrouter/google/veo-3.1-fast",
      },
    },
  },
}

يرسل OpenClaw مهام تحويل النص إلى فيديو والصورة إلى فيديو، ويستطلع polling_url المُعاد، ثم ينزّل الفيديو المكتمل من unsigned_urls في OpenRouter أو من نقطة نهاية محتوى المهمة. تُستخدم الصور المرجعية افتراضيًا كصور للإطار الأول/الأخير؛ أما الصور الموسومة بـ reference_image فتُرسل كمراجع إدخال بدلًا من ذلك. يدعم النموذج الافتراضي المضمّن google/veo-3.1-fast مددًا قدرها 4/6/8 ثوانٍ، ودقتي 720P و1080P، ونسبتي عرض إلى ارتفاع 16:9 و9:16. تحويل الفيديو إلى فيديو غير مدعوم: لا تقبل واجهة API المصدرية إلا مراجع النصوص والصور.

توليد الموسيقى

يمكن لـ OpenRouter دعم أداة music_generate من خلال إخراج الصوت في إكمالات المحادثة. عيّن نموذج صوت من OpenRouter ضمن agents.defaults.musicGenerationModel:

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "openrouter/google/lyria-3-pro-preview",
        timeoutMs: 180_000,
      },
    },
  },
}

يستخدم موفّر الموسيقى المضمّن في OpenRouter النموذج google/lyria-3-pro-preview افتراضيًا، ويتيح أيضًا google/lyria-3-clip-preview. يرسل OpenClaw ‏modalities: ["text", "audio"]، ويبث الاستجابة، ويجمع مقاطع الصوت، ويحفظ النتيجة كوسائط مولّدة لتسليمها عبر القناة. تقبل نماذج Lyria صورة مرجعية واحدة من خلال المعامل المشترك music_generate image=.... يُحدّ الصوت المتدفق، والاحتفاظ بالنص المنسوخ، وغلاف أحداث SSE المشتق بواسطة agents.defaults.mediaMaxMb (الحد الافتراضي للصوت هو 16 ميغابايت).

تحويل النص إلى كلام

يمكن أن يعمل OpenRouter كمزوّد لتحويل النص إلى كلام (TTS) من خلال نقطة النهاية المتوافقة مع OpenAI /audio/speech.

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          model: "hexgrad/kokoro-82m",
          speakerVoice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

إذا حُذف messages.tts.providers.openrouter.apiKey، فسيعود تحويل النص إلى كلام احتياطيًا إلى models.providers.openrouter.apiKey، ثم إلى OPENROUTER_API_KEY.

تحويل الكلام إلى نص (الصوت الوارد)

يمكن لـ OpenRouter نسخ مرفقات الصوت/الرسائل الصوتية الواردة من خلال المسار المشترك tools.media.audio، باستخدام نقطة نهاية تحويل الكلام إلى نص (STT) الخاصة به (/audio/transcriptions). ينطبق ذلك على أي Plugin قناة يمرّر الصوت/الرسائل الصوتية الواردة إلى الفحص التمهيدي لفهم الوسائط.

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "openrouter", model: "openai/whisper-large-v3-turbo" }],
      },
    },
  },
}

يرسل OpenClaw طلبات تحويل الكلام إلى نص في OpenRouter بصيغة JSON مع صوت مشفّر بـ base64 ضمن input_audio (وفق عقد تحويل الكلام إلى نص الخاص بـ OpenRouter)، وليس كعمليات رفع لنماذج OpenAI متعددة الأجزاء.

موجّه Fusion

يرسل OpenRouter Fusion مرجع نموذج واحدًا من OpenClaw إلى عدة نماذج OpenRouter بالتوازي، ويجعل OpenRouter يحكم على إجاباتها، ثم يعيد استجابة نهائية واحدة من خلال نقطة نهاية OpenRouter المعتادة. معرّف النموذج في المصدر الأعلى هو openrouter/fusion، ولذلك يحمل مرجع نموذج OpenClaw كلًا من بادئة مزوّد OpenClaw ونطاق أسماء OpenRouter في المصدر الأعلى:

openclaw models set openrouter/openrouter/fusion

اضبط لجنة Fusion ونموذج التحكيم من خلال params.extraBody الخاص بالنموذج؛ تُمرّر هذه الحقول مباشرةً إلى متن طلب إكمالات المحادثة في OpenRouter. يعمل Fusion مع الإعداد الأولي عبر OAuth أو مفتاح API؛ وإذا كنت تستخدم OAuth، فاحذف سطر env.OPENROUTER_API_KEY أدناه.

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/openrouter/fusion" },
      models: {
        "openrouter/openrouter/fusion": {
          params: {
            extraBody: {
              plugins: [
                {
                  id: "fusion",
                  analysis_models: [
                    "google/gemini-3.5-flash",
                    "moonshotai/kimi-k2.6",
                    "deepseek/deepseek-v4-pro",
                  ],
                  model: "google/gemini-3.5-flash",
                },
              ],
            },
          },
        },
      },
    },
  },
}

تمثّل analysis_models اللجنة المتوازية؛ أما model داخل إعدادات Plugin الخاص بـ Fusion فهو نموذج التحكيم. لا تضبط tool_choice في المستوى الأعلى على "required" في أدوار الوكيل/المحادثة المعتادة لمحاولة فرض Fusion؛ إذ قد تتضمن أدوار OpenClaw تعريفات أدواته الخاصة، وقد يؤدي فرض اختيار أداة في المستوى الأعلى إلى اختيار إحدى تلك الأدوات بدلًا من موجّه Fusion. عند وجود إعداد Plugin الخاص بـ Fusion هذا، يضيف OpenClaw ملاحظة منقّحة إلى موجّه النظام تسرد نماذج التحليل المضبوطة ونموذج التحكيم، بحيث يستطيع الوكيل الإجابة عن الأسئلة المتعلقة بلجنة Fusion الخاصة به. لا تُنسخ حقول extraBody الأخرى إلى الموجّه. يكون Fusion أبطأ حسب التصميم: يوزّع OpenRouter الموجّه على عدة نماذج تحليل، ثم ينفّذ خطوة تحكيم/توليف، ولذلك يكون زمن الاستجابة أعلى من طلب مباشر إلى نموذج واحد. استخدمه للحصول على إجابات متأنية وعالية الجودة أو في مسارات التصعيد، وليس كخيار افتراضي حساس لزمن الاستجابة. أبقِ اللجنة صغيرة واختر نماذج تحليل وتحكيم أسرع للحصول على استجابات أسرع. اختبر مرجعًا مضبوطًا باستدعاء محلي لمرة واحدة:

openclaw infer model run --local \
  --model openrouter/openrouter/fusion \
  --prompt "Reply with exactly: FUSION_OK" \
  --json

المصادقة والترويسات

يستخدم OpenRouter رمز Bearer من مفتاح API الخاص بك. يمثّل OAuth في OpenRouter تدفق تسجيل دخول باستخدام PKCE يُصدر مفتاح API لـ OpenRouter، ولذلك يخزّن OpenClaw النتيجة في ملف تعريف مصادقة مفتاح API نفسه openrouter:default المستخدم عند الإعداد اليدوي لمفتاح API. لتسجيل الدخول أو تدوير المفتاح المخزّن في تثبيت حالي من دون إعادة تشغيل الإعداد الأولي الكامل:

openclaw models auth login --provider openrouter --method oauth
openclaw models auth login --provider openrouter --method api-key

في طلبات OpenRouter الموثّقة (https://openrouter.ai/api/v1)، يضيف OpenClaw ترويسات إسناد التطبيق الموثّقة في OpenRouter:

الترويسة	القيمة
`HTTP-Referer`	`https://openclaw.ai`
`X-OpenRouter-Title`	`OpenClaw`
`X-OpenRouter-Categories`	`cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent`

إذا أعدت توجيه مزوّد OpenRouter إلى وكيل آخر أو عنوان URL أساسي مختلف، فلن يحقن OpenClaw ترويسات OpenRouter تلك أو علامات التخزين المؤقت الخاصة بـ Anthropic.

الإعدادات المتقدمة

تخزين الاستجابات مؤقتًا

يتطلب تخزين استجابات OpenRouter مؤقتًا تفعيله صراحةً. فعّله لكل نموذج على حدة:

{
  agents: {
    defaults: {
      models: {
        "openrouter/auto": {
          params: {
            responseCache: true,
            responseCacheTtlSeconds: 300,
          },
        },
      },
    },
  },
}

يرسل OpenClaw X-OpenRouter-Cache: true، ويرسل أيضًا عند ضبطه X-OpenRouter-Cache-TTL. تفرض responseCacheClear: true تحديثًا للطلب الحالي وتخزّن الاستجابة البديلة. تُقبل الأسماء البديلة بصيغة snake_case (response_cache وresponse_cache_ttl_seconds وresponse_cache_clear)، كما تُقبل responseCacheTtl / response_cache_ttl من دون اللاحقة Seconds.يختلف ذلك عن تخزين موجّه المزوّد مؤقتًا وعن علامات Anthropic cache_control الخاصة بـ OpenRouter. ولا ينطبق إلا على مسارات openrouter.ai الموثّقة، وليس على عناوين URL الأساسية للوكلاء المخصصين.

علامات التخزين المؤقت الخاصة بـ Anthropic

في مسارات OpenRouter الموثّقة، تحتفظ مراجع نماذج Anthropic بعلامات cache_control الخاصة بـ Anthropic في OpenRouter لتحسين إعادة استخدام ذاكرة الموجّهات المؤقتة في كتل موجّهات النظام/المطوّر.

الملء المسبق لاستدلال Anthropic

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

حقن التفكير / الاستدلال

في المسارات المدعومة غير المضبوطة على auto، يربط OpenClaw مستوى التفكير المحدد بحمولات استدلال وكيل OpenRouter. يتخطى openrouter/auto وتلميحات النماذج غير المدعومة هذا الحقن. كما تتخطاه مراجع openrouter/hunter-alpha القديمة، لأن OpenRouter كان من الممكن أن يعيد نص الإجابة النهائية في حقول الاستدلال على ذلك المسار المتقاعد.

إعادة تشغيل استدلال DeepSeek V4

في مسارات OpenRouter المتحقق منها، يملأ openrouter/deepseek/deepseek-v4-flash وopenrouter/deepseek/deepseek-v4-pro قيمة reasoning_content المفقودة في أدوار المساعد المُعاد تشغيلها، مما يُبقي محادثات التفكير/الأدوات بالصيغة اللاحقة التي يتطلبها DeepSeek V4. يرسل OpenClaw قيم reasoning.effort التي يدعمها OpenRouter لهذه المسارات: تُربط xhigh/max بـ xhigh، ويُربط كل مستوى آخر غير معطّل بـ high.

تشكيل الطلبات الخاص بـ OpenAI فقط

يعمل OpenRouter عبر المسار المتوافق مع OpenAI والمصمم بأسلوب الوكيل، لذلك لا يُعاد توجيه تشكيل الطلبات الأصلي الخاص بـ OpenAI فقط، مثل serviceTier وstore في Responses وحمولات توافق استدلال OpenAI وتلميحات ذاكرة التخزين المؤقت للموجّه.

المسارات المدعومة بواسطة Gemini

تظل مراجع OpenRouter المدعومة بواسطة Gemini على مسار الوكيل الخاص بـ Gemini: يحتفظ OpenClaw هناك بتنقية توقيعات أفكار Gemini، لكنه لا يُمكّن التحقق الأصلي من إعادة تشغيل Gemini أو عمليات إعادة كتابة التمهيد.

بيانات تعريف توجيه المزوّد

يدعم OpenRouter كائن طلب provider لتوجيه المزوّد الأساسي. اضبط سياسة افتراضية لجميع طلبات نماذج OpenRouter النصية باستخدام models.providers.openrouter.params.provider:

{
  models: {
    providers: {
      openrouter: {
        params: {
          provider: {
            sort: "latency",
            require_parameters: true,
            data_collection: "deny",
          },
        },
      },
    },
  },
}

يمرر OpenClaw ذلك الكائن إلى OpenRouter بصفته حمولة provider للطلب. استخدم حقول snake_case الموثقة في OpenRouter، بما فيها sort وonly وignore وorder وallow_fallbacks وrequire_parameters وdata_collection وquantizations وmax_price وpreferred_max_latency وpreferred_min_throughput وzdr وenforce_distillable_text.تتجاوز معاملات كل نموذج كائن التوجيه العام للمزوّد:

{
  agents: {
    defaults: {
      models: {
        "openrouter/anthropic/claude-sonnet-4-6": {
          params: {
            provider: {
              order: ["anthropic"],
              allow_fallbacks: false,
            },
          },
        },
      },
    },
  },
}

ينطبق هذا فقط على مسارات إكمال المحادثة في OpenRouter. تتجاهل مسارات Anthropic أو Google أو OpenAI المباشرة، وكذلك مسارات المزوّدين المخصصين، معاملات توجيه OpenRouter.

ذو صلة

اختيار النموذج

اختيار المزوّدين ومراجع النماذج وسلوك التحويل عند التعطل.

مرجع الإعدادات

مرجع الإعدادات الكامل للوكلاء والنماذج والمزوّدين.

Overview

Concepts and configuration

Providers

بدء الاستخدام

مثال على الإعداد

مراجع النماذج

توليد الصور

توليد الفيديو

توليد الموسيقى

تحويل النص إلى كلام

تحويل الكلام إلى نص (الصوت الوارد)

موجّه Fusion

المصادقة والترويسات

الإعدادات المتقدمة

ذو صلة

اختيار النموذج

مرجع الإعدادات

​بدء الاستخدام

​مثال على الإعداد

​مراجع النماذج

​توليد الصور

​توليد الفيديو

​توليد الموسيقى

​تحويل النص إلى كلام

​تحويل الكلام إلى نص (الصوت الوارد)

​موجّه Fusion

​المصادقة والترويسات

​الإعدادات المتقدمة

​ذو صلة

اختيار النموذج

مرجع الإعدادات

بدء الاستخدام

مثال على الإعداد

مراجع النماذج

توليد الصور

توليد الفيديو

توليد الموسيقى

تحويل النص إلى كلام

تحويل الكلام إلى نص (الصوت الوارد)

موجّه Fusion

المصادقة والترويسات

الإعدادات المتقدمة

ذو صلة