​

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

​

목표

• 선택 사항: 더 빠른 라우팅 + 더 나은 명령 파싱을 위해 수신 미디어를 짧은 텍스트로 사전 소화
• 원본 미디어 전달은 항상 모델에 그대로 유지
• provider API와 CLI 대체 경로 지원
• 오류/크기/시간 초과 시 순서가 있는 대체를 포함해 여러 모델 허용

​

상위 수준 동작

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

​

구성 개요

• tools.media.models: 공유 모델 목록(capabilities로 게이팅 가능)
• tools.media.image / tools.media.audio / tools.media.video:
  • 기본값 (prompt, maxChars, maxBytes, timeoutSeconds, language)
  • provider 재정의 (baseUrl, headers, providerOptions)
  • tools.media.audio.providerOptions.deepgram을 통한 Deepgram 오디오 옵션
  • 오디오 transcript echo 제어 (echoTranscript, 기본값 false; echoFormat)
  • 선택적 capability별 models 목록 (공유 모델보다 우선)
  • attachments 정책 (mode, maxAttachments, prefer)
  • scope (채널/chatType/세션 키 기준 선택적 게이팅)
• tools.media.concurrency: 최대 동시 capability 실행 수(기본값 2)

{
  tools: {
    media: {
      models: [
        /* shared list */
      ],
      image: {
        /* optional overrides */
      },
      audio: {
        /* optional overrides */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* optional overrides */
      },
    },
  },
}

​

모델 항목

{
  type: "provider", // default if omitted
  provider: "openai",
  model: "gpt-5.4-mini",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // optional, used for multi‑modal entries
  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"],
}

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

​

기본값과 제한

• maxChars: 이미지/비디오는 500 (짧고 명령 친화적)
• maxChars: 오디오는 미설정 (제한을 설정하지 않으면 전체 transcript)
• maxBytes:
  • 이미지: 10MB
  • 오디오: 20MB
  • 비디오: 50MB

• 미디어가 maxBytes를 초과하면 해당 모델은 건너뛰고 다음 모델을 시도합니다.
• 1024바이트보다 작은 오디오 파일은 비어 있거나 손상된 것으로 간주되어 provider/CLI 전사 전에 건너뜁니다.
• 모델이 maxChars보다 많은 내용을 반환하면 출력이 잘립니다.
• prompt 기본값은 단순한 “Describe the .”에 maxChars 안내를 더한 형태입니다(이미지/비디오 전용).
• 활성 기본 이미지 모델이 이미 네이티브 vision을 지원하면 OpenClaw는 [Image] 요약 블록을 건너뛰고 대신 원본 이미지를 모델에 전달합니다.
• <capability>.enabled: true이지만 구성된 모델이 없으면 OpenClaw는 해당 provider가 capability를 지원할 때 활성 응답 모델을 시도합니다.

​

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

1. provider가 capability를 지원할 때 활성 응답 모델
2. **agents.defaults.imageModel**의 primary/fallback ref (이미지 전용)
3. 로컬 CLI (오디오 전용, 설치된 경우)
   • sherpa-onnx-offline (SHERPA_ONNX_MODEL_DIR에 encoder/decoder/joiner/tokens 필요)
   • whisper-cli (whisper-cpp; WHISPER_CPP_MODEL 또는 번들 tiny 모델 사용)
   • whisper (Python CLI; 모델 자동 다운로드)
4. read_many_files를 사용하는 Gemini CLI (gemini)
5. Provider auth
   • capability를 지원하는 구성된 models.providers.* 항목은 번들 대체 순서보다 먼저 시도됩니다.
   • image-capable 모델을 가진 이미지 전용 config provider는 번들 벤더 plugin이 아니더라도 미디어 이해용으로 자동 등록됩니다.
   • 번들 대체 순서:
     • 오디오: OpenAI → Groq → Deepgram → Google → Mistral
     • 이미지: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
     • 비디오: Google → Qwen → Moonshot

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

​

프록시 환경 지원(provider 모델)

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

Capabilities(선택 사항)

• openai, anthropic, minimax: 이미지
• minimax-portal: 이미지
• moonshot: 이미지 + 비디오
• openrouter: 이미지
• google (Gemini API): 이미지 + 오디오 + 비디오
• qwen: 이미지 + 비디오
• mistral: 오디오
• zai: 이미지
• groq: 오디오
• deepgram: 오디오
• image-capable 모델을 가진 모든 models.providers.<id>.models[] 카탈로그: 이미지

​

Provider 지원 매트릭스(OpenClaw 통합)

• minimax와 minimax-portal 이미지 이해는 plugin 소유의 MiniMax-VL-01 미디어 provider에서 옵니다.
• 번들 MiniMax 텍스트 카탈로그는 여전히 텍스트 전용으로 시작하며, 명시적인 models.providers.minimax 항목이 image-capable M2.7 chat ref를 구체화합니다.

​

모델 선택 가이드

• 품질과 안전성이 중요할 때는 각 미디어 capability에 대해 사용 가능한 가장 강력한 최신 세대 모델을 선호하세요.
• 신뢰할 수 없는 입력을 처리하는 도구 활성 agent의 경우, 오래되었거나 약한 미디어 모델은 피하세요.
• 가용성을 위해 capability별로 적어도 하나의 대체를 유지하세요(고품질 모델 + 더 빠르고 저렴한 모델).
• CLI 대체 경로(whisper-cli, whisper, gemini)는 provider API를 사용할 수 없을 때 유용합니다.
• parakeet-mlx 참고: --output-dir과 함께 사용할 때 출력 형식이 txt(또는 미지정)라면 OpenClaw는 <output-dir>/<media-basename>.txt를 읽습니다. txt가 아닌 형식은 stdout으로 대체됩니다.

​

첨부 파일 정책

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

• 추출된 파일 텍스트는 미디어 프롬프트에 추가되기 전에 신뢰할 수 없는 외부 콘텐츠로 감싸집니다.
• 주입된 블록은 <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> 같은 명시적 경계 마커를 사용하고, Source: External 메타데이터 줄을 포함합니다.
• 이 첨부 파일 추출 경로는 미디어 프롬프트가 비대해지는 것을 피하기 위해 긴 SECURITY NOTICE: 배너를 의도적으로 생략합니다. 대신 경계 마커와 메타데이터는 그대로 유지됩니다.
• 파일에 추출 가능한 텍스트가 없으면 OpenClaw는 [No extractable text]를 주입합니다.
• PDF가 이 경로에서 렌더링된 페이지 이미지로 대체될 경우, 미디어 프롬프트는 [PDF content rendered to images; images not forwarded to model] 플레이스홀더를 유지합니다. 이 첨부 파일 추출 단계는 렌더링된 PDF 이미지가 아니라 텍스트 블록을 전달하기 때문입니다.

​

구성 예시

​

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

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.4-mini", 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.4-mini" },
          { 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) 멀티모달 단일 항목(명시적 capabilities)

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

​

상태 출력

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

​

참고

• 이해 기능은 best-effort입니다. 오류가 응답을 막지는 않습니다.
• 이해 기능이 비활성화되어 있어도 첨부 파일은 여전히 모델에 전달됩니다.
• scope를 사용해 이해 기능이 실행되는 위치를 제한하세요(예: DM에서만).

​

관련 문서

• Configuration
• 이미지 및 미디어 지원