​

Hiểu Nội Dung Media - Đầu Vào (2026-01-17)

​

Mục tiêu

• Tùy chọn: xử lý trước media đầu vào thành văn bản ngắn để định tuyến nhanh hơn và phân tích lệnh tốt hơn.
• Bảo toàn việc chuyển giao media gốc cho mô hình (luôn luôn).
• Hỗ trợ API của nhà cung cấp và CLI dự phòng.
• Cho phép nhiều mô hình với thứ tự dự phòng (lỗi/kích thước/hết thời gian).

​

Hành vi tổng quan

1. Thu thập tệp đính kèm đầu vào (MediaPaths, MediaUrls, MediaTypes).
2. Với mỗi khả năng được bật (hình ảnh/âm thanh/video), chọn tệp đính kèm theo chính sách (mặc định: đầu tiên).
3. Chọn mục nhập mô hình đủ điều kiện đầu tiên (kích thước + khả năng + xác thực).
4. Nếu một mô hình thất bại hoặc media quá lớn, chuyển sang mục nhập tiếp theo.
5. Khi thành công:
   • Body trở thành khối [Image], [Audio], hoặc [Video].
   • Âm thanh thiết lập {{Transcript}}; phân tích lệnh sử dụng văn bản chú thích khi có, nếu không thì dùng bản ghi.
   • Chú thích được giữ lại dưới dạng User text: bên trong khối.

​

Tổng quan cấu hình

• tools.media.models: danh sách mô hình chia sẻ (sử dụng capabilities để giới hạn).
• tools.media.image / tools.media.audio / tools.media.video:
  • mặc định (prompt, maxChars, maxBytes, timeoutSeconds, language)
  • ghi đè của nhà cung cấp (baseUrl, headers, providerOptions)
  • tùy chọn âm thanh Deepgram qua tools.media.audio.providerOptions.deepgram
  • kiểm soát echo bản ghi âm thanh (echoTranscript, mặc định false; echoFormat)
  • danh sách mô hình theo khả năng tùy chọn (ưu tiên trước mô hình chia sẻ)
  • chính sách attachments (mode, maxAttachments, prefer)
  • scope (giới hạn tùy chọn theo kênh/loại chat/khóa phiên)
• tools.media.concurrency: số lượng khả năng chạy đồng thời tối đa (mặc định 2).

{
  tools: {
    media: {
      models: [
        /* danh sách chia sẻ */
      ],
      image: {
        /* ghi đè tùy chọn */
      },
      audio: {
        /* ghi đè tùy chọn */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* ghi đè tùy chọn */
      },
    },
  },
}

​

Mục nhập mô hình

{
  type: "provider", // mặc định nếu không có
  provider: "openai",
  model: "gpt-5.2",
  prompt: "Mô tả hình ảnh trong <= 500 ký tự.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // tùy chọn, dùng cho mục nhập đa phương thức
  profile: "vision-profile",
  preferredProfile: "vision-fallback",
}

{
  type: "cli",
  command: "gemini",
  args: [
    "-m",
    "gemini-3-flash",
    "--allowed-tools",
    "read_file",
    "Đọc media tại {{MediaPath}} và mô tả nó trong <= {{MaxChars}} ký tự.",
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"],
}

• {{MediaDir}} (thư mục chứa file media)
• {{OutputDir}} (thư mục tạm tạo cho lần chạy này)
• {{OutputBase}} (đường dẫn cơ sở file tạm, không có phần mở rộng)

​

Mặc định và giới hạn

• maxChars: 500 cho hình ảnh/video (ngắn, thân thiện với lệnh)
• maxChars: không đặt cho âm thanh (bản ghi đầy đủ trừ khi bạn đặt giới hạn)
• maxBytes:
  • hình ảnh: 10MB
  • âm thanh: 20MB
  • video: 50MB

• Nếu media vượt quá maxBytes, mô hình đó bị bỏ qua và mô hình tiếp theo được thử.
• File âm thanh nhỏ hơn 1024 byte được coi là trống/hỏng và bị bỏ qua trước khi chuyển đổi của provider/CLI.
• Nếu mô hình trả về nhiều hơn maxChars, đầu ra sẽ bị cắt ngắn.
• prompt mặc định là “Mô tả .” đơn giản cùng với hướng dẫn maxChars (chỉ hình ảnh/video).
• Nếu <capability>.enabled: true nhưng không có mô hình nào được cấu hình, OpenClaw thử mô hình trả lời đang hoạt động khi nhà cung cấp của nó hỗ trợ khả năng đó.

​

Tự động phát hiện hiểu media (mặc định)

1. CLI cục bộ (chỉ âm thanh; nếu đã cài đặt)
   • sherpa-onnx-offline (yêu cầu SHERPA_ONNX_MODEL_DIR với encoder/decoder/joiner/tokens)
   • whisper-cli (whisper-cpp; sử dụng WHISPER_CPP_MODEL hoặc mô hình nhỏ đi kèm)
   • whisper (Python CLI; tự động tải xuống mô hình)
2. Gemini CLI (gemini) sử dụng read_many_files
3. Khóa provider
   • Âm thanh: OpenAI → Groq → Deepgram → Google
   • Hình ảnh: OpenAI → Anthropic → Google → MiniMax
   • Video: Google

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

​

Hỗ trợ môi trường proxy (mô hình provider)

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

Khả năng (tùy chọn)

• openai, anthropic, minimax: hình ảnh
• moonshot: hình ảnh + video
• google (Gemini API): hình ảnh + âm thanh + video
• mistral: âm thanh
• zai: hình ảnh
• groq: âm thanh
• deepgram: âm thanh

​

Ma trận hỗ trợ provider (tích hợp OpenClaw)

​

Hướng dẫn chọn mô hình

• Ưu tiên mô hình thế hệ mới mạnh nhất có sẵn cho mỗi khả năng media khi chất lượng và an toàn quan trọng.
• Đối với các agent có công cụ xử lý đầu vào không đáng tin cậy, tránh các mô hình media cũ/yếu hơn.
• Giữ ít nhất một dự phòng cho mỗi khả năng để đảm bảo khả dụng (mô hình chất lượng + mô hình nhanh hơn/rẻ hơn).
• CLI dự phòng (whisper-cli, whisper, gemini) hữu ích khi API của provider không khả dụng.
• Lưu ý parakeet-mlx: với --output-dir, OpenClaw đọc <output-dir>/<media-basename>.txt khi định dạng đầu ra là txt (hoặc không xác định); các định dạng không phải txt quay lại stdout.

​

Chính sách tệp đính kèm

• mode: first (mặc định) hoặc all
• maxAttachments: giới hạn số lượng được xử lý (mặc định 1)
• prefer: first, last, path, url

​

Ví dụ cấu hình

​

1) Danh sách mô hình chia sẻ + ghi đè

{
  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",
            "Đọc media tại {{MediaPath}} và mô tả nó trong <= {{MaxChars}} ký tự.",
          ],
          capabilities: ["image", "video"],
        },
      ],
      audio: {
        attachments: { mode: "all", maxAttachments: 2 },
      },
      video: {
        maxChars: 500,
      },
    },
  },
}

​

2) Chỉ Âm thanh + Video (tắt hình ảnh)

{
  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",
              "Đọc media tại {{MediaPath}} và mô tả nó trong <= {{MaxChars}} ký tự.",
            ],
          },
        ],
      },
    },
  },
}

​

3) Hiểu hình ảnh tùy chọn

{
  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",
              "Đọc media tại {{MediaPath}} và mô tả nó trong <= {{MaxChars}} ký tự.",
            ],
          },
        ],
      },
    },
  },
}

​

4) Mục nhập đơn đa phương thức (khả năng rõ ràng)

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

​

Kết quả trạng thái

📎 Media: hình ảnh ok (openai/gpt-5.2) · âm thanh bị bỏ qua (maxBytes)

​

Ghi chú

• Hiểu là nỗ lực tốt nhất. Lỗi không chặn trả lời.
• Tệp đính kèm vẫn được chuyển đến mô hình ngay cả khi hiểu bị tắt.
• Sử dụng scope để giới hạn nơi hiểu chạy (ví dụ: chỉ DMs).

​

Tài liệu liên quan

• Cấu hình
• Hỗ trợ Hình ảnh & Media