Nodes and media

미디어 이해

OpenClaw는 응답 파이프라인이 실행되기 전에 인바운드 미디어를 요약(이미지/오디오/동영상)할 수 있습니다. 로컬 도구나 공급자 키를 사용할 수 있는지 자동으로 감지하며, 비활성화하거나 사용자 지정할 수 있습니다. 이해 기능이 꺼져 있어도 모델은 평소처럼 원본 파일/URL을 받습니다.

벤더별 미디어 동작은 벤더 Plugin에서 등록하고, OpenClaw core는 공유 tools.media 구성, 폴백 순서, 응답 파이프라인 통합을 담당합니다.

목표

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

상위 수준 동작

첨부 파일 수집

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

기능별 선택

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

모델 선택

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

실패 시 폴백

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

성공 블록 적용

성공 시:

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).

json5

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

모델 항목

각 models[] 항목은 공급자 또는 CLI일 수 있습니다.

공급자 항목

json5

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

CLI 항목

json5

{  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}}(확장자가 없는 스크래치 파일 기본 경로)

공급자 자격 증명(`apiKey`)

공급자 미디어 이해 기능은 일반 모델 호출과 동일한 공급자 인증 확인을 사용합니다. 인증 프로필, 환경 변수, 그리고 models.providers.<providerId>.apiKey 순서입니다.

tools.media.*.models[] 항목은 인라인 apiKey 필드를 허용하지 않습니다. 미디어 모델 항목의 provider 값(예: openai 또는 moonshot)에는 표준 공급자 인증 소스 중 하나를 통해 사용할 수 있는 자격 증명이 있어야 합니다.

최소 예시:

json5

{  models: {    providers: {      openai: { apiKey: "&lt;OPENAI_API_KEY&gt;" },      moonshot: { apiKey: "&lt;MOONSHOT_API_KEY&gt;" },    },  },}

프로필, 환경 변수, 사용자 지정 base URL을 포함한 전체 공급자 인증 참조는 도구 및 사용자 지정 공급자를 참조하세요.

기본값 및 제한

권장 기본값:

maxChars: 이미지/동영상은 500(짧고 명령 친화적)
maxChars: 오디오는 설정 안 함(제한을 설정하지 않는 한 전체 transcript)
maxBytes:
- 이미지: 10MB
- 오디오: 20MB
- 동영상: 50MB

규칙

미디어가 maxBytes를 초과하면 해당 모델을 건너뛰고 다음 모델을 시도합니다.
1024바이트보다 작은 오디오 파일은 비어 있거나 손상된 것으로 처리되어 공급자/CLI transcription 전에 건너뜁니다. 인바운드 응답 컨텍스트는 결정적인 placeholder transcript를 받아 에이전트가 노트가 너무 작았음을 알 수 있습니다.
모델이 maxChars보다 많은 내용을 반환하면 출력이 잘립니다.
prompt는 간단한 "Describe the {media}."와 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는 다음 순서로 자동 감지하고 첫 번째로 작동하는 옵션에서 중지합니다.

활성 응답 모델

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

agents.defaults.imageModel

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

로컬 CLI(오디오만)

로컬 CLI(설치된 경우):

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

Gemini CLI

read_many_files를 사용하는 gemini.

공급자 인증

기능을 지원하는 구성된 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

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

json5

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

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

공급자 기반 오디오 및 동영상 미디어 이해 기능이 활성화되면, 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 엔드포인트를 사용합니다.

모델 선택 가이드

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

첨부 파일 정책

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

mode"first" | "all"default: first

첫 번째로 선택된 첨부 파일을 처리할지, 아니면 모두 처리할지 여부입니다.

maxAttachmentsnumberdefault: 1

처리할 개수를 제한합니다.

prefer"first" | "last" | "path" | "url"

후보 첨부 파일 중 선택 선호도입니다.

mode: "all"일 때 출력은 [Image 1/2], [Audio 2/2] 등으로 라벨이 붙습니다.

File-attachment extraction behavior

추출된 파일 텍스트는 미디어 프롬프트에 추가되기 전에 신뢰할 수 없는 외부 콘텐츠로 래핑됩니다.
삽입된 블록은 <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> 같은 명시적 경계 표시자를 사용하며 Source: External 메타데이터 줄을 포함합니다.
이 첨부 파일 추출 경로는 미디어 프롬프트가 지나치게 커지는 것을 피하기 위해 긴 SECURITY NOTICE: 배너를 의도적으로 생략합니다. 경계 표시자와 메타데이터는 그대로 유지됩니다.
파일에 추출 가능한 텍스트가 없으면 OpenClaw는 [No extractable text]를 삽입합니다.
이 경로에서 PDF가 렌더링된 페이지 이미지로 대체되면 OpenClaw는 해당 페이지 이미지를 비전 지원 답변 모델로 전달하고 파일 블록에는 자리표시자 [PDF content rendered to images]를 유지합니다.

설정 예시

Shared models + overrides

json5

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

Audio + video only

json5

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

Image-only

json5

{  tools: {    media: {      image: {        enabled: true,        maxBytes: 10485760,        maxChars: 500,        models: [          { provider: "openai", model: "gpt-5.5" },          { 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.",            ],          },        ],      },    },  },}

Multi-modal single entry

json5

{  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에 짧은 요약 줄이 포함됩니다.

Code

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

이는 기능별 결과와 적용 가능한 경우 선택된 제공자/모델을 보여줍니다.

참고

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

미디어 이해

목표

상위 수준 동작

첨부 파일 수집

기능별 선택

모델 선택

실패 시 폴백

성공 블록 적용

구성 개요

모델 항목

공급자 항목

CLI 항목

공급자 자격 증명(`apiKey`)

기본값 및 제한

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

활성 응답 모델

agents.defaults.imageModel

로컬 CLI(오디오만)

Gemini CLI

공급자 인증

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

기능(선택 사항)

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

모델 선택 가이드

첨부 파일 정책

설정 예시

Shared models + overrides

Audio + video only

Image-only

Multi-modal single entry

상태 출력

참고

관련 항목

On this page

Molty

목표

상위 수준 동작

첨부 파일 수집

기능별 선택

모델 선택

실패 시 폴백

성공 블록 적용

구성 개요

모델 항목

공급자 항목

CLI 항목

공급자 자격 증명(apiKey)

기본값 및 제한

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

활성 응답 모델

agents.defaults.imageModel

로컬 CLI(오디오만)

Gemini CLI

공급자 인증

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

기능(선택 사항)

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

모델 선택 가이드

첨부 파일 정책

설정 예시

Shared models + overrides

Audio + video only

Image-only

Multi-modal single entry

상태 출력

참고

관련 항목

On this page

공급자 자격 증명(`apiKey`)