Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
เป้าหมาย

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

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

1

รวบรวมไฟล์แนบ

รวบรวมไฟล์แนบขาเข้า (MediaPaths, MediaUrls, MediaTypes)
2

เลือกตามความสามารถ

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

เลือกโมเดล

เลือกรายการโมเดลแรกที่มีสิทธิ์ (ขนาด + ความสามารถ + การยืนยันตัวตน)
4

สำรองเมื่อเกิดความล้มเหลว

หากโมเดลล้มเหลวหรือสื่อมีขนาดใหญ่เกินไป ให้ สำรองไปยังรายการถัดไป
5

ใช้บล็อกเมื่อสำเร็จ

เมื่อสำเร็จ:
  • Body จะกลายเป็นบล็อก [Image], [Audio] หรือ [Video]
  • เสียงจะตั้งค่า {{Transcript}}; การแยกวิเคราะห์คำสั่งใช้ข้อความคำบรรยายภาพ/เสียงเมื่อมี มิฉะนั้นจะใช้ทรานสคริปต์
  • คำบรรยายภาพ/เสียงจะถูกเก็บไว้เป็น User text: ภายในบล็อก
หากการทำความเข้าใจล้มเหลวหรือถูกปิดใช้ โฟลว์การตอบกลับจะดำเนินต่อ ด้วยเนื้อหาต้นฉบับ + ไฟล์แนบเดิม

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

tools.media รองรับ โมเดลที่ใช้ร่วมกัน รวมถึงการแทนที่รายความสามารถ:
  • tools.media.models: รายการโมเดลที่ใช้ร่วมกัน (ใช้ capabilities เพื่อควบคุม)
  • tools.media.image / tools.media.audio / tools.media.video:
    • ค่าเริ่มต้น (prompt, maxChars, maxBytes, timeoutSeconds, language)
    • การแทนที่ของผู้ให้บริการ (baseUrl, headers, providerOptions)
    • ตัวเลือกเสียง Deepgram ผ่าน tools.media.audio.providerOptions.deepgram
    • การควบคุมการสะท้อนทรานสคริปต์เสียง (echoTranscript, ค่าเริ่มต้น false; echoFormat)
    • รายการ models รายความสามารถ ที่ไม่บังคับ (ต้องการก่อนโมเดลที่ใช้ร่วมกัน)
    • นโยบาย attachments (mode, maxAttachments, prefer)
    • scope (การควบคุมแบบไม่บังคับตามช่องทาง/chatType/คีย์เซสชัน)
  • tools.media.concurrency: จำนวนการเรียกใช้ความสามารถพร้อมกันสูงสุด (ค่าเริ่มต้น 2)
{
  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",
}

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

ค่าเริ่มต้นที่แนะนำ:
  • maxChars: 500 สำหรับรูปภาพ/วิดีโอ (สั้น เหมาะกับคำสั่ง)
  • maxChars: ไม่ตั้งค่า สำหรับเสียง (ทรานสคริปต์เต็ม เว้นแต่คุณตั้งขีดจำกัด)
  • maxBytes:
    • รูปภาพ: 10MB
    • เสียง: 20MB
    • วิดีโอ: 50MB
  • หากสื่อเกิน maxBytes โมเดลนั้นจะถูกข้ามและจะ ลองโมเดลถัดไป
  • ไฟล์เสียงที่เล็กกว่า 1024 bytes จะถือว่าว่างเปล่า/เสียหาย และถูกข้ามก่อนการถอดเสียงโดยผู้ให้บริการ/CLI; บริบทการตอบกลับขาเข้าจะได้รับทรานสคริปต์ตัวแทนที่กำหนดแน่นอน เพื่อให้เอเจนต์รู้ว่าโน้ตสั้นเกินไป
  • หากโมเดลส่งคืนผลลัพธ์มากกว่า maxChars ผลลัพธ์จะถูกตัดให้สั้นลง
  • prompt มีค่าเริ่มต้นเป็น “Describe the .” แบบง่าย ๆ พร้อมคำแนะนำ maxChars (เฉพาะรูปภาพ/วิดีโอ)
  • หากโมเดลรูปภาพหลักที่ใช้งานอยู่รองรับวิชันโดยกำเนิดอยู่แล้ว OpenClaw จะข้ามบล็อกสรุป [Image] และส่งรูปภาพต้นฉบับเข้าโมเดลแทน
  • หากโมเดลหลักของ Gateway/WebChat เป็นแบบข้อความเท่านั้น ไฟล์แนบรูปภาพจะถูกเก็บไว้เป็นอ้างอิง media://inbound/* ที่ถ่ายโอนออกไป เพื่อให้เครื่องมือรูปภาพ/PDF หรือโมเดลรูปภาพที่กำหนดค่าไว้ยังคงตรวจสอบได้แทนที่จะสูญเสียไฟล์แนบ
  • คำขอ openclaw infer image describe --model <provider/model> แบบระบุชัดจะแตกต่างกัน: คำขอเหล่านี้จะเรียกใช้ผู้ให้บริการ/โมเดลที่รองรับรูปภาพนั้นโดยตรง รวมถึงอ้างอิง Ollama เช่น ollama/qwen2.5vl:7b
  • หากตั้งค่า <capability>.enabled: true แต่ไม่ได้กำหนดค่าโมเดลไว้ OpenClaw จะลองใช้ โมเดลตอบกลับที่ใช้งานอยู่ เมื่อผู้ให้บริการของโมเดลนั้นรองรับความสามารถดังกล่าว

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

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

โมเดลตอบกลับที่ใช้งานอยู่

โมเดลตอบกลับที่ใช้งานอยู่เมื่อผู้ให้บริการรองรับความสามารถดังกล่าว
2

agents.defaults.imageModel

อ้างอิงหลัก/สำรองของ agents.defaults.imageModel (เฉพาะรูปภาพ) ควรใช้อ้างอิง provider/model อ้างอิงแบบไม่มีคุณสมบัติจะถูกเติมคุณสมบัติจากรายการโมเดลผู้ให้บริการที่รองรับรูปภาพซึ่งกำหนดค่าไว้เท่านั้น เมื่อรายการที่ตรงกันมีเพียงหนึ่งเดียว
3

CLI ในเครื่อง (เฉพาะเสียง)

CLI ในเครื่อง (หากติดตั้งไว้):
  • sherpa-onnx-offline (ต้องใช้ SHERPA_ONNX_MODEL_DIR ที่มี encoder/decoder/joiner/tokens)
  • whisper-cli (whisper-cpp; ใช้ WHISPER_CPP_MODEL หรือโมเดล tiny ที่รวมมา)
  • whisper (Python CLI; ดาวน์โหลดโมเดลอัตโนมัติ)
4

Gemini CLI

gemini โดยใช้ read_many_files
5

การยืนยันตัวตนผู้ให้บริการ

  • รายการ models.providers.* ที่กำหนดค่าไว้และรองรับความสามารถดังกล่าวจะถูกลองก่อนลำดับสำรองที่รวมมา
  • ผู้ให้บริการจากการกำหนดค่าเฉพาะรูปภาพที่มีโมเดลรองรับรูปภาพจะลงทะเบียนอัตโนมัติสำหรับการทำความเข้าใจสื่อ แม้จะไม่ใช่ Plugin ผู้จำหน่ายที่รวมมาก็ตาม
  • การทำความเข้าใจรูปภาพของ Ollama พร้อมใช้งานเมื่อเลือกอย่างชัดเจน เช่น ผ่าน agents.defaults.imageModel หรือ openclaw infer image describe --model ollama/<vision-model>
ลำดับสำรองที่รวมมา:
  • เสียง: OpenAI → Groq → xAI → Deepgram → OpenRouter → Google → SenseAudio → ElevenLabs → Mistral
  • รูปภาพ: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
  • วิดีโอ: Google → Qwen → Moonshot
หากต้องการปิดการตรวจหาอัตโนมัติ ให้ตั้งค่า: 
{
  tools: {
    media: {
      audio: {
        enabled: false,
      },
    },
  },
}
การตรวจหาไบนารีเป็นแบบพยายามให้ดีที่สุดใน macOS/Linux/Windows; ตรวจให้แน่ใจว่า CLI อยู่บน PATH (เราขยาย ~) หรือตั้งค่าโมเดล CLI แบบชัดเจนด้วยพาธคำสั่งแบบเต็ม

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

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

​
ความสามารถ (ไม่บังคับ)

หากคุณตั้งค่า 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)

ความสามารถการผสานรวมผู้ให้บริการหมายเหตุ
รูปภาพOpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, ผู้ให้บริการจากการกำหนดค่าPlugin ของผู้จำหน่ายลงทะเบียนการรองรับรูปภาพ; openai-codex/* ใช้ระบบผู้ให้บริการ OAuth; codex/* ใช้เทิร์น Codex app-server ที่มีขอบเขตจำกัด; MiniMax และ MiniMax OAuth ต่างใช้ MiniMax-VL-01; ผู้ให้บริการจากการกำหนดค่าที่รองรับรูปภาพจะลงทะเบียนอัตโนมัติ
เสียงOpenAI, Groq, xAI, Deepgram, OpenRouter, Google, SenseAudio, ElevenLabs, Mistralการถอดเสียงโดยผู้ให้บริการ (Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral)
วิดีโอGoogle, Qwen, Moonshotการทำความเข้าใจวิดีโอโดยผู้ให้บริการผ่าน Plugin ของผู้จำหน่าย; การทำความเข้าใจวิดีโอของ Qwen ใช้ปลายทาง Standard DashScope
หมายเหตุ MiniMax
  • การทำความเข้าใจรูปภาพของ minimax และ minimax-portal มาจากผู้ให้บริการสื่อ MiniMax-VL-01 ที่ Plugin เป็นเจ้าของ
  • แค็ตตาล็อกข้อความ MiniMax ที่รวมมายังคงเริ่มต้นเป็นแบบข้อความเท่านั้น; รายการ models.providers.minimax ที่ระบุชัดเจนจะทำให้เกิดอ้างอิงแชต M2.7 ที่รองรับรูปภาพ

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

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

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

attachments รายความสามารถควบคุมว่าไฟล์แนบใดจะถูกประมวลผล:
​
mode
"first" | "all"
default:"first"
ระบุว่าจะประมวลผลไฟล์แนบที่เลือกไฟล์แรก หรือทั้งหมด
​
maxAttachments
number
default:"1"
จำกัดจำนวนที่ประมวลผล
​
prefer
"first" | "last" | "path" | "url"
การตั้งค่าการเลือกจากไฟล์แนบผู้สมัคร
เมื่อ mode: "all" เอาต์พุตจะติดป้ายกำกับเป็น [Image 1/2], [Audio 2/2] และอื่น ๆ
  • ข้อความไฟล์ที่แยกออกมาจะถูกห่อเป็น เนื้อหาภายนอกที่ไม่น่าเชื่อถือ ก่อนผนวกเข้ากับพรอมป์สื่อ
  • บล็อกที่แทรกใช้ตัวทำเครื่องหมายขอบเขตอย่างชัดเจน เช่น <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> และมีบรรทัดเมตาดาต้า Source: External
  • เส้นทางการแยกไฟล์แนบนี้ตั้งใจละเว้นแบนเนอร์ SECURITY NOTICE: แบบยาว เพื่อหลีกเลี่ยงการทำให้พรอมป์สื่อยืดยาวเกินไป แต่ตัวทำเครื่องหมายขอบเขตและเมตาดาต้ายังคงอยู่
  • หากไฟล์ไม่มีข้อความที่แยกได้ OpenClaw จะแทรก [No extractable text]
  • หาก PDF ถอยกลับไปใช้รูปภาพหน้าที่เรนเดอร์แล้วในเส้นทางนี้ พรอมป์สื่อจะยังคงเก็บตัวยึดตำแหน่ง [PDF content rendered to images; images not forwarded to model] ไว้ เพราะขั้นตอนการแยกไฟล์แนบนี้ส่งต่อบล็อกข้อความ ไม่ใช่รูปภาพ PDF ที่เรนเดอร์แล้ว

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

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

​
เอาต์พุตสถานะ

เมื่อการทำความเข้าใจสื่อทำงาน /status จะมีบรรทัดสรุปสั้น ๆ: 
📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)
ส่วนนี้แสดงผลลัพธ์แยกตามความสามารถ และผู้ให้บริการ/โมเดลที่เลือกเมื่อเกี่ยวข้อง

​
หมายเหตุ

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

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