---
read_when:
    - การสร้างไคลเอนต์สำหรับผู้ดำเนินการ แดชบอร์ด หรือ WebChat ภายนอกที่เก็บ OpenClaw
    - การติดตั้งใช้งานการเชื่อมต่อ Gateway ใหม่ ประวัติ การอนุมัติ หรือการจับคู่อุปกรณ์
    - การอัปเดตไคลเอ็นต์ของบุคคลที่สามสำหรับเวอร์ชันโปรโตคอลแบบ wire ใหม่ของ Gateway
summary: สร้างไคลเอนต์โอเปอเรเตอร์หรือ WebChat ของบุคคลที่สามสำหรับโปรโตคอล WebSocket ของ Gateway
title: การสร้างไคลเอนต์ Gateway
x-i18n:
    generated_at: "2026-07-20T15:58:24Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: fa24b196ff1fa28fb3b64d49ac25597f22cf1945aea56029e78e4375f1bdddb7
    source_path: gateway/clients.md
    workflow: 16
---

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

สำหรับรูปแบบเฟรม การจับมือ ข้อผิดพลาด และชุดเมธอดทั้งหมด โปรดอ่าน
[ข้อกำหนดโปรโตคอล Gateway](https://docs.openclaw.ai/gateway/protocol)

## ติดตั้งแพ็กเกจ

```bash
npm install @openclaw/gateway-client @openclaw/gateway-protocol
```

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

- [`@openclaw/gateway-protocol`](https://www.npmjs.com/package/@openclaw/gateway-protocol)
  มีสคีมา ตัวตรวจสอบความถูกต้องขณะรันไทม์ ชนิด TypeScript รีจิสทรีข้อมูลประจำตัวและ
  ความสามารถของไคลเอนต์ ตัวอ่านข้อผิดพลาดแบบมีโครงสร้าง และค่าคงที่เวอร์ชันโปรโตคอล
  tarball บน npm ยังมีสัญญาที่เครื่องอ่านได้ซึ่งสร้างขึ้นเป็น
  [`protocol.schema.json`](https://unpkg.com/@openclaw/gateway-protocol/protocol.schema.json)
- [`@openclaw/gateway-client`](https://www.npmjs.com/package/@openclaw/gateway-client)
  เป็นการใช้งานการเชื่อมต่ออ้างอิง ให้นำเข้าจากรากของแพ็กเกจสำหรับไคลเอนต์ Node
  และ `@openclaw/gateway-client/browser` สำหรับโปรโตคอลที่ปลอดภัยสำหรับเบราว์เซอร์
  ตัวช่วยการยืนยันตัวตนของอุปกรณ์ และตัวช่วยการเชื่อมต่อใหม่

จุดเข้า Node จัดการการขนส่ง WebSocket ของตนเอง โฮสต์เบราว์เซอร์จะจัดหาอะแดปเตอร์ WebSocket
พร้อมพื้นที่จัดเก็บถาวรและคอลแบ็กการลงนามสำหรับข้อมูลประจำตัวของอุปกรณ์และ
โทเค็นอุปกรณ์

## เลือกขอบเขตและจับคู่อุปกรณ์

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

| ขอบเขต                | ใช้สำหรับ                                                                                |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `operator.read`      | `chat.history`, `sessions.list`, `sessions.subscribe`, สถานะโมเดล และเหตุการณ์แบบอ่านอย่างเดียว |
| `operator.write`     | `chat.send` และการเปลี่ยนแปลงเซสชันทั่วไป                                                |
| `operator.approvals` | การแสดงรายการ การแสดงผล และการตัดสินคำขออนุมัติ exec หรือ Plugin                               |

เพิ่ม `operator.questions` เฉพาะเมื่อไคลเอนต์จัดการคำถามแบบโต้ตอบ
เพิ่ม `operator.pairing` เฉพาะเมื่อไคลเอนต์จัดการอุปกรณ์หรือ Node ที่จับคู่แล้ว และ
เพิ่ม `operator.admin` เฉพาะสำหรับการดำเนินการด้านการดูแล เช่น `config.patch`
[ข้อมูลอ้างอิงขอบเขตผู้ปฏิบัติงาน](https://docs.openclaw.ai/gateway/operator-scopes)
กำหนดกฎทั้งหมดสำหรับเมธอดและช่วงเวลาการอนุมัติ

อย่าสร้าง bearer token แยกสำหรับแต่ละไคลเอนต์ด้วยการแก้ไข `openclaw.json` ด้วยตนเอง ให้กำหนดค่า
การยืนยันตัวตนเริ่มต้นที่ใช้ร่วมกันของ Gateway ด้วย `openclaw configure --section
gateway` หรือตัวเลือก `openclaw onboard --gateway-auth ...` จากนั้นให้การจับคู่
อุปกรณ์ออกโทเค็นของไคลเอนต์:

1. จัดเก็บข้อมูลประจำตัวอุปกรณ์ Ed25519 แบบถาวรในไคลเอนต์
2. รอ `connect.challenge` ลงนามเพย์โหลดอุปกรณ์ที่ผูกกับชาเลนจ์ และส่ง
   `connect` พร้อมบทบาทผู้ปฏิบัติงาน ขอบเขตที่ร้องขอ และโทเค็น Gateway
   หรือรหัสผ่านที่ใช้ร่วมกันสำหรับการยืนยันตัวตนเริ่มต้น
3. หาก Gateway ส่งคืนรายละเอียด `PAIRING_REQUIRED` แบบมีโครงสร้าง ให้แสดง ID คำขอ
   และหยุดชั่วคราวหรือลองใหม่ตาม `error.details.recommendedNextStep`
4. บนโฮสต์ Gateway ให้ตรวจสอบคำขอด้วย `openclaw devices list` จากนั้น
   อนุมัติคำขอปัจจุบันนั้นโดยตรงด้วย `openclaw devices approve <requestId>`
5. เชื่อมต่อใหม่และจัดเก็บ `hello-ok.auth.deviceToken` แบบถาวรพร้อมบทบาทและ
   ขอบเขตที่เจรจาแล้ว ใช้โทเค็นอุปกรณ์นั้นสำหรับการเชื่อมต่อในภายหลัง

การอัปเกรดขอบเขตหรือบทบาทจะสร้างคำขอจับคู่ใหม่ที่รอดำเนินการ การหมุนเวียนโทเค็นไม่สามารถ
ขยายสัญญาการจับคู่ที่ได้รับอนุมัติ โปรดดู
[CLI อุปกรณ์](https://docs.openclaw.ai/cli/devices) สำหรับคำสั่งอนุมัติ หมุนเวียน และ
เพิกถอน

## ประกาศความสามารถของไคลเอนต์

`connect.params.caps` อธิบายลักษณะการทำงานทางเลือกที่ไคลเอนต์สามารถใช้ได้ แต่
ไม่ได้มอบสิทธิ์ ให้นำเข้าชื่อจาก `GATEWAY_CLIENT_CAPS` แทนการ
เขียนลิเทอรัลสตริงซ้ำ:

```ts
import { GATEWAY_CLIENT_CAPS } from "@openclaw/gateway-protocol/client-info";

const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];
```

รีจิสทรีปัจจุบันประกอบด้วย `approvals`, `exec-approvals`, `inline-widgets`,
`run-tool-bindings`, `session-scoped-events`, `plugin-approvals`,
`task-suggestions`, `terminal-offset-seq`, `tool-events` และ `ui-commands`
ประกาศเฉพาะความสามารถที่ไคลเอนต์ใช้งานจริงเท่านั้น

<Warning>
`tool-events` ควบคุมการสตรีมการเรียกใช้เครื่องมือแบบสด Gateway จะลงทะเบียนเฉพาะ
การเชื่อมต่อที่ประกาศความสามารถนี้เป็นผู้รับเหตุการณ์เครื่องมือแบบมีโครงสร้างของการรัน
หากไม่มีความสามารถนี้ การเชื่อมต่อจะไม่ได้รับเหตุการณ์เครื่องมือแบบสด และ
การจับมือจะไม่รายงานข้อผิดพลาด
</Warning>

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

## กู้คืนสถานะหลังเชื่อมต่อใหม่

ให้ถือว่าทุกการเชื่อมต่อใหม่ที่สำเร็จเป็นการฉายภาพใหม่จากประวัติที่คงทนและ
สถานะการรันในหน่วยความจำปัจจุบัน:

1. สร้าง `sessions.subscribe` และการสมัครรับ `sessions.messages.subscribe`
   ของเซสชันที่เลือกขึ้นใหม่
2. เรียก `chat.history` สำหรับ `sessionKey` ที่เลือก และแทนที่แถวที่จัดเก็บ
   ภายในเครื่องด้วยการฉายภาพ `messages` ที่ส่งคืน
3. หากมี `inFlightRun` ให้รับ `runId`, `text` ที่บัฟเฟอร์ไว้ และ
   `plan` ซึ่งเป็นทางเลือก ให้รับการรันแม้ว่า `text` จะว่างเปล่า
4. อ่าน `sessionInfo.hasActiveRun` และ `sessionInfo.activeRunIds` ให้ใช้การเป็นสมาชิก
   ใน `activeRunIds` ที่ตรงกันทุกประการเป็นหลัก เมื่อตัดสินว่าการรันที่เก็บไว้ยังคงเป็นเจ้าของ
   UI การสตรีมหรือไม่ ค่า `hasActiveRun` ที่เป็นจริงแต่ไม่มี ID ในรายการอาจแสดงถึง
   การฉายภาพรันไทม์อื่นที่กำลังทำงาน
5. กระทบยอดเหตุการณ์ `agent` ที่ตามมาโดยใช้ `payload.runId` และ `payload.seq`
   รักษาลำดับสูงสุดที่ยอมรับแยกกันสำหรับแต่ละการรัน ละเว้นลำดับที่เห็นแล้วหรือ
   ต่ำกว่า และถือว่าช่องว่างไปข้างหน้าเป็นเหตุผลให้โหลดประวัติจากแหล่งข้อมูลที่เชื่อถือได้ใหม่

เฟรมเหตุการณ์ชั้นนอกยังมี `seq` ซึ่งเป็นทางเลือกและใช้จัดลำดับเหตุการณ์บน
การเชื่อมต่อ WebSocket ปัจจุบัน ค่านี้จะรีเซ็ตเมื่อมีการเชื่อมต่อใหม่ ส่วน `seq` ภายใน
เพย์โหลดเหตุการณ์ `agent` จะถูกกำหนดแยกต่อการรัน และจัดลำดับวงจรชีวิต
ผู้ช่วย แผน เครื่องมือ และเหตุการณ์สตรีมอื่นๆ ของการรันนั้น

## ใช้ข้อมูลเมตาของประวัติและจุดยึดที่เสถียร

แถวที่ `chat.history` ส่งคืนสามารถมีซองข้อมูลเมตา `__openclaw`:

- `id` คือข้อมูลประจำตัวของรายการทรานสคริปต์ ใช้สำหรับคำขอประวัติแบบมีจุดยึด
  แต่ห้ามใช้เป็นคีย์แถวแสดงผลที่ไม่ซ้ำกัน
- `seq` คือลำดับระเบียนทรานสคริปต์ที่เป็นจำนวนบวก ระเบียนหนึ่งที่จัดเก็บไว้อาจฉายภาพ
  เป็นแถวแสดงผลมากกว่าหนึ่งแถว ดังนั้นให้เก็บแถวที่เกี่ยวข้องซึ่งมี `id` และลำดับเดียวกัน
  ไว้ด้วยกัน
- `kind` ระบุแถวสังเคราะห์ ขอบเขต Compaction ใช้
  `kind: "compaction"` และอาจมี `tokensBefore` และ `tokensAfter` เมื่อ
  จุดตรวจที่ตรงกันบันทึกเมตริกเหล่านั้นไว้

แบ่งหน้าไปย้อนหลังด้วยค่า `hasMore` และ `nextOffset` ของการตอบกลับ ออฟเซ็ตตัวเลข
อธิบายการฉายภาพทรานสคริปต์ปัจจุบัน ดังนั้นอย่าจัดเก็บเป็นบุ๊กมาร์กระยะยาว
ข้ามการรีเซ็ตหรือ Compaction ให้จัดเก็บ `__openclaw.id` แทน
หากต้องการคืนค่าบริเวณรอบแถวที่ทราบ ให้เรียก `chat.history` พร้อม `messageId` และ
`sessionId` ที่ส่งแถวนั้นคืนมา Gateway สามารถแก้ไขจุดยึดนั้นจากประวัติที่เก็บถาวร
หลังการรีเซ็ตได้ การตอบกลับแบบมีจุดยึดจะละเว้นข้อมูลเมตาการแบ่งหน้าแบบตัวเลขโดยตั้งใจ

## สมัครรับข้อมูลแทนการสำรวจการใช้งานเป็นระยะ

โหลดแค็ตตาล็อกเริ่มต้นด้วย `sessions.list` จากนั้นเรียก `sessions.subscribe` หนึ่งครั้ง
ต่อการเชื่อมต่อ ผสานเหตุการณ์ `sessions.changed` โดยใช้ `sessionKey` เพย์โหลดการเปลี่ยนแปลง
ของเซสชันสามารถมี `inputTokens`, `outputTokens`, `totalTokens`,
`totalTokensFresh`, `contextTokens`, `estimatedCostUsd` แบบสด การตั้งค่าการใช้งาน
ของการตอบกลับ และสถานะการรันที่ทำงานอยู่

การแจ้งเตือนการเปลี่ยนแปลงบางอย่างเป็นเพียงสัญญาณว่าข้อมูลใช้ไม่ได้แล้ว หากเหตุการณ์ละเว้น
ฟิลด์แถวที่มุมมองต้องใช้ ให้รีเฟรช `sessions.list` อย่าสำรวจ `usage.cost` หรือ
`sessions.usage` เป็นระยะเพื่อทำให้รายการเซสชันสดเป็นปัจจุบัน ให้สงวนเมธอดเหล่านั้นไว้สำหรับ
รายงานรวมโดยเรียกใช้เมื่อต้องการหรือรายงานโดยละเอียด

## เติมข้อมูลย้อนหลังสำหรับการอนุมัติ exec

ไคลเอนต์ที่มี `operator.approvals` ควรติดตั้งตัวรับฟังเหตุการณ์ทันทีที่
`hello-ok` เสร็จสมบูรณ์ จากนั้นเรียก `exec.approval.list` เพื่อเติมคำขอที่
เกิดก่อนการเชื่อมต่อ กระทบยอดรายการและเหตุการณ์สด
`exec.approval.requested` / `exec.approval.resolved` โดยใช้ ID การอนุมัติ เพื่อไม่ให้
การเปลี่ยนสถานะที่เกิดพร้อมกับคำขอรายการสูญหายหรือถูกกู้คืนอย่างไม่ถูกต้อง

## ติดตามเวอร์ชันโปรโตคอล

เวอร์ชันการสื่อสารผ่านสายในปัจจุบันคือ `4` ไคลเอนต์ผู้ปฏิบัติงานทั่วไปและ WebChat ต้อง
เจรจาเวอร์ชันปัจจุบันที่ตรงกันทุกประการด้วย `minProtocol: 4` และ `maxProtocol: 4`
เฉพาะไคลเอนต์ Node ที่ยืนยันตัวตนแล้วและโพรบน้ำหนักเบาเท่านั้นที่มีช่วงการยอมรับ N-1
ซึ่งปัจจุบันคือโปรโตคอล `3` ถึง `4`

การเปลี่ยนแปลงโปรโตคอลจะเป็นแบบเพิ่มเติมก่อน `protocol.schema.json` มีข้อมูลเมตา
`since` ของรุ่นที่เผยแพร่และข้อมูลเมตาขอบเขตที่จำเป็นสำหรับเมธอดแกนหลัก
แต่การเพิ่มเวอร์ชันการสื่อสารผ่านสายยังคงเป็นเหตุการณ์ที่ทำให้เกิดความไม่เข้ากันอย่างชัดเจนสำหรับไคลเอนต์
บุคคลที่สาม ให้ตรึงเวอร์ชันแพ็กเกจที่ทดสอบ อัปเกรดไคลเอนต์และ Gateway พร้อมกันเมื่อเวอร์ชัน
การสื่อสารผ่านสายเปลี่ยนแปลง และตรวจสอบ
[บันทึกการเปลี่ยนแปลง OpenClaw](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
ก่อนการอัปเกรดแต่ละครั้ง

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

- [โปรโตคอล Gateway](https://docs.openclaw.ai/gateway/protocol)
- [การฝัง OpenClaw](https://docs.openclaw.ai/gateway/embedding)
- [ข้อมูลอ้างอิง RPC ของ Gateway](https://docs.openclaw.ai/reference/rpc)
- [การผสานรวม Gateway สำหรับแอปภายนอก](https://docs.openclaw.ai/gateway/external-apps)