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 دوباره استفاده می‌کند، در حالی که ارجاع‌های مدل را به‌صورت canonical به شکل 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 # or npmnpm install -g @google/gemini-cli

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

openclaw models list --provider google

قابلیت‌ها

جستجوی وب

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

{  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 اختیاری است و برای پراکسی‌های اپراتور یا endpointهای سازگار با Gemini API وجود دارد؛ وقتی حذف شود، جستجوی وب Gemini از models.providers.google.baseUrl دوباره استفاده می‌کند. برای رفتار ابزار مخصوص ارائه‌دهنده، جستجوی Gemini را ببینید.

تولید تصویر

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

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

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

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

تولید ویدیو

Plugin همراه google همچنین تولید ویدیو را از طریق ابزار مشترک video_generate ثبت می‌کند.

• مدل ویدیوی پیش‌فرض: google/veo-3.1-fast-generate-preview
• حالت‌ها: جریان‌های متن به ویدیو، تصویر به ویدیو، و ارجاع تک‌ویدیویی
• از aspectRatio (16:9، 9:16) و resolution (720P، 1080P) پشتیبانی می‌کند؛ خروجی صدا امروز توسط Veo پشتیبانی نمی‌شود
• مدت‌های پشتیبانی‌شده: ۴، ۶، یا ۸ ثانیه (مقادیر دیگر به نزدیک‌ترین مقدار مجاز می‌چسبند)

برای استفاده از 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 پشتیبانی می‌کند
• کنترل‌های prompt: lyrics و instrumental
• قالب خروجی: به‌صورت پیش‌فرض mp3، به‌علاوه wav روی google/lyria-3-pro-preview
• ورودی‌های ارجاع: تا ۱۰ تصویر
• اجراهای مبتنی بر نشست از طریق جریان مشترک task/status جدا می‌شوند، از جمله 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 برای مقصدهای voice-note، PCM برای Talk/تلفن
• خروجی voice-note: PCM گوگل به‌صورت WAV بسته‌بندی می‌شود و با ffmpeg به Opus با نرخ ۴۸ kHz تبدیل می‌شود

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

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

{  messages: {    tts: {      auto: "always",      provider: "google",      providers: {        google: {          model: "gemini-3.1-flash-tts-preview",          speakerVoice: "Kore",          audioProfile: "Speak professionally with a calm tone.",        },      },    },  },}

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

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

Here is the clean reply text. [[tts:text]][whispers] Here is the spoken version.[[/tts:text]]

صدای بلادرنگ

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

نمونه پیکربندی بلادرنگ 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",                speakerVoice: "Kore",                activityHandling: "start-of-activity-interrupts",                turnCoverage: "only-activity",              },            },          },        },      },    },  },}

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

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

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

مرتبط