OpenClaw接入Google Gemini模型教程

前言

Google Gemini 是 Google 推出的新一代多模态 AI 模型，具备强大的文本、图像、音频和视频理解能力。OpenClaw 完整支持 Gemini 系列模型，并且 Google 提供了相当慷慨的免费额度，非常适合个人用户和小团队使用。本教程将详细介绍 Gemini 模型的接入方法。

准备工作

第一步：获取 Gemini API Key

1.1 通过 Google AI Studio 获取（推荐）

这是最简单的获取方式，适合个人开发者：

1. 访问 aistudio.google.com
2. 使用 Google 账号登录
3. 点击左侧菜单中的 Get API key
4. 点击 Create API key
5. 选择一个现有的 Google Cloud 项目，或创建一个新项目
6. 复制生成的 API Key

API Key 格式示例：

AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

1.2 确认可用区域

Gemini API 在部分地区可能不可用。截至 2026 年，以下区域已支持：

• 美国、加拿大
• 欧洲大部分国家
• 日本、韩国、新加坡、印度
• 澳大利亚

如果你所在的区域暂不支持，可以考虑使用 Vertex AI 方案（见后文）。

第二步：配置 OpenClaw

2.1 基础配置

编辑 OpenClaw 配置文件：

nano ~/.config/openclaw/openclaw.json5

添加 Gemini 模型配置：

{
  models: {
    gemini: {
      provider: "google",
      apiKey: "AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      defaultModel: "gemini-2.5-pro",
    }
  }
}

2.2 使用环境变量存储密钥

# 添加到 ~/.bashrc 或 ~/.zshrc
export GOOGLE_AI_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

配置文件改为引用环境变量：

{
  models: {
    gemini: {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-pro",
    }
  }
}

2.3 重启服务

openclaw restart
openclaw doctor

看到 ✓ Google Gemini connection OK 即表示配置成功。

第三步：Gemini 模型选择

Google 目前提供多个 Gemini 模型，各有侧重：

3.1 推荐配置方案

对于大多数用户，推荐以下搭配：

{
  models: {
    "gemini-main": {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-pro",
      parameters: {
        temperature: 0.7,
        maxTokens: 8192,
      }
    },
    "gemini-fast": {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-flash",
      parameters: {
        temperature: 0.7,
        maxTokens: 4096,
      }
    }
  }
}

第四步：免费额度详解

Google AI Studio 提供的免费额度非常慷慨：

对于个人用户，gemini-2.5-flash 的免费额度基本够用。如果超出免费额度，可以在 Google Cloud Console 中开通付费计划。

4.1 最大化利用免费额度的技巧

{
  models: {
    gemini: {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-flash",  // 默认用 flash，免费额度更多
      parameters: {
        maxTokens: 2048,                  // 限制输出长度，节省 token
      }
    }
  },
  rateLimit: {
    gemini: {
      maxRequestsPerMinute: 14,           // 留一点余量，避免触发限制
      maxRequestsPerDay: 480,
    }
  }
}

第五步：Vertex AI 方案

如果你需要企业级服务或所在区域不支持 AI Studio，可以使用 Google Cloud 的 Vertex AI：

5.1 开通 Vertex AI

1. 登录 Google Cloud Console
2. 创建或选择一个项目
3. 启用 Vertex AI API
4. 创建服务账号并下载 JSON 密钥文件

5.2 配置 OpenClaw 使用 Vertex AI

{
  models: {
    "gemini-vertex": {
      provider: "google-vertex",
      serviceAccountKeyFile: "/path/to/service-account-key.json",
      projectId: "your-gcp-project-id",
      region: "us-central1",            // 选择离你最近的区域
      defaultModel: "gemini-2.5-pro",
      parameters: {
        temperature: 0.7,
        maxTokens: 8192,
      }
    }
  }
}

5.3 Vertex AI 与 AI Studio 对比

第六步：多模态能力配置

Gemini 的一大亮点是原生多模态支持。你可以通过聊天频道发送图片、PDF 等内容，Gemini 能够理解并回复。

6.1 启用图片理解

{
  models: {
    gemini: {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-flash",
      capabilities: {
        vision: true,        // 启用图像理解
        pdf: true,           // 启用 PDF 解析
        audio: true,         // 启用音频理解
      }
    }
  }
}

6.2 支持的文件类型

第七步：常见问题排查

API Key 无效

Error: API key not valid. Please pass a valid API key.

确认 API Key 是否正确复制，是否以 AIza 开头。如果仍然报错，尝试在 AI Studio 中重新生成。

区域限制

Error: User location is not supported for the API use.

你所在的区域可能不支持 Gemini API。解决方案：

• 使用 Vertex AI 方案
• 通过 OpenRouter 间接调用 Gemini（参考 OpenRouter 教程）

超出免费额度

Error: 429 Resource has been exhausted

解决方法：

• 切换到 gemini-2.0-flash-lite，免费额度更高
• 开通 Google Cloud 付费计划
• 在 OpenClaw 中配置速率限制避免频繁触发

响应截断

如果回复经常被截断，检查 maxTokens 设置：

parameters: {
  maxTokens: 8192,  // 增大输出限制
}

小结

Gemini 模型是 OpenClaw 生态中性价比极高的选择。借助慷慨的免费额度和强大的多模态能力，个人用户完全可以零成本运行一个功能丰富的 AI 助手。推荐日常使用 gemini-2.5-flash 平衡速度和质量，遇到复杂任务时切换到 gemini-2.5-pro。如果你的团队有企业级需求，Vertex AI 方案值得认真考虑。