OpenClaw에서 Gemini 이미지 인식 실패를 해결하는 3가지 방법: OpenAI 호환 모드 일반 오류 및 네이티브 형식 구성 가이드

OpenClaw에서 OpenAI 호환 모드를 사용하여 Gemini 모델로 이미지 인식을 수행할 때 발생하는 오류는 멀티모달 AI 에이전트를 구성하는 많은 개발자들이 겪는 흔한 골칫거리입니다. 이번 글에서는 Invalid JSON payload 오류의 근본 원인을 깊이 있게 분석하고, OpenClaw Gemini 이미지 인식 실패 문제를 빠르게 해결할 수 있는 3가지 검증된 솔루션을 제공합니다.

핵심 가치: 이 글을 읽고 나면 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 공식 비주얼 이해 데모로 API를 직접 테스트해보면 이미지 인식 기능은 완벽하게 작동합니다. 문제는 OpenClaw가 OpenAI 호환 모드를 통해 요청을 전달할 때 발생하는 형식 불일치입니다.

검증 방법은 간단합니다:

# Gemini API를 직접 호출하여 이미지 인식 테스트 — 정상 작동
import google.generativeai as genai
import PIL.Image

# API 키 설정
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 키와 모델 자체에 문제가 없는지 확인하세요. APIYI(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의 형식 요구 사항과 일치하지 않아서 발생하는 문제입니다.

솔루션 1: 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로 빠르게 전환하기

# 방법 1: Gemini 설정 재초기화
openclaw onboard --auth-choice gemini-api-key

# 방법 2: 설정 파일 직접 수정
# 설정 파일 위치: ~/.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
        }
      }
    }
  }
}

🚀 빠른 시작: 설정 호환성 문제를 직접 해결하고 싶지 않다면 APIYI(apiyi.com) 플랫폼의 통합 인터페이스를 사용하는 것을 추천합니다. 플랫폼 내부에서 OpenAI 형식의 요청을 Gemini 네이티브 형식으로 자동으로 변환해주므로, 개발자가 스키마 차이를 신경 쓸 필요가 없습니다.

솔루션 2: API 중계 서비스를 통한 호환성 자동 처리

OpenClaw에서 OpenAI 호환 모드를 유지하면서 Gemini를 포함한 다양한 모델을 계속 사용하고 싶다면, API 중계 서비스를 통해 형식 호환성 문제를 해결할 수 있습니다.

중계 서비스의 작동 원리

OpenClaw (OpenAI 형식 요청)
    ↓
API 중계 서비스 (예: APIYI)
    ↓ 호환되지 않는 JSON 스키마 필드 자동 정리
    ↓ 요청 형식 자동 변환
Gemini API (네이티브 형식)
    ↓
✅ 이미지 인식 결과 정상 반환

설정 예시

# APIYI 중계 서비스를 통한 Gemini 이미지 인식 호출
import openai
import base64

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI 통합 인터페이스
)

# 이미지 읽기 및 인코딩
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에서 APIYI 중계 서비스 설정하기:

{
  "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 등 다양한 모델을 함께 사용 중이라면, APIYI(apiyi.com)를 통해 API 호출을 통합 관리하는 것이 훨씬 효율적입니다. 모델마다 다른 API 형식을 일일이 설정할 필요가 없기 때문이죠.

솔루션 3: 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 수동 정리 방식은 각 도구의 매개변수 정의를 일일이 처리해야 하므로 유지보수 비용이 높습니다. 도구 개수가 많거나 자주 변경된다면 솔루션 1(네이티브 형식)이나 솔루션 2(API 중계 서비스)를 우선적으로 고려하세요.

3가지 솔루션 비교 및 선택 가이드

선택 가이드

• OpenClaw에서 Gemini만 사용한다면 → 솔루션 1(네이티브 형식), 가장 안정적입니다.
• OpenClaw에서 여러 모델을 혼용한다면 → 솔루션 2(APIYI 중계), 가장 편리합니다.
• 자체 AI 앱에서 정밀한 제어가 필요하다면 → 솔루션 3(수동 정리), 가장 유연합니다.
• 무엇을 선택할지 고민된다면 → 솔루션 2를 먼저 시도해 보세요. APIYI(apiyi.com)를 통해 빠르게 검증할 수 있습니다.

자주 묻는 질문 (FAQ)

요약

OpenClaw에서 Gemini 이미지 인식이 실패하는 근본 원인은 Gemini 모델의 시각적 능력 문제가 아니라, OpenAI 호환 모드에서의 JSON Schema 필드 비호환성 때문입니다. 상황에 맞는 3가지 해결책을 제안합니다.

• 네이티브 형식 (google-generative-ai): 가장 확실한 방법, Gemini만 단독으로 사용하는 경우 추천
• API 중계 서비스: 가장 간편한 방법, 여러 모델을 혼용하는 경우 추천
• 수동 Schema 정리: 가장 유연한 방법, 자체 시스템을 구축하는 경우 추천

APIYI(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 — 대규모 언어 모델 API 연동 및 기술 분석 전문
🔗 더 많은 튜토리얼: APIYI apiyi.com에서 더 많은 모델 호출 가이드와 무료 테스트 크레딧을 확인하세요.