Google (Gemini)

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

• ارائه‌دهنده: google
• احراز هویت: GEMINI_API_KEY یا GOOGLE_API_KEY
• API: Google Gemini API
• گزینه زمان اجرا: provider/model ‏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 از grounding جست‌وجوی Google در 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 پشتیبانی می‌کند
• تولید: تا 4 تصویر در هر درخواست
• حالت ویرایش: فعال، تا 5 تصویر ورودی
• کنترل‌های هندسه: 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 پشتیبانی نمی‌شود
• مدت‌های پشتیبانی‌شده: 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 پشتیبانی می‌کند
• کنترل‌های prompt: lyrics و instrumental
• قالب خروجی: به‌طور پیش‌فرض mp3، به‌علاوه wav روی google/lyria-3-pro-preview
• ورودی‌های مرجع: تا 10 تصویر
• اجراهای متکی به session از طریق جریان مشترک 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 برای مقصدهای یادداشت صوتی، PCM برای Talk/telephony
• خروجی یادداشت صوتی: Google PCM به‌صورت WAV بسته‌بندی می‌شود و با ffmpeg به Opus با 48 kHz ترنسکد می‌شود

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

برای استفاده از 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 برای کنترل سبک از 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 یک ارائه‌دهنده صدای بلادرنگ را ثبت می‌کند که برای پل‌های صوتی backend مانند Voice Call و Google Meet، با Gemini Live API پشتیبانی می‌شود.

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

{  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",              },            },          },        },      },    },  },}

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

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

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

مرتبط