Nhận hiểu nội dung đa phương tiện

OpenClaw có thể tóm tắt nội dung phương tiện đầu vào (hình ảnh/âm thanh/video) trước khi quy trình phản hồi chạy, nhờ đó việc phân tích lệnh và định tuyến sử dụng văn bản ngắn thay vì các byte thô. Tính năng nhận hiểu tự động phát hiện các công cụ cục bộ hoặc khóa của nhà cung cấp, hoặc bạn có thể cấu hình rõ các mô hình. Phương tiện gốc luôn được chuyển đến mô hình như bình thường; khi quá trình nhận hiểu thất bại hoặc bị tắt, luồng phản hồi vẫn tiếp tục mà không thay đổi.

Các Plugin của nhà cung cấp đăng ký siêu dữ liệu về khả năng (nhà cung cấp nào hỗ trợ loại phương tiện nào, mô hình mặc định, mức ưu tiên). Phần lõi OpenClaw quản lý cấu hình tools.media dùng chung, thứ tự dự phòng và việc tích hợp vào quy trình phản hồi.

Cách hoạt động

Cấu hình

tools.media chứa danh sách mô hình dùng chung cùng các phần ghi đè theo từng khả năng:

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

Các khóa theo từng khả năng (image/audio/video):

Các tùy chọn dành riêng cho Deepgram nằm trong providerOptions.deepgram (trường cấp cao nhất deepgram: { detectLanguage, punctuate, smartFormat } đã lỗi thời nhưng vẫn được đọc).

Các mục mô hình

Mỗi mục models[] là một mục nhà cung cấp (mặc định) hoặc một mục 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"],}

Thông tin xác thực của nhà cung cấp

Tính năng nhận hiểu phương tiện của nhà cung cấp sử dụng cùng cách phân giải xác thực như các lệnh gọi mô hình thông thường: hồ sơ xác thực, biến môi trường, sau đó là models.providers.<providerId>.apiKey. Các mục tools.media.*.models[] không chấp nhận trường apiKey nội tuyến.

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

Xem Công cụ và nhà cung cấp tùy chỉnh để biết về hồ sơ, biến môi trường và URL cơ sở tùy chỉnh.

Quy tắc và hành vi

• Phương tiện vượt quá maxBytes sẽ bỏ qua mô hình đó và thử mô hình tiếp theo.
• Các tệp âm thanh nhỏ hơn 1024 byte được coi là trống/hỏng và bị bỏ qua trước khi chép lời; tác tử sẽ nhận được một bản chép lời giữ chỗ có tính xác định.
• Nếu mô hình hình ảnh chính đang hoạt động đã hỗ trợ thị giác nguyên bản, OpenClaw sẽ bỏ qua khối tóm tắt [Image] và chuyển trực tiếp hình ảnh gốc vào mô hình. MiniMax là một ngoại lệ: minimax, minimax-cn, minimax-portal và minimax-portal-cn luôn định tuyến việc nhận hiểu hình ảnh qua nhà cung cấp phương tiện MiniMax-VL-01 do Plugin quản lý, ngay cả khi siêu dữ liệu trò chuyện MiniMax M2.x cũ tuyên bố hỗ trợ đầu vào hình ảnh (chỉ MiniMax-M3 trở lên được coi là có khả năng thị giác nguyên bản).
• Nếu mô hình chính của Gateway/WebChat chỉ hỗ trợ văn bản, các tệp đính kèm hình ảnh được giữ lại dưới dạng tham chiếu media://inbound/* đã chuyển tải, để các công cụ hình ảnh/PDF hoặc mô hình hình ảnh đã cấu hình vẫn có thể kiểm tra chúng thay vì làm mất tệp đính kèm.
• Lệnh rõ ràng openclaw infer image describe --file <path> --model <provider/model> (bí danh: openclaw capability image describe) chạy trực tiếp nhà cung cấp/mô hình có khả năng xử lý hình ảnh đó, bao gồm các tham chiếu Ollama như ollama/qwen2.5vl:7b khi một mô hình có khả năng xử lý hình ảnh tương ứng được cấu hình trong models.providers.ollama.models[].
• Nếu <capability>.enabled không phải là false nhưng không có mô hình nào được cấu hình, OpenClaw sẽ thử mô hình phản hồi đang hoạt động khi nhà cung cấp của mô hình đó hỗ trợ khả năng này.

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

Khi tools.media.<capability>.enabled không phải là false và không có mô hình nào được cấu hình, OpenClaw thử các tùy chọn sau theo thứ tự và dừng lại ở tùy chọn hoạt động đầu tiên:

Để tắt tính năng tự động phát hiện cho một khả năng:

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

Hỗ trợ proxy (các lệnh gọi nhà cung cấp âm thanh/video)

Tính năng nhận hiểu âm thanh và video dựa trên nhà cung cấp tuân theo các biến môi trường proxy đầu ra tiêu chuẩn, bao gồm các quy tắc bỏ qua NO_PROXY/no_proxy: HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, https_proxy, http_proxy, all_proxy. Các biến chữ thường được ưu tiên hơn biến chữ hoa. Nếu không có biến nào được đặt, tính năng nhận hiểu phương tiện sử dụng kết nối đi trực tiếp; nếu giá trị proxy không hợp lệ, OpenClaw ghi cảnh báo và quay về tải trực tiếp. Tính năng nhận hiểu hình ảnh không đi qua đường dẫn proxy này.

Các khả năng

Đặt capabilities trên một mục models[] để giới hạn mục đó cho các loại phương tiện cụ thể. Với danh sách dùng chung, OpenClaw suy luận các giá trị mặc định theo từng nhà cung cấp đi kèm:

Đối với các mục CLI, hãy đặt capabilities rõ ràng để tránh các kết quả khớp ngoài dự kiến; nếu bỏ qua, mục đó đủ điều kiện cho mọi danh sách khả năng mà nó xuất hiện trong đó.

Ma trận hỗ trợ của nhà cung cấp

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

• Ưu tiên mô hình thế hệ hiện tại mạnh nhất cho từng khả năng phương tiện khi chất lượng và độ an toàn là quan trọng.
• Đối với các tác nhân có hỗ trợ công cụ xử lý đầu vào không đáng tin cậy, tránh sử dụng các mô hình phương tiện cũ hoặc yếu hơn.
• Duy trì ít nhất một phương án dự phòng cho mỗi khả năng để đảm bảo tính sẵn sàng (mô hình chất lượng cao + mô hình nhanh hơn/rẻ hơn).
• Các phương án dự phòng CLI (whisper-cli, whisper, gemini) hữu ích khi API của nhà cung cấp không khả dụng.
• Các chế độ xuất tệp đã biết có tính quyết định: tệp bản chép lời được suy luận bị trống hoặc thiếu sẽ không tạo ra bản chép lời, thay vì dự phòng bằng đầu ra tiến trình CLI.
• parakeet-mlx: sử dụng --output-format txt (hoặc all) cùng với --output-dir và mẫu đầu ra mặc định {filename}. Các biến môi trường thượng nguồn PARAKEET_OUTPUT_FORMAT và PARAKEET_OUTPUT_TEMPLATE cũng được tôn trọng. OpenClaw đọc <output-dir>/<media-basename>.txt; định dạng srt mặc định, các định dạng khác và mẫu đầu ra tùy chỉnh tiếp tục sử dụng stdout.

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

attachments theo từng khả năng kiểm soát những tệp đính kèm nào được xử lý:

Khi mode: "all", đầu ra được gắn nhãn [Hình ảnh 1/2], [Âm thanh 2/2], v.v.

Trích xuất tệp đính kèm

• Văn bản được trích xuất từ tệp được bao bọc dưới dạng nội dung bên ngoài không đáng tin cậy trước khi được nối vào lời nhắc phương tiện, sử dụng các dấu mốc biên như <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> cùng với dòng siêu dữ liệu Source: External.
• Đường dẫn này cố ý bỏ qua biểu ngữ dài SECURITY NOTICE: để giữ lời nhắc phương tiện ngắn gọn; các dấu mốc biên và siêu dữ liệu vẫn được áp dụng.
• Tệp không có văn bản có thể trích xuất sẽ nhận [Không có văn bản có thể trích xuất].
• Nếu PDF chuyển sang phương án dự phòng là hình ảnh trang được kết xuất, OpenClaw chuyển tiếp các hình ảnh đó đến các mô hình trả lời có khả năng thị giác và giữ chỗ [Nội dung PDF được kết xuất thành hình ảnh] trong khối tệp.

Ví dụ cấu hình

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

Đầu ra trạng thái

Khi quá trình hiểu phương tiện chạy, /status bao gồm một dòng tóm tắt cho mỗi khả năng:

📎 Media: image ok (openai/gpt-5.6-sol) · audio ok (whisper-cli observed=metal)

Để kiểm kê trước khi chạy, hãy chạy openclaw capability audio providers. Các hàng cục bộ hiển thị riêng phương án dự phòng cục bộ được chọn so với lựa chọn nhà cung cấp toàn cục, trạng thái sẵn sàng và các trường phần phụ trợ có khả năng/được yêu cầu/quan sát được tách biệt. Lựa chọn cục bộ tương tự cũng có sẵn dưới dạng một phát hiện thông tin của doctor:

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

Ghi chú

• Khả năng hiểu được thực hiện theo nỗ lực tối đa. Lỗi không chặn phản hồi.
• Tệp đính kèm vẫn được truyền đến mô hình ngay cả khi khả năng hiểu bị tắt.
• Sử dụng scope để giới hạn nơi khả năng hiểu chạy (ví dụ: chỉ tin nhắn trực tiếp).

Liên quan

• Cấu hình
• Hỗ trợ hình ảnh và phương tiện