การทำความเข้าใจสื่อ

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

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

# เป้าหมาย

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

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

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

# ภาพรวมคอนฟิก

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

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

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

• maxChars: 500 สำหรับรูปภาพ/วิดีโอ (สั้น เป็นมิตรต่อคำสั่ง)
• maxChars: ไม่ได้ตั้งค่า สำหรับเสียง (ถอดเสียงเต็ม เว้นแต่คุณตั้งขีดจำกัด)
• 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

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

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

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