OpenClaw 配置 Gemma 4 31B IT 完全指南（2026年4月版）

背景

本文详细讲解了如何在 OpenClaw 平台中正确配置谷歌最新开源大模型 Gemma 4 31B IT，解决了三层兼容性问题，实现该模型在 OpenClaw 中的稳定运行。该模型拥有 256K 上下文窗口和多模态输入能力，参数规模 31B，是目前开源大模型中的性能标杆。

核心问题：三层兼容性障碍

Gemma 4 无法直接在 OpenClaw 中运行，主要涉及三层不兼容问题：

1. 路由层不兼容：OpenRouter/HuggingFace Router 不支持 Gemma 4 的工具调用（tool/function calling）能力，而 OpenClaw 的 Agent 架构高度依赖工具调用功能，因此这两种接入方式不可用。
2. 内置 Provider 不兼容：OpenClaw 内置的 google/* provider 尚未包含 Gemma 模型系列，直接使用时会被识别为未知模型。
3. 响应解析不兼容：Gemma 4 的流式响应中包含 "thought": true 的思维/推理 token，OpenClaw 的响应解析器会尝试将其按结构化 reasoning 输出处理，进而触发 MALFORMED_RESPONSE 错误。

完整解决方案

总体思路

• 使用自定义 google-ai provider 直连 Google AI Studio 原生 API。
• 采用 Google Generative AI 原生 API 格式而非通用路由层格式。
• 在模型定义中显式设置 "reasoning": false，让 OpenClaw 跳过对 reasoning/thinking token 的解析，避免解析失败。

分步配置

1. 添加自定义 provider（修改 ~/.openclaw/openclaw.json）

在 models.providers 数组中加入以下配置：

"google-ai": {
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
  "api": "google-generative-ai",
  "authHeader": true,
  "models": [
    {
      "id": "gemma-4-31b-it",
      "name": "Gemma 4 31B IT",
      "reasoning": false,
      "input": ["text", "image"],
      "cost": {
        "input": 0,
        "output": 0
      },
      "contextWindow": 262144,
      "maxTokens": 32768
    }
  ]
}

2. 设置默认模型（修改 ~/.openclaw/openclaw.json）

• 在 agents.defaults.model 中设置：

  "primary": "google-ai/gemma-4-31b-it",
  "fallbacks": ["minimax/MiniMax-M2.7", "minimax-portal/MiniMax-M2.1"]
  

• 在 agents.list[0]（主 Agent 配置）中设置：

  "primary": "google-ai/gemma-4-31b-it"
  

• 在 agents.defaults.models 中添加模型别名：

  "google-ai/gemma-4-31b-it": {
    "alias": "gemma4"
  }
  

3. 配置认证信息（修改 ~/.openclaw/agents/main/agent/auth-profiles.json）

添加 Google AI Studio 认证配置：

"google-ai:default": {
  "type": "api_key",
  "provider": "google-ai",
  "key": ""
}

4. 配置环境变量（修改 ~/.openclaw/.env）

添加 API Key：

GOOGLE_AI_API_KEY=AIza...

关键要点

要让 OpenClaw 正常使用 Gemma 4 31B IT，需严格遵循三点核心配置：

1. ✅ 不使用 OpenRouter/HuggingFace Router 作为工具调用接入方式。
2. ✅ 通过自定义 google-ai provider 直连 Google AI Studio 原生 API。
3. ✅ 在模型定义中显式设置 "reasoning": false，避免解析 thinking token 时出错。

---

引用来源：在OpenClaw实测谷歌开源大模型Gemma 4 – AI超元域的博客

配套视频：哔哩哔哩 | YouTube