메인 콘텐츠로 건너뛰기
OpenClaw는 응답 파이프라인이 실행되기 전에 인바운드 미디어를 요약(이미지/오디오/동영상)할 수 있습니다. 로컬 도구나 공급자 키를 사용할 수 있는지 자동으로 감지하며, 비활성화하거나 사용자 지정할 수 있습니다. 이해 기능이 꺼져 있어도 모델은 평소처럼 원본 파일/URL을 받습니다. 벤더별 미디어 동작은 벤더 Plugin에서 등록하고, OpenClaw core는 공유 tools.media 구성, 폴백 순서, 응답 파이프라인 통합을 담당합니다.

​
목표

  • 선택 사항: 더 빠른 라우팅과 더 나은 명령 파싱을 위해 인바운드 미디어를 짧은 텍스트로 미리 요약합니다.
  • 모델로 원본 미디어 전달을 보존합니다(항상).
  • 공급자 API와 CLI 폴백을 지원합니다.
  • 순서가 있는 폴백으로 여러 모델을 허용합니다(오류/크기/시간 초과).

​
상위 수준 동작

1

첨부 파일 수집

인바운드 첨부 파일(MediaPaths, MediaUrls, MediaTypes)을 수집합니다.
2

기능별 선택

활성화된 각 기능(이미지/오디오/동영상)에 대해 정책에 따라 첨부 파일을 선택합니다(기본값: 첫 번째).
3

모델 선택

첫 번째 적격 모델 항목을 선택합니다(크기 + 기능 + 인증).
4

실패 시 폴백

모델이 실패하거나 미디어가 너무 크면 다음 항목으로 폴백합니다.
5

성공 블록 적용

성공 시:
  • Body는 [Image], [Audio] 또는 [Video] 블록이 됩니다.
  • 오디오는 {{Transcript}}를 설정합니다. 명령 파싱은 캡션 텍스트가 있으면 그것을 사용하고, 없으면 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 오디오 옵션
    • 오디오 transcript echo 제어(echoTranscript, 기본값 false; echoFormat)
    • 선택적 기능별 models 목록(공유 모델보다 우선)
    • attachments 정책(mode, maxAttachments, prefer)
    • scope(channel/chatType/session key별 선택적 게이팅)
  • tools.media.concurrency: 최대 동시 기능 실행 수(기본값 2).
{
  tools: {
    media: {
      models: [
        /* shared list */
      ],
      image: {
        /* optional overrides */
      },
      audio: {
        /* optional overrides */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* optional overrides */
      },
    },
  },
}

​
모델 항목

각 models[] 항목은 공급자 또는 CLI일 수 있습니다. 
{
  type: "provider", // default if omitted
  provider: "openai",
  model: "gpt-5.5",
  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",
}

​
공급자 자격 증명(apiKey)

공급자 미디어 이해 기능은 일반 모델 호출과 동일한 공급자 인증 확인을 사용합니다. 인증 프로필, 환경 변수, 그리고 models.providers.<providerId>.apiKey 순서입니다. tools.media.*.models[] 항목은 인라인 apiKey 필드를 허용하지 않습니다. 미디어 모델 항목의 provider 값(예: openai 또는 moonshot)에는 표준 공급자 인증 소스 중 하나를 통해 사용할 수 있는 자격 증명이 있어야 합니다. 최소 예시: 
{
  models: {
    providers: {
      openai: { apiKey: "<OPENAI_API_KEY>" },
      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },
    },
  },
}
프로필, 환경 변수, 사용자 지정 base URL을 포함한 전체 공급자 인증 참조는 도구 및 사용자 지정 공급자를 참조하세요.

​
기본값 및 제한

권장 기본값:
  • maxChars: 이미지/동영상은 500(짧고 명령 친화적)
  • maxChars: 오디오는 설정 안 함(제한을 설정하지 않는 한 전체 transcript)
  • maxBytes:
    • 이미지: 10MB
    • 오디오: 20MB
    • 동영상: 50MB
  • 미디어가 maxBytes를 초과하면 해당 모델을 건너뛰고 다음 모델을 시도합니다.
  • 1024바이트보다 작은 오디오 파일은 비어 있거나 손상된 것으로 처리되어 공급자/CLI transcription 전에 건너뜁니다. 인바운드 응답 컨텍스트는 결정적인 placeholder transcript를 받아 에이전트가 노트가 너무 작았음을 알 수 있습니다.
  • 모델이 maxChars보다 많은 내용을 반환하면 출력이 잘립니다.
  • prompt는 간단한 “Describe the .”와 maxChars 안내로 기본 설정됩니다(이미지/동영상만).
  • 활성 기본 이미지 모델이 이미 vision을 네이티브로 지원하면 OpenClaw는 [Image] 요약 블록을 건너뛰고 원본 이미지를 모델에 대신 전달합니다.
  • Gateway/WebChat 기본 모델이 텍스트 전용이면 이미지 첨부 파일은 오프로드된 media://inbound/* 참조로 보존되어 첨부 파일을 잃지 않고 이미지/PDF 도구 또는 구성된 이미지 모델이 계속 검사할 수 있습니다.
  • 명시적인 openclaw infer image describe --model <provider/model> 요청은 다릅니다. 이 요청은 ollama/qwen2.5vl:7b 같은 Ollama 참조를 포함하여 해당 이미지 지원 공급자/모델을 직접 실행합니다.
  • <capability>.enabled: true이지만 모델이 구성되지 않은 경우, OpenClaw는 공급자가 해당 기능을 지원하면 활성 응답 모델을 시도합니다.

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

tools.media.<capability>.enabled가 false로 설정되어 있지 않고 모델을 구성하지 않았다면, OpenClaw는 다음 순서로 자동 감지하고 첫 번째로 작동하는 옵션에서 중지합니다.
1

활성 응답 모델

공급자가 해당 기능을 지원할 때의 활성 응답 모델입니다.
2

agents.defaults.imageModel

agents.defaults.imageModel 기본/폴백 참조(이미지만). provider/model 참조를 선호합니다. bare 참조는 일치 항목이 고유할 때만 구성된 이미지 지원 공급자 모델 항목에서 한정됩니다.
3

로컬 CLI(오디오만)

로컬 CLI(설치된 경우):
  • sherpa-onnx-offline(encoder/decoder/joiner/tokens가 포함된 SHERPA_ONNX_MODEL_DIR 필요)
  • whisper-cli(whisper-cpp; WHISPER_CPP_MODEL 또는 번들 tiny 모델 사용)
  • whisper(Python CLI; 모델을 자동으로 다운로드)
4

Gemini CLI

read_many_files를 사용하는 gemini.
5

공급자 인증

  • 기능을 지원하는 구성된 models.providers.* 항목은 번들 폴백 순서보다 먼저 시도됩니다.
  • 이미지 지원 모델이 있는 이미지 전용 구성 공급자는 번들 벤더 Plugin이 아니어도 미디어 이해 기능에 자동 등록됩니다.
  • Ollama 이미지 이해 기능은 명시적으로 선택한 경우 사용할 수 있습니다. 예를 들어 agents.defaults.imageModel 또는 openclaw infer image describe --model ollama/<vision-model>을 통해 사용할 수 있습니다.
번들 폴백 순서:
  • 오디오: OpenAI → Groq → xAI → Deepgram → OpenRouter → Google → SenseAudio → ElevenLabs → Mistral
  • 이미지: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
  • 동영상: Google → Qwen → Moonshot
자동 감지를 비활성화하려면 다음을 설정하세요. 
{
  tools: {
    media: {
      audio: {
        enabled: false,
      },
    },
  },
}
바이너리 감지는 macOS/Linux/Windows 전반에서 최선 노력 방식입니다. CLI가 PATH에 있는지 확인하거나(~를 확장함), 전체 명령 경로가 있는 명시적 CLI 모델을 설정하세요.

​
프록시 환경 지원(공급자 모델)

공급자 기반 오디오 및 동영상 미디어 이해 기능이 활성화되면, OpenClaw는 공급자 HTTP 호출에 대해 표준 아웃바운드 프록시 환경 변수를 준수합니다.
  • HTTPS_PROXY
  • HTTP_PROXY
  • ALL_PROXY
  • https_proxy
  • http_proxy
  • all_proxy
프록시 환경 변수가 설정되지 않은 경우 미디어 이해 기능은 직접 egress를 사용합니다. 프록시 값 형식이 잘못된 경우 OpenClaw는 경고를 기록하고 직접 fetch로 폴백합니다.

​
기능(선택 사항)

capabilities를 설정하면 해당 항목은 그 미디어 유형에 대해서만 실행됩니다. 공유 목록의 경우 OpenClaw는 기본값을 추론할 수 있습니다.
  • openai, anthropic, minimax: 이미지
  • minimax-portal: 이미지
  • moonshot: 이미지 + 동영상
  • openrouter: 이미지 + 오디오
  • google(Gemini API): 이미지 + 오디오 + 동영상
  • qwen: 이미지 + 동영상
  • mistral: 오디오
  • zai: 이미지
  • groq: 오디오
  • xai: 오디오
  • deepgram: 오디오
  • 이미지 지원 모델이 있는 모든 models.providers.<id>.models[] 카탈로그: 이미지
CLI 항목의 경우 예상치 못한 일치를 피하려면 capabilities를 명시적으로 설정하세요. capabilities를 생략하면 해당 항목은 자신이 나타나는 목록에 적격합니다.

​
공급자 지원 매트릭스(OpenClaw 통합)

기능공급자 통합참고
이미지OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, 구성 공급자벤더 Plugin이 이미지 지원을 등록합니다. openai/*는 API 키 또는 Codex OAuth 라우팅을 사용할 수 있습니다. codex/*는 제한된 Codex app-server 턴을 사용합니다. MiniMax와 MiniMax OAuth는 둘 다 MiniMax-VL-01을 사용합니다. 이미지 지원 구성 공급자는 자동 등록됩니다.
오디오OpenAI, Groq, xAI, Deepgram, OpenRouter, Google, SenseAudio, ElevenLabs, Mistral공급자 transcription(Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral).
동영상Google, Qwen, Moonshot벤더 Plugin을 통한 공급자 동영상 이해 기능입니다. Qwen 동영상 이해 기능은 Standard DashScope 엔드포인트를 사용합니다.
MiniMax 참고
  • minimax, minimax-cn, minimax-portal, minimax-portal-cn의 이미지 이해는 Plugin 소유 MiniMax-VL-01 미디어 제공자에서 제공됩니다.
  • 자동 이미지 라우팅은 레거시 MiniMax M2.x 채팅 메타데이터가 이미지 입력을 지원한다고 표시하더라도 계속 MiniMax-VL-01을 사용합니다.

​
모델 선택 가이드

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

​
첨부 파일 정책

기능별 attachments는 처리할 첨부 파일을 제어합니다.
​
mode
"first" | "all"
기본값:"first"
첫 번째로 선택된 첨부 파일을 처리할지, 아니면 모두 처리할지 여부입니다.
​
maxAttachments
number
기본값:"1"
처리할 개수를 제한합니다.
​
prefer
"first" | "last" | "path" | "url"
후보 첨부 파일 중 선택 선호도입니다.
mode: "all"일 때 출력은 [Image 1/2], [Audio 2/2] 등으로 라벨이 붙습니다.
  • 추출된 파일 텍스트는 미디어 프롬프트에 추가되기 전에 신뢰할 수 없는 외부 콘텐츠로 래핑됩니다.
  • 삽입된 블록은 <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> 같은 명시적 경계 표시자를 사용하며 Source: External 메타데이터 줄을 포함합니다.
  • 이 첨부 파일 추출 경로는 미디어 프롬프트가 지나치게 커지는 것을 피하기 위해 긴 SECURITY NOTICE: 배너를 의도적으로 생략합니다. 경계 표시자와 메타데이터는 그대로 유지됩니다.
  • 파일에 추출 가능한 텍스트가 없으면 OpenClaw는 [No extractable text]를 삽입합니다.
  • 이 경로에서 PDF가 렌더링된 페이지 이미지로 대체되면 OpenClaw는 해당 페이지 이미지를 비전 지원 답변 모델로 전달하고 파일 블록에는 자리표시자 [PDF content rendered to images]를 유지합니다.

​
설정 예시

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.5", 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,
      },
    },
  },
}

​
상태 출력

미디어 이해가 실행되면 /status에 짧은 요약 줄이 포함됩니다. 
📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)
이는 기능별 결과와 적용 가능한 경우 선택된 제공자/모델을 보여줍니다.

​
참고

  • 이해는 최선의 노력으로 수행됩니다. 오류가 답변을 차단하지 않습니다.
  • 이해가 비활성화된 경우에도 첨부 파일은 계속 모델에 전달됩니다.
  • 이해가 실행되는 위치를 제한하려면 scope를 사용하세요(예: DM만).

​
관련 항목