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

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

<Note>
  สำหรับแพ็กเกจ npm การจับคู่อุปกรณ์ การกู้คืนการเชื่อมต่อใหม่ ประวัติ การสมัครรับข้อมูล
  และการอนุมัติ ให้เริ่มจาก
  [การสร้างไคลเอนต์ Gateway](https://docs.openclaw.ai/gateway/clients) หาก
  แอปของคุณกำกับดูแล Gateway ในฐานะกระบวนการลูก โปรดอ่าน
  [การฝัง OpenClaw](https://docs.openclaw.ai/gateway/embedding) เพิ่มเติม ระหว่าง
  การทยอยเปิดตัวแพ็กเกจครั้งแรก npm อาจส่งคืน `E404` จนกว่าจะเผยแพร่ OpenClaw
  รุ่นแรกที่มีแพ็กเกจ
</Note>

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

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

| ส่วนเชื่อมต่อ                                                          | สถานะ        | ใช้สำหรับ                                                                                    |
| ---------------------------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------- |
| [คู่มือไคลเอนต์ Gateway](https://docs.openclaw.ai/gateway/clients) | รอบการเผยแพร่ | แพ็กเกจ npm การยืนยันตัวตน การเชื่อมต่อใหม่ ประวัติ เหตุการณ์ การอนุมัติ และนโยบายเวอร์ชัน                |
| [คู่มือการฝัง](https://docs.openclaw.ai/gateway/embedding)    | รอบการเผยแพร่ | สภาพแวดล้อมของกระบวนการลูก ความพร้อม วงจรชีวิต การกู้คืน ความเป็นเจ้าของ RPC และการจัดทำแพ็กเกจ      |
| [โปรโตคอล 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 โดย 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 ปิดการรับงานใหม่ระดับรูท/เซสชัน/คำสั่ง
หยุดรอบ 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](https://docs.openclaw.ai/gateway/clients)
- [การฝัง OpenClaw](https://docs.openclaw.ai/gateway/embedding)
- [โปรโตคอล 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)