---
read_when:
    - คุณต้องการให้เอเจนต์แสดงผลลัพธ์แบบโต้ตอบได้ในเว็บแชต แอปเนทีฟ หรือ Discord
    - คุณต้องการให้ปุ่มวิดเจ็ตส่งพรอมต์ติดตามผลไปยังแชต
    - คุณต้องการกำหนดธีมให้วิดเจ็ตด้วยโทเค็นการออกแบบที่ใช้ร่วมกัน
    - คุณต้องมีสัญญาอินพุต ความปลอดภัย หรือการเก็บรักษาข้อมูลของ show_widget
sidebarTitle: Show widget
summary: แสดงวิดเจ็ต HTML แบบครบจบในตัวบนแพลตฟอร์มแชตที่รองรับ
title: แสดงวิดเจ็ต
x-i18n:
    generated_at: "2026-07-21T15:25:42Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 903adff1fadeb9d224d3e2d839c86082b5244e1e319255c8d3f6619344b749a3
    source_path: tools/show-widget.md
    workflow: 16
---

`show_widget` เป็นเครื่องมือหลักที่แสดงวิดเจ็ต HTML แบบครบในตัวบนพื้นผิวที่ผู้ใช้กำลังใช้งานอยู่ OpenClaw แสดงผลแบบอินไลน์ใน Control UI และในบันทึกการสนทนา Quick Chat ของ iOS, Android, macOS และ Linux ส่วนแดชบอร์ด Linux ใช้ Control UI บนเบราว์เซอร์ ในเซสชัน Discord ที่เปิดใช้ [Activities](/th/channels/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 แดชบอร์ดใช้ช่องทางคำขอที่ผูกกับตั๋วมุมมอง ดู [วิดเจ็ตแบบโต้ตอบ](#interactive-widgets) และ [ความสามารถของแดชบอร์ด](#dashboard-capabilities)
- บริดจ์ธีมจะรอรับโทเค็นการออกแบบปัจจุบันของ 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 ทุกตัวมีสไตล์ชีตพื้นฐานแบบไม่ใช้คลาสและชุดโทเค็นขนาดเล็ก:

| โทเค็น                                                                                 | วัตถุประสงค์                               |
| ------------------------------------------------------------------------------------- | ------------------------------------- |
| `--surface`                                                                           | สีพื้นผิวระดับหน้า              |
| `--card`                                                                              | พื้นหลังของการ์ด ปุ่ม และโค้ด     |
| `--elevated`                                                                          | พื้นหลังของตัวควบคุมฟอร์มแบบยกระดับ      |
| `--text`                                                                              | ข้อความเริ่มต้นของเนื้อหาและตัวควบคุม         |
| `--text-strong`                                                                       | หัวข้อและค่าที่โดดเด่น         |
| `--muted`                                                                             | ข้อความรองและเส้นขอบแบบละเอียด     |
| `--border`                                                                            | ตัวคั่นมาตรฐานและเส้นขอบการ์ด  |
| `--border-strong`                                                                     | เส้นขอบตัวควบคุมแบบเด่น                |
| `--accent`                                                                            | ลิงก์และวงแหวนโฟกัส                 |
| `--accent-fill`                                                                       | สีเติมการดำเนินการหลัก                   |
| `--accent-fg`                                                                         | ข้อความบนการดำเนินการหลัก              |
| `--ok`                                                                                | สถานะสำเร็จ                         |
| `--warn`                                                                              | สถานะคำเตือน                         |
| `--danger`                                                                            | สถานะข้อผิดพลาดหรือการทำลายข้อมูล            |
| `--info`                                                                              | สถานะให้ข้อมูล                   |
| `--radius`                                                                            | รัศมีมุมร่วมของตัวควบคุมและการ์ด |
| `--font-body`                                                                         | ชุดแบบอักษรเนื้อหาของโฮสต์                  |
| `--font-mono`                                                                         | ชุดแบบอักษรความกว้างคงที่ของโฮสต์             |
| `--accent-subtle`, `--ok-subtle`, `--warn-subtle`, `--danger-subtle`, `--info-subtle` | พื้นหลังสถานะแบบโปร่งแสงที่ได้จากการคำนวณ |

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

- `.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 แทน

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

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

<ParamField path="title" type="string" required>
  ชื่อสั้นที่แสดงพร้อมตัวอย่างแบบอินไลน์และในชื่อเอกสารที่โฮสต์
</ParamField>

<ParamField path="widget_code" type="string" required>
  HTML หรือ SVG แบบครบในตัว สำหรับไคลเอนต์วิดเจ็ตแบบอินไลน์ อินพุตที่ขึ้นต้นด้วย `<svg` หลังตัดช่องว่างจะแสดงผลในโหมด SVG โดยมีความยาวสูงสุด 262,144 อักขระ Discord รองรับเอกสาร HTML ฉบับสมบูรณ์หรือส่วนเนื้อหาขนาดสูงสุด 48 KiB
</ParamField>

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` ไปยังแชตเสมือนว่าผู้ใช้ได้พิมพ์และส่งข้อความ เชื่อมฟังก์ชันนี้กับปุ่มหรือตัวควบคุมอื่นเพื่อสร้างขั้นตอนการโต้ตอบ เช่น ตัวเลือก แบบทดสอบ หรือแดชบอร์ดแบบเจาะลึก แอปเนทีฟแสดงผลโค้ดวิดเจ็ตแบบโต้ตอบ แต่ไม่เปิดให้ใช้บริดจ์พรอมต์แชตนี้

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

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

- `sendPrompt` ต้องมี [การเปิดใช้งานชั่วคราวโดยผู้ใช้](https://developer.mozilla.org/en-US/docs/Web/Security/User_activation) ภายในวิดเจ็ต โดยจะทำงานเฉพาะในช่วงไม่กี่วินาทีหลังผู้ใช้คลิกหรือกดปุ่มในวิดเจ็ต ดังนั้นให้เชื่อมกับปุ่มและเป้าหมายการคลิกอื่น ๆ — การเรียกโดยอัตโนมัติขณะโหลดจะไม่มีผล บริดจ์จะเก็บปลายทางการส่งไว้เป็นส่วนตัวสำหรับตัวเองและปิดกั้นโดยค่าเริ่มต้นในเบราว์เซอร์ที่ไม่เปิดเผยการเปิดใช้งานโดยผู้ใช้ ดังนั้นโค้ดวิดเจ็ตจึงไม่สามารถหลีกเลี่ยงการตรวจสอบได้
- สิทธิ์ในการส่งพรอมต์เป็นของเอกสารวิดเจ็ตต้นฉบับเท่านั้น บริดจ์ที่เชื่อถือได้จะเสนอปลายทางช่องทางของตนให้แชตก่อนที่โค้ดวิดเจ็ตจะทำงานหรือนำทางเฟรมได้ แชตจะรับเฉพาะข้อเสนอแรก และช่องทางจะสิ้นสุดพร้อมเอกสารเมื่อมีการนำทาง 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`](/th/web/control-ui#hosted-embeds) ระดับเริ่มต้น `scripts` รองรับวิดเจ็ตแบบโต้ตอบพร้อมคงการแยกต้นทางไว้

ความเสี่ยงคงเหลือที่ยอมรับได้จากการส่งข้อมูลออกผ่านช่องข้อมูล WebRTC มีบันทึกไว้ใน [สถาปัตยกรรมแดชบอร์ด](/th/web/dashboard-architecture#modeled-residual-webrtc-data-channels)

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

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

- [การฝังที่โฮสต์โดย Control UI](/th/web/control-ui#hosted-embeds)
- [กิจกรรม Discord](/th/channels/discord-activities)
- [การควบคุมโหนด Canvas](/th/plugins/reference/canvas)
- [ความสามารถของไคลเอนต์โปรโตคอล Gateway](/th/gateway/protocol#client-capabilities)