미디어 이해 (수신) — 2026-01-17

OpenClaw는 응답 파이프라인이 실행되기 전에 수신 미디어 (이미지/오디오/비디오)를 요약할 수 있습니다. 로컬 도구나 프로바이더 키가 사용 가능하면 자동으로 감지하며, 비활성화하거나 커스터마이징할 수 있습니다. 이해 기능이 꺼져 있어도 모델은 원본 파일/URL을 그대로 받습니다.

목표

  • 선택 사항: 수신 미디어를 짧은 텍스트로 사전 처리하여 더 빠른 라우팅과 정확한 명령어 파싱을 지원합니다.
  • 모델에 대한 원본 미디어 전달은 항상 보존됩니다.
  • 프로바이더 API와 CLI 폴백을 지원합니다.
  • 순서가 있는 폴백을 통해 여러 모델을 허용합니다 (오류/크기/타임아웃).

상위 수준 동작

  1. 수신 첨부파일 수집 (MediaPaths, MediaUrls, MediaTypes).
  2. 활성화된 각 기능(이미지/오디오/비디오)에 대해 정책에 따라 첨부파일 선택 (기본값: 첫 번째).
  3. 첫 번째 적격 모델 항목 선택 (크기 + 기능 + 인증).
  4. 모델이 실패하거나 미디어가 너무 크면 다음 항목으로 폴백.
  5. 성공 시:
    • Body가 [Image], [Audio] 또는 [Video] 블록이 됩니다.
    • 오디오는 {{Transcript}}를 설정합니다. 캡션 텍스트가 있으면 명령어 파싱에 사용하고, 없으면 변환된 텍스트를 사용합니다.
    • 캡션은 블록 내에 User text:로 보존됩니다.

이해가 실패하거나 비활성화되면, 응답 흐름은 원본 본문 + 첨부파일과 함께 계속됩니다.

설정 개요

tools.media는 공유 모델과 기능별 재정의를 지원합니다:

  • tools.media.models: 공유 모델 목록 (capabilities로 게이팅 가능).
  • tools.media.image / tools.media.audio / tools.media.video:
    • 기본값 (prompt, maxChars, maxBytes, timeoutSeconds, language)
    • 프로바이더 재정의 (baseUrl, headers, providerOptions)
    • tools.media.audio.providerOptions.deepgram을 통한 Deepgram 오디오 옵션
    • 오디오 변환 텍스트 에코 제어 (echoTranscript, 기본값 false; echoFormat)
    • 선택적 기능별 models 목록 (공유 모델보다 우선)
    • attachments 정책 (mode, maxAttachments, prefer)
    • scope (채널/chatType/세션 키별 선택적 게이팅)
  • tools.media.concurrency: 최대 동시 기능 실행 수 (기본값 2).
{
  tools: {
    media: {
      models: [
        /* 공유 목록 */
      ],
      image: {
        /* 선택적 재정의 */
      },
      audio: {
        /* 선택적 재정의 */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* 선택적 재정의 */
      },
    },
  },
}

모델 항목

각 models[] 항목은 프로바이더 또는 CLI일 수 있습니다:

{
  type: "provider", // 생략 시 기본값
  provider: "openai",
  model: "gpt-5.2",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // 선택사항, 멀티모달 항목에 사용
  profile: "vision-profile",
  preferredProfile: "vision-fallback",
}
{
  type: "cli",
  command: "gemini",
  args: [
    "-m",
    "gemini-3-flash",
    "--allowed-tools",
    "read_file",
    "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"],
}

CLI 템플릿에서 사용할 수 있는 추가 변수:

  • {{MediaDir}} (미디어 파일이 있는 디렉토리)
  • {{OutputDir}} (이번 실행을 위해 생성된 스크래치 디렉토리)
  • {{OutputBase}} (확장자 없는 스크래치 파일 기본 경로)

기본값 및 제한

권장 기본값:

  • maxChars: 이미지/비디오의 경우 500 (짧고 명령어 친화적)
  • maxChars: 오디오의 경우 미설정 (제한을 설정하지 않으면 전체 변환 텍스트)
  • maxBytes:
    • 이미지: 10MB
    • 오디오: 20MB
    • 비디오: 50MB

규칙:

  • 미디어가 maxBytes를 초과하면, 해당 모델은 건너뛰고 다음 모델이 시도됩니다.
  • 1024바이트 미만의 오디오 파일은 비어있거나 손상된 것으로 간주하여 프로바이더/CLI 텍스트 변환 전에 건너뜁니다.
  • 모델이 maxChars보다 많은 출력을 반환하면, 출력이 잘립니다.
  • prompt는 간단한 “Describe the {media}.”와 maxChars 안내로 기본 설정됩니다 (이미지/비디오만 해당).
  • <capability>.enabled: true이지만 모델이 구성되지 않은 경우, OpenClaw는 프로바이더가 해당 기능을 지원하면 활성 응답 모델을 시도합니다.

미디어 이해 자동 감지 (기본값)

tools.media.<capability>.enabled가 false로 설정되어 있지 않고 모델을 구성하지 않은 경우, OpenClaw는 다음 순서로 자동 감지하며 첫 번째로 작동하는 옵션에서 멈춥니다:

  1. 로컬 CLI (오디오만; 설치된 경우)
    • sherpa-onnx-offline (SHERPA_ONNX_MODEL_DIR에 encoder/decoder/joiner/tokens 필요)
    • whisper-cli (whisper-cpp; WHISPER_CPP_MODEL 또는 번들된 tiny 모델 사용)
    • whisper (Python CLI; 자동으로 모델 다운로드)
  2. Gemini CLI (gemini) read_many_files 사용
  3. 프로바이더 키
    • 오디오: OpenAI → Groq → Deepgram → Google
    • 이미지: OpenAI → Anthropic → Google → MiniMax
    • 비디오: Google

자동 감지를 비활성화하려면 다음을 설정하세요:

{
  tools: {
    media: {
      audio: {
        enabled: false,
      },
    },
  },
}

참고: 바이너리 감지는 macOS/Linux/Windows에서 최선의 노력으로 수행됩니다. CLI가 PATH에 있는지 확인하세요(~는 확장됨). 또는 전체 명령 경로로 명시적 CLI 모델을 설정하세요.

프록시 환경 지원 (프로바이더 모델)

프로바이더 기반 오디오 및 비디오 미디어 이해가 활성화되면, OpenClaw는 프로바이더 HTTP 호출에 표준 아웃바운드 프록시 환경 변수를 사용합니다:

  • HTTPS_PROXY
  • HTTP_PROXY
  • https_proxy
  • http_proxy

프록시 환경 변수가 설정되지 않으면 직접 연결을 사용합니다. 프록시 값이 잘못되면 OpenClaw는 경고를 기록하고 직접 연결로 폴백합니다.

기능 (선택사항)

capabilities를 설정하면, 해당 항목은 지정된 미디어 유형에서만 실행됩니다. 공유 목록의 경우, OpenClaw는 기본값을 추론할 수 있습니다:

  • openai, anthropic, minimax: 이미지
  • google (Gemini API): 이미지 + 오디오 + 비디오
  • groq: 오디오
  • deepgram: 오디오

CLI 항목의 경우, 예기치 않은 매칭을 방지하기 위해 capabilities를 명시적으로 설정하세요. capabilities를 생략하면, 해당 항목은 소속된 목록에서 적격합니다.

프로바이더 지원 매트릭스 (OpenClaw 통합)

기능프로바이더 통합참고
이미지OpenAI / Anthropic / Google / 기타 pi-ai 통해레지스트리의 이미지 지원 모델 사용 가능.
오디오OpenAI, Groq, Deepgram, Google, Mistral프로바이더 텍스트 변환 (Whisper/Deepgram/Gemini/Voxtral).
비디오Google (Gemini API)프로바이더 비디오 이해.

모델 선택 가이드

  • 품질과 안전이 중요한 경우 각 미디어 기능에 대해 최신 세대의 가장 강력한 모델을 선호하세요.
  • 신뢰할 수 없는 입력을 처리하는 도구 지원 에이전트의 경우, 이전/약한 미디어 모델을 피하세요.
  • 가용성을 위해 기능당 최소 하나의 폴백을 유지하세요 (품질 모델 + 빠르고 저렴한 모델).
  • CLI 폴백 (whisper-cli, whisper, gemini)은 프로바이더 API를 사용할 수 없을 때 유용합니다.
  • parakeet-mlx 참고: --output-dir 사용 시, 출력 형식이 txt(또는 미지정)이면 OpenClaw가 <output-dir>/<media-basename>.txt를 읽습니다. txt가 아닌 형식은 stdout으로 폴백합니다.

첨부파일 정책

기능별 attachments로 처리할 첨부파일을 제어합니다:

  • mode: first (기본값) 또는 all
  • maxAttachments: 처리할 최대 수 (기본값 1)
  • prefer: first, last, path, url

mode: "all"일 때, 출력에 [Image 1/2], [Audio 2/2] 등으로 레이블이 표시됩니다.

설정 예시

1) 공유 모델 목록 + 재정의

{
  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,
      },
    },
  },
}

2) 오디오 + 비디오만 (이미지 비활성화)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
          },
        ],
      },
      video: {
        enabled: true,
        maxChars: 500,
        models: [
          { provider: "google", model: "gemini-3-flash-preview" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

3) 선택적 이미지 이해

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.2" },
          { provider: "anthropic", model: "claude-opus-4-6" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

4) 단일 멀티모달 항목 (명시적 기능)

{
  tools: {
    media: {
      image: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      audio: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      video: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
    },
  },
}

상태 출력

미디어 이해가 실행되면, /status에 짧은 요약 줄이 포함됩니다:

📎 Media: image ok (openai/gpt-5.2) · audio skipped (maxBytes)

기능별 결과와 해당 시 선택된 프로바이더/모델을 보여줍니다.

참고

  • 이해는 최선의 노력입니다. 오류가 응답을 차단하지 않습니다.
  • 이해가 비활성화되어도 첨부파일은 모델에 전달됩니다.
  • scope를 사용하여 이해가 실행되는 범위를 제한할 수 있습니다 (예: DM만).

관련 문서

arrow_back
이전
Troubleshooting
다음
Images
arrow_forward