OpenClaw 멀티모달 및 비전 모델 설정 가이드

서문

멀티모달 기능은 AI가 텍스트에만 국한되지 않고, 이미지, 문서, 심지어 비디오까지 "보고" 이해할 수 있게 해줍니다. OpenClaw에서는 WhatsApp, Telegram 등의 채널을 통해 이미지를 보내면 AI 어시스턴트가 자동으로 이미지 내용을 인식하고 분석합니다. 본 가이드에서는 멀티모달 비전 모델의 설정과 활용 방법을 상세히 안내합니다.

비전 기능을 지원하는 모델

현재 OpenClaw가 지원하는 주요 비전 모델:

1단계: 기본 설정

1.1 클라우드 비전 모델 사용

Claude Sonnet 4를 예로 들어 비전 기능을 설정합니다:

{
  models: {
    vision: {
      provider: "anthropic",
      apiKey: "${ANTHROPIC_API_KEY}",
      defaultModel: "claude-sonnet-4",
      capabilities: {
        vision: true,          // 이미지 이해 활성화
        maxImageSize: 20,      // 최대 이미지 크기 (MB)
        maxImagesPerMessage: 5, // 메시지당 최대 이미지 수
      },
      parameters: {
        temperature: 0.3,       // 비전 작업에는 낮은 온도 권장
        maxTokens: 4096,
      }
    }
  }
}

1.2 GPT-4o 비전 사용

{
  models: {
    vision: {
      provider: "openai",
      apiKey: "${OPENAI_API_KEY}",
      defaultModel: "gpt-4o",
      capabilities: {
        vision: true,
        imageDetail: "high",     // high 또는 low, high가 더 정확하지만 비용 높음
      }
    }
  }
}

1.3 Gemini 비전 사용

{
  models: {
    vision: {
      provider: "google",
      apiKey: "${GOOGLE_AI_API_KEY}",
      defaultModel: "gemini-2.5-flash",
      capabilities: {
        vision: true,
        pdf: true,               // Gemini 네이티브 PDF 지원
        video: true,             // 비디오 이해 지원
      }
    }
  }
}

1.4 로컬 비전 모델 사용

# 비전 지원 로컬 모델 다운로드
ollama pull llava:13b
# 또는 더 강력한 Qwen VL
ollama pull qwen2.5-vl:72b   # 대용량 VRAM 필요

OpenClaw 설정:

{
  models: {
    "local-vision": {
      provider: "ollama",
      baseUrl: "http://localhost:11434",
      defaultModel: "llava:13b",
      capabilities: {
        vision: true,
      }
    }
  }
}

2단계: 채널 연동 설정

2.1 Telegram 이미지 처리

Telegram은 이미지 직접 전송을 지원합니다. 설정 방법:

{
  channels: {
    telegram: {
      token: "${TELEGRAM_BOT_TOKEN}",
      model: "vision",             // 위에서 설정한 비전 모델 지정
      mediaHandling: {
        images: true,              // 이미지 수신 및 처리
        documents: true,           // 문서 수신 (PDF 등)
        maxFileSize: 20,           // 최대 파일 크기 (MB)
        compressImages: true,      // 대용량 이미지 압축으로 토큰 절약
        compressionQuality: 85,    // 압축 품질 (0-100)
      }
    }
  }
}

2.2 WhatsApp 이미지 처리

{
  channels: {
    whatsapp: {
      model: "vision",
      mediaHandling: {
        images: true,
        documents: true,
        stickers: false,            // 스티커는 보통 분석 불필요
      }
    }
  }
}

2.3 Discord 이미지 처리

{
  channels: {
    discord: {
      token: "${DISCORD_BOT_TOKEN}",
      model: "vision",
      mediaHandling: {
        images: true,
        attachments: true,          // 메시지 첨부파일 처리
      }
    }
  }
}

3단계: 활용 사례 상세 설명

3.1 OCR 문자 인식

채팅에서 텍스트가 포함된 이미지를 보내면, AI가 자동으로 문자를 인식합니다:

사용자: [메뉴 사진 전송]
사용자: 이 메뉴를 번역해 주세요

AI: 이것은 일식 레스토랑 메뉴입니다. 번역은 다음과 같습니다:
    - 刺身盛り合わせ → 모둠 사시미
    - 焼き鳥 → 야키토리 (꼬치구이)
    - 天ぷら盛り合わせ → 모둠 덴푸라
    ...

OCR 최적화를 위한 시스템 프롬프트:

{
  models: {
    vision: {
      provider: "anthropic",
      defaultModel: "claude-sonnet-4",
      systemPrompt: "当用户发送图片时，首先仔细识别图中所有文字内容，然后根据用户的要求进行处理。对于模糊或不确定的文字，用 [?] 标记。",
      capabilities: {
        vision: true,
      }
    }
  }
}

3.2 차트 및 데이터 분석

차트, 표 스크린샷을 보내면 AI가 데이터를 해석할 수 있습니다:

사용자: [매출 데이터 꺾은선 그래프 전송]
사용자: 이 추세를 분석해 주세요

AI: 차트 분석 결과:
    1. 전체 추세: Q1-Q3 매출 꾸준히 상승, Q4에서 하락
    2. 최고점은 9월, 약 $450K
    3. 전년 대비 약 23% 성장
    4. Q4 하락은 계절적 요인과 관련이 있을 수 있습니다
    다음 연도 전략을 위해 Q4 하락 원인에 주목하시기를 권장합니다.

3.3 문서 및 스크린샷 이해

UI 스크린샷, 코드 스크린샷, 문서 사진 등을 전송합니다:

사용자: [오류 스크린샷 전송]
사용자: 이 오류는 어떻게 해결하나요?

AI: 오류 메시지는 "TypeError: Cannot read property 'map' of undefined"입니다.
    이는 undefined 값에 .map() 메서드를 호출하려 했음을 의미합니다.
    가능한 원인:
    1. API 반환 데이터 형식이 예상과 다름
    2. 데이터가 로드되기 전에 렌더링 시도
    .map() 호출 전에 null 검사를 추가하는 것을 권장합니다:
    data?.items?.map(...) 또는 (data.items || []).map(...)

3.4 이미지 비교

여러 이미지를 보내 비교 분석을 합니다:

사용자: [인테리어 시안 2장 전송]
사용자: 두 방안의 장단점을 비교해 주세요

AI: 방안 A (첫 번째 이미지):
    - 장점: 공간감이 뛰어남, 채광 우수, 모던 심플 스타일
    - 단점: 수납 공간 부족, 색감이 차가운 편

    방안 B (두 번째 이미지):
    - 장점: 수납 공간 충분, 따뜻한 색조로 아늑함
    - 단점: 공간이 다소 좁아 보임, 가구 배치가 빽빽함

    제안: 편안함을 중시하면 방안 B, 공간감을 중시하면 방안 A를 선택하세요.

4단계: 이미지 처리 최적화

4.1 이미지 해상도 및 비용 제어

고해상도 이미지는 더 많은 토큰을 소비합니다 (특히 OpenAI 모델). 적절한 설정으로 비용을 절감할 수 있습니다:

{
  models: {
    vision: {
      provider: "openai",
      defaultModel: "gpt-4o",
      capabilities: {
        vision: true,
        imageDetail: "low",       // low: 고정 85 토큰
                                   // high: 해상도에 따라 계산, 수천 토큰 가능
        imageResize: {
          maxWidth: 1024,          // 대용량 이미지 자동 축소
          maxHeight: 1024,
        }
      }
    }
  }
}

4.2 Token 소비 참고

4.3 이미지 캐싱

같은 유형의 이미지를 자주 분석하는 경우, 캐싱을 활성화하면 중복 처리를 줄일 수 있습니다:

{
  models: {
    vision: {
      provider: "anthropic",
      defaultModel: "claude-sonnet-4",
      capabilities: {
        vision: true,
      },
      cache: {
        enabled: true,
        imageHashCache: true,     // 동일 이미지의 분석 결과 캐싱
        ttl: 3600,                // 캐시 유효 기간 (초)
      }
    }
  }
}

5단계: 비전 모델 비교 평가

실제 사용 사례 테스트 결과

추천 선택

• 최고 품질: Claude Sonnet 4 (전반적으로 가장 우수)
• 최고 가성비: Gemini 2.5 Flash (무료 할당량 + 괜찮은 품질)
• 완전 무료: Llava 13B 로컬 배포 (품질은 제한적이지만 사용 가능)
• PDF 처리: Gemini 2.5 Pro (네이티브 PDF 지원이 가장 우수)

자주 묻는 질문

이미지 인식 불가

설정에서 vision: true가 활성화되어 있는지 확인하고, 로그를 점검합니다:

openclaw logs | grep -i "vision\|image\|media"

이미지 용량 초과로 인한 타임아웃

capabilities: {
  vision: true,
  imageResize: {
    maxWidth: 1024,
    maxHeight: 1024,
  }
}

로컬 비전 모델 성능 부족

Llava 등 로컬 비전 모델은 복잡한 사용 사례에서 성능이 제한적입니다. 높은 정확도가 요구되는 작업에는 클라우드 모델 사용을 권장합니다.

비디오 전송 후 응답 없음

현재 Gemini 시리즈만 비디오 이해를 지원합니다. 다른 모델은 비디오를 수신하면 무시하거나 오류를 반환합니다. 설정에서 안내 메시지를 구성할 수 있습니다:

mediaHandling: {
  video: false,
  unsupportedMediaReply: "抱歉，我目前不支持视频分析，请发送截图或图片。",
}

요약

멀티모달 비전 기능은 OpenClaw의 활용 범위를 크게 확장합니다. 일상적인 OCR 인식부터 전문적인 차트 분석까지, 비전 모델은 챗봇을 한층 더 실용적으로 만들어줍니다. 최고의 비전 이해 성능을 원한다면 Claude Sonnet 4 또는 GPT-4o를, 무료 할당량 내에서 비전 기능을 체험하고 싶다면 Gemini 2.5 Flash를, 로컬에서 무료로 실행하고 싶다면 Llava/Qwen VL을 사용하시기 바랍니다. 실제 요구사항과 예산에 맞는 가장 적합한 방안을 선택하십시오.