OpenClaw 멀티미디어 메시지 처리 설정

서문

현대 메신저는 텍스트에만 국한되지 않습니다. 사용자는 이미지를 보내 AI에게 내용을 설명하도록 요청하거나, 음성을 보내 AI에게 전사하도록 하거나, 문서를 업로드하여 AI에게 분석을 요청할 수 있습니다. OpenClaw은 멀티 채널 AI 게이트웨이로서 서로 다른 플랫폼에서 오는 멀티미디어 메시지를 통합 처리해야 하며, 각 플랫폼의 미디어 능력도 제각각입니다. 이 글에서는 OpenClaw의 멀티미디어 메시지 처리 메커니즘과 설정 방법을 상세히 설명합니다.

지원하는 미디어 타입

OpenClaw은 현재 다음 네 가지 주요 멀티미디어 콘텐츠를 지원합니다:

전역 미디어 설정

openclaw.json에서 미디어 처리의 전역 설정은 advanced.media 섹션에 위치합니다:

{
  "advanced": {
    "media": {
      "enabled": true,
      "maxFileSize": "20mb",
      "tempDir": "~/.openclaw/temp/media",
      "cleanupInterval": "1h",
      "image": {
        "enabled": true,
        "maxResolution": "2048x2048",
        "autoResize": true,
        "compressionQuality": 85
      },
      "audio": {
        "enabled": true,
        "sttProvider": "whisper",
        "sttModel": "whisper-1",
        "maxDuration": 300
      },
      "document": {
        "enabled": true,
        "maxPages": 50,
        "ocrEnabled": false
      },
      "video": {
        "enabled": false,
        "maxDuration": 60,
        "keyframeInterval": 5
      }
    }
  }
}

핵심 매개변수 설명

• maxFileSize: 처리 허용 파일 크기 상한, 초과하는 파일은 무시되고 안내 메시지 반환
• autoResize: 이미지 해상도가 모델 제한을 초과하면 자동 축소
• sttProvider: 음성-텍스트 변환 서비스 제공자, whisper(OpenAI)와 local(로컬 모델) 지원
• maxDuration: 오디오 및 비디오의 최대 길이 제한(초)

이미지 메시지 처리 흐름

사용자가 이미지를 보내면 OpenClaw의 처리 흐름은 다음과 같습니다:

1. 수신: 채널 API에서 임시 디렉터리로 이미지 다운로드
2. 전처리: 형식, 크기 확인; 필요 시 형식 변환 및 크기 조정
3. 라우팅: 현재 Agent에 설정된 모델이 비전 입력을 지원하는지 확인
4. 전송: Base64 또는 URL 형태로 API 요청에 이미지 첨부
5. 정리: 처리 완료 후 cleanupInterval 주기에 따라 임시 파일 삭제

현재 모델이 비전 기능을 지원하지 않는 경우, OpenClaw은 두 가지 대응 전략을 제공합니다:

{
  "advanced": {
    "media": {
      "image": {
        "fallbackOnNoVision": "describe",
        "visionFallbackModel": "claude"
      }
    }
  }
}

• "describe": 비전을 지원하는 모델로 자동 전환하여 이미지 내용을 설명하고, 설명 텍스트를 원래 모델에 전달
• "reject": 현재 모델이 이미지 입력을 지원하지 않음을 사용자에게 직접 알림

오디오 메시지 처리

오디오 메시지는 먼저 음성-텍스트 변환(STT) 처리를 거친 후, 텍스트 메시지로 모델에 전달됩니다:

사용자 음성 전송 → 오디오 파일 다운로드 → STT 전사 → 텍스트를 사용자 메시지로 사용 → 모델에 전송

STT 결과는 세션 기록의 metadata 필드에 첨부되어 추적이 가능합니다:

{
  "id": "msg_010",
  "role": "user",
  "content": "내일 오후 3시에 회의실 예약해줘",
  "metadata": {
    "originalType": "audio",
    "sttConfidence": 0.95,
    "audioDuration": 4.2
  }
}

문서 메시지 처리

사용자가 업로드한 문서는 텍스트 내용이 추출된 후 대화의 컨텍스트로 주입됩니다:

{
  "advanced": {
    "media": {
      "document": {
        "enabled": true,
        "maxPages": 50,
        "extractionMethod": "auto",
        "injectAs": "system"
      }
    }
  }
}

injectAs는 문서 내용이 컨텍스트에서 어떤 역할로 사용되는지를 제어합니다:

• "system": 시스템 메시지로 주입, 모델이 배경 지식으로 간주
• "user": 사용자 메시지의 일부로, 사용자 텍스트 뒤에 첨부

각 채널 미디어 지원 차이

서로 다른 메신저 플랫폼의 미디어 메시지 지원은 상당한 차이가 있습니다. 다음은 OpenClaw이 적응한 현황입니다:

채널별 미디어 재정의

특정 채널에서 특정 미디어 기능을 비활성화하고 싶다면, 채널 설정에서 전역 설정을 재정의할 수 있습니다:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "your-token",
      "mediaSupport": {
        "image": true,
        "audio": true,
        "document": true,
        "video": false
      }
    },
    "slack": {
      "enabled": true,
      "mediaSupport": {
        "image": true,
        "audio": false,
        "document": true,
        "video": false
      }
    }
  }
}

모델의 미디어 능력

모든 모델이 멀티미디어 입력을 지원하는 것은 아닙니다. OpenClaw 내부에는 모델 능력 표가 유지됩니다:

OpenClaw은 모델 능력에 따라 전처리 필요 여부를 자동으로 결정합니다. 예를 들어, GPT-4o에 보내는 오디오는 직접 전달할 수 있지만, Claude에 보내는 오디오는 먼저 STT 전사가 필요합니다.

미디어 파일 정리

임시 파일의 무한 증가를 방지하기 위해, OpenClaw은 정기적으로 정리합니다:

# 미디어 캐시 수동 정리
openclaw media cleanup

# 미디어 캐시 사용량 확인
openclaw media stats

정리

OpenClaw의 멀티미디어 처리 시스템은 통합 추상화를 기반으로 각 채널의 차별화된 능력을 충분히 적응시킵니다. 적절한 설정을 통해 AI 어시스턴트가 서로 다른 플랫폼에서 이미지, 오디오, 문서를 원활하게 처리하면서 리소스 소비를 제어할 수 있습니다. 핵심은 실제 사용하는 채널과 모델에 따라 적절한 미디어 처리 매개변수와 폴백 전략을 설정하는 것입니다.