OpenClaw Gemini API 接入教程

本教程介绍如何在 OpenClaw 中配置和使用 Google Gemini 模型。OpenClaw 支持多种接入方式，你可以根据自己的需求选择最合适的方案。

---

简介

Google Gemini 是 Google DeepMind 开发的多模态 AI 模型，支持文本、图像、视频等多种输入形式。在 OpenClaw 中使用 Gemini，你可以获得：

• Gemini 2.0 Flash - 100 万 token 上下文，适合高频快速响应场景
• Gemini 1.5 Pro - 200 万 token 上下文，适合复杂推理和代码生成
• Gemini 1.5 Flash - 100 万 token 上下文，速度与效率的平衡之选

方式一：使用 Defapi 接入 Gemini（推荐）

Defapi 是一个聚合多种大模型 API 的平台，专为开发者提供更优惠、更稳定的服务。

Defapi 的优势

• 价格优惠：仅为官方价格的 50%
• 完全兼容：兼容 OpenAI v1/chat/completions、Anthropic v1/messages、Google v1beta/models/ 等标准接口
• 无需改代码：切换到 Defapi 只需修改 baseUrl，原有代码无需任何修改
• 多模型支持：一个平台接入 Gemini、Claude、GPT 等多种模型

接入方式

方式 A：直接调用 Defapi

# 设置环境变量
export DEFAPI_API_KEY="你的Defapi密钥"

# 配置 OpenClaw 使用 Defapi
{
  env: { DEFAPI_API_KEY: "dk-..." },
  agents: {
    defaults: {
      model: { primary: "defapi/gemini-3-flash" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      "defapi": {
        baseUrl: "https://api.defapi.org/v1beta",
        apiKey: "${DEFAPI_API_KEY}",
        api: "google-generative-ai",
        models: [
          {
            id: "gemini-3-flash",
            name: "Gemini 3 Flash",
            contextWindow: 1000000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

方式 B：通过兼容 OpenAI 接口

如果你的应用使用的是 OpenAI 格式：

{
  models: {
    mode: "merge",
    providers: {
      "defapi-openai": {
        baseUrl: "https://api.defapi.org/v1/chat/completions",
        apiKey: "${DEFAPI_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gemini-3-flash", name: "Gemini 3 Flash", contextWindow: 1000000 },
        ],
      },
    },
  },
}

Defapi 支持的 Gemini 模型

获取 Defapi

访问 Defapi 官网 注册账号，即可获取 API Key 并开始使用。

---

方式二：直接使用 Google 官方 API

获取 API Key

1. 访问 Google AI Studio
2. 使用 Google 账号登录
3. 点击「Get API Key」创建新密钥
4. 复制密钥备用

CLI 配置

# 交互式配置
openclaw onboard --auth-choice google-api-key

# 非交互式配置（环境变量）
export GOOGLE_API_KEY="你的API密钥"
openclaw onboard --google-api-key "$GOOGLE_API_KEY"

配置文件

文件路径: ~/.openclaw/openclaw.json

{
  env: { GOOGLE_API_KEY: "AIza..." },
  agents: { defaults: { model: { primary: "google-generative-ai/gemini-1.5-flash" } } },
}

支持的模型

---

方式二：使用 OpenRouter 统一接入

OpenRouter 提供统一的 API 端点，可以同时访问多个模型提供商的模型。

获取 OpenRouter API Key

1. 访问 OpenRouter 注册账号
2. 在控制台获取 API Key

CLI 配置

export OPENROUTER_API_KEY="sk-or-..."
openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY"

配置文件

文件路径: ~/.openclaw/openclaw.json

{
  env: { OPENROUTER_API_KEY: "sk-or-..." },
  agents: {
    defaults: {
      model: { primary: "openrouter/google/gemini-2.0-flash-exp" },
    },
  },
}

💡 OpenRouter 优势

• 多提供商比价：可选择不同提供商的 Gemini 模型
• 统一接口：只需一个 API Key 即可访问多个模型
• 兼容 OpenAI 格式：无需修改代码即可切换模型

---

方式三：自定义提供商接入

如果平台提供 OpenAI 兼容的 /v1/chat/completions 接口，可配置为自定义提供商。

配置文件示例

文件路径: ~/.openclaw/openclaw.json

{
  agents: {
    defaults: {
      model: { primary: "custom-gemini/gemini-1.5-flash" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      "custom-gemini": {
        baseUrl: "https://your-gemini-proxy.example.com/v1",
        apiKey: "${CUSTOM_GEMINI_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gemini-1.5-flash",
            name: "Gemini 1.5 Flash",
            contextWindow: 1000000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

配置项说明

---

Thinking Blocks 配置

Gemini 2.0 模型支持 Thinking Blocks 用于扩展推理能力。OpenClaw 自动处理这些配置以确保兼容性：

文件路径: ~/.openclaw/openclaw.json

{
  agents: {
    defaults: {
      models: {
        "google-generative-ai/gemini-2.0-flash-exp": {
          params: {
            thinkingConfig: {
              thinkingBudget: 8192,
            },
          },
        },
      },
    },
  },
}

---

常见问题排查

401 错误 / API Key 无效

• 验证 API Key 是否正确且未被撤销
• 检查 Key 是否有访问 Generative Language API 的权限

速率限制

• Gemini 有基于层级的速率限制（免费层: 15 RPM）
• 在 Google AI Studio 仪表板中监控使用情况
• 解决方案：使用 Defapi 可获得更高的调用限额

工具 Schema 错误

• Google 不支持某些 JSON Schema 关键字（如 patternProperties、additionalProperties 等）
• OpenClaw 自动剥离不支持的关键字
• 复杂 Schema 可考虑拆分为更简单的工具定义

需要项目 ID

• 设置 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID 环境变量

---

成本对比

对于高频调用场景，使用 Defapi 可显著降低成本。