الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

يوفّر Google Plugin إمكانية الوصول إلى نماذج Gemini عبر Google AI Studio، إضافةً إلى توليد الصور، وفهم الوسائط (الصور/الصوت/الفيديو)، وتحويل النص إلى كلام، والبحث على الويب عبر Gemini Grounding.
  • المزوّد: google
  • المصادقة: GEMINI_API_KEY أو GOOGLE_API_KEY
  • API: Google Gemini API
  • خيار وقت التشغيل: المزوّد/النموذج agentRuntime.id: "google-gemini-cli" يعيد استخدام Gemini CLI OAuth مع إبقاء مراجع النماذج معيارية بصيغة google/*.

البدء

اختر طريقة المصادقة المفضلة لديك واتبع خطوات الإعداد.
الأفضل لـ: الوصول القياسي إلى Gemini API عبر Google AI Studio.
1

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

openclaw onboard --auth-choice gemini-api-key
أو مرّر المفتاح مباشرةً:
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"
2

تعيين نموذج افتراضي

{
  agents: {
    defaults: {
      model: { primary: "google/gemini-3.1-pro-preview" },
    },
  },
}
3

التحقق من توفر النموذج

openclaw models list --provider google
متغيرا البيئة GEMINI_API_KEY وGOOGLE_API_KEY مقبولان كلاهما. استخدم أيهما سبق أن أعددته.

القدرات

القدرةمدعومة
إكمالات المحادثةنعم
توليد الصورنعم
توليد الموسيقىنعم
تحويل النص إلى كلامنعم
الصوت الفورينعم (Google Live API)
فهم الصورنعم
تفريغ الصوتنعم
فهم الفيديونعم
البحث على الويب (Grounding)نعم
التفكير/الاستدلالنعم (Gemini 2.5+ / Gemini 3+)
نماذج Gemma 4نعم

البحث على الويب

يستخدم مزوّد البحث على الويب gemini المضمّن تأريض Gemini Google Search. اضبط مفتاح بحث مخصصًا ضمن plugins.entries.google.config.webSearch، أو دعه يعيد استخدام models.providers.google.apiKey بعد GEMINI_API_KEY:
{
  plugins: {
    entries: {
      google: {
        config: {
          webSearch: {
            apiKey: "AIza...", // optional if GEMINI_API_KEY or models.providers.google.apiKey is set
            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // falls back to models.providers.google.baseUrl
            model: "gemini-2.5-flash",
          },
        },
      },
    },
  },
}
أولوية بيانات الاعتماد هي webSearch.apiKey المخصص، ثم GEMINI_API_KEY، ثم models.providers.google.apiKey. يُعد webSearch.baseUrl اختياريًا وموجودًا لوكلاء المشغلين أو نقاط نهاية Gemini API المتوافقة؛ وعند حذفه، يعيد بحث الويب في Gemini استخدام models.providers.google.baseUrl. راجع بحث Gemini لمعرفة سلوك الأداة الخاص بالمزوّد.
تستخدم نماذج Gemini 3 thinkingLevel بدلًا من thinkingBudget. يربط OpenClaw عناصر تحكم الاستدلال في أسماء Gemini 3 وGemini 3.1 وgemini-*-latest المستعارة بـ thinkingLevel حتى لا ترسل عمليات التشغيل الافتراضية/منخفضة زمن الاستجابة قيم thinkingBudget معطّلة.يحافظ /think adaptive على دلالات التفكير الديناميكي في Google بدلًا من اختيار مستوى ثابت في OpenClaw. يحذف Gemini 3 وGemini 3.1 قيمة thinkingLevel ثابتة كي تتمكن Google من اختيار المستوى؛ ويرسل Gemini 2.5 قيمة الحارس الديناميكية من Google thinkingBudget: -1.تدعم نماذج Gemma 4 (مثل gemma-4-26b-a4b-it) وضع التفكير. يعيد OpenClaw كتابة thinkingBudget إلى thinkingLevel مدعوم من Google لـ Gemma 4. ضبط التفكير على off يبقي التفكير معطّلًا بدلًا من ربطه بـ MINIMAL.

توليد الصور

يعتمد مزوّد توليد الصور google المضمّن افتراضيًا على google/gemini-3.1-flash-image-preview.
  • يدعم أيضًا google/gemini-3-pro-image-preview
  • التوليد: حتى 4 صور لكل طلب
  • وضع التحرير: مفعّل، حتى 5 صور إدخال
  • عناصر التحكم الهندسية: size وaspectRatio وresolution
لاستخدام Google كمزوّد الصور الافتراضي:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
راجع توليد الصور لمعرفة معلمات الأداة المشتركة، واختيار المزوّد، وسلوك تجاوز الفشل.

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

يسجّل Google Plugin المضمّن أيضًا توليد الفيديو عبر أداة video_generate المشتركة.
  • نموذج الفيديو الافتراضي: google/veo-3.1-fast-generate-preview
  • الأوضاع: تحويل النص إلى فيديو، وتحويل الصورة إلى فيديو، وتدفقات مرجع فيديو واحد
  • يدعم aspectRatio (16:9 و9:16) وresolution (720P و1080P)؛ لا يدعم Veo إخراج الصوت حاليًا
  • المدد المدعومة: 4 أو 6 أو 8 ثوانٍ (تُقرّب القيم الأخرى إلى أقرب قيمة مسموح بها)
لاستخدام Google كمزوّد الفيديو الافتراضي:
{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "google/veo-3.1-fast-generate-preview",
      },
    },
  },
}
راجع توليد الفيديو لمعرفة معلمات الأداة المشتركة، واختيار المزوّد، وسلوك تجاوز الفشل.

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

يسجّل Google Plugin المضمّن أيضًا توليد الموسيقى عبر أداة music_generate المشتركة.
  • نموذج الموسيقى الافتراضي: google/lyria-3-clip-preview
  • يدعم أيضًا google/lyria-3-pro-preview
  • عناصر التحكم في الموجه: lyrics وinstrumental
  • تنسيق الإخراج: mp3 افتراضيًا، بالإضافة إلى wav على google/lyria-3-pro-preview
  • مدخلات مرجعية: حتى 10 صور
  • تنفصل عمليات التشغيل المدعومة بالجلسات عبر تدفق المهمة/الحالة المشترك، بما في ذلك action: "status"
لاستخدام Google كمزوّد الموسيقى الافتراضي:
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}
راجع توليد الموسيقى لمعرفة معلمات الأداة المشتركة، واختيار المزوّد، وسلوك تجاوز الفشل.

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

يستخدم مزوّد الكلام google المضمّن مسار TTS في Gemini API مع gemini-3.1-flash-tts-preview.
  • الصوت الافتراضي: Kore
  • المصادقة: messages.tts.providers.google.apiKey أو models.providers.google.apiKey أو GEMINI_API_KEY أو GOOGLE_API_KEY
  • الإخراج: WAV لمرفقات TTS العادية، وOpus لأهداف الملاحظات الصوتية، وPCM لـ Talk/الهاتف
  • إخراج الملاحظات الصوتية: يُغلّف Google PCM كـ WAV ويُحوّل إلى Opus بتردد 48 كيلوهرتز باستخدام ffmpeg
يعيد مسار Gemini TTS الدفعي من Google الصوت المولّد في استجابة generateContent المكتملة. للحصول على محادثات منطوقة بأدنى زمن استجابة، استخدم مزوّد الصوت الفوري من Google المدعوم بـ Gemini Live API بدلًا من TTS الدفعي. لاستخدام Google كمزوّد TTS الافتراضي:
{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "Kore",
          audioProfile: "Speak professionally with a calm tone.",
        },
      },
    },
  },
}
يستخدم Gemini API TTS التوجيه باللغة الطبيعية للتحكم في الأسلوب. اضبط audioProfile لإضافة موجه أسلوب قابل لإعادة الاستخدام قبل النص المنطوق. اضبط speakerName عندما يشير نص الموجه إلى متحدث مسمّى. يقبل Gemini API TTS أيضًا وسومًا صوتية تعبيرية بين أقواس مربعة في النص، مثل [whispers] أو [laughs]. لإبقاء الوسوم خارج رد المحادثة المرئي مع إرسالها إلى TTS، ضعها داخل كتلة [[tts:text]]...[[/tts:text]]:
Here is the clean reply text.

[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]
يصلح مفتاح Google Cloud Console API المقيد بـ Gemini API لهذا المزوّد. هذا ليس مسار Cloud Text-to-Speech API المنفصل.

الصوت الفوري

يسجّل Google Plugin المضمّن مزوّد صوت فوري مدعومًا بـ Gemini Live API لجسور الصوت الخلفية مثل Voice Call وGoogle Meet.
الإعدادمسار الإعداداتالافتراضي
النموذجplugins.entries.voice-call.config.realtime.providers.google.modelgemini-2.5-flash-native-audio-preview-12-2025
الصوت...google.voiceKore
درجة الحرارة...google.temperature(غير معيّن)
حساسية بدء VAD...google.startSensitivity(غير معيّن)
حساسية انتهاء VAD...google.endSensitivity(غير معيّن)
مدة الصمت...google.silenceDurationMs(غير معيّن)
معالجة النشاط...google.activityHandlingافتراضي Google، start-of-activity-interrupts
تغطية الدور...google.turnCoverageافتراضي Google، only-activity
تعطيل VAD التلقائي...google.automaticActivityDetectionDisabledfalse
استئناف الجلسة...google.sessionResumptiontrue
ضغط السياق...google.contextWindowCompressiontrue
مفتاح API...google.apiKeyيعود احتياطيًا إلى models.providers.google.apiKey أو GEMINI_API_KEY أو GOOGLE_API_KEY
مثال لإعدادات الوقت الفعلي في Voice Call:
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          realtime: {
            enabled: true,
            provider: "google",
            providers: {
              google: {
                model: "gemini-2.5-flash-native-audio-preview-12-2025",
                voice: "Kore",
                activityHandling: "start-of-activity-interrupts",
                turnCoverage: "only-activity",
              },
            },
          },
        },
      },
    },
  },
}
تستخدم Google Live API صوتًا ثنائي الاتجاه واستدعاء الدوال عبر WebSocket. يوائم OpenClaw صوت جسر الهاتف/Meet مع تدفق Gemini Live API بتنسيق PCM ويبقي استدعاءات الأدوات على عقد الصوت المشترك في الوقت الفعلي. اترك temperature غير معيّن ما لم تكن تحتاج إلى تغييرات في أخذ العينات؛ إذ يحذف OpenClaw القيم غير الموجبة لأن Google Live يمكن أن يعيد نصوصًا منسوخة بلا صوت عند temperature: 0. يتم تفعيل النسخ الصوتي في Gemini API بدون languageCodes؛ إذ ترفض حزمة SDK الحالية من Google تلميحات رموز اللغة في مسار API هذا.
تدعم واجهة Control UI Talk جلسات Google Live في المتصفح باستخدام رموز مقيدة صالحة لاستخدام واحد. يمكن لموفري الصوت في الوقت الفعلي الخاصين بالخلفية فقط العمل أيضًا عبر نقل الترحيل العام في Gateway، مما يبقي بيانات اعتماد المزوّد على Gateway.
للتحقق المباشر من قِبل المشرفين، شغّل OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts. يغطي اختبار الدخان أيضًا مسارات خلفية OpenAI وWebRTC؛ إذ ينشئ جزء Google شكل رمز Live API المقيد نفسه الذي تستخدمه Control UI Talk، ويفتح نقطة نهاية WebSocket في المتصفح، ويرسل حمولة الإعداد الأولية، وينتظر setupComplete.

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

في عمليات تشغيل Gemini API المباشرة (api: "google-generative-ai")، يمرر OpenClaw مقبض cachedContent المهيّأ إلى طلبات Gemini.
  • هيّئ معاملات على مستوى النموذج أو عالميًا باستخدام cachedContent أو cached_content القديم
  • إذا وُجدا معًا، تكون الأولوية لـ cachedContent
  • قيمة مثال: cachedContents/prebuilt-context
  • يتم توحيد استخدام إصابة ذاكرة التخزين المؤقت في Gemini إلى cacheRead في OpenClaw من cachedContentTokenCount في المصدر الأعلى
{
  agents: {
    defaults: {
      models: {
        "google/gemini-2.5-pro": {
          params: {
            cachedContent: "cachedContents/prebuilt-context",
          },
        },
      },
    },
  },
}
عند استخدام موفّر OAuth ‏google-gemini-cli، يوحّد OpenClaw مخرجات CLI بصيغة JSON كما يلي:
  • يأتي نص الرد من حقل response في JSON الخاص بـ CLI.
  • يعود الاستخدام احتياطيًا إلى stats عندما يترك CLI قيمة usage فارغة.
  • يتم توحيد stats.cached إلى cacheRead في OpenClaw.
  • إذا كان stats.input مفقودًا، يستنتج OpenClaw رموز الإدخال من stats.input_tokens - stats.cached.
إذا كان Gateway يعمل كخدمة daemon (launchd/systemd)، فتأكد من أن GEMINI_API_KEY متاح لتلك العملية (على سبيل المثال، في ~/.openclaw/.env أو عبر env.shellEnv).

ذات صلة

Model selection

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

Image generation

معاملات أداة الصور المشتركة واختيار المزوّد.

Video generation

معاملات أداة الفيديو المشتركة واختيار المزوّد.

Music generation

معاملات أداة الموسيقى المشتركة واختيار المزوّد.