미디어 이해

OpenClaw은 응답 파이프라인이 실행되기 전에 수신 미디어(이미지/오디오/비디오)를 요약할 수 있으므로, 명령어 구문 분석과 라우팅이 원시 바이트 대신 짧은 텍스트를 기반으로 작동합니다. 이해 기능은 로컬 도구 또는 제공업체 키를 자동으로 감지하며, 명시적으로 모델을 구성할 수도 있습니다. 원본 미디어는 항상 평소와 같이 모델에 전달됩니다. 이해 기능이 실패하거나 비활성화되어도 응답 흐름은 변경 없이 계속됩니다.

공급업체 Plugin은 기능 메타데이터(어떤 제공업체가 어떤 미디어 유형을 지원하는지, 기본 모델, 우선순위)를 등록합니다. OpenClaw 코어는 공유 tools.media 구성, 폴백 순서, 응답 파이프라인 통합을 담당합니다.

작동 방식

구성

tools.media에는 공유 모델 목록과 기능별 재정의가 포함됩니다.

{  tools: {    media: {      concurrency: 2, // max concurrent capability runs (default)      models: [/* shared list, gate with capabilities */],      image: {/* optional overrides */},      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* optional overrides */},    },  },}

기능별(image/audio/video) 키:

Deepgram 전용 옵션은 providerOptions.deepgram 아래에 지정합니다(최상위 deepgram: { detectLanguage, punctuate, smartFormat } 필드는 더 이상 권장되지 않지만 여전히 읽습니다).

모델 항목

각 models[] 항목은 제공업체 항목(기본값) 또는 CLI 항목입니다.

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

제공업체 자격 증명

제공업체 미디어 이해 기능은 일반 모델 호출과 동일한 인증 확인 순서를 사용합니다. 인증 프로필, 환경 변수, models.providers.<providerId>.apiKey 순입니다. tools.media.*.models[] 항목에는 인라인 apiKey 필드를 사용할 수 없습니다.

{  models: {    providers: {      openai: { apiKey: "<OPENAI_API_KEY>" },      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },    },  },}

프로필, 환경 변수, 사용자 지정 기본 URL은 도구 및 사용자 지정 제공업체를 참조하세요.

규칙 및 동작

• maxBytes를 초과하는 미디어는 해당 모델을 건너뛰고 다음 모델을 시도합니다.
• 1024바이트 미만의 오디오 파일은 비어 있거나 손상된 것으로 간주하여 전사 전에 건너뜁니다. 대신 에이전트에는 결정론적 자리표시자 전사문이 전달됩니다.
• 활성 기본 이미지 모델이 이미 비전을 기본 지원하면 OpenClaw은 [Image] 요약 블록을 생략하고 원본 이미지를 모델에 직접 전달합니다. MiniMax는 예외입니다. 기존 MiniMax M2.x 채팅 메타데이터가 이미지 입력을 지원한다고 표시하더라도 minimax, minimax-cn, minimax-portal, minimax-portal-cn은 항상 Plugin이 소유한 MiniMax-VL-01 미디어 제공업체를 통해 이미지 이해를 라우팅합니다(MiniMax-M3 이상만 비전을 기본 지원하는 것으로 취급합니다).
• Gateway/WebChat 기본 모델이 텍스트 전용이면 이미지 첨부 파일을 오프로딩된 media://inbound/* 참조로 보존합니다. 따라서 첨부 파일을 잃지 않고 이미지/PDF 도구나 구성된 이미지 모델에서 계속 검사할 수 있습니다.
• 명시적 openclaw infer image describe --file <path> --model <provider/model>(별칭: openclaw capability image describe)은 이미지 기능을 지원하는 해당 제공업체/모델을 직접 실행합니다. models.providers.ollama.models[] 아래에 일치하는 이미지 지원 모델이 구성되어 있으면 ollama/qwen2.5vl:7b 같은 Ollama 참조도 포함됩니다.
• <capability>.enabled가 false가 아니지만 구성된 모델이 없으면 OpenClaw은 활성 응답 모델의 제공업체가 해당 기능을 지원할 때 그 모델을 시도합니다.

자동 감지(기본값)

tools.media.<capability>.enabled가 false가 아니고 구성된 모델이 없으면 OpenClaw은 다음 순서로 시도하고, 처음 작동하는 옵션에서 중단합니다.

기능의 자동 감지를 비활성화하려면 다음과 같이 설정합니다.

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

프록시 지원(오디오/비디오 제공업체 호출)

제공업체 기반 오디오 및 비디오 이해 기능은 NO_PROXY/no_proxy 우회 규칙을 포함한 표준 아웃바운드 프록시 환경 변수 HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy를 따릅니다. 소문자 변수가 대문자 변수보다 우선합니다. 아무것도 설정되지 않으면 미디어 이해 기능은 직접 송신을 사용합니다. 프록시 값의 형식이 잘못된 경우 OpenClaw은 경고를 기록하고 직접 가져오기로 폴백합니다. 이미지 이해 기능은 이 프록시 경로를 사용하지 않습니다.

기능

models[] 항목에 capabilities를 설정하여 특정 미디어 유형으로 제한합니다. 공유 목록에서는 OpenClaw이 번들 제공업체별 기본값을 추론합니다.

CLI 항목에서는 예상치 못한 일치를 방지하도록 capabilities를 명시적으로 설정하세요. 생략하면 해당 항목이 표시되는 모든 기능 목록의 대상이 됩니다.

제공자 지원 매트릭스

모델 선택 지침

• 품질과 안전이 중요할 때는 각 미디어 기능에 가장 강력한 최신 세대 모델을 우선 사용하세요.
• 신뢰할 수 없는 입력을 처리하는 도구 지원 에이전트에는 오래되거나 성능이 낮은 미디어 모델을 사용하지 마세요.
• 가용성을 위해 기능별로 하나 이상의 대체 모델을 유지하세요(고품질 모델 + 더 빠르거나 저렴한 모델).
• CLI 대체 수단(whisper-cli, whisper, gemini)은 제공자 API를 사용할 수 없을 때 유용합니다.
• 알려진 파일 출력 모드가 최종 기준입니다. 추론된 변환 결과 파일이 비어 있거나 없으면 CLI 진행률 출력으로 대체하지 않고 변환 결과를 생성하지 않습니다.
• parakeet-mlx: --output-dir 및 기본 {filename} 출력 템플릿과 함께 --output-format txt(또는 all)를 사용하세요. 업스트림 PARAKEET_OUTPUT_FORMAT 및 PARAKEET_OUTPUT_TEMPLATE 환경 변수도 적용됩니다. OpenClaw는 <output-dir>/<media-basename>.txt를 읽습니다. 기본 srt 형식, 기타 형식 및 사용자 지정 출력 템플릿은 계속 표준 출력을 사용합니다.

첨부 파일 정책

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

mode: "all"이면 출력에 [이미지 1/2], [오디오 2/2] 등의 레이블이 지정됩니다.

파일 첨부 내용 추출

• 추출된 파일 텍스트는 미디어 프롬프트에 추가되기 전에 신뢰할 수 없는 외부 콘텐츠로 감싸집니다. <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> 같은 경계 마커와 출처: 외부 메타데이터 줄을 사용합니다.
• 이 경로에서는 미디어 프롬프트를 짧게 유지하기 위해 긴 보안 알림: 배너를 의도적으로 생략합니다. 경계 마커와 메타데이터는 계속 적용됩니다.
• 추출할 수 있는 텍스트가 없는 파일에는 [추출 가능한 텍스트 없음]이 사용됩니다.
• PDF가 렌더링된 페이지 이미지로 대체되면 OpenClaw는 해당 이미지를 비전 지원 응답 모델로 전달하고 파일 블록에 [PDF 콘텐츠가 이미지로 렌더링됨] 자리표시자를 유지합니다.

구성 예시

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

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

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

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

📎 미디어: 이미지 정상 (openai/gpt-5.6-sol) · 오디오 정상 (whisper-cli 관측됨=metal)

사전 점검 인벤토리를 확인하려면 openclaw capability audio providers를 실행하세요. 로컬 행은 전역 제공자 선택, 준비 상태, 그리고 구분된 지원 가능/요청됨/관측됨 백엔드 필드와 별도로 로컬 대체 수단의 우선 선택 항목을 표시합니다. 동일한 로컬 선택 사항은 정보성 doctor 결과로도 확인할 수 있습니다.

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

참고

• 이해 기능은 최선형으로 동작합니다. 오류가 발생해도 응답을 차단하지 않습니다.
• 이해 기능이 비활성화되어 있어도 첨부 파일은 모델에 계속 전달됩니다.
• scope를 사용하여 이해 기능이 실행되는 위치를 제한하세요(예: DM에서만 실행).

관련 문서

• 구성
• 이미지 및 미디어 지원