แสดงวิดเจ็ต

show_widget เป็นเครื่องมือหลักที่แสดงวิดเจ็ต HTML แบบครบในตัวบนพื้นผิวที่ผู้ใช้กำลังใช้งานอยู่ OpenClaw แสดงผลแบบอินไลน์ใน Control UI และในบันทึกการสนทนา Quick Chat ของ iOS, Android, macOS และ Linux ส่วนแดชบอร์ด Linux ใช้ Control UI บนเบราว์เซอร์ ในเซสชัน Discord ที่เปิดใช้ Activities Plugin Discord จะโพสต์ปุ่ม เปิดวิดเจ็ต ซึ่งเปิดวิดเจ็ตเป็น Activity

วิธีการทำงานของวิดเจ็ต

เมื่อเอเจนต์เรียก show_widget แกนหลักของ OpenClaw จะครอบ widget_code ไว้ในเอกสาร HTML ขั้นต่ำ จัดเก็บเป็นเอกสาร Canvas และส่งคืนแฮนเดิลตัวอย่าง Control UI แสดงผลแฮนเดิลดังกล่าวใน iframe แบบแซนด์บ็อกซ์ ส่วน Quick Chat บน iOS, Android, macOS และ Linux ใช้เว็บวิวที่แยกออกจากกัน ไคลเอนต์แชตแบบเต็มจะกู้คืนวิดเจ็ตหลังโหลดประวัติใหม่ ส่วน Quick Chat จะเก็บวิดเจ็ตไว้ตลอดการตอบกลับที่กำลังใช้งาน

ในเซสชัน Control UI ยังสามารถปักหมุดวิดเจ็ต Canvas ไว้ที่แดชบอร์ดของเซสชันได้ด้วย ตั้งค่า pin: true ในการเรียกเครื่องมือ หรือใช้ ปักหมุดไว้ที่แดชบอร์ด บนวิดเจ็ตที่มีอยู่ในบันทึกการสนทนา HTML ที่ปักหมุดจะทำงานเบื้องหลังโฮสต์แซนด์บ็อกซ์แบบต้นทางเฉพาะและ iframe สองชั้นเช่นเดียวกับที่ MCP Apps ใช้ โดยเบราว์เซอร์จะไม่แก้ไขการเชื่อมโยงข้อมูลของวิดเจ็ตภายในเฟรมที่ไม่น่าเชื่อถือ

สำหรับการฝังในเบราว์เซอร์ เอกสารตัวครอบจะแทรกบริดจ์โฮสต์ขนาดเล็กสี่รายการไว้รอบโค้ดวิดเจ็ต:

• ตัวรายงานขนาดจะโพสต์ความสูงของเนื้อหาที่แสดงผลไปยังแชตที่ฝัง ซึ่งจะจำกัดและปรับ iframe ให้พอดี (160 ถึง 1200 พิกเซล)
• บริดจ์โฮสต์กำหนดตัวช่วยรุ่นเก่า sendPrompt(text) รวมถึง API แบบมีโครงสร้าง openclaw.prompt, openclaw.state, openclaw.data และ openclaw.cron พรอมต์แชตแบบอินไลน์จะคงช่องทางข้อความส่วนตัวไว้ ส่วน API แดชบอร์ดใช้ช่องทางคำขอที่ผูกกับตั๋วมุมมอง ดู วิดเจ็ตแบบโต้ตอบ และ ความสามารถของแดชบอร์ด
• บริดจ์ธีมจะรอรับโทเค็นการออกแบบปัจจุบันของ Control UI และนำไปใช้เป็นตัวแปร CSS ทั้งตอนโหลดและทุกครั้งที่ธีมเปลี่ยน
• บริดจ์สแนปช็อตจะแสดงผลเอกสารวิดเจ็ตปัจจุบันเป็น PNG เมื่อแชตที่ฝังร้องขอการส่งออก

ส่วนอื่นทั้งหมดจะอยู่ภายในเฟรม เอกสารทำงานในต้นทางแบบทึบพร้อม Content Security Policy ที่เข้มงวด ดังนั้นสคริปต์วิดเจ็ตจึงไม่สามารถเข้าถึง Control UI, Gateway หรือเครือข่ายได้

การทำงานของแกนหลักจะใช้ได้เฉพาะเมื่อไคลเอนต์ Gateway ต้นทางประกาศความสามารถ inline-widgets Control UI และแอปเนทีฟที่รองรับจะประกาศความสามารถนี้โดยอัตโนมัติ Quick Chat บน Linux จะเป็นแบบข้อความเท่านั้นสำหรับการเชื่อมต่อ Gateway ที่ต้องใช้การปักหมุดใบรับรองปลายทาง TLS แบบกำหนดเอง เนื่องจาก WebView ของแพลตฟอร์มไม่สามารถผูกการปักหมุดดังกล่าวได้ การทำงานของ Discord จะใช้ได้เฉพาะในเซสชัน Discord ที่กำหนดค่า Activities แล้ว การทำงานบนช่องทางอื่นจะไม่ได้รับ show_widget

การส่งผ่านความสามารถครอบคลุมแบ็กเอนด์โมเดลแบบฝัง, Codex app-server และแบบที่มี CLI รองรับ ผู้เรียก MCP ที่ยืนยันตัวตนด้วยสิทธิ์อนุญาตและผู้เรียกเครื่องมือผ่าน HTTP โดยตรงจะยังคงปิดกั้นโดยค่าเริ่มต้น เนื่องจากไม่ได้ประกาศความสามารถของไคลเอนต์

ระบบการออกแบบ

วิดเจ็ต Canvas ทุกตัวมีสไตล์ชีตพื้นฐานแบบไม่ใช้คลาสและชุดโทเค็นขนาดเล็ก:

หัวข้อ ย่อหน้า ลิงก์ ปุ่ม ช่องป้อนข้อมูล เมนูเลือก พื้นที่ข้อความ ตาราง และบล็อกโค้ดที่ไม่ระบุคลาสจะได้รับสไตล์พื้นฐาน คลาสตัวช่วยมีรูปแบบทั่วไปดังนี้:

• .card สำหรับพื้นผิวเนื้อหาที่มีเส้นขอบ
• .badge พร้อม .ok, .warn, .danger หรือ .info สำหรับป้ายสถานะแบบกะทัดรัด
• .metric สำหรับค่าตัวเลขที่โดดเด่น
• .muted สำหรับข้อความรอง
• .row สำหรับเลย์เอาต์แนวนอนแบบตัดขึ้นบรรทัดใหม่
• button.primary สำหรับการดำเนินการหลัก

Control UI จะโพสต์ข้อความ openclaw:widget-theme พร้อมค่าธีมที่ใช้งานอยู่เมื่อวิดเจ็ตโหลดและทุกครั้งที่ธีมเปลี่ยน ดังนั้นวิดเจ็ตจึงติดตามธีมทุกตระกูล รวมถึง Claw, Knot, Dash และธีมแบบกำหนดเองได้โดยไม่ต้องโหลดใหม่ นอก Control UI รวมถึงในแอปเนทีฟและการเปิดโดยตรง วิดเจ็ตจะใช้พาเลตสว่างหรือมืดที่ฝังไว้ซึ่งเลือกโดย prefers-color-scheme

สร้างวิดเจ็ตตามกฎสามข้อต่อไปนี้:

1. ใช้ตัวแปรการออกแบบสำหรับทุกสีและพื้นหลัง ห้ามกำหนดค่าสีแบบตายตัว
2. ทำให้พื้นหลังหน้าโปร่งใส เพื่อให้วิดเจ็ตกลมกลืนกับพื้นผิวโฮสต์
3. สงวน --accent-fill ไว้สำหรับการดำเนินการหลักไม่เกินหนึ่งรายการ

การส่งออก: ในเว็บแชต ให้เปิดเมนูการ์ดวิดเจ็ตเพื่อคัดลอกวิดเจ็ตที่แสดงผลไปยังคลิปบอร์ดหรือดาวน์โหลดเป็น PNG เอกสารวิดเจ็ตรุ่นเก่าที่ไม่มีบริดจ์สแนปช็อตจะเปลี่ยนไปดาวน์โหลดไฟล์ HTML แทน

ใช้เครื่องมือ

การทำงานทั้งสองแบบใช้ฟิลด์บังคับเดียวกัน:

Discord ยังรองรับข้อความ button_label แบบไม่บังคับสำหรับปุ่มเปิด Activity สคีมา Canvas จงใจไม่รวมฟิลด์ที่ใช้เฉพาะ Discord นี้

เครื่องมือ Canvas หลักรองรับฟิลด์การจัดวางบนแดชบอร์ดแบบไม่บังคับดังต่อไปนี้:

• pin: วางวิดเจ็ตบนแดชบอร์ดของเซสชันด้วย
• name: ชื่อวิดเจ็ตแบบคงที่ ค่าเริ่มต้นเป็น slug ของ title
• tab: slug ของแท็บปลายทาง
• size: ค่าใดค่าหนึ่งจาก sm, md, lg, xl หรือ full
• after: ชื่อวิดเจ็ตพี่น้องที่จะวางวิดเจ็ตนี้ไว้ถัดจากด้านหลัง
• capabilities: สิทธิ์เข้าถึงที่วิดเจ็ตซึ่งปักหมุดร้องขอ netOrigins มีต้นทาง HTTPS ที่ตรงกันทุกประการ ส่วน tools มี prompt, การเชื่อมโยงการอ่านที่อยู่ในรายการอนุญาต หรือการดำเนินการ cron.trigger:<jobId> ที่ตรงกันทุกประการ

ผลลัพธ์หลักประกอบด้วยแฮนเดิลตัวอย่าง Canvas ดังนั้น Control UI และแอปเนทีฟที่รองรับจึงแสดงผลวิดเจ็ตโดยตรงจากการเรียกเครื่องมือ และกู้คืนวิดเจ็ตหลังโหลดประวัติใหม่ ผลลัพธ์ที่ปักหมุดยังคงเก็บชื่อวิดเจ็ตบนบอร์ดไว้ เพื่อไม่ให้ Control UI เสนอการปักหมุดซ้ำหลังโหลดบันทึกการสนทนาใหม่ Discord ส่งคืนตัวระบุวิดเจ็ตที่จัดเก็บและข้อความที่โพสต์

discord_widget ยังคงลงทะเบียนเป็นชื่อแทนที่เลิกใช้แล้วเป็นเวลาหนึ่งรุ่น การเรียกใหม่จากเอเจนต์ควรใช้ show_widget

วิดเจ็ตแบบโต้ตอบ

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

<button onclick="sendPrompt('แสดงรายละเอียดการทดสอบที่ล้มเหลว')">การทดสอบที่ล้มเหลว</button>

ทุกพรอมต์จะได้รับการตรวจสอบทั้งสองด้านของขอบเขตเฟรม:

• sendPrompt ต้องมี การเปิดใช้งานชั่วคราวโดยผู้ใช้ ภายในวิดเจ็ต โดยจะทำงานเฉพาะในช่วงไม่กี่วินาทีหลังผู้ใช้คลิกหรือกดปุ่มในวิดเจ็ต ดังนั้นให้เชื่อมกับปุ่มและเป้าหมายการคลิกอื่น ๆ — การเรียกโดยอัตโนมัติขณะโหลดจะไม่มีผล บริดจ์จะเก็บปลายทางการส่งไว้เป็นส่วนตัวสำหรับตัวเองและปิดกั้นโดยค่าเริ่มต้นในเบราว์เซอร์ที่ไม่เปิดเผยการเปิดใช้งานโดยผู้ใช้ ดังนั้นโค้ดวิดเจ็ตจึงไม่สามารถหลีกเลี่ยงการตรวจสอบได้
• สิทธิ์ในการส่งพรอมต์เป็นของเอกสารวิดเจ็ตต้นฉบับเท่านั้น บริดจ์ที่เชื่อถือได้จะเสนอปลายทางช่องทางของตนให้แชตก่อนที่โค้ดวิดเจ็ตจะทำงานหรือนำทางเฟรมได้ แชตจะรับเฉพาะข้อเสนอแรก และช่องทางจะสิ้นสุดพร้อมเอกสารเมื่อมีการนำทาง URL สำหรับฝังที่อนุญาตจากภายนอกจะไม่ถูกรับ
• เฟรมวิดเจ็ตต้องมองเห็นได้ในบันทึกการสนทนาและมีโฟกัส ซึ่งเป็นสัญญาณเพิ่มเติมที่โฮสต์สังเกตได้ว่าผู้ใช้กำลังโต้ตอบกับวิดเจ็ตนี้จริง
• ข้อความต้องไม่ว่างเปล่าหลังตัดช่องว่างและต้องมีความยาวไม่เกิน 4,000 อักขระ
• พรอมต์ที่ขึ้นต้นด้วย / จะถูกปฏิเสธ ดังนั้นโค้ดวิดเจ็ตจึงไม่สามารถเรียกคำสั่งแชต เช่น /approve หรือ /stop
• เอกสารวิดเจ็ตแต่ละรายการส่งพรอมต์ได้ไม่เกิน 10 รายการต่อนาทีแบบต่อเนื่อง พรอมต์ที่เกินจะถูกละทิ้งโดยไม่มีการแจ้งเตือน

พรอมต์ที่ได้รับการยอมรับจะปรากฏในบันทึกการสนทนาเป็นข้อความผู้ใช้ปกติ และเริ่มรอบการทำงานของเอเจนต์ตามปกติในเซสชันที่เป็นเจ้าของวิดเจ็ต ไม่มีช่องทางส่งผลตอบกลับเข้าสู่วิดเจ็ต พรอมต์ที่ถูกละทิ้งจะล้มเหลวโดยไม่มีการแจ้งเตือน และวิดเจ็ตไม่สามารถอ่านคำตอบของเอเจนต์ได้

ความสามารถของแดชบอร์ด

วิดเจ็ตที่ปักหมุดสามารถใช้ API โฮสต์ที่ผูกกับตั๋วหนึ่งรายการ หลังจากผู้ดำเนินการตรวจสอบคำประกาศที่แสดงบนการ์ดที่รอดำเนินการ:

• openclaw.prompt.send(text) ต้องมีการเปิดใช้งานชั่วคราวจากผู้ใช้และโพสต์ข้อความที่มองเห็นได้ในช่องเขียนข้อความ การประกาศและรับสิทธิ์เครื่องมือ prompt จะข้ามการยืนยันเพิ่มเติมต่อการคลิกแต่ละครั้ง แต่การตรวจสอบความถูกต้อง การตรวจสอบโฟกัส และขีดจำกัดอัตรายังคงมีผล
• openclaw.state.emit(payload) เพิ่มประกาศในเซสชัน เพย์โหลดถูกจำกัดไว้ที่ 8 KiB และการส่งข้อมูลที่เหมือนกันจากไคลเอนต์ภายในห้าวินาทีจะถูกรวมเข้าด้วยกัน
• openclaw.data.read(bindingId, params?) จะได้รับการแก้ไขที่ Gateway เท่านั้น การเชื่อมโยงที่ให้สิทธิ์ได้คือ sessions.list, usage.status, usage.cost, cron.list, cron.status, agents.list และ health
• openclaw.cron.trigger(jobId) เรียกใช้งานที่มีอยู่ทันทีได้เฉพาะเมื่อได้รับสิทธิ์ความสามารถ cron.trigger:<jobId> ที่ตรงกันทุกประการเท่านั้น

การเข้าถึงเครือข่ายแยกจากเครื่องมือของโฮสต์ ให้ใส่ต้นทาง HTTPS ที่ตรงกันทุกประการใน capabilities.netOrigins หลังจากได้รับอนุมัติ เฉพาะต้นทางเหล่านั้นเท่านั้นที่จะเข้าสู่ connect-src ของวิดเจ็ต ไวลด์การ์ด ข้อมูลประจำตัว พาธ สตริงคำค้นหา และต้นทางที่ไม่ได้ประกาศจะยังคงถูกบล็อก อนุญาตให้ใช้พอร์ตแบบระบุค่าตายตัวได้เฉพาะเมื่อเป็นส่วนหนึ่งของต้นทางที่ประกาศเท่านั้น

ความปลอดภัยและพื้นที่จัดเก็บ

เอกสารวิดเจ็ตใช้นโยบาย Content Security Policy ที่เข้มงวด อนุญาตให้ใช้สไตล์และสคริปต์แบบอินไลน์ แต่ยังคงบล็อกการโหลดทรัพยากรภายนอก วิดเจ็ตบทสนทนาแบบอินไลน์ไม่สามารถดึงข้อมูลจากเครือข่ายได้ วิดเจ็ตแดชบอร์ดที่ปักหมุดสามารถดึงข้อมูลได้เฉพาะจากต้นทาง HTTPS ที่ตรงกันทุกประการซึ่งเอเจนต์ประกาศและผู้ดำเนินการให้สิทธิ์เท่านั้น

iframe ของ Control UI จะไม่รวม allow-same-origin เสมอ แม้ว่าโหมดฝังส่วนกลางจะเป็น trusted เพื่อไม่ให้สคริปต์ของวิดเจ็ตอ่านต้นทางของแอปพลิเคชันแม่ได้ ไคลเอนต์แบบเนทีฟใช้มุมมองเว็บที่แยกออกจากกันและไม่คงอยู่ พร้อมทั้งบล็อกการนำทางออกจากวิดเจ็ตที่โฮสต์ไว้ โฮสต์เอกสารหลักยังให้บริการวิดเจ็ตพร้อมส่วนหัวการตอบกลับ Content-Security-Policy: sandbox allow-scripts ดังนั้นแม้จะแสดงผลโดยตรง วิดเจ็ตก็ยังทำงานในต้นทางแบบทึบแทนต้นทางของแอปพลิเคชัน แสดงผลเฉพาะโค้ดวิดเจ็ตที่คุณยินยอมให้ทำงานในเฟรมที่แยกออกจากกันนั้น

iframe ยังเป็นไปตาม gateway.controlUi.embedSandbox ระดับเริ่มต้น scripts รองรับวิดเจ็ตแบบโต้ตอบพร้อมคงการแยกต้นทางไว้

ความเสี่ยงคงเหลือที่ยอมรับได้จากการส่งข้อมูลออกผ่านช่องข้อมูล WebRTC มีบันทึกไว้ใน สถาปัตยกรรมแดชบอร์ด

Canvas เก็บวิดเจ็ตได้สูงสุด 32 รายการต่อเซสชัน (หรือต่อเอเจนต์เมื่อไม่มีเซสชัน) การสร้างวิดเจ็ตอีกหนึ่งรายการจะลบเอกสารที่เก่าที่สุดในขอบเขตนั้น

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

• การฝังที่โฮสต์โดย Control UI
• กิจกรรม Discord
• การควบคุมโหนด Canvas
• ความสามารถของไคลเอนต์โปรโตคอล Gateway