---
read_when:
    - คุณกำลังสร้างแอปภายนอก สคริปต์ แดชบอร์ด งาน CI หรือส่วนขยาย IDE ที่สื่อสารกับ OpenClaw
    - คุณกำลังเลือกระหว่าง Gateway RPC กับ Plugin SDK
    - คุณกำลังผสานรวมกับการเรียกใช้เอเจนต์ เซสชัน เหตุการณ์ การอนุมัติ โมเดล หรือเครื่องมือของ Gateway
    - คุณกำลังจับคู่ตัวควบคุมโฮสติ้งกับตัวกำหนดเวลาปลุกภายนอก
sidebarTitle: External apps
summary: แนวทางการผสานรวมปัจจุบันสำหรับแอปภายนอก สคริปต์ แดชบอร์ด งาน CI และส่วนขยาย IDE
title: การผสานรวม Gateway สำหรับแอปภายนอก
x-i18n:
    generated_at: "2026-07-12T16:04:54Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 0034db64dea64f8c5c400cf2adc69c6e046d0cd574914fe7497099018cb28745
    source_path: gateway/external-apps.md
    workflow: 16
---

แอปภายนอกสื่อสารกับ OpenClaw ผ่านโปรโตคอล Gateway ซึ่งประกอบด้วยการรับส่งข้อมูลผ่าน WebSocket
และเมธอด RPC ใช้โปรโตคอลนี้เมื่อสคริปต์ แดชบอร์ด งาน CI ส่วนขยาย IDE
หรือโปรเซสอื่นต้องการเริ่มการทำงานของเอเจนต์ สตรีมเหตุการณ์ รอ
ผลลัพธ์ ยกเลิกงาน หรือตรวจสอบทรัพยากรของ Gateway

<Warning>
  ขณะนี้ยังไม่มีแพ็กเกจไคลเอนต์ npm สาธารณะ อย่าเพิ่มชื่อแพ็กเกจไคลเอนต์
  OpenClaw เป็นการขึ้นต่อกันของแอปพลิเคชัน จนกว่าบันทึกประจำรุ่นจะประกาศแพ็กเกจ
  ที่เผยแพร่แล้ว และหน้านี้มีคำแนะนำในการติดตั้ง
</Warning>

<Note>
  หน้านี้มีไว้สำหรับโค้ดที่อยู่นอกโปรเซส OpenClaw ส่วนโค้ด Plugin ที่ทำงาน
  ภายใน OpenClaw ควรใช้พาธย่อย `openclaw/plugin-sdk/*` ที่มีเอกสารกำกับแทน
</Note>

## สิ่งที่พร้อมใช้งานในปัจจุบัน

| ส่วนเชื่อมต่อ                             | สถานะ       | ใช้สำหรับ                                                                                              |
| --------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| [โปรโตคอล Gateway](/th/gateway/protocol)   | พร้อมใช้งาน | การรับส่งข้อมูลผ่าน WebSocket การจับมือเชื่อมต่อ ขอบเขตการยืนยันตัวตน การกำหนดเวอร์ชันโปรโตคอล และเหตุการณ์ |
| [ข้อมูลอ้างอิง RPC ของ Gateway](/th/reference/rpc) | พร้อมใช้งาน | เมธอด Gateway ปัจจุบันสำหรับเอเจนต์ เซสชัน งาน โมเดล เครื่องมือ อาร์ติแฟกต์ และการอนุมัติ                     |
| [`openclaw agent`](/th/cli/agent)          | พร้อมใช้งาน | การผสานรวมสคริปต์แบบครั้งเดียว เมื่อเรียกใช้ CLI ผ่านเชลล์ก็เพียงพอ                                      |
| [`openclaw message`](/th/cli/message)      | พร้อมใช้งาน | การส่งข้อความหรือการดำเนินการของช่องทางจากสคริปต์                                                        |

แพ็กเกจไลบรารีไคลเอนต์ในอนาคตกำลังอยู่ระหว่างการพัฒนาภายใน แต่ยังไม่ใช่
ส่วนเชื่อมต่อสำหรับติดตั้งแบบสาธารณะ ให้ถือว่าเป็นรายละเอียดการใช้งานรุ่นตัวอย่าง จนกว่าจะมี
รุ่นที่ประกาศแพ็กเกจที่เผยแพร่และมีการกำหนดเวอร์ชันแล้ว

## แนวทางที่แนะนำ

1. เรียกใช้หรือค้นหา Gateway
2. เชื่อมต่อผ่าน[โปรโตคอล Gateway](/th/gateway/protocol)
3. เรียกเมธอด RPC ที่มีเอกสารกำกับจาก[ข้อมูลอ้างอิง RPC ของ Gateway](/th/reference/rpc)
4. ตรึงเวอร์ชัน OpenClaw ที่คุณใช้ทดสอบ
5. ตรวจสอบข้อมูลอ้างอิง RPC อีกครั้งเมื่ออัปเกรด OpenClaw

สำหรับการทำงานของเอเจนต์ ให้เริ่มด้วย RPC `agent` และใช้ร่วมกับ `agent.wait` เพื่อรับ
ผลลัพธ์สุดท้าย สำหรับสถานะการสนทนาที่คงอยู่ ให้ใช้เมธอด `sessions.*`
สำหรับการผสานรวม UI ให้สมัครรับเหตุการณ์ของ Gateway และแสดงผลเฉพาะกลุ่มเหตุการณ์
ที่แอปของคุณเข้าใจ

## การระงับโฮสต์แบบร่วมมือกัน

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

1. หยุดรับทราฟฟิกขาเข้าภายนอกที่โฮสต์ควบคุม
2. เรียก `gateway.suspend.prepare` พร้อม `requestId` ที่คงที่และไม่ซ้ำกัน
3. หากการตอบกลับเป็น `busy` ให้โปรเซสทำงานต่อและลองอีกครั้งภายหลัง
4. หากเป็น `ready` ให้บันทึก `suspensionId` ที่ส่งคืน จากนั้นหยุดชั่วคราวหรือสร้างสแนปช็อต
   ของโปรเซสก่อน `expiresAtMs`
5. หลังจากปลดการหยุดชั่วคราว หรือหากยกเลิกการระงับ ให้เรียก `gateway.suspend.resume`
   พร้อม `suspensionId` นั้นผ่าน WebSocket เดิมหรือพาธควบคุม Admin HTTP

Gateway ที่เตรียมพร้อมแล้วจะปฏิเสธการจับมือ WebSocket ใหม่ ตัวควบคุม WebSocket
ต้องเปิดการเชื่อมต่อที่ยืนยันตัวตนแล้วไว้ตลอดการดำเนินการของโฮสต์ หากไม่สามารถ
รับประกันได้ ให้เปิดใช้งานและใช้
[Plugin Admin HTTP RPC](/th/plugins/admin-http-rpc) ก่อนเตรียมพร้อม หาก
พาธควบคุมขาดหาย ให้รอสัญญาเช่าสองนาทีหมดอายุก่อน
เชื่อมต่อใหม่ เมื่อหมดอายุ ระบบจะเปิดรับการเชื่อมต่ออีกครั้งโดยอัตโนมัติ

สัญญา RPC มีดังนี้:

- `gateway.suspend.prepare` — `operator.admin`; พารามิเตอร์
  `{ "requestId": "stable-host-operation-id" }`
- `gateway.suspend.status` — `operator.read`; พารามิเตอร์
  `{ "suspensionId": "id-from-prepare" }`
- `gateway.suspend.resume` — `operator.admin`; พารามิเตอร์
  `{ "suspensionId": "id-from-prepare" }`

ID จะถูกตัดช่องว่างหัวท้าย ต้องมีอักขระที่ไม่ใช่ช่องว่าง และจำกัดความยาวไว้ที่
128 อักขระ ผลลัพธ์การเตรียมพร้อมที่ไม่ว่างมี `status: "busy"`, `reason`,
`retryAfterMs`, `activeCount` และ `blockers` ผลลัพธ์พร้อมใช้งานมีรูปแบบดังนี้:

```json
{
  "status": "ready",
  "suspensionId": "2c3f...",
  "expiresAtMs": 1770000000000,
  "activeCount": 0,
  "blockers": []
}
```

สถานะจะส่งคืน `{"status":"running"}` หรือผลลัพธ์พร้อมใช้งานที่มี `expiresAtMs`
การทำงานต่อจะส่งคืน `{"ok":true,"status":"running","resumed":true}` ส่วนการเรียกซ้ำ
หลังจากทำงานต่อสำเร็จแล้วจะส่งคืน `resumed: false`

ID คำขอที่แข่งขันกันหรือความล้มเหลวชั่วคราวในการให้ตัวกำหนดเวลาทำงานต่อ จะส่งคืน
`UNAVAILABLE` ที่ลองใหม่ได้พร้อม `retryAfterMs` ระหว่างการกู้คืนตัวกำหนดเวลา การเตรียมพร้อม สถานะ
และการทำงานต่อทั้งหมดจะส่งคืนข้อผิดพลาดนั้น Gateway จะยังคงไม่พร้อมใช้งานและ
ปิดกั้นเมื่อเกิดความล้มเหลว และโฮสต์ต้องไม่หยุดชั่วคราวหรือสร้างสแนปช็อต OpenClaw จะลองกู้คืน
ตัวกำหนดเวลาใหม่โดยอัตโนมัติ และเปิดรับการเชื่อมต่ออีกครั้งหลังจากกู้คืนสำเร็จเท่านั้น
ID สำหรับทำงานต่อที่ไม่ตรงกันจะส่งคืน `INVALID_REQUEST` การเตรียมพร้อมใช้
โควตาการเขียนของระนาบควบคุม Gateway ร่วมกันที่สามครั้งต่อนาที โปรดปฏิบัติตาม
ระยะเวลารอก่อนลองใหม่ที่ส่งคืน ไคลเอนต์ WebSocket ถูกจัดกลุ่มโควตาตามอุปกรณ์และ IP
ตัวควบคุม Admin HTTP ถูกจัดกลุ่มโควตาตาม IP ไคลเอนต์ที่ระบุได้ ดังนั้นตัวควบคุมที่อยู่หลัง
พร็อกซีเดียวกันอาจใช้โควตาร่วมกัน

การเตรียมพร้อมเป็นการปฏิเสธเท่านั้น: OpenClaw ปิดการรับงาน root/เซสชัน/คำสั่งใหม่
หยุดรอบ cron อัตโนมัติชั่วคราว และตรวจสอบงานแบบซิงโครนัส หากมีสิ่งใด
กำลังทำงานอยู่ ระบบจะให้ตัวกำหนดเวลาทำงานต่อและเปิดรับการเชื่อมต่ออีกครั้งก่อนส่งคืน
`busy` โดยจะไม่ขัดจังหวะหรือระบายงานนั้น สัญญาเช่าพร้อมใช้งานมีอายุสอง
นาที การเรียก `prepare` ซ้ำด้วย `requestId` เดิมจะต่ออายุสัญญา เมื่อหมดอายุ
ระบบจะให้ตัวกำหนดเวลาทำงานต่อก่อนเปิดรับการเชื่อมต่ออีกครั้ง
การส่งสัญญาณรีสตาร์ตที่ถึงกำหนดระหว่างสัญญาเช่าพร้อมใช้งานจะรอจนกว่าสัญญาเช่า
จะกลับมาทำงานต่อ ส่วนการรีสตาร์ตที่กำลังดำเนินอยู่จะทำให้การเตรียมพร้อมส่งคืน `busy`

ขณะพร้อมใช้งาน `/healthz` ยังคงตอบสนอง และ `/readyz` ส่งคืน `503` การตอบกลับ
ความพร้อมใช้งานแบบภายในเครื่องหรือที่ยืนยันตัวตนแล้วจะมี `gateway-draining` ส่วนโพรบระยะไกล
ที่ไม่ได้ยืนยันตัวตนจะได้รับเพียง `{ "ready": false }` โพรบสถานะ HTTP
เมธอดระงับบนการเชื่อมต่อ WebSocket ที่มีอยู่ และเส้นทาง Admin HTTP RPC
ที่เปิดใช้งานอยู่แล้วจะยังคงพร้อมใช้งาน RPC อื่นจะส่งคืน `UNAVAILABLE`
ที่ลองใหม่ได้ เส้นทาง HTTP สำหรับงานผู้ใช้ที่มีมาให้และเส้นทาง HTTP ของ Plugin ทั่วไป
รวมถึง API ที่เข้ากันได้กับ OpenAI การดำเนินการเกี่ยวกับเครื่องมือ/เซสชัน การเฝ้าดู Node และ
ฮุกที่กำหนดค่าไว้ จะส่งคืน `503` พร้อม `error.code: "gateway_unavailable"` การอัปเกรด
WebSocket ใหม่ที่ Plugin เป็นเจ้าของจะส่งคืน `503` เช่นกัน ขอบเขตนี้ครอบคลุมความเป็นเจ้าของ
การอัปเกรด ไม่ใช่งานที่ดำเนินการภายหลังผ่านซ็อกเก็ต Plugin ที่สร้างการเชื่อมต่อแล้ว

การจับมือนี้ไม่จัดเก็บข้อความขาเข้าแบบถาวร ไม่หยุดการรับส่งข้อมูลของช่องทางบุคคลที่สาม
และไม่ควบคุมแพลตฟอร์มโฮสติ้ง โฮสต์ต้องกั้นทราฟฟิกขาเข้าของตน
ก่อนเตรียมพร้อม และยังคงรับผิดชอบการปลุก การสร้างสแนปช็อต/การหยุดชั่วคราว และ
การหยุด `activeCount` คือจำนวนรวมของงานที่ติดตาม ส่วน `blockers`
ประกอบด้วยจำนวนหมวดหมู่ที่ไม่เป็นศูนย์และรายละเอียดงานแบบจำกัด นี่ไม่ใช่
แนวกั้นเพื่อให้ทั้งโปรเซสเข้าสู่ภาวะสงบโดยทั่วไป ตัวขัดขวาง `background-exec` เป็นเพียงข้อมูลรวม:
ข้อความคำสั่ง ID โปรเซส เอาต์พุต และตัวระบุเซสชันหรือขอบเขตจะไม่
ถูกส่งผ่านโปรโตคอล สถานะช่องทาง การบำรุงรักษา การรีเฟรชแคช เซสชัน
WebSocket ของ Plugin ที่เชื่อมต่อแล้ว และงานเบื้องหลังที่ Plugin เป็นเจ้าของแต่ไม่ได้ลงทะเบียน
อาจยังคงทำงานอยู่
แพลตฟอร์มโฮสติ้งต้องหยุดชั่วคราวหรือสร้างสแนปช็อตของผังโปรเซสทั้งหมดและ
ระบบไฟล์อย่างสอดคล้องกัน สัญญาฉบับแรกนี้ไม่สามารถพิสูจน์ได้ว่างานที่ไม่ได้ลงทะเบียน
อยู่ในสถานะว่าง

<Tip>
  สำหรับการกำหนดเวลาปลุกโฮสต์ ให้เก็บส่วนที่เชื่อมกับ OpenClaw ไว้ใน Plugin
  ภายในโปรเซส และฉายสแนปช็อตแบบเต็มที่ทำซ้ำได้อย่างปลอดภัยไปยังอะแดปเตอร์โฮสต์ภายนอก
  ตัวควบคุมโฮสติ้งไม่ควรนำเข้า Plugin SDK หรือสร้างสถานะ cron
  ขึ้นใหม่จากส่วนต่างของเหตุการณ์ ดู[การฉาย cron ภายนอกอย่างปลอดภัย](/th/plugins/hooks#safe-external-cron-projection)
</Tip>

## โค้ดแอปเทียบกับโค้ด Plugin

ใช้ Gateway RPC เมื่อโค้ดอยู่นอก OpenClaw:

- สคริปต์ Node ที่เริ่มหรือสังเกตการทำงานของเอเจนต์
- งาน CI ที่เรียก Gateway
- แดชบอร์ดและแผงผู้ดูแลระบบ
- ส่วนขยาย IDE
- บริดจ์ภายนอกที่ไม่จำเป็นต้องเป็น Plugin ช่องทาง
- การทดสอบการผสานรวมที่ใช้การรับส่งข้อมูล Gateway จำลองหรือจริง

ใช้ Plugin SDK เมื่อโค้ดทำงานภายใน OpenClaw:

- Plugin ผู้ให้บริการ
- Plugin ช่องทาง
- ฮุกเครื่องมือหรือวงจรชีวิต
- Plugin ชุดควบคุมเอเจนต์
- ตัวช่วยรันไทม์ที่เชื่อถือได้

แอปภายนอกไม่ควรนำเข้า `openclaw/plugin-sdk/*` พาธย่อยเหล่านั้นมีไว้สำหรับ
Plugin ที่ OpenClaw โหลด

## เนื้อหาที่เกี่ยวข้อง

- [โปรโตคอล Gateway](/th/gateway/protocol)
- [ข้อมูลอ้างอิง RPC ของ Gateway](/th/reference/rpc)
- [คำสั่งเอเจนต์ CLI](/th/cli/agent)
- [คำสั่งข้อความ CLI](/th/cli/message)
- [ลูปเอเจนต์](/th/concepts/agent-loop)
- [รันไทม์เอเจนต์](/th/concepts/agent-runtimes)
- [เซสชัน](/th/concepts/session)
- [งานเบื้องหลัง](/th/automation/tasks)
- [เอเจนต์ ACP](/th/tools/acp-agents)
- [ภาพรวม Plugin SDK](/th/plugins/sdk-overview)