미디어 이해(Media Understanding) 기능 활용하기

사용자가 갑자기 긴 녹음 파일이나 고해상도 이미지를 보내면 당황스러울 때가 있어요. 모델이 이 파일을 다 읽을 때까지 기다려야 하고, 정작 중요한 명령은 요약 없이는 놓칠 수도 있으니까요.

이런 상황에서 미디어의 핵심 내용을 미리 텍스트로 요약해두면 시스템이 훨씬 영리하게 작동할 수 있어요. OpenClaw는 응답 파이프라인이 실행되기 전에 인바운드 미디어를 미리 파악하는 기능을 제공해요.

필요한 것

• MediaPaths, MediaUrls, MediaTypes 데이터가 포함된 첨부 파일
• 지원되는 Provider API 키 (OpenAI, Anthropic, Google, Groq, Deepgram)
• 로컬 CLI 도구 (선택 사항: sherpa-onnx-offline, whisper-cli, whisper, gemini)
• OpenClaw 설정 파일 접근 권한

빠른 시작

5분 안에 미디어 요약 기능을 시작하는 방법이에요.

1. tools.media 설정에서 image, audio, video 중 원하는 기능을 활성화하세요.
2. models 배열에 사용할 Provider 모델이나 CLI 명령어를 추가하세요.
3. maxBytes로 처리 가능한 파일 크기를 제한하고, maxChars로 요약본의 길이를 정하세요.
4. /status 명령어를 입력해 미디어 이해 기능이 정상적으로 작동하는지 확인하세요.

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.2", capabilities: ["image"] },
        {
          provider: "google",
          model: "gemini-3-flash-preview",
          capabilities: ["image", "audio", "video"],
        },
        {
          type: "cli",
          command: "gemini",
          args: [
            "-m",
            "gemini-3-flash",
            "--allowed-tools",
            "read_file",
            "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
          ],
          capabilities: ["image", "video"],
        },
      ],
      audio: {
        attachments: { mode: "all", maxAttachments: 2 },
      },
      video: {
        maxChars: 500,
      },
    },
  },
}

Recommended Providers

상황에 맞는 최적의 모델을 선택해 보세요.

• Image: openai/gpt-5.2, anthropic/claude-opus-4-6
• Audio: openai/gpt-4o-mini-transcribe, groq/whisper-large-v3-turbo
• Video: google/gemini-3-flash-preview, google/gemini-3-pro-preview
• CLI Fallback: whisper-cli (오디오), gemini CLI (비디오/오디오)

문제 해결

• 미디어 파일이 maxBytes 제한을 넘어가면 해당 모델은 건너뛰고 리스트에 있는 다음 모델을 시도해요.
• 모델이 반환한 텍스트가 maxChars보다 길면 설정된 길이에 맞춰 내용이 자동으로 잘려요.
• 미디어 이해 과정에서 오류가 발생해도 응답 파이프라인은 멈추지 않고 원본 파일과 함께 계속 실행돼요.
• 설정된 모델이 없으면 OpenClaw가 로컬에 설치된 CLI나 사용 가능한 Provider 키를 자동으로 감지해 사용해요.

도움이 필요하다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Configuration
• Image & Media Support