Google Gemini 模型配置教程

2025-07-10 · 4 分钟模型接入

概述

Google Gemini 是目前多模态能力最强的模型系列之一，支持文字、图片、音频、视频的混合理解，以及内置的网络搜索（Grounding）和推理增强功能（Gemini 3.1 起）。OpenClaw 提供 API Key 和 OAuth 两种接入方式，日常开发推荐使用 API Key 方式，稳定且易于维护。

快速开始

首先前往 Google AI Studio 创建一个 API Key，然后通过以下命令完成配置：

openclaw onboard --auth-choice google-api-key

如需非交互式批量部署，可使用完整参数一次性完成：

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

也可以直接设置环境变量，OpenClaw 会自动识别：

export GEMINI_API_KEY="AIza..."
# 或者使用旧版变量名
export GOOGLE_API_KEY="AIza..."

配置参数

以下是在配置文件中手动设置 Gemini 模型的示例：

{
  // API Key 写入环境变量，不要硬编码在配置文件中
  agents: {
    defaults: {
      model: { primary: "google/gemini-3.1-pro-preview" },
    },
  },
}

如果需要同时使用 OAuth 方式（适合个人账户，无需付费），提供者标识符改为 google-gemini-cli：

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

支持的模型

Gemini 模型在 OpenClaw 中以 google/ 为前缀引用：

google/gemini-3.1-pro-preview — 最新旗舰推理模型，支持 Grounding
google/gemini-2.5-pro — 上一代 Pro，平衡性能与成本
google/gemini-2.5-flash — 高速轻量版，适合高频调用
google/gemini-2.0-flash — 稳定版 Flash，适合生产环境

完整可用模型列表可通过以下命令查看：

openclaw models list | grep google

注意事项

关于 OAuth 方式：OAuth 接入路径属于非官方用法，部分用户反馈可能导致 Google 账户受到访问限制，建议在正式项目中优先使用 API Key 方式。

关于守护进程部署：在使用 launchd 或 systemd 运行 OpenClaw 时，确保 API Key 通过 ~/.openclaw/.env 文件注入，而非仅依赖当前 Shell 的环境变量，否则进程启动后无法读取到凭据。

关于网络访问：Gemini API 在中国大陆需要代理访问。可以通过环境变量设置代理：

export HTTPS_PROXY="http://127.0.0.1:7890"

或在配置文件中为提供者指定自定义 baseUrl，使用国内可访问的中转服务。