OpenClaw 接入 Gemini 3.1 Flash：谷歌最新模型详细配置步骤

谷歌的 Gemini 系列是 OpenClaw 社区中使用量增长最快的 AI 模型之一——得益于 Google AI Studio 提供的慷慨免费额度（每天 1500 次请求，完全无需绑定信用卡），Gemini 已成为新手体验 OpenClaw、零成本搭建个人 AI 助手的首选入口。

Gemini 3.1 Flash（在 OpenClaw 中的模型 ID 为 google/gemini-3-flash-preview）是目前性价比最高的 Gemini 模型——100 万 Token 上下文、66K Token 超长输出、原生多模态，并内置网页搜索工具，价格仅为 $0.50/百万输入 Token。本文提供完整配置教程。更多资源请访问 OpenClaw 中文版官网。

一、Gemini 3.1 Flash 核心优势

在正式开始配置前，有必要理解为什么 Gemini 3.1 Flash 值得接入 OpenClaw：

• 66K Token 输出上限：相比早期 Flash 模型仅 8K 输出，这是最关键的升级。意味着 AI 可以在一次调用中生成完整的代码文件、长篇报告或详细分析，不会被截断
• 100 万 Token 上下文：可以将整个代码仓库、几百页文档一次性送入分析，是 Claude Sonnet 200K 上下文的 5 倍
• 原生多模态：支持图片、视频、URL 内容直接作为输入，无需额外配置
• 内置网页搜索与 URL 上下文：AI 可以主动搜索最新信息，不依赖第三方搜索插件
• SWE-bench 78%：在编程评测上甚至超越了 Gemini 3 Pro（76.2%），对代码任务友好
• 免费额度充足：每分钟 15 次请求、每天 1500 次请求（免费层），轻度个人使用无需付费

二、关键说明：模型 ID 命名规则

Gemini 的模型 ID 命名方式容易混淆，在配置 OpenClaw 前务必理解以下对应关系：

常见错误：不要使用 gemini-3.0-flash（带 .0）或 gemini-3.1-flash（无 “-preview”）——这些不是有效的 OpenClaw 模型 ID，配置后 Gateway 能正常启动但请求时会报 Unknown model 错误。官方文档明确说明：旧版 google/gemini-3.1-flash-preview 写法会被自动规范化为 google/gemini-3-flash-preview。

三、获取 Google AI Studio API Key

1. 访问 aistudio.google.com/apikey，用 Google 账号登录
2. 点击 「Create API Key」
3. 选择一个 Google Cloud 项目（如果没有，创建一个新项目）
4. 复制生成的 API Key（格式：AIzaSy...）
5. 免费账户无需绑定信用卡即可使用，如需更高限额，在 Google Cloud Console 中为项目开启计费即可

免费额度详情（2026 年 4 月）

对于轻度个人使用，每天 1500 次请求已绰绰有余。如果是 24 小时运行 Heartbeat 任务的场景，建议开通付费计划以避免额度耗尽导致服务中断。

四、方式一：引导向导快速配置

# 通过引导向导配置 Gemini API Key
openclaw onboard --auth-choice gemini-api-key

向导中依次操作：

1. 粘贴 API Key（AIzaSy...）
2. 选择默认模型：选择 Gemini 3 Flash Preview（即 gemini-3-flash-preview）
3. 完成其他渠道和技能配置

向导完成后验证：

openclaw models list | grep google
# 应看到：google/gemini-3-flash-preview  text+image  1024k  no  yes

五、方式二：手动编辑 openclaw.json（推荐完整配置）

第一步：设置环境变量

在 ~/.openclaw/.env 中添加（OpenClaw 支持多个 Key 的轮换）：

# 单个 Key
GEMINI_API_KEY=AIzaSy你的密钥

# 多 Key 轮换（达速率限制时自动切换）
GEMINI_API_KEY_1=AIzaSy密钥1
GEMINI_API_KEY_2=AIzaSy密钥2
# 也支持：GEMINI_API_KEYS、GOOGLE_API_KEY 作为回退

第二步：配置 openclaw.json

{
  "env": {
    "GEMINI_API_KEY": "AIzaSy你的密钥"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "google/gemini-3-flash-preview",
        "fallbacks": [
          "google/gemini-3.1-pro-preview",
          "google/gemini-2.5-flash"
        ]
      },
      "models": {
        "google/gemini-3-flash-preview": {
          "alias": "flash"
        },
        "google/gemini-3.1-pro-preview": {
          "alias": "pro"
        },
        "google/gemini-3.1-flash-lite-preview": {
          "alias": "flash-lite"
        },
        "google/gemini-2.5-flash": {
          "alias": "25flash"
        },
        "google/gemini-2.0-flash": {
          "alias": "20flash"
        }
      }
    }
  }
}

如果需要显式指定端点（用于自定义代理或 Vertex AI 路由），可以添加自定义服务商块：

{
  "models": {
    "mode": "merge",
    "providers": {
      "google": {
        "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
        "apiKey": "${GEMINI_API_KEY}",
        "api": "google-generative-ai",
        "models": [
          {
            "id": "gemini-3-flash-preview",
            "name": "Gemini 3 Flash（默认推荐）",
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 65535
          },
          {
            "id": "gemini-3.1-pro-preview",
            "name": "Gemini 3.1 Pro（复杂推理）",
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 65535
          },
          {
            "id": "gemini-3.1-flash-lite-preview",
            "name": "Gemini 3.1 Flash Lite（高量轻任务）",
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 65535
          },
          {
            "id": "gemini-2.5-flash",
            "name": "Gemini 2.5 Flash（大文档分析专用）",
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 8192
          },
          {
            "id": "gemini-2.0-flash",
            "name": "Gemini 2.0 Flash（免费额度最大）",
            "input": ["text", "image"],
            "contextWindow": 1000000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

重要提示：必须显式设置 maxTokens: 65535——OpenClaw 的默认值通常远低于此，会静默截断长生成内容。Gemini 3 Flash 支持最高 66K Token 输出，不设置此值会浪费该模型最大的优势。

第三步：重启并验证

openclaw daemon restart

# 确认模型已加载
openclaw models list | grep google

# 运行健康检查
openclaw doctor

# 测试请求（发送一条消息，观察是否有 Gemini 响应）
# 或通过别名切换确认：
# /model flash

六、方式三：Gemini CLI OAuth（免 API Key，个人使用）

如果你已安装并登录了 Google Gemini CLI，OpenClaw 支持通过 OAuth 方式接入，无需管理 API Key：

# 确认 Gemini CLI 已安装并登录
gemini --version
gemini "hello"   # 测试 CLI 是否正常工作

# 在 OpenClaw 中登录 Gemini CLI provider
openclaw models auth login --provider google-gemini-cli --set-default

登录后会打开浏览器完成 Google OAuth 授权，token 存储在 Gateway 的 auth profiles 中。

# 使用 Gemini CLI 作为后端的模型引用格式
"primary": "google-gemini-cli/gemini-3-flash-preview"

重要警告：官方文档明确标注 Gemini CLI OAuth 集成为非官方（Unofficial）。Google 保留随时更改或限制此接入方式的权利。对于自动化任务和服务器部署，强烈建议使用标准 API Key 方式，不要依赖 OAuth 方式作为生产环境的主要认证。

七、Gemini 全系列模型选型指南

实用建议：gemini-2.5-flash 和 gemini-2.0-flash 的输出上限仅 8K Token，适合需要读取大量内容但输出简短的场景（如文档问答、代码审查评论）。如果需要生成较长内容，只选 Gemini 3 系列模型。

八、Gemini 在 OpenClaw 的实战场景

场景一：大文档处理（1M 上下文的实际用法）

# 将一个 400 页 PDF 报告全文送入分析（Gemini 独有优势）
帮我分析 workspace/annual-report-2025.pdf 中的财务数据，
列出三个最值得关注的风险点和两个增长机会

# Gemini 3 Flash 可以在一次调用中处理完整文档
# 而不需要分块处理

场景二：代码生成（66K 输出的优势）

# 生成完整的模块代码（不担心截断）
/model flash
帮我实现一个完整的 JWT 认证中间件，包括：
- 用户注册和登录接口
- Token 生成和验证逻辑
- 刷新 Token 机制
- 单元测试文件

# Gemini 3 Flash 在单次输出中可以生成数千行代码

场景三：多模型混合策略

# 日常任务 → Gemini 3 Flash（平衡）
/model flash   # 成本低、速度快、够用

# 复杂推理 → Gemini 3.1 Pro（精准）
/model pro    # 关键任务、不容出错

# 批量轻任务 → Flash Lite（最省成本）
/model flash-lite   # 心跳任务、通知处理

# 接近免费的测试 → Gemini 2.0 Flash
/model 20flash   # 60 RPM 免费额度

九、常见问题速查

报错：Unknown model: google/gemini-3.0-flash

模型 ID 错误。Gemini 3 Flash 在 OpenClaw 中的正确 ID 是 gemini-3-flash-preview（无版本号，有 “-preview” 后缀）。参考第二节的命名规则表。

报错：400 status code（无 body）

这是 google/gemini-3-flash-preview 在某些旧版本中（v2026.3.7 附近）出现的 Bug，已在后续版本修复。升级到 v2026.4.1 即可解决：npm install -g openclaw@latest。

响应被截断，没有完整输出

未显式设置 maxTokens。在自定义服务商配置中加入 "maxTokens": 65535，或通过引导向导配置时选择 Gemini 3 Flash，OpenClaw 会自动使用正确的上限。

免费额度耗尽后如何处理

在 Google Cloud Console 中为项目开启计费，同一个 API Key 即可升级到付费层，额度大幅提升。也可以配置多个 Key 轮换使用（GEMINI_API_KEY_1、GEMINI_API_KEY_2）来累加免费额度。

Gemini CLI OAuth 突然失效

这是官方非正式集成的已知风险。切换回标准 API Key 方式：重新运行 openclaw onboard --auth-choice gemini-api-key，粘贴从 Google AI Studio 创建的 API Key。

中国大陆用户无法访问 generativelanguage.googleapis.com

Google API 在中国大陆需要代理访问。建议将 OpenClaw 部署在境外 VPS（新加坡、日本节点延迟较低），或在本地使用代理。如需国产模型替代，参考 DeepSeek、Qwen、MiniMax 等国内模型的接入教程。

总结

OpenClaw 接入 Gemini 3.1 Flash 的核心配置要点：

1. 正确的模型 ID：使用 google/gemini-3-flash-preview，不是 gemini-3.0-flash 或其他变体
2. 显式设置 maxTokens: 65535：不设置会静默截断 66K 输出能力
3. API Key 获取免费：aistudio.google.com/apikey，免费账户每天 1500 次请求，无需信用卡
4. 多模型组合：Flash 作为主力，Pro 作为复杂任务备用，Lite 用于高频轻量任务
5. OAuth 仅限个人测试：生产和自动化场景坚持使用 API Key

想了解更多 OpenClaw 模型接入配置与实战技巧，欢迎访问 OpenClaw 中文版官网。