解決 OpenClaw 調用 Gemini 圖片識別失敗的 3 種方法：OpenAI 兼容模式常見報錯與原生格式配置指南

OpenClaw 中使用 OpenAI 兼容模式調用 Gemini 模型進行圖片識別時經常遇到報錯，是很多開發者在配置多模態 AI 代理時的常見痛點。本文將深入分析 Invalid JSON payload 報錯的根本原因，並提供 3 種經過驗證的解決方案，幫助你快速修復 OpenClaw Gemini 圖片識別失敗問題。

核心價值: 讀完本文，你將理解 OpenAI 兼容模式與 Gemini 原生 API 的關鍵差異，掌握正確的配置方法，徹底解決圖片識別失敗問題。

OpenClaw Gemini 圖片識別失敗的錯誤現象

在 OpenClaw 中配置 Gemini 模型後，嘗試進行圖片識別時，後臺日誌通常會出現以下典型報錯：

Invalid JSON payload received. Unknown name "patternProperties"
at 'tools[0].function_declarations[3].parameters.properties[4].value':
Cannot find field.

Invalid JSON payload received. Unknown name "const"
at 'tools[0].function_declarations[37].parameters.properties[0].value':
Cannot find field.

OpenClaw Gemini 圖片識別報錯的關鍵特徵

OpenClaw Gemini 圖片識別失敗的快速診斷

一個常見的誤區是認爲 Gemini 的圖片識別能力有問題。實際上，使用 Gemini 官方的視覺理解 demo 直接測試 API，圖片識別功能完全正常。問題出在 OpenClaw 通過 OpenAI 兼容模式轉發請求時的格式不兼容。

驗證方法很簡單：

# 直接調用 Gemini API 測試圖片識別 — 完全正常
import google.generativeai as genai
import PIL.Image

genai.configure（api_key="YOUR_GEMINI_API_KEY"）
model = genai.GenerativeModel（"gemini-2.5-flash"）

image = PIL.Image.open（"test.jpg"）
response = model.generate_content（["描述這張圖片"， image]）
print（response.text）  # ✅ 正常輸出圖片描述

🎯 診斷建議: 如果你在 OpenClaw 中遇到 Gemini 圖片識別問題，先用上述方式確認 API Key 和模型本身沒問題。通過 API易 apiyi.com 平臺也可以快速測試 Gemini 視覺理解能力，平臺會自動處理格式兼容性問題。

OpenClaw Gemini 圖片識別失敗的根本原因分析

理解問題的根本原因，才能選擇最合適的解決方案。OpenClaw 調用 Gemini 圖片識別失敗，核心原因是 JSON Schema 兼容性問題。

OpenAI 與 Gemini 工具調用 JSON Schema 差異

當 OpenClaw 使用 OpenAI 兼容模式 （openai-completions） 調用 Gemini 時，請求流程如下：

OpenClaw 構建請求 （OpenAI 格式）
    ↓
包含工具定義的 JSON Schema
    ↓
發送到 Gemini OpenAI 兼容端點
    ↓
Gemini 解析 function_declarations
    ↓
❌ 遇到不支持的 Schema 字段 → 400 錯誤

Gemini API 不支持的 JSON Schema 字段清單

這是問題的核心。Gemini 的 function_declarations 對 JSON Schema 的支持是 受限子集，以下字段會直接導致 400 錯誤：

爲什麼換成 GPT-5.4 就沒問題

這進一步印證了根因分析。當在 OpenClaw 中將模型從 Gemini 切換爲 GPT-5.4 時，圖片識別立即恢復正常——因爲 GPT-5.4 的 API 原生支持完整的 JSON Schema 規範，OpenClaw 生成的工具定義 Schema 完全兼容。

📌 關鍵認知: 這不是 Gemini 圖片識別能力的問題，而是 OpenClaw 的 OpenAI 兼容模式發送的工具 Schema 與 Gemini API 的格式要求不匹配。

解決方案一：切換 Gemini 原生格式（推薦）

最徹底的解決方案是在 OpenClaw 中將 Gemini 的 API 接口類型從 openai-completions 切換爲 google-generative-ai 原生格式。

配置步驟

修改前 （OpenAI 兼容模式 — 有問題）:

{
  "provider": "google"，
  "model": "gemini-2.5-flash"，
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai"，
  "api": "openai-completions"，
  "apiKey": "YOUR_GEMINI_API_KEY"
}

修改後 （Gemini 原生格式 — 推薦）:

{
  "provider": "google"，
  "model": "gemini-2.5-flash"，
  "baseUrl": "https://generativelanguage.googleapis.com/v1beta"，
  "api": "google-generative-ai"，
  "apiKey": "YOUR_GEMINI_API_KEY"
}

原生格式配置的核心變化

使用 OpenClaw CLI 快速切換

# 方式一: 重新初始化 Gemini 配置
openclaw onboard --auth-choice gemini-api-key

# 方式二: 手動編輯配置文件
# 配置文件位置: ~/.openclaw/config.json
# 將 api 字段從 "openai-completions" 改爲 "google-generative-ai"

{
  "providers": {
    "google": {
      "apiKey": "YOUR_GEMINI_API_KEY"，
      "models": {
        "gemini-2.5-flash": {
          "api": "google-generative-ai"，
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta"，
          "capabilities": {
            "vision": true，
            "functionCalling": true，
            "streaming": true
          }，
          "reasoning": false
        }，
        "gemini-2.5-pro": {
          "api": "google-generative-ai"，
          "baseUrl": "https://generativelanguage.googleapis.com/v1beta"，
          "capabilities": {
            "vision": true，
            "functionCalling": true，
            "streaming": true
          }，
          "reasoning": true，
          "thinkingBudget": 8192
        }
      }
    }
  }
}

🚀 快速開始: 如果你不想手動處理配置兼容性問題，推薦使用 API易 apiyi.com 平臺的統一接口。平臺內部會自動將 OpenAI 格式請求轉換爲 Gemini 原生格式，開發者無需關注 Schema 差異。

解決方案二：通過 API 中轉平臺自動處理兼容性

如果你希望在 OpenClaw 中繼續使用 OpenAI 兼容模式調用多種模型（包括 Gemini），可以通過 API 中轉平臺來解決格式兼容性問題。

中轉平臺的工作原理

OpenClaw （OpenAI 格式請求）
    ↓
API 中轉平臺 （如 API易）
    ↓ 自動清理不兼容的 JSON Schema 字段
    ↓ 自動轉換請求格式
Gemini API （原生格式）
    ↓
✅ 正常返回圖片識別結果

配置示例

# 通過 API易 中轉平臺調用 Gemini 圖片識別
import openai
import base64

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://api.apiyi.com/v1"  # API易 統一接口
）

# 讀取圖片並編碼
with open（"test.jpg"， "rb"） as f:
    image_data = base64.b64encode（f.read（））.decode（"utf-8"）

response = client.chat.completions.create（
    model="gemini-2.5-flash"，
    messages=[
        {
            "role": "user"，
            "content": [
                {"type": "text"， "text": "描述這張圖片的內容"}，
                {
                    "type": "image_url"，
                    "image_url": {
                        "url": f"data:image/jpeg；base64，{image_data}"
                    }
                }
            ]
        }
    ]
）
print（response.choices[0].message.content）

中轉平臺 vs 直連對比

在 OpenClaw 中配置 API易 中轉：

{
  "provider": "apiyi"，
  "model": "gemini-2.5-flash"，
  "baseUrl": "https://api.apiyi.com/v1"，
  "api": "openai-completions"，
  "apiKey": "YOUR_APIYI_KEY"
}

💡 選擇建議: 如果你在 OpenClaw 中同時使用多種模型（GPT-5.4、Claude、Gemini 等），通過 API易 apiyi.com 統一管理 API 調用是更高效的選擇，避免爲每個模型單獨配置不同的 API 格式。

解決方案三：手動清理 JSON Schema 不兼容字段

如果你需要在代碼層面解決兼容性問題，可以在發送請求前手動清理 Gemini 不支持的 JSON Schema 字段。

JSON Schema 清理函數

def clean_schema_for_gemini（schema: dict） -> dict:
    """清理 Gemini 不支持的 JSON Schema 字段"""
    unsupported_keys = {
        "patternProperties"，
        "const"，
        "additionalProperties"，
        "$schema"，
        "exclusiveMaximum"，
        "exclusiveMinimum"，
        "propertyNames"，
    }

    if isinstance（schema， dict）:
        return {
            k: clean_schema_for_gemini（v）
            for k， v in schema.items（）
            if k not in unsupported_keys
        }
    elif isinstance（schema， list）:
        return [clean_schema_for_gemini（item） for item in schema]
    return schema

import openai
import json

def clean_schema_for_gemini（schema）:
    """遞歸清理 Gemini 不支持的 JSON Schema 字段"""
    unsupported_keys = {
        "patternProperties"， "const"， "additionalProperties"，
        "$schema"， "exclusiveMaximum"， "exclusiveMinimum"，
        "propertyNames"， "if"， "then"， "else"，
        "allOf"， "anyOf"， "oneOf"， "not"，
    }

    if isinstance（schema， dict）:
        cleaned = {}
        for k， v in schema.items（）:
            if k not in unsupported_keys:
                cleaned[k] = clean_schema_for_gemini（v）
        return cleaned
    elif isinstance（schema， list）:
        return [clean_schema_for_gemini（item） for item in schema]
    return schema

def clean_tools_for_gemini（tools）:
    """清理工具列表中的所有 Schema"""
    cleaned_tools = []
    for tool in tools:
        tool_copy = json.loads（json.dumps（tool））
        if "function" in tool_copy:
            params = tool_copy["function"].get（"parameters"， {}）
            tool_copy["function"]["parameters"] = clean_schema_for_gemini（params）
        cleaned_tools.append（tool_copy）
    return cleaned_tools

# 使用示例
tools = [
    {
        "type": "function"，
        "function": {
            "name": "analyze_image"，
            "description": "分析圖片內容"，
            "parameters": {
                "type": "object"，
                "properties": {
                    "image_url": {"type": "string"}，
                    "detail": {"type": "string"， "const": "high"}  # Gemini 不支持
                }，
                "patternProperties": {"^x-": {"type": "string"}}，  # Gemini 不支持
                "additionalProperties": False  # Gemini 不支持
            }
        }
    }
]

# 清理後調用
cleaned_tools = clean_tools_for_gemini（tools）

client = openai.OpenAI（
    api_key="YOUR_API_KEY"，
    base_url="https://api.apiyi.com/v1"
）

response = client.chat.completions.create（
    model="gemini-2.5-flash"，
    messages=[{"role": "user"， "content": "Hello"}]，
    tools=cleaned_tools
）

⚠️ 注意: 手動清理 Schema 的方案需要你對每個工具的參數定義都進行處理，維護成本較高。如果工具數量多或經常變動，建議優先考慮方案一（原生格式）或方案二（API 中轉平臺）。

3 種解決方案對比與選型建議

選型決策樹

• 只在 OpenClaw 中使用 Gemini → 方案一（原生格式），最穩定
• OpenClaw 中混用多種模型 → 方案二（API易中轉），最省心
• 自建 AI 應用需要精細控制 → 方案三（手動清理），最靈活
• 不確定選哪個 → 先試方案二，通過 API易 apiyi.com 快速驗證

常見問題

總結

OpenClaw 調用 Gemini 圖片識別失敗的根本原因是 OpenAI 兼容模式下的 JSON Schema 字段不兼容，而非 Gemini 模型的視覺能力有問題。3 種解決方案各有適用場景：

• 原生格式 （google-generative-ai）: 最徹底，推薦單一使用 Gemini 的場景
• API 中轉: 最省心，推薦多模型混用的場景
• 手動清理 Schema: 最靈活，推薦自建系統的場景

推薦通過 API易 apiyi.com 快速驗證 Gemini 圖片識別效果，平臺支持 Gemini、GPT、Claude 等主流模型的統一調用，自動處理各模型 API 格式差異。

參考資料

1. Gemini 官方文檔 – 圖片理解: Gemini 視覺理解能力說明

   • 鏈接: ai.google.dev/gemini-api/docs/image-understanding

2. Gemini 官方文檔 – OpenAI 兼容: OpenAI SDK 調用 Gemini 的說明

   • 鏈接: ai.google.dev/gemini-api/docs/openai

3. OpenClaw GitHub Issue #21172: patternProperties 導致 Gemini API 400 錯誤

   • 鏈接: github.com/openclaw/openclaw/issues/21172

4. OpenClaw GitHub Issue #14456: Gemini 2.5 Flash OpenAI 兼容模式 400 錯誤

   • 鏈接: github.com/openclaw/openclaw/issues/14456

5. OpenClaw 模型配置文檔: 模型提供商配置指南

   • 鏈接: docs.openclaw.ai/concepts/model-providers

📝 本文作者: APIYI Team — 專注 AI 大模型 API 接入與技術解析
🔗 更多教程: 訪問 API易 apiyi.com 獲取更多模型調用指南和免費測試額度