Google (Gemini)

Plugin گوگل دسترسی به مدل‌های Gemini را از طریق Google AI Studio فراهم می‌کند و همچنین شامل تولید تصویر، درک رسانه (تصویر/صدا/ویدئو)، تبدیل متن به گفتار و جست‌وجوی وب از طریق Gemini Grounding است.

• ارائه‌دهنده: google
• احراز هویت: GEMINI_API_KEY یا GOOGLE_API_KEY
• API: Google Gemini API
• گزینه زمان اجرا: agentRuntime.id: "google-gemini-cli" از OAuth مربوط به Gemini CLI مجدداً استفاده می‌کند و هم‌زمان ارجاع‌های مدل را به‌شکل استاندارد google/* نگه می‌دارد.

شروع به کار

روش احراز هویت دلخواه خود را انتخاب کنید و مراحل راه‌اندازی را دنبال کنید.

openclaw onboard --auth-choice gemini-api-key

openclaw onboard --non-interactive \  --mode local \  --auth-choice gemini-api-key \  --gemini-api-key "$GEMINI_API_KEY"

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

openclaw models list --provider google

# Homebrewbrew install gemini-cli # یا npmnpm install -g @google/gemini-cli

openclaw models auth login --provider google-gemini-cli --set-default

openclaw models list --provider google

قابلیت‌ها

جست‌وجوی وب

ارائه‌دهنده جست‌وجوی وب همراه بسته، یعنی gemini، از اتصال جست‌وجوی Google در Gemini استفاده می‌کند. یک کلید جست‌وجوی اختصاصی را در plugins.entries.google.config.webSearch پیکربندی کنید، یا اجازه دهید پس از GEMINI_API_KEY از models.providers.google.apiKey مجدداً استفاده کند:

{  plugins: {    entries: {      google: {        config: {          webSearch: {            apiKey: "AIza...", // در صورت تنظیم بودن GEMINI_API_KEY یا models.providers.google.apiKey اختیاری است            baseUrl: "https://generativelanguage.googleapis.com/v1beta", // به 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 را ببینید.

تولید تصویر

ارائه‌دهنده تولید تصویر همراه بسته، یعنی google، به‌طور پیش‌فرض از google/gemini-3.1-flash-image استفاده می‌کند.

• همچنین از google/gemini-3-pro-image پشتیبانی می‌کند
• تولید: حداکثر 4 تصویر در هر درخواست
• حالت ویرایش: فعال، با حداکثر 5 تصویر ورودی
• کنترل‌های هندسی: size، aspectRatio و resolution

برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض تصویر:

{  agents: {    defaults: {      imageGenerationModel: {        primary: "google/gemini-3.1-flash-image",      },    },  },}

تولید ویدئو

Plugin همراه بسته google همچنین تولید ویدئو را از طریق ابزار مشترک 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",      },    },  },}

تولید موسیقی

Plugin همراه بسته google همچنین تولید موسیقی را از طریق ابزار مشترک 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
• احراز هویت: tts.providers.google.apiKey، models.providers.google.apiKey، GEMINI_API_KEY یا GOOGLE_API_KEY
• خروجی: WAV برای پیوست‌های عادی TTS، ‏Opus برای مقصدهای پیام صوتی و PCM برای مکالمه/تلفن
• خروجی پیام صوتی: PCM مربوط به Google در قالب WAV بسته‌بندی و با ffmpeg به Opus با نرخ 48 kHz تبدیل می‌شود

مسیر دسته‌ای Gemini TTS در Google، صدای تولیدشده را در پاسخ تکمیل‌شده generateContent بازمی‌گرداند. برای مکالمات گفتاری با کمترین تأخیر، به‌جای TTS دسته‌ای از ارائه‌دهنده صدای بلادرنگ Google مبتنی بر Gemini Live API استفاده کنید.

برای استفاده از Google به‌عنوان ارائه‌دهنده پیش‌فرض TTS:

{  tts: {    auto: "always",    provider: "google",    providers: {      google: {        model: "gemini-3.1-flash-tts-preview",        speakerVoice: "Kore",        audioProfile: "حرفه‌ای و با لحنی آرام صحبت کن.",      },    },  },}

Gemini API TTS برای کنترل سبک از اعلان زبان طبیعی استفاده می‌کند. برای افزودن یک اعلان سبک قابل‌استفاده مجدد پیش از متن گفتاری، audioProfile را تنظیم کنید. هنگامی که متن اعلان به گوینده‌ای نام‌گذاری‌شده اشاره می‌کند، speakerName را تنظیم کنید.

Gemini API TTS همچنین برچسب‌های صوتی بیانی داخل کروشه را در متن می‌پذیرد، مانند [whispers] یا [laughs]. برای اینکه برچسب‌ها در پاسخ قابل‌مشاهده گفت‌وگو نمایش داده نشوند اما به TTS ارسال شوند، آن‌ها را داخل یک بلوک [[tts:text]]...[[/tts:text]] قرار دهید:

این متن پاکیزه پاسخ است. [[tts:text]][whispers] این نسخه گفتاری است.[[/tts:text]]

صدای بلادرنگ

Plugin همراه بسته google یک ارائه‌دهنده صدای بلادرنگ مبتنی بر Gemini Live API را برای پل‌های صوتی بک‌اند مانند Voice Call و Google Meet ثبت می‌کند.

نمونه پیکربندی بلادرنگ تماس صوتی:

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          realtime: {            enabled: true,            provider: "google",            providers: {              google: {                model: "gemini-3.1-flash-live-preview",                speakerVoice: "Kore",                activityHandling: "start-of-activity-interrupts",                turnCoverage: "audio-activity-and-all-video",              },            },          },        },      },    },  },}

برای راستی‌آزمایی زنده توسط نگه‌دارنده، فرمان OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts را اجرا کنید. آزمون دود همچنین مسیرهای بک‌اند/WebRTC در OpenAI را پوشش می‌دهد؛ بخش Google همان قالب توکن محدود Live API مورداستفاده گفت‌وگوی Control UI را صادر می‌کند، نقطه پایانی WebSocket مرورگر را باز می‌کند، بار راه‌اندازی اولیه را همراه با یک فریم JPEG می‌فرستد و یک پاسخ متنی و رفت‌وبرگشت تابع describe_view را راستی‌آزمایی می‌کند.

پیکربندی پیشرفته

{  agents: {    defaults: {      models: {        "google/gemini-2.5-pro": {          params: {            cachedContent: "cachedContents/prebuilt-context",          },        },      },    },  },}

مرتبط