ความเข้าใจสื่อ

OpenClaw สามารถสรุปสื่อขาเข้า (รูปภาพ/เสียง/วิดีโอ) ก่อนที่ไปป์ไลน์การตอบกลับจะทำงาน โดยตรวจจับอัตโนมัติเมื่อมีเครื่องมือภายในเครื่องหรือคีย์ของผู้ให้บริการ และสามารถปิดใช้งานหรือปรับแต่งได้ หากปิดการทำความเข้าใจ โมเดลจะยังได้รับไฟล์/URL ต้นฉบับตามปกติ

พฤติกรรมสื่อเฉพาะผู้ขายจะลงทะเบียนโดย Plugin ของผู้ขาย ขณะที่แกนหลักของ OpenClaw เป็นเจ้าของการกำหนดค่า tools.media ที่ใช้ร่วมกัน ลำดับ fallback และการผสานรวมกับไปป์ไลน์การตอบกลับ

เป้าหมาย

• ไม่บังคับ: ย่อยสื่อขาเข้าเบื้องต้นเป็นข้อความสั้นเพื่อการกำหนดเส้นทางที่เร็วขึ้น + การแยกวิเคราะห์คำสั่งที่ดีขึ้น
• รักษาการส่งสื่อต้นฉบับไปยังโมเดล (เสมอ)
• รองรับ API ของผู้ให้บริการ และ CLI fallbacks
• อนุญาตให้ใช้หลายโมเดลพร้อม fallback ตามลำดับ (ข้อผิดพลาด/ขนาด/หมดเวลา)

พฤติกรรมระดับสูง

หากการทำความเข้าใจล้มเหลวหรือถูกปิดใช้งาน โฟลว์การตอบกลับจะดำเนินต่อไป พร้อม body + ไฟล์แนบต้นฉบับ

ภาพรวมการกำหนดค่า

tools.media รองรับ โมเดลที่ใช้ร่วมกัน พร้อมการ override รายความสามารถ:

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

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

ข้อมูลประจำตัวผู้ให้บริการ (apiKey)

การทำความเข้าใจสื่อของผู้ให้บริการใช้การแก้ไขการยืนยันตัวตนผู้ให้บริการแบบเดียวกับการเรียกโมเดลปกติ: โปรไฟล์การยืนยันตัวตน ตัวแปรสภาพแวดล้อม จากนั้นคือ models.providers.<providerId>.apiKey

รายการ tools.media.*.models[] ไม่ยอมรับฟิลด์ apiKey แบบ inline ค่า provider ในรายการโมเดลสื่อ เช่น openai หรือ moonshot ต้องมีข้อมูลประจำตัวที่พร้อมใช้งานผ่านแหล่งการยืนยันตัวตนผู้ให้บริการมาตรฐานรายการใดรายการหนึ่ง

ตัวอย่างขั้นต่ำ:

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

สำหรับอ้างอิงการยืนยันตัวตนผู้ให้บริการฉบับเต็ม รวมถึงโปรไฟล์ ตัวแปรสภาพแวดล้อม และ URL ฐานแบบกำหนดเอง โปรดดู เครื่องมือและผู้ให้บริการแบบกำหนดเอง

ค่าเริ่มต้นและขีดจำกัด

ค่าเริ่มต้นที่แนะนำ:

• maxChars: 500 สำหรับรูปภาพ/วิดีโอ (สั้น เหมาะกับคำสั่ง)
• maxChars: ไม่ได้ตั้งค่า สำหรับเสียง (transcript เต็ม เว้นแต่คุณจะตั้งขีดจำกัด)
• maxBytes:
  • รูปภาพ: 10MB
  • เสียง: 20MB
  • วิดีโอ: 50MB

ตรวจจับการทำความเข้าใจสื่ออัตโนมัติ (ค่าเริ่มต้น)

หาก tools.media.<capability>.enabled ไม่ได้ ตั้งเป็น false และคุณไม่ได้กำหนดค่าโมเดล OpenClaw จะตรวจจับอัตโนมัติตามลำดับนี้ และ หยุดที่ตัวเลือกแรกที่ทำงานได้:

หากต้องการปิดการตรวจจับอัตโนมัติ ให้ตั้งค่า:

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

การรองรับสภาพแวดล้อมพร็อกซี (โมเดลผู้ให้บริการ)

เมื่อเปิดใช้งานการทำความเข้าใจสื่อแบบผู้ให้บริการสำหรับ เสียง และ วิดีโอ OpenClaw จะเคารพตัวแปรสภาพแวดล้อมพร็อกซีขาออกมาตรฐานสำหรับการเรียก HTTP ของผู้ให้บริการ:

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

หากไม่ได้ตั้งค่าตัวแปรสภาพแวดล้อมพร็อกซี การทำความเข้าใจสื่อจะใช้ egress โดยตรง หากค่าพร็อกซีมีรูปแบบไม่ถูกต้อง OpenClaw จะบันทึกคำเตือนและ fallback ไปยังการ 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)

คำแนะนำในการเลือกโมเดล

• ควรเลือกโมเดลรุ่นล่าสุดที่แข็งแกร่งที่สุดที่มีให้สำหรับความสามารถด้านสื่อแต่ละประเภท เมื่อคุณภาพและความปลอดภัยเป็นสิ่งสำคัญ
• สำหรับเอเจนต์ที่เปิดใช้เครื่องมือและจัดการอินพุตที่ไม่น่าเชื่อถือ ให้หลีกเลี่ยงโมเดลสื่อที่เก่ากว่าหรืออ่อนแอกว่า
• เก็บ fallback อย่างน้อยหนึ่งรายการต่อความสามารถเพื่อความพร้อมใช้งาน (โมเดลคุณภาพ + โมเดลที่เร็วกว่า/ถูกกว่า)
• fallback ของ CLI (whisper-cli, whisper, gemini) มีประโยชน์เมื่อ API ของผู้ให้บริการไม่พร้อมใช้งาน
• หมายเหตุ parakeet-mlx: เมื่อใช้ --output-dir OpenClaw จะอ่าน <output-dir>/<media-basename>.txt เมื่อรูปแบบเอาต์พุตเป็น txt (หรือไม่ได้ระบุ); รูปแบบที่ไม่ใช่ txt จะ fallback ไปที่ stdout

นโยบายไฟล์แนบ

attachments ตามแต่ละความสามารถควบคุมว่าไฟล์แนบใดจะถูกประมวลผล:

เมื่อ mode: "all" เอาต์พุตจะมีป้ายกำกับ [Image 1/2], [Audio 2/2] เป็นต้น

ตัวอย่างการกำหนดค่า

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

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

{  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 จะมีบรรทัดสรุปสั้น ๆ:

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

สิ่งนี้แสดงผลลัพธ์ตามแต่ละความสามารถและผู้ให้บริการ/โมเดลที่เลือกเมื่อเกี่ยวข้อง

หมายเหตุ

• การทำความเข้าใจเป็นแบบ พยายามอย่างดีที่สุด ข้อผิดพลาดไม่บล็อกการตอบกลับ
• ไฟล์แนบยังคงถูกส่งไปยังโมเดลแม้ว่าจะปิดการทำความเข้าใจไว้
• ใช้ scope เพื่อจำกัดตำแหน่งที่การทำความเข้าใจทำงาน (เช่น เฉพาะ DM)

ที่เกี่ยวข้อง

• การกำหนดค่า
• การรองรับรูปภาพและสื่อ