如何接入 Gemini 到 OpenClaw

如何接入 Gemini 到 OpenClaw

Gemini 是 Google 推出的多模态大模型系列，其 Gemini 2.5 Pro 旗舰支持 1M+ 超长上下文与深度推理，Gemini 2.5 Flash 兼顾速度与成本，在视觉、代码、长文档场景表现卓越。本教程教你把 Gemini 接入 OpenClaw AI Agent 框架，让 AI 帮你写代码、做分析、看图片。

Gemini 接入 OpenClaw 有两种方式，选一种就行：

前置准备

不管选哪种方式，都需要这几样东西：

• 已安装 Node.js 22.x 或更高版本（运行 node --version 验证）
• 已注册 Google 账号，能访问 Google AI Studio
• 操作系统为 Windows 10/11、macOS 或 Linux
• 电脑能上网（国内访问 Gemini 需梯子，且节点需稳定；推荐使用日本/新加坡/美西节点）

步骤一：获取 Gemini API Key

两种方式都要先领一张 Gemini 的「通行证」（API Key）。

1.1 注册并登录

1. 访问 Google AI Studio，使用 Google 账号登录
2. 首次访问需同意《Generative AI 服务条款》并确认所在地区
3. 国内用户：访问前请先开启代理，全程保持代理在线

1.2 创建 API Key

1. 登录后点击左侧导航栏 「Get API key」，或直接访问 https://aistudio.google.com/apikey
2. 点击 「Create API key」 按钮
3. 选择「Create API key in new project」（推荐新手），Google 会自动创建一个 Cloud 项目
4. 页面会显示一串以 AIza 开头的长字符串，这就是你的通行证

1.3 了解可用模型

注：Gemini 2.5 Pro 自 2026-04-01 起为付费专用（无免费额度）；Gemini 2.5 Flash 仍提供免费层（约 1500 RPD）。>200K tokens 的长上下文请求会触发溢价定价。

步骤二：安装 OpenClaw

如果你还没装 OpenClaw，先装上。

1. 打开终端

• Windows 用户：按 Win + R，输入 cmd，回车
• Mac 用户：按 Command + 空格，输入「终端」，回车

2. 安装 OpenClaw CLI

1npm install -g openclaw-cli

步骤三：接入 Gemini

从这里开始，方式 A 和方式 B 分开走，选一种跟着做即可。

方式 A：引导向导接入（推荐新手）

OpenClaw 自带一个引导向导，跟着它一步步填就能接好，全程不用手写配置。

A1. 启动向导

在终端里输入：

1openclaw onboard

A2. 依次选择 Yes → QuickStart → Custom Provider

向导会问你几个问题，照下面选：

1. 第一个问「是否开始配置」→ 输入 Yes，回车
2. 问你选哪种模式 → 选 QuickStart（快速开始）
3. 问你选哪种供应商 → 选 Custom Provider（自定义供应商，因为我们要接 Gemini）

A3. 输入 API Base URL

向导问你 API 地址，填这个（OpenAI 兼容端点）：

回车确认。

A4. 粘贴 Gemini API Key

向导问你 API Key，把步骤一领到的 AIza 开头的通行证粘进去，回车。

A5. 粘贴模型 ID

向导问你用哪个模型，先填默认的：

回车。之后还会问你选什么协议，选 OpenAI-compatible（Gemini 兼容 OpenAI 格式）。

A6. 验证连接

向导会自动测试连接，出现 Verification successful（验证成功）字样就说明接通了！

A7. 自定义显示名称

最后向导会让你给这个接入点起个名字（显示用），随便填，比如 Gemini，回车完成。

方式 B：配置文件手动接入（进阶）

如果你更喜欢直接改配置文件，可以跳过向导，手动编辑。

B1. 初始化配置文件

如果还没初始化过，先跑：

1openclaw config init

这会在当前目录生成 config.json 文件。

B2. 编写 Gemini 模型配置

打开 config.json，推荐用环境变量方式（最安全，避免 Key 明文写入）：

1{
2  "models": [
3    {
4      "name": "gemini-2.5-flash",
5      "provider": "openai-compatible",
6      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai",
7      "apiKeyEnv": "GEMINI_API_KEY",
8      "maxTokens": 4096,
9      "temperature": 0.7
10    },
11    {
12      "name": "gemini-2.5-pro",
13      "provider": "openai-compatible",
14      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai",
15      "apiKeyEnv": "GEMINI_API_KEY",
16      "maxTokens": 8192,
17      "temperature": 0.7
18    }
19  ],
20  "defaultModel": "gemini-2.5-flash"
21}

然后设置环境变量：

1# PowerShell（临时，当前会话有效）
2$env:GEMINI_API_KEY = "AIza你的实际Key"
3
4# 或设为系统永久环境变量（重启终端仍有效）
5[System.Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "AIza你的实际Key", "User")

1# macOS / Linux（临时）
2export GEMINI_API_KEY="AIza你的实际Key"
3
4# 写入 ~/.bashrc 永久生效
5echo 'export GEMINI_API_KEY="AIza你的实际Key"' >> ~/.bashrc
6source ~/.bashrc

B3. 关键参数说明

步骤四：测试验证

4.1 重启 OpenClaw 服务

配置完成后（方式 B 需重启加载配置；方式 A 向导已自动处理，可跳过）：

1openclaw restart

4.2 检查当前模型状态

1openclaw status

预期输出应显示 gemini-2.5-flash 为默认模型。

4.3 发送测试消息

在 OpenClaw 的聊天界面中发送一条测试消息：

如果收到来自 Gemini 的回复，恭喜你——接入成功！🎉

4.4 Python 快速验证（可选）

绕过 OpenClaw 直接验证 API Key 是否有效（使用 OpenAI SDK 走兼容端点）：

1from openai import OpenAI
2
3client = OpenAI(
4    api_key="AIza你的Gemini API Key",   # 替换为实际 Key
5    base_url="https://generativelanguage.googleapis.com/v1beta/openai"
6)
7
8response = client.chat.completions.create(
9    model="gemini-2.5-flash",
10    messages=[
11        {"role": "system", "content": "你是一个有用的 AI 助手。"},
12        {"role": "user", "content": "说一句'Hello, Gemini!'"}
13    ],
14    max_tokens=100
15)
16
17print("✅ 连接成功！模型回复：")
18print(response.choices[0].message.content)

运行前确保已安装依赖：

1pip install openai
2python test_gemini.py

场景应用示例

🧩 场景 1：多模态图像理解

利用 Gemini 的原生视觉能力，让它分析图片：

使用示例：上传一张架构图，提问「请分析这张系统架构图，指出潜在的单点故障」

效果：

• 识别图中的服务节点与依赖关系
• 定位无副本、无负载均衡的关键服务
• 给出可用性改进建议

🧩 场景 2：超长文档处理

利用 Gemini 2.5 Pro 的 1M+ tokens 上下文窗口：

效果：

• 单次处理数十万字的研究报告/合同
• 整本技术书籍的知识点抽取与摘要
• 大型代码库的全局理解与重构建议

🧩 场景 3：智能编程助手

将 gemini-2.5-flash 设为默认模型，配合 OpenClaw 的代码执行插件：

效果：

• 自然语言描述需求 → 自动生成代码
• 支持 Python、JavaScript、Go、Java 等主流语言
• 代码解释、Bug 定位、单元测试生成一站式完成

最佳实践

💰 成本优化技巧

1. 善用免费层：Gemini 2.5 Flash 在 AI Studio 仍有约 1500 RPD 的免费额度，开发期足够用

2. 按需选模：

   • 简单问答/视觉 → gemini-2.5-flash
   • 长文档/代码 → gemini-2.5-flash（性价比最高）
   • 复杂推理 → gemini-2.5-pro

3. 控制上下文长度：>200K tokens 触发溢价，长文档先做切片或摘要

4. 批处理任务用 Batch API：异步批处理享 50% 折扣，适合非实时场景

🔒 安全建议

1. 永远不要将 API Key 提交到 Git 仓库 —— 确保 .gitignore 包含 .env 和 config.json
2. 定期轮换 Key —— 在 AI Studio 控制台定期更新密钥
3. 设置用量告警 —— 在 Google Cloud Console 配置预算告警，防止意外超额
4. 使用最小权限原则 —— 仅授予必要的 API 权限范围

🐛 故障排查速查表

扩展与进阶

📚 更多学习资源

🚀 进阶玩法

• 多模型混合部署：在 config.json 中同时配置 Gemini + DeepSeek 等其他模型，根据任务类型动态切换
• 流式输出（Streaming）：开启 SSE 流式返回，提升长文本的交互体验
• 工具调用（Function Calling）：Gemini 2.5 系列支持精准的函数调用，可对接外部 API
• 多模态输入：传入图片 URL 或 Base64，让 Gemini 进行图像理解、OCR、图表分析
• Google Search Grounding：开启搜索增强，让模型回答基于实时网络信息