โปรโตคอล Gateway

โปรโตคอล Gateway WS เป็นระนาบควบคุมและการขนส่ง Node แบบรวมศูนย์สำหรับ OpenClaw ไคลเอนต์ของผู้ดำเนินการและ Node (CLI, UI เว็บ, แอป macOS, Node iOS/Android, Node แบบไม่มีส่วนติดต่อผู้ใช้) เชื่อมต่อผ่าน WebSocket และประกาศ บทบาท และ ขอบเขต ใน ระหว่างแฮนด์เชก

แพ็กเกจ npm

แพ็กเกจเหล่านี้จัดส่งพร้อมรอบการเผยแพร่ OpenClaw ระหว่างการเปิดตัวครั้งแรก npm อาจส่งคืน E404 จนกว่าจะเผยแพร่รุ่นแรกที่มีแพ็กเกจ

• @openclaw/gateway-protocol เผยแพร่สคีมา ตัวตรวจสอบความถูกต้อง ชนิด TypeScript ตัวช่วยขนาดเล็กสำหรับเฟรมและข้อผิดพลาด ตลอดจนค่าคงที่ของเวอร์ชัน tarball ของแพ็กเกจมีสัญญาที่สร้างขึ้นในรูปแบบที่เครื่องอ่านได้ protocol.schema.json
• @openclaw/gateway-client เผยแพร่ไคลเอนต์ Node อ้างอิงและเอนทรีที่ปลอดภัยสำหรับเบราว์เซอร์ที่ @openclaw/gateway-client/browser

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

การขนส่งและการจัดเฟรม

• WebSocket, เฟรมข้อความ, เพย์โหลด JSON
• เฟรมแรก ต้อง เป็นคำขอ connect
• เฟรมก่อนเชื่อมต่อถูกจำกัดไว้ที่ 64 KiB (MAX_PREAUTH_PAYLOAD_BYTES) หลังจาก แฮนด์เชก ให้ปฏิบัติตาม hello-ok.policy.maxPayload และ hello-ok.policy.maxBufferedBytes เมื่อเปิดใช้การวินิจฉัย เฟรมขาเข้าที่มีขนาดเกินกำหนด และบัฟเฟอร์ขาออกที่ทำงานช้าจะปล่อยเหตุการณ์ payload.large ก่อนที่ Gateway จะปิดหรือทิ้งเฟรม เหตุการณ์เหล่านี้มี surface, ขนาดเป็นไบต์, ขีดจำกัด และรหัสเหตุผลที่ปลอดภัย โดยจะไม่มีเนื้อหาข้อความ เนื้อหาไฟล์แนบ ไบต์ดิบของเฟรม โทเค็น คุกกี้ หรือข้อมูลลับ

รูปแบบเฟรม:

• คำขอ: {type:"req", id, method, params}
• การตอบกลับ: {type:"res", id, ok, payload|error}
• เหตุการณ์: {type:"event", event, payload, seq?, stateVersion?}

ข้อผิดพลาดในการตอบกลับใช้ { code, message, details?, retryable?, retryAfterMs? } ไคลเอนต์ควรแยกการทำงานตาม code และ details.code; message ยังคงเป็นข้อความ ที่มนุษย์อ่านได้และอาจเปลี่ยนแปลง เว้นแต่หมายเหตุด้านความเข้ากันได้จะระบุไว้เป็นอย่างอื่น ความล้มเหลว ในการอนุญาตระดับเมธอดใช้ code: "FORBIDDEN" ระดับบนสุด พร้อมรายละเอียด ขอบเขตที่ขาดหายไปแบบมีโครงสร้าง:

• ขอบเขตที่ขาดหายไป: { code: "MISSING_SCOPE", missingScope, requiredScopes } requiredScopes คือชุดขอบเขตที่รู้จักทั้งหมดสำหรับการดำเนินการที่ร้องขอ ข้อความแบบเดิม missing scope: <scope> ยังคงเก็บไว้สำหรับไคลเอนต์รุ่นเก่า

ไคลเอนต์ควรอ่าน details ก่อน และใช้ข้อความแบบเดิมเป็นเพียงทางเลือกสำรอง เพื่อความเข้ากันได้ readMissingScopeError และ readMissingScopeErrorDetails ถูกส่งออกจาก @openclaw/gateway-protocol/gateway-error-details; ไคลเอนต์ Gateway ที่ปลอดภัยสำหรับเบราว์เซอร์ ส่งออกค่าเหล่านี้อีกครั้งจาก @openclaw/gateway-client/browser

สคีมาถูกส่งออกเป็น GatewayErrorDetailsSchema, MissingScopeErrorDetailsSchema จาก @openclaw/gateway-protocol/schema ความล้มเหลวของขอบเขต HTTP สะท้อนออบเจ็กต์ MISSING_SCOPE ภายใต้ error.details และ ใช้สถานะ HTTP 403

เมธอดที่ก่อให้เกิดผลข้างเคียงต้องใช้คีย์ความเป็นไอดอมโพเทนต์ (ดูสคีมา)

แฮนด์เชก

Gateway ส่งชาเลนจ์ก่อนเชื่อมต่อ:

{  "type": "event",  "event": "connect.challenge",  "payload": { "nonce": "…", "ts": 1737264000000 }}

ไคลเอนต์ตอบกลับด้วย connect:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "maxProtocol": 4,    "client": {      "id": "cli",      "version": "1.2.3",      "platform": "macos",      "mode": "operator"    },    "role": "operator",    "scopes": ["operator.read", "operator.write"],    "caps": [],    "commands": [],    "permissions": {},    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-cli/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Gateway ตอบกลับด้วย hello-ok:

{  "type": "res",  "id": "…",  "ok": true,  "payload": {    "type": "hello-ok",    "protocol": 4,    "server": { "version": "…", "connId": "…" },    "features": { "methods": ["…"], "events": ["…"] },    "snapshot": { "…": "…" },    "auth": {      "role": "operator",      "scopes": ["operator.read", "operator.write"]    },    "policy": {      "maxPayload": 26214400,      "maxBufferedBytes": 52428800,      "tickIntervalMs": 15000    }  }}

server, features, snapshot, policy และ auth ล้วนเป็นค่าที่ HelloOkSchema (packages/gateway-protocol/src/schema/frames.ts) กำหนดให้ต้องมี auth รายงานบทบาท/ขอบเขตที่เจรจาแล้ว แม้จะไม่มีการออกโทเค็นอุปกรณ์ (รูปแบบ ด้านบน) pluginSurfaceUrls เป็นค่าเสริมและแมปชื่อพื้นผิวของ Plugin (เช่น canvas) กับ URL ที่โฮสต์และมีขอบเขต URL อาจหมดอายุ ดังนั้น Node จึงเรียก node.pluginSurface.refresh พร้อม { "surface": "canvas" } เพื่อรับเอนทรีใหม่ ไม่รองรับเส้นทาง canvasHostUrl / canvasCapability / node.canvas.capability.refresh ที่เลิกใช้แล้ว ให้ใช้พื้นผิวของ Plugin ค่าเสริม appliedConfigHash ของสแนปช็อตคือรีวิชันการกำหนดค่าต้นทางที่แก้ไขแล้ว ซึ่งรันไทม์ Gateway ที่ทำงานอยู่ยอมรับ ไคลเอนต์สามารถเปรียบเทียบค่านี้กับ config.get.configRevisionHash เพื่อพิจารณาว่าการกำหนดค่าที่บันทึกไว้ซึ่งใหม่กว่า ยังต้องรีสตาร์ตหรือไม่ config.get.hash ยังคงเป็นรีวิชันดิบของไฟล์รากที่ใช้โดย ตัวป้องกันข้อขัดแย้งในการเขียนการกำหนดค่า

ขณะที่ Gateway ยังดำเนินการเริ่มต้นไซด์คาร์ให้เสร็จสิ้น connect อาจส่งคืน ข้อผิดพลาด UNAVAILABLE ที่ลองใหม่ได้ พร้อม details.reason: "startup-sidecars" และ retryAfterMs ให้ลองใหม่ภายในงบประมาณการเชื่อมต่อ แทนที่จะถือว่าเป็น ความล้มเหลวขั้นสุดท้ายของแฮนด์เชก

เมื่อมีการออกโทเค็นอุปกรณ์ hello-ok.auth จะเพิ่มโทเค็นดังกล่าว:

{  "auth": {    "deviceToken": "…",    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

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

{  "auth": {    "deviceToken": "…",    "role": "node",    "scopes": [],    "deviceTokens": [      {        "deviceToken": "…",        "role": "operator",        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]      }    ]  }}

การส่งต่อให้ผู้ดำเนินการนี้ถูกจำกัดไว้โดยตั้งใจ: เพียงพอสำหรับเริ่มลูป ผู้ดำเนินการบนอุปกรณ์เคลื่อนที่และการตั้งค่าแบบเนทีฟ รวมถึง operator.talk.secrets สำหรับการอ่าน การกำหนดค่า Talk แต่ไม่มีขอบเขตสำหรับแก้ไขการจับคู่และไม่มี operator.admin การเข้าถึง การจับคู่/ผู้ดูแลระบบที่กว้างกว่านี้ต้องใช้การจับคู่หรือขั้นตอนโทเค็นที่ได้รับอนุมัติแยกต่างหาก ให้เก็บ hello-ok.auth.deviceTokens ไว้เฉพาะเมื่อการรับรองความถูกต้องแบบบูตสแตรปทำงานผ่านการขนส่ง ที่เชื่อถือได้ (wss:// หรือการจับคู่แบบลูปแบ็ก/ภายในเครื่อง)

ไคลเอนต์แบ็กเอนด์ในโปรเซสเดียวกันที่เชื่อถือได้ (client.id: "gateway-client", client.mode: "backend") อาจละเว้น device บนการเชื่อมต่อลูปแบ็กโดยตรง เมื่อ รับรองความถูกต้องด้วยโทเค็น/รหัสผ่าน Gateway ที่ใช้ร่วมกัน เส้นทางนี้สงวนไว้ สำหรับ RPC ภายในของระนาบควบคุม (เช่น การอัปเดตเซสชันของเอเจนต์ย่อย) และป้องกันไม่ให้ ข้อมูลพื้นฐานการจับคู่ CLI/อุปกรณ์ที่ล้าสมัยขัดขวางงานแบ็กเอนด์ภายในเครื่อง ไคลเอนต์ระยะไกล, จากต้นทางเบราว์เซอร์, Node และไคลเอนต์ที่ระบุโทเค็นอุปกรณ์/ข้อมูลประจำตัวอุปกรณ์อย่างชัดเจน ยังคง ผ่านการตรวจสอบการจับคู่และการยกระดับขอบเขตตามปกติ

บทบาทเวิร์กเกอร์และโปรโตคอลแบบปิด

เวิร์กเกอร์คลาวด์ใช้อินเกรสลูปแบ็กเฉพาะผ่านทันเนล SSH ที่ Gateway เป็นเจ้าของ และตรึงคีย์โฮสต์ อินเกรสนี้ยอมรับเฉพาะข้อมูลประจำตัวของเวิร์กเกอร์ และจะไม่ส่งต่อ การรับรองความถูกต้องทั่วไป เหตุการณ์ Node, RPC ของผู้ดำเนินการ หรือเมธอดของ Plugin โดยเด็ดขาด connect ที่เข้มงวด จะตรวจสอบข้อมูลประจำตัวอายุสั้นซึ่งแฮชขณะจัดเก็บและผูกกับสภาพแวดล้อม แฮชของบันเดิล เอพ็อกของเจ้าของ เวอร์ชันชุด RPC วันหมดอายุ และเซสชันที่เป็นค่าว่างได้หนึ่งเซสชัน โดย ตรวจสอบเวอร์ชันปัจจุบันและชุดฟีเจอร์แยกต่างหาก เมื่อสำเร็จจะส่งคืน worker-hello-ok ขั้นต่ำ การเจรจาฟีเจอร์ไม่ขึ้นกับเวอร์ชันโปรโตคอลทั่วไป เฟรมยังคงมีขนาดต่ำกว่า 64 KiB ยกเว้นเฟรม worker.inference.start ที่เจรจาแล้วอาจมีขนาดได้ถึง 25 MiB รายการอนุญาตแบบปิดประกอบด้วย worker.heartbeat, worker.transcript.commit, worker.live-event, worker.inference.start และ worker.inference.cancel

การคอมมิตทรานสคริปต์ใช้การกั้นด้วยเอพ็อกของเจ้าของ การผูกเซสชันที่ Gateway เป็นเจ้าของ การเปรียบเทียบและสลับลีฟฐาน และการเล่นลำดับซ้ำแบบถาวร Gateway สร้าง เอนทรีทรานสคริปต์และ ID พาเรนต์ผ่านตัวเขียนเซสชันตามปกติ โดยจะตรวจสอบความเป็นเจ้าของและ วันหมดอายุอีกครั้งใน RPC แต่ละครั้ง

ความสามารถของไคลเอนต์

ไคลเอนต์ผู้ดำเนินการอาจประกาศความสามารถเสริมใน connect.params.caps:

• tool-events: ยอมรับเหตุการณ์วงจรชีวิตของเครื่องมือแบบมีโครงสร้าง
• inline-widgets: สามารถเรนเดอร์ผลลัพธ์ของเครื่องมือวิดเจ็ตอินไลน์ที่โฮสต์ไว้

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

ตัวอย่างการเชื่อมต่อ Node

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "maxProtocol": 4,    "client": {      "id": "ios-node",      "version": "1.2.3",      "platform": "ios",      "mode": "node"    },    "role": "node",    "scopes": [],    "caps": ["camera", "canvas", "screen", "location", "voice"],    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],    "permissions": { "camera.capture": true, "screen.record": false },    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-ios/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Node ประกาศการอ้างสิทธิ์ความสามารถในขณะเชื่อมต่อ:

• caps: หมวดหมู่ระดับสูง เช่น camera, canvas, screen, location, voice, talk
• commands: รายการอนุญาตคำสั่งสำหรับการเรียกใช้
• permissions: ตัวสลับแบบละเอียด (เช่น screen.record, camera.capture)

Gateway ถือว่าสิ่งเหล่านี้เป็นการอ้างสิทธิ์และบังคับใช้รายการอนุญาตฝั่งเซิร์ฟเวอร์

บทบาทและขอบเขต

สำหรับโมเดลขอบเขตของผู้ดำเนินการทั้งหมด การตรวจสอบในเวลาอนุมัติ และความหมายของข้อมูลลับ ที่ใช้ร่วมกัน โปรดดู ขอบเขตของผู้ดำเนินการ

บทบาท:

• operator: ไคลเอนต์ระนาบควบคุม (CLI/UI/ระบบอัตโนมัติ)
• node: โฮสต์ความสามารถ (กล้อง/หน้าจอ/แคนวาส/system.run)
• worker: โฮสต์การดำเนินการบนคลาวด์ในโปรโตคอลเวิร์กเกอร์เฉพาะแบบปิด

ขอบเขตของผู้ดำเนินการ (src/gateway/operator-scopes.ts) ซึ่งเป็นชุดแบบปิดทั้งหมด:

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

talk.config ที่มี includeSecrets: true ต้องใช้ operator.talk.secrets (หรือ operator.admin) เมื่อรวมข้อมูลลับ ให้อ่านข้อมูลรับรองของผู้ให้บริการ Talk ที่ใช้งานอยู่ จาก talk.resolved.config.apiKey; talk.providers.<id>.apiKey ยังคงมีรูปแบบตามต้นทางและอาจเป็นออบเจ็กต์ SecretRef หรือสตริงที่ปกปิดข้อมูลแล้ว

เมธอด RPC ของ Gateway ที่ Plugin ลงทะเบียนอาจร้องขอขอบเขตผู้ดำเนินการของตนเอง แต่คำนำหน้าหลักที่สงวนไว้เหล่านี้จะแปลงเป็น operator.admin (src/shared/gateway-method-policy.ts) เสมอ: config.*, exec.approvals.*, wizard.*, update.*

ขอบเขตของเมธอดเป็นเพียงด่านแรก คำสั่งแบบสแลชบางรายการที่เข้าถึงผ่าน chat.send ใช้การตรวจสอบระดับคำสั่งที่เข้มงวดยิ่งขึ้น: การเขียน /config set และ /config unset แบบถาวรต้องใช้ operator.admin แม้สำหรับไคลเอนต์ Gateway ที่ มีขอบเขตผู้ดำเนินการระดับต่ำกว่าอยู่แล้ว

node.pair.approve มีการตรวจสอบขอบเขตเพิ่มเติมในเวลาอนุมัติ นอกเหนือจาก ขอบเขตพื้นฐานของเมธอด (operator.pairing) โดยอิงตาม commands (src/infra/node-pairing-authz.ts) ที่คำขอซึ่งรอดำเนินการประกาศไว้:

ความสามารถ/คำสั่ง/สิทธิ์ (Node)

Node ประกาศการอ้างสิทธิ์ความสามารถขณะเชื่อมต่อ:

• caps: หมวดหมู่ความสามารถระดับสูง เช่น camera, canvas, screen, location, voice และ talk
• commands: รายการคำสั่งที่อนุญาตสำหรับการเรียกใช้
• permissions: ตัวเลือกเปิด/ปิดแบบละเอียด (เช่น screen.record, camera.capture)

Gateway ถือว่าสิ่งเหล่านี้เป็น การอ้างสิทธิ์ และบังคับใช้รายการที่อนุญาตฝั่งเซิร์ฟเวอร์ Node ที่เชื่อมต่อสามารถเผยแพร่ตัวอธิบาย Plugin หรือเครื่องมือ MCP ซึ่งให้เอเจนต์มองเห็นได้และเป็นตัวเลือก ผ่าน node.pluginTools.update หลังจากเชื่อมต่อหรือ เชื่อมต่อใหม่สำเร็จ โฮสต์ Node แบบไม่มีส่วนติดต่อผู้ใช้จะรีสตาร์ตเพื่อใช้การเปลี่ยนแปลง รายการ MCP ที่ประกาศไว้ วิธีอัปเดตนี้เป็นช่องทางเผยแพร่เพียงช่องทางเดียว ระบบไม่ยอมรับตัวอธิบายเครื่องมือ Plugin ใน พารามิเตอร์ connect ตัวอธิบายแต่ละรายการต้องใช้ name ของเครื่องมือที่ปลอดภัยสำหรับผู้ให้บริการ และระบุ command ที่อยู่ในรายการคำสั่งที่อนุญาตปัจจุบันของ Node Gateway เชื่อถือเมทาดาทา ของตัวอธิบายจาก Node ที่จับคู่ กรองตัวอธิบายที่อยู่นอกขอบเขตคำสั่ง ที่อนุมัติ ลบออกเมื่อ Node ตัดการเชื่อมต่อ และปฏิเสธความพยายามของผู้ปฏิบัติงาน ในการแก้ไขแค็ตตาล็อกของ Node อื่น ตั้งค่า gateway.nodes.pluginTools.enabled: false เพื่อไม่สนใจตัวอธิบายที่ Node เผยแพร่

โฮสต์ Node ที่เชื่อมต่อเผยแพร่แค็ตตาล็อกทดแทน Skills ทั้งหมดผ่าน node.skills.update เมธอดสำหรับบทบาท Node นี้เป็นช่องทางเผยแพร่ Skills ของ Node เพียงช่องทางเดียว ระบบไม่ยอมรับ Skills ในพารามิเตอร์ connect ตัวอธิบายแต่ละรายการประกอบด้วย ชื่อที่ปลอดภัย คำอธิบาย และเนื้อหา SKILL.md ที่มีขอบเขตจำกัด Gateway จะแยกวิเคราะห์ เนื้อหานั้นด้วยตัวโหลด Skills ตามปกติ รวมไว้ในสแนปช็อต Skills ของเอเจนต์ ขณะที่ Node เชื่อมต่อ และลบออกเมื่อตัดการเชื่อมต่อ ตั้งค่า gateway.nodes.skills.enabled: false เพื่อไม่สนใจ Skills ที่ Node เผยแพร่

สถานะการปรากฏ

• system-presence ส่งคืนรายการที่ใช้ข้อมูลประจำตัวของอุปกรณ์เป็นคีย์ รวมถึง deviceId, roles และ scopes เพื่อให้ UI แสดงหนึ่งแถวต่ออุปกรณ์ได้ แม้ อุปกรณ์นั้นจะเชื่อมต่อทั้งในฐานะผู้ปฏิบัติงานและ Node
• node.list มี lastSeenAtMs และ lastSeenReason ซึ่งระบุหรือไม่ก็ได้ Node ที่เชื่อมต่อ รายงานเวลาเชื่อมต่อปัจจุบันโดยใช้เหตุผล connect; Node ที่จับคู่ยังสามารถ รายงานสถานะการปรากฏเบื้องหลังแบบคงอยู่ผ่านเหตุการณ์ Node ที่เชื่อถือได้

Node แบบเนทีฟบน macOS ยังสามารถส่งเหตุการณ์ node.presence.activity ที่ผ่านการยืนยันตัวตน พร้อมระยะเวลาที่ไม่มีการป้อนข้อมูลซึ่งมีขอบเขตจำกัด Gateway จะคำนวณการประทับเวลากิจกรรมด้วย นาฬิกาของตนเอง เปิดเผย Mac ที่เชื่อมต่อและเป็นปัจจุบันที่สุดผ่าน node.list และ node.describe และกระจายการอัปเดต node.presence ไปยังไคลเอนต์ที่มีขอบเขตสิทธิ์อ่าน ดูพฤติกรรมการเลือก ความเป็นส่วนตัว บริบทโมเดล และการกำหนดเส้นทางการแจ้งเตือนได้ที่ สถานะการปรากฏของคอมพิวเตอร์ที่ใช้งานอยู่

เหตุการณ์ที่ Node ยังทำงานในเบื้องหลัง

Node เรียก node.event พร้อม event: "node.presence.alive" เพื่อบันทึกว่า Node ที่จับคู่ยังทำงานอยู่ระหว่างการปลุกเบื้องหลัง โดยไม่ทำเครื่องหมายว่าเชื่อมต่ออยู่:

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"}

trigger เป็น enum แบบปิด: background, silent_push, bg_app_refresh, significant_location, manual, connect ค่าที่ไม่รู้จักจะถูกปรับเป็น background (src/shared/node-presence.ts) เหตุการณ์จะคงอยู่เฉพาะสำหรับ เซสชันอุปกรณ์ Node ที่ผ่านการยืนยันตัวตน ส่วนเซสชันที่ไม่มีอุปกรณ์หรือไม่ได้จับคู่จะส่งคืน handled: false

Gateway ที่ดำเนินการสำเร็จจะส่งคืนผลลัพธ์แบบมีโครงสร้าง:

{  "ok": true,  "event": "node.presence.alive",  "handled": true,  "reason": "persisted"}

Gateway รุ่นเก่าอาจส่งคืนเพียง { "ok": true } สำหรับ node.event; ให้ถือว่า เป็น RPC ที่ได้รับการตอบรับ ไม่ใช่การคงสถานะการปรากฏแบบถาวร

การกำหนดขอบเขตเหตุการณ์กระจาย

เหตุการณ์กระจายที่เซิร์ฟเวอร์พุชจะถูกควบคุมตามขอบเขต เพื่อไม่ให้เซสชัน ที่มีขอบเขตเฉพาะการจับคู่หรือเฉพาะ Node รับเนื้อหาเซสชันโดยไม่ร้องขอ (src/gateway/server-broadcast.ts):

• เฟรมแชต เอเจนต์ และผลลัพธ์เครื่องมือ (เหตุการณ์ agent แบบสตรีม เหตุการณ์ ผลลัพธ์เครื่องมือ) ต้องมีอย่างน้อย operator.read เซสชันที่ไม่มีสิทธิ์นี้จะข้าม เฟรมเหล่านี้ทั้งหมด
• การกระจาย plugin.* ที่ Plugin กำหนดจะถูกจำกัดไว้ที่ operator.write หรือ operator.admin โดยค่าเริ่มต้น ส่วนรายการที่ระบุชัด เช่น plugin.approval.requested / plugin.approval.resolved จะใช้ operator.approvals แทน
• เหตุการณ์สถานะ/การขนส่ง (heartbeat, presence, tick, วงจรชีวิต การเชื่อมต่อ/ตัดการเชื่อมต่อ) ยังคงไม่ถูกจำกัด เพื่อให้ทุกเซสชัน ที่ผ่านการยืนยันตัวตนสามารถสังเกตสถานะการทำงานของการขนส่งได้
• ตระกูลเหตุการณ์กระจายที่ไม่รู้จักจะถูกจำกัดตามขอบเขตโดยค่าเริ่มต้น (ปฏิเสธเมื่อไม่แน่ใจ) เว้นแต่ตัวจัดการที่ลงทะเบียนจะผ่อนปรนข้อจำกัดอย่างชัดเจน

การเชื่อมต่อของไคลเอนต์แต่ละรายการจะเก็บหมายเลขลำดับเฉพาะของตนเอง ดังนั้นเหตุการณ์กระจาย จึงยังคงเรียงลำดับเพิ่มขึ้นอย่างสม่ำเสมอบนซ็อกเก็ตนั้น แม้ไคลเอนต์ต่างกันจะเห็น ชุดย่อยของสตรีมเหตุการณ์ที่ผ่านการกรองตามขอบเขตแตกต่างกัน

ตระกูลเมธอด RPC

hello-ok.features.methods เป็นรายการค้นพบแบบระมัดระวังซึ่งสร้างจาก src/gateway/server-methods-list.ts ร่วมกับการส่งออกเมธอดของ Plugin/ช่องทาง ที่โหลดแล้ว โดยไม่ใช่รายการทุกเมธอดที่สร้างขึ้นโดยอัตโนมัติ และบางเมธอด (เช่น push.test, web.login.start, web.login.wait, sessions.usage) ถูกตัดออกจากการค้นพบโดยเจตนา แม้จะเป็นเมธอดจริงที่เรียกใช้ได้ ให้ถือว่านี่เป็นการค้นพบคุณสมบัติ ไม่ใช่รายการ src/gateway/server-methods/*.ts ทั้งหมด

กลุ่มเหตุการณ์ทั่วไป

• chat: การอัปเดตแชตใน UI เช่น chat.inject และเหตุการณ์แชตอื่น ที่มีเฉพาะในทรานสคริปต์ ในโปรโตคอล v4 เพย์โหลดเดลตาจะมี deltaText ส่วน message ยังคงเป็น สแนปช็อตสะสมของผู้ช่วย การแทนที่ที่ไม่ใช่คำนำหน้าจะตั้งค่า replace=true และใช้ deltaText เป็นข้อความแทนที่
• session.message, session.operation, session.tool: การอัปเดตทรานสคริปต์ การดำเนินการเซสชัน ที่กำลังทำงาน และสตรีมเหตุการณ์สำหรับเซสชันที่สมัครรับข้อมูล
• session.approval: ข้อมูลจริงของการอนุมัติที่รอดำเนินการและขั้นสุดท้ายซึ่งผ่านการล้างข้อมูลแล้ว สำหรับผู้สมัครรับข้อมูล เซสชันที่ตรงกันทุกประการและเลือกรับอย่างชัดเจน การอนุมัติของรายการลูกใช้กลุ่มผู้รับของบรรพบุรุษ ที่บันทึกไว้อย่างคงทน เหตุการณ์จะไม่เปลี่ยนทรานสคริปต์หรือปลุกเอเจนต์
• sessions.changed: ดัชนีหรือข้อมูลเมตาของเซสชันเปลี่ยนแปลง
• presence: การอัปเดตสแนปช็อตสถานะการปรากฏของระบบ
• tick: เหตุการณ์ตรวจสอบการเชื่อมต่อ/ความพร้อมใช้งานตามรอบ
• health: การอัปเดตสแนปช็อตสถานภาพของ Gateway
• heartbeat: การอัปเดตสตรีมเหตุการณ์ Heartbeat
• cron: เหตุการณ์การเปลี่ยนแปลงการเรียกใช้/งาน Cron
• shutdown: การแจ้งเตือนการปิดระบบ Gateway
• node.pair.requested / node.pair.resolved: วงจรชีวิตการจับคู่ Node
• node.invoke.request: การกระจายคำขอเรียกใช้ Node
• device.pair.requested / device.pair.resolved: วงจรชีวิตอุปกรณ์ที่จับคู่แล้ว
• voicewake.changed: การกำหนดค่าทริกเกอร์คำปลุกเปลี่ยนแปลง
• config.changed: การเขียนการกำหนดค่าถูกบันทึกอย่างคงทน (เพย์โหลดมีพาธการกำหนดค่า แฮชสแนปช็อตใหม่ และการประทับเวลา — ไม่มีเนื้อหาการกำหนดค่าโดยเด็ดขาด) มีขอบเขตสำหรับการอ่านโดยผู้ปฏิบัติงาน ไคลเอนต์รีเฟรชผ่าน config.get
• exec.approval.requested / exec.approval.resolved: วงจรชีวิต การอนุมัติ exec
• plugin.approval.requested / plugin.approval.resolved: วงจรชีวิต การอนุมัติ Plugin

เมธอดตัวช่วยของ Node

Node สามารถเรียก skills.bins เพื่อดึงรายการไฟล์ปฏิบัติการของ Skills ปัจจุบัน สำหรับการตรวจสอบการอนุญาตอัตโนมัติ

RPC บัญชีแยกประเภทการตรวจสอบ

audit.activity.list มอบมุมมองที่เสถียรตามลำดับใหม่สุดก่อนแก่ไคลเอนต์ผู้ปฏิบัติงาน สำหรับข้อมูลเมตาวงจรชีวิต ของการเรียกใช้เอเจนต์ การดำเนินการของเครื่องมือ และข้อความที่เลือกรับ โดยต้องมี operator.read คิวรีจะไม่รวมระเบียนที่เก่ากว่า 30 วัน และบัญชีแยกประเภท SQLite ที่ใช้ร่วมกัน จำกัดไว้ที่ 100,000 ระเบียน แถวที่หมดอายุจะถูกลบระหว่างการเริ่มต้น Gateway การบำรุงรักษารายชั่วโมง และการเขียนครั้งต่อ ๆ ไป ดูโมเดลข้อมูลและความหมายด้านความเป็นส่วนตัวได้ที่ ประวัติการตรวจสอบ

• พารามิเตอร์: agentId, sessionKey หรือ runId ที่ตรงกันทุกประการและเลือกใช้ได้; kind ที่เลือกใช้ได้ ("agent_run", "tool_action" หรือ "message"); status ที่เลือกใช้ได้ ("started", "succeeded", "failed", "cancelled", "timed_out", "blocked" หรือ "unknown"); direction ของข้อความที่เลือกใช้ได้ ("inbound" หรือ "outbound") และ channel ที่ตรงกันทุกประการ; ขอบเขตมิลลิวินาที Unix แบบรวมค่าขอบ after / before ที่เลือกใช้ได้; limit ตั้งแต่ 1 ถึง 500 ที่เลือกใช้ได้; และสตริง cursor จากหน้าก่อนหน้าที่เลือกใช้ได้
• ผลลัพธ์: { "events": AuditActivityEventV1[], "nextCursor"?: string }

ยูเนียนผลลัพธ์ V1 ที่มีชื่อประกอบด้วยสคีมาแยกกันสำหรับการเรียกใช้เอเจนต์ การดำเนินการของเครื่องมือ ข้อความขาเข้า และข้อความขาออก ตัวจำแนก eventType คือ agent_run, tool_action, inbound_message หรือ outbound_message ตามลำดับ ส่วน kind และ direction ของข้อความยังคงใช้สำหรับการกรองและแสดงผลได้ ทุกเหตุการณ์มี schemaVersion: 1 ซึ่งเป็นจำนวนเต็ม การอ้างอิงข้อมูลประจำตัวของข้อความใช้รูปแบบ hmac-sha256:v1:<32 hex key id>:<64 hex digest> ที่ตรงกันทุกประการ รหัสแอ็กเตอร์ของผู้ส่งผ่านช่องทาง ใช้รูปแบบเดียวกัน

ตัวแปรทั้งหมดกำหนดให้มี eventType, schemaVersion, eventId, sequence, sourceSequence, occurredAt, kind, action, status, actor และ redaction ฟิลด์ของตัวแปรมีดังนี้:

enum แบบปิดของข้อความมีดังนี้:

• conversationKind: direct, group, channel หรือ unknown
• outcome ขาเข้า: completed, skipped หรือ failed; reasonCode ที่เลือกใช้ได้: duplicate, reply_operation_active, reply_operation_aborted, fast_abort, plugin_bound_handled, plugin_bound_unavailable, plugin_bound_declined, plugin_bound_error, before_dispatch_handled, acp_dispatch_completed, acp_dispatch_failed, acp_dispatch_empty หรือ acp_dispatch_aborted
• outcome ขาออก: sent, suppressed, failed หรือ unknown; reasonCode ที่เลือกใช้ได้: cancelled_by_message_sending_hook, cancelled_by_reply_payload_sending_hook, empty_after_message_sending_hook, empty_after_reply_payload_sending_hook หรือ no_visible_payload อะแดปเตอร์ที่ไม่ส่งคืนข้อมูลประจำตัวของแพลตฟอร์มจะเป็น unknown เนื่องจากไม่สามารถหักล้างได้ว่าผลข้างเคียงภายนอกไม่ได้เกิดขึ้น
• deliveryKind: text, media หรือ other; failureStage: platform_send, queue หรือ unknown

ฟิลด์ขั้นสุดท้ายมีความสัมพันธ์กัน ไม่ได้เป็นฟิลด์ที่เลือกใช้ได้อย่างเป็นอิสระ:

เหตุการณ์กิจกรรมแต่ละรายการประกอบด้วยรหัสเหตุการณ์ที่คงที่ ลำดับบัญชีแยกประเภทที่เพิ่มขึ้นแบบทางเดียว ลำดับเหตุการณ์ต้นทาง การประทับเวลา ผู้ดำเนินการ การดำเนินการ สถานะ ค่า schemaVersion: 1 ซึ่งเป็นจำนวนเต็ม และ redaction: "metadata_only" ระเบียนการเรียกใช้และเครื่องมือ ต้องมีข้อมูลที่มาของเอเจนต์และการเรียกใช้ และอาจมีข้อมูลที่มาของเซสชัน ระเบียนข้อความ อาจมีรหัสเอเจนต์และรหัสการเรียกใช้ แต่ตั้งใจไม่รวม sessionKey หรือ sessionId; ดังนั้นตัวกรองการสืบค้น sessionKey จึงใช้กับ แถวการเรียกใช้และเครื่องมือเท่านั้น เหตุการณ์เครื่องมืออาจมีรหัสการเรียกเครื่องมือและชื่อเครื่องมือ

ระเบียนข้อความใช้ message.inbound.processed หรือ message.outbound.finished และเพิ่มทิศทาง ช่องทาง ประเภทการสนทนา ผลลัพธ์ที่ปรับให้อยู่ในรูปแบบมาตรฐาน ตลอดจนประเภทการส่ง ขั้นตอนที่ล้มเหลว ระยะเวลา จำนวนผลลัพธ์ รหัสเหตุผล และนามแฝงบัญชี/การสนทนา/ข้อความ/เป้าหมาย ที่ใช้คีย์ภายในแต่ละการติดตั้งซึ่งเป็นข้อมูลเสริม นามแฝงเหล่านี้ช่วย เชื่อมโยงข้อมูลแต่ไม่ใช่การทำให้เป็นนิรนาม เนื่องจากฐานข้อมูลสถานะมีคีย์ของนามแฝง แต่ข้อมูลส่งออกจาก RPC และ CLI ไม่มีคีย์ดังกล่าว บัญชีแยกประเภทไม่จัดเก็บพรอมต์ เนื้อหา ข้อความ อาร์กิวเมนต์เครื่องมือ ผลลัพธ์เครื่องมือ เอาต์พุตคำสั่ง หรือข้อความข้อผิดพลาดดิบ ค่า sessionKey ของการเรียกใช้/เครื่องมือยังคงเป็นเมทาดาทาดิบสำหรับการเชื่อมโยงและอาจฝัง รหัสบัญชีหรือรหัสเพียร์ของแพลตฟอร์ม ส่วนระเบียนข้อความจะไม่รวมคีย์เซสชัน

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

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

การบันทึกเปิดใช้งานโดยค่าเริ่มต้นและควบคุมด้วย audit.enabled การบันทึกข้อความควบคุม แยกต่างหากด้วย audit.messages และมีค่าเริ่มต้นเป็น "off" เมื่อ ปิดใช้งานการบันทึก audit.activity.list จะยังคงให้บริการระเบียนที่เขียนไว้ ก่อนหน้านี้จนกว่าจะหมดอายุ

สคีมาคำขอ ผลลัพธ์ และ AuditEvent ของ audit.list ที่เผยแพร่แล้ว ยังคงไม่เปลี่ยนแปลงและส่งคืนเฉพาะระเบียนการเรียกใช้เอเจนต์และการดำเนินการของเครื่องมือ ไคลเอนต์ ผู้ดำเนินการใหม่ควรเรียก audit.activity.list เมื่อ Gateway ประกาศว่ารองรับ เมื่อตอบ คำขอที่มีขอบเขตการอ่าน Gateway รุ่นเก่าอาจรายงาน unknown method: audit.activity.list หรือ missing scope: operator.admin เนื่องจากในเวอร์ชันที่เผยแพร่แล้ว การอนุญาตเกิดขึ้นก่อนการค้นหาเมธอด ให้ถือว่ากรณีหลังหมายถึงไม่มีเมธอด เฉพาะเมื่อไม่ได้มีการประกาศเมธอดดังกล่าว จากนั้นไคลเอนต์อาจลอง audit.list อีกครั้ง ได้เฉพาะเมื่อตัวกรองไม่ต้องการรองรับประเภทข้อความ ทิศทาง หรือช่องทาง

ใช้ openclaw audit สำหรับการสืบค้นข้อความและการส่งออก JSON แบบจำกัดขนาด

RPC ของบัญชีแยกประเภทงาน

ไคลเอนต์ผู้ดำเนินการตรวจสอบและยกเลิกระเบียนงานเบื้องหลังของ Gateway ผ่าน RPC ของบัญชีแยกประเภทงาน (packages/gateway-protocol/src/schema/tasks.ts) RPC เหล่านี้ ส่งคืนสรุปงานที่ผ่านการล้างข้อมูลแล้ว ไม่ใช่สถานะรันไทม์ดิบ

• tasks.list ต้องใช้ operator.read
  • พารามิเตอร์: status ซึ่งเป็นตัวเลือก ("queued", "running", "completed", "failed", "cancelled" หรือ "timed_out") หรืออาร์เรย์ของสถานะเหล่านั้น agentId ซึ่งเป็นตัวเลือก, sessionKey ซึ่งเป็นตัวเลือก, limit ซึ่งเป็นตัวเลือกตั้งแต่ 1 ถึง 500 และสตริง cursor ซึ่งเป็นตัวเลือก
  • ผลลัพธ์: { "tasks": TaskSummary[], "nextCursor"?: string }
• tasks.get ต้องใช้ operator.read
  • พารามิเตอร์: { "taskId": string }
  • ผลลัพธ์: { "task": TaskSummary }
  • รหัสงานที่ไม่มีอยู่จะส่งคืนข้อผิดพลาดรูปแบบไม่พบของ Gateway
• tasks.cancel ต้องใช้ operator.write
  • พารามิเตอร์: { "taskId": string, "reason"?: string }
  • ผลลัพธ์: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }
  • found รายงานว่าบัญชีแยกประเภทมีงานที่ตรงกันหรือไม่ cancelled รายงานว่ารันไทม์ยอมรับหรือบันทึกการยกเลิกหรือไม่

TaskSummary ประกอบด้วย id, status และเมทาดาทาที่เป็นตัวเลือก ได้แก่ kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, การประทับเวลา ความคืบหน้า สรุปสถานะสิ้นสุด และข้อความข้อผิดพลาดที่ผ่านการล้างข้อมูลแล้ว agentId ระบุเอเจนต์ ที่ดำเนินงาน ส่วน sessionKey และ ownerKey จะเก็บรักษาบริบทของผู้ร้องขอและการควบคุม

เมธอดตัวช่วยสำหรับผู้ดำเนินการ

• commands.list (operator.read) ดึงรายการคำสั่งรันไทม์สำหรับ เอเจนต์
  • agentId เป็นตัวเลือกเสริม หากละไว้ ระบบจะอ่านพื้นที่ทำงานเริ่มต้นของเอเจนต์
  • scope ควบคุมว่าพื้นผิวใดเป็นเป้าหมายของ name หลัก: text จะส่งคืน โทเค็นคำสั่งข้อความหลักโดยไม่มี / นำหน้า ส่วน native และเส้นทาง both เริ่มต้นจะส่งคืนชื่อเนทีฟที่รับรู้ผู้ให้บริการเมื่อมี
  • textAliases มีนามแฝงแบบสแลชที่ตรงกันทุกประการ เช่น /model และ /m
  • nativeName มีชื่อคำสั่งเนทีฟที่รับรู้ผู้ให้บริการเมื่อมี ชื่อดังกล่าว
  • provider เป็นตัวเลือกเสริมและมีผลเฉพาะต่อการตั้งชื่อแบบเนทีฟ รวมถึงความพร้อมใช้งานของคำสั่ง Plugin แบบเนทีฟ
  • includeArgs=false จะตัดข้อมูลเมตาของอาร์กิวเมนต์ที่ซีเรียลไลซ์แล้วออกจากการตอบกลับ
• tools.catalog (operator.read) ดึงแค็ตตาล็อกเครื่องมือรันไทม์สำหรับ เอเจนต์ การตอบกลับประกอบด้วยเครื่องมือที่จัดกลุ่มและข้อมูลเมตาแหล่งที่มา:
  • source: core หรือ plugin
  • pluginId: เจ้าของ Plugin เมื่อเป็น source="plugin"
  • optional: ระบุว่าเครื่องมือของ Plugin เป็นตัวเลือกเสริมหรือไม่
• tools.effective (operator.read) ดึงรายการเครื่องมือที่มีผลจริงในรันไทม์ สำหรับเซสชัน
  • จำเป็นต้องระบุ sessionKey
  • Gateway จะอนุมานบริบทรันไทม์ที่เชื่อถือได้จากเซสชันที่ฝั่งเซิร์ฟเวอร์ แทนที่จะยอมรับบริบทการยืนยันตัวตนหรือการส่งมอบที่ผู้เรียกส่งมา
  • การตอบกลับคือภาพฉายที่เซิร์ฟเวอร์อนุมานและจำกัดขอบเขตตามเซสชันของรายการที่ใช้งานอยู่ ซึ่งรวมถึงเครื่องมือหลัก เครื่องมือของ Plugin เครื่องมือของช่องทาง และเครื่องมือของเซิร์ฟเวอร์ MCP ที่ค้นพบแล้ว
  • tools.effective เป็นแบบอ่านอย่างเดียวสำหรับ MCP: อาจฉายแค็ตตาล็อก MCP ของเซสชันที่วอร์มแล้วผ่านนโยบายเครื่องมือขั้นสุดท้าย แต่จะไม่สร้างรันไทม์ MCP เชื่อมต่อการขนส่ง หรือส่ง tools/list หากไม่มีแค็ตตาล็อกที่วอร์มแล้ว ซึ่งตรงกัน การตอบกลับอาจมีข้อความแจ้ง เช่น mcp-not-yet-connected, mcp-not-yet-listed หรือ mcp-stale-catalog
  • รายการเครื่องมือที่มีผลจริงใช้ source="core", source="plugin", source="channel" หรือ source="mcp"
• tools.invoke (operator.write) เรียกใช้เครื่องมือหนึ่งรายการที่พร้อมใช้งานผ่าน เส้นทางนโยบาย Gateway เดียวกับ /tools/invoke
  • จำเป็นต้องระบุ name ส่วน args, sessionKey, agentId, confirm และ idempotencyKey เป็นตัวเลือกเสริม
  • หากมีทั้ง sessionKey และ agentId เอเจนต์ของเซสชันที่แก้ค่าแล้ว ต้องตรงกับ agentId
  • ตัวหุ้มแกนหลักสำหรับเจ้าของเท่านั้น เช่น cron, gateway และ nodes ต้องใช้ ข้อมูลประจำตัวเจ้าของ/ผู้ดูแลระบบ (operator.admin) แม้ว่า tools.invoke เอง จะเป็น operator.write
  • การตอบกลับเป็นเอนเวโลปสำหรับ SDK ที่มี ok, toolName, output ซึ่งเป็นตัวเลือกเสริม และฟิลด์ error ที่มีชนิดกำกับ การปฏิเสธจากการอนุมัติหรือนโยบายจะส่งคืน ok:false ในเพย์โหลด แทนที่จะข้ามไปป์ไลน์นโยบายเครื่องมือของ Gateway
• skills.status (operator.read) ดึงรายการ Skills ที่มองเห็นได้สำหรับ เอเจนต์
  • agentId เป็นตัวเลือกเสริม หากละไว้ ระบบจะอ่านพื้นที่ทำงานเริ่มต้นของเอเจนต์
  • การตอบกลับประกอบด้วยคุณสมบัติที่เข้าเกณฑ์ ข้อกำหนดที่ขาดหาย การตรวจสอบการกำหนดค่า และตัวเลือกการติดตั้งที่ผ่านการล้างข้อมูล โดยไม่เปิดเผยค่าความลับดิบ
• skills.search และ skills.detail (operator.read) ส่งคืนข้อมูลเมตา การค้นพบของ ClawHub
• skills.upload.begin, skills.upload.chunk และ skills.upload.commit (operator.admin) จัดเตรียมไฟล์เก็บถาวร Skills ส่วนตัวก่อนติดตั้ง นี่คือ เส้นทางอัปโหลดสำหรับผู้ดูแลระบบที่แยกต่างหากสำหรับไคลเอนต์ที่เชื่อถือได้ ไม่ใช่ขั้นตอนการติดตั้ง Skills ของ ClawHub ตามปกติ และจะปิดใช้งานโดยค่าเริ่มต้น เว้นแต่จะเปิดใช้ skills.install.allowUploadedArchives
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) จะสร้างการอัปโหลดที่ผูกกับ slug และค่าบังคับดังกล่าว
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) จะผนวกไบต์ ณ ออฟเซ็ตที่ถอดรหัสแล้วอย่างตรงกันทุกประการ
  • skills.upload.commit({ uploadId, sha256? }) จะตรวจสอบขนาดสุดท้ายและ SHA-256 การคอมมิตเพียงทำให้การอัปโหลดเสร็จสมบูรณ์เท่านั้น ไม่ได้ติดตั้ง Skills
  • ไฟล์เก็บถาวร Skills ที่อัปโหลดเป็นไฟล์ zip ซึ่งมีราก SKILL.md ชื่อไดเรกทอรี ภายในไฟล์เก็บถาวรจะไม่ใช้เลือกเป้าหมายการติดตั้ง
• skills.install (operator.admin) มีสามโหมด:
  • โหมด ClawHub: { source: "clawhub", slug, version?, force? } จะติดตั้ง โฟลเดอร์ Skills ลงในไดเรกทอรี skills/ ของพื้นที่ทำงานเริ่มต้นของเอเจนต์
  • โหมดอัปโหลด: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } จะติดตั้งการอัปโหลดที่คอมมิตแล้วลงในไดเรกทอรี skills/<slug> ของพื้นที่ทำงานเริ่มต้นของเอเจนต์ slug และค่าบังคับต้องตรงกับคำขอ skills.upload.begin เดิม ระบบจะปฏิเสธเว้นแต่จะเปิดใช้ skills.install.allowUploadedArchives การตั้งค่านี้ไม่มีผลต่อการติดตั้งจาก ClawHub
  • โหมดตัวติดตั้ง Gateway: { name, installId, timeoutMs? } จะเรียกใช้การดำเนินการ metadata.openclaw.install ที่ประกาศไว้บนโฮสต์ Gateway ไคลเอนต์รุ่นเก่าอาจยังคง ส่ง dangerouslyForceUnsafeInstall อยู่ ฟิลด์นี้เลิกใช้แล้ว ยอมรับเฉพาะเพื่อความเข้ากันได้ของโปรโตคอล และจะถูกละเว้น ใช้ security.installPolicy สำหรับการตัดสินใจติดตั้งที่ผู้ปฏิบัติงานเป็นเจ้าของ
• skills.update (operator.admin) มีสองโหมด:
  • โหมด ClawHub จะอัปเดต slug ที่ติดตามหนึ่งรายการ หรือการติดตั้ง ClawHub ที่ติดตามทั้งหมดในพื้นที่ทำงานเริ่มต้นของเอเจนต์
  • โหมดการกำหนดค่าจะแพตช์ค่า skills.entries.<skillKey> เช่น enabled, apiKey และ env

มุมมอง models.list

models.list ยอมรับพารามิเตอร์ view ซึ่งเป็นตัวเลือกเสริม (src/agents/model-catalog-visibility.ts):

• ละไว้หรือ "default": หากกำหนดค่า agents.defaults.modelPolicy.allow ไว้ การตอบกลับจะเป็นแค็ตตาล็อกที่อนุญาต ซึ่งรวมถึงโมเดลที่ค้นพบแบบไดนามิก สำหรับรายการ provider/* มิฉะนั้น การตอบกลับจะเป็นแค็ตตาล็อก Gateway ทั้งหมด
• "configured": ลักษณะการทำงานขนาดพอดีกับตัวเลือก หากกำหนดค่า agents.defaults.modelPolicy.allow ไว้ ค่านี้ยังคงมีผลเหนือกว่า รวมถึงการค้นพบที่จำกัดขอบเขตตามผู้ให้บริการสำหรับ รายการ provider/* หากไม่มีรายการอนุญาต การตอบกลับจะใช้รายการ models.providers.<provider>.models ที่ระบุไว้อย่างชัดเจน และจะย้อนกลับไปใช้แค็ตตาล็อกทั้งหมด เฉพาะเมื่อไม่มีแถวโมเดลที่กำหนดค่าไว้
• "provider-config": รายการ models.providers.*.models ที่กำหนดโดยแหล่งที่มา และเป็นอิสระจากรายการอนุญาตของตัวเลือก แถวต่าง ๆ ประกอบด้วยความสามารถสาธารณะของโมเดลและ ความพร้อมใช้งานที่รับรู้เส้นทาง แต่ไม่รวมเอนด์พอยต์ของผู้ให้บริการ ข้อมูลการยืนยันตัวตน และ การกำหนดค่าคำขอรันไทม์
• "all": แค็ตตาล็อก Gateway ทั้งหมด โดยข้าม agents.defaults.modelPolicy.allow ใช้สำหรับ UI การวินิจฉัย/การค้นพบ ไม่ใช่ตัวเลือกโมเดลตามปกติ

การอนุมัติการดำเนินการ

• เมื่อคำขอดำเนินการต้องได้รับการอนุมัติ Gateway จะกระจาย exec.approval.requested
• ไคลเอนต์ของผู้ปฏิบัติงานจะแก้ไขโดยเรียก exec.approval.resolve (ต้องมี operator.approvals)
• สำหรับ host=node นั้น exec.approval.request ต้องมี systemRunPlan (ข้อมูลเมตา argv/cwd/rawCommand/เซสชันแบบมาตรฐาน) คำขอที่ไม่มี systemRunPlan จะถูกปฏิเสธ
• หลังจากอนุมัติแล้ว การเรียก node.invoke system.run ที่ส่งต่อจะนำ systemRunPlan แบบมาตรฐานนั้นกลับมาใช้เป็นบริบทคำสั่ง/cwd/เซสชันที่เชื่อถือได้
• หากผู้เรียกแก้ไข command, rawCommand, cwd, agentId หรือ sessionKey ระหว่างการเตรียมกับการส่งต่อ system.run ขั้นสุดท้ายที่ได้รับอนุมัติ Gateway จะปฏิเสธการเรียกใช้แทนที่จะเชื่อถือเพย์โหลดที่ถูกแก้ไข

การย้อนกลับของการส่งมอบจากเอเจนต์

• คำขอ agent สามารถระบุ deliver=true เพื่อขอการส่งมอบขาออก
• bestEffortDeliver=false (ค่าเริ่มต้น) จะคงลักษณะการทำงานที่เข้มงวดไว้: เป้าหมายการส่งมอบ ที่แก้ค่าไม่ได้หรือใช้ภายในเท่านั้นจะส่งคืน INVALID_REQUEST
• bestEffortDeliver=true อนุญาตให้ย้อนกลับไปดำเนินการเฉพาะในเซสชันเมื่อไม่สามารถ แก้หาเส้นทางที่ส่งมอบไปภายนอกได้ (เช่น เซสชันภายใน/เว็บแชต หรือการกำหนดค่าหลายช่องทางที่กำกวม)
• ผลลัพธ์ agent ขั้นสุดท้ายอาจมี result.deliveryStatus เมื่อมีการร้องขอ การส่งมอบ โดยใช้สถานะ sent, suppressed, partial_failed และ failed เดียวกับที่ระบุไว้สำหรับ openclaw agent --json --deliver

การกำหนดเวอร์ชัน

• PROTOCOL_VERSION, MIN_CLIENT_PROTOCOL_VERSION, MIN_NODE_PROTOCOL_VERSION และ MIN_PROBE_PROTOCOL_VERSION อยู่ใน packages/gateway-protocol/src/version.ts
• ไคลเอนต์ส่ง minProtocol + maxProtocol ไคลเอนต์ผู้ปฏิบัติงานและ UI ต้อง รวมโปรโตคอลปัจจุบันไว้ในช่วงดังกล่าว ไคลเอนต์และเซิร์ฟเวอร์ปัจจุบันใช้ โปรโตคอล v4
• ไคลเอนต์ที่ผ่านการยืนยันตัวตนและมีทั้ง role: "node" และ client.mode: "node" สามารถใช้โปรโตคอล Node รุ่น N-1 (ปัจจุบันคือ v3) โพรบการรีสตาร์ทแบบเบาใช้ ช่วง N-1 เดียวกัน การยืนยันตัวตนอุปกรณ์ การจับคู่ ขอบเขต นโยบายคำสั่ง และการอนุมัติ การดำเนินการจะไม่เปลี่ยนแปลงจากช่วงความเข้ากันได้นี้ ความสามารถและคำสั่งของ Node ที่ Plugin เป็นเจ้าของจะถูกระงับไว้จนกว่า Node จะอัปเกรดเป็นโปรโตคอลปัจจุบัน เนื่องจากพื้นผิวที่โฮสต์โดยความสามารถและคำสั่งเหล่านั้นไม่ได้เป็นส่วนหนึ่งของสัญญา N-1
• สคีมาและโมเดลสร้างขึ้นจากข้อกำหนด TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

ค่าคงที่ของไคลเอนต์

การติดตั้งใช้งานไคลเอนต์อ้างอิงอยู่ใน packages/gateway-client/src/ (OpenClaw ห่อหุ้มผ่านฟาซาดแบบบาง src/gateway/client.ts) ค่าเริ่มต้นเหล่านี้ คงที่ตลอดโปรโตคอล v4 และเป็นค่าพื้นฐานที่คาดหวังสำหรับ ไคลเอนต์ของบุคคลที่สาม

เซิร์ฟเวอร์ประกาศค่า policy.tickIntervalMs, policy.maxPayload และ policy.maxBufferedBytes ที่มีผลจริงใน hello-ok; ไคลเอนต์ ควรใช้ค่าเหล่านั้นแทนค่าเริ่มต้นก่อนการแฮนด์เชค

ไคลเอนต์อ้างอิงยอมให้คำขอแบบจำกัดเวลาควบคุมกำหนดเวลาสิ้นสุดที่ตั้งค่าไว้เอง เมื่อ คำขอที่รอดำเนินการทุกคำขอมีการกำหนดเวลาดังกล่าว คำขอ expectFinal ที่ไม่มี timeoutMs แบบจำกัดเวลา คำขอใดก็ตามที่มี timeoutMs: null หรือคำขอแบบจำกัดเวลาและ ไม่จำกัดเวลาที่ปะปนกัน จะทำให้ตัวเฝ้าระวังทิกยังคงทำงานอยู่ หากไม่มีเหตุการณ์ขาเข้าและ การตอบกลับนานเกินเกณฑ์หมดเวลาของทิก ไคลเอนต์จะปิด ซ็อกเก็ตด้วยรหัส 4000 ปฏิเสธคำขอที่รอดำเนินการทั้งหมด และเชื่อมต่อใหม่ โดยจะ ไม่ส่งคำขอที่ถูกปฏิเสธซ้ำหลังจากเชื่อมต่อใหม่

การตรวจสอบสิทธิ์

• การตรวจสอบสิทธิ์ Gateway ด้วยข้อมูลลับร่วมใช้ connect.params.auth.token หรือ connect.params.auth.password ตาม gateway.auth.mode ที่กำหนดค่าไว้ ("none" | "token" | "password" | "trusted-proxy")
• โหมดที่มีข้อมูลระบุตัวตน เช่น Tailscale Serve (gateway.auth.allowTailscale: true) หรือ gateway.auth.mode: "trusted-proxy" ที่ไม่ใช่ลูปแบ็ก จะผ่านการตรวจสอบสิทธิ์ การเชื่อมต่อจากส่วนหัวคำขอแทน connect.params.auth.*
• gateway.auth.mode: "none" สำหรับทางเข้าระบบแบบส่วนตัวจะข้ามการตรวจสอบสิทธิ์การเชื่อมต่อด้วยข้อมูลลับร่วม ทั้งหมด ห้ามเปิดเผยโหมดนี้บนทางเข้าระบบสาธารณะ/ที่ไม่น่าเชื่อถือ
• หลังจากจับคู่แล้ว Gateway จะออกโทเค็นอุปกรณ์ที่จำกัดขอบเขตตามบทบาท + ขอบเขตของการเชื่อมต่อ และส่งคืนใน hello-ok.auth.deviceToken ไคลเอนต์ควร เก็บโทเค็นนี้ไว้อย่างถาวรหลังจากเชื่อมต่อสำเร็จทุกครั้ง
• เมื่อเชื่อมต่อใหม่ด้วยโทเค็นอุปกรณ์ที่จัดเก็บไว้ ควรนำชุดขอบเขตที่อนุมัติและ จัดเก็บไว้สำหรับโทเค็นนั้นกลับมาใช้ด้วย ซึ่งจะคงสิทธิ์การเข้าถึงเพื่ออ่าน/ตรวจสอบ/ดูสถานะ ที่ได้รับแล้ว และหลีกเลี่ยงการลดขอบเขตการเชื่อมต่อใหม่โดยไม่แจ้งให้เหลือเพียง ขอบเขตผู้ดูแลระบบโดยนัยที่แคบกว่า
• การประกอบข้อมูลตรวจสอบสิทธิ์การเชื่อมต่อฝั่งไคลเอนต์ (selectConnectAuth ใน packages/gateway-client/src/client.ts):
  • auth.password เป็นอิสระจากส่วนอื่นและจะถูกส่งต่อตลอดเมื่อตั้งค่าไว้
  • auth.token จะถูกกำหนดค่าตามลำดับความสำคัญดังนี้: โทเค็นร่วมที่ระบุโดยตรงก่อน ตามด้วย deviceToken ที่ระบุโดยตรง แล้วจึงเป็นโทเค็นที่จัดเก็บไว้แยกตามอุปกรณ์ (ใช้ deviceId + role เป็นคีย์)
  • auth.bootstrapToken จะถูกส่งต่อเมื่อไม่มีรายการข้างต้นใด ให้ค่า auth.token เท่านั้น โทเค็นร่วมหรือโทเค็นอุปกรณ์ใดก็ตามที่หาได้จะระงับการส่งค่านี้
  • การเลื่อนใช้โทเค็นอุปกรณ์ที่จัดเก็บไว้โดยอัตโนมัติในการลอง AUTH_TOKEN_MISMATCH แบบครั้งเดียว จำกัดไว้เฉพาะปลายทางที่เชื่อถือได้: ลูปแบ็ก หรือ wss:// ที่ตรึง tlsFingerprint ไว้ ส่วน wss:// สาธารณะที่ไม่มีการตรึง ไม่เข้าเงื่อนไข
• การเริ่มต้นระบบด้วยรหัสตั้งค่าในตัวจะส่งคืน hello-ok.auth.deviceToken ของ Node หลัก พร้อมโทเค็นผู้ปฏิบัติงานแบบจำกัดใน hello-ok.auth.deviceTokens สำหรับการส่งต่อไปยังอุปกรณ์เคลื่อนที่ที่เชื่อถือได้ โทเค็นผู้ปฏิบัติงาน มี operator.talk.secrets สำหรับการอ่านการกำหนดค่า Talk แบบเนทีฟ แต่ ไม่รวมขอบเขตการแก้ไขการจับคู่และ operator.admin
• ระหว่างที่การเริ่มต้นระบบด้วยรหัสตั้งค่าซึ่งไม่ใช่ค่าพื้นฐานกำลังรอการอนุมัติ รายละเอียด PAIRING_REQUIRED จะมี recommendedNextStep: "wait_then_retry", retryable: true และ pauseReconnect: false ให้เชื่อมต่อใหม่ต่อไปโดยใช้ โทเค็นเริ่มต้นระบบเดิมจนกว่าคำขอจะได้รับอนุมัติหรือโทเค็น ใช้งานไม่ได้
• เก็บ hello-ok.auth.deviceTokens ไว้อย่างถาวรเฉพาะเมื่อการเชื่อมต่อใช้การตรวจสอบสิทธิ์ แบบเริ่มต้นระบบผ่านการขนส่งที่เชื่อถือได้ เช่น wss:// หรือการจับคู่ผ่านลูปแบ็ก/ภายในเครื่อง
• หากไคลเอนต์ระบุ deviceToken หรือ scopes โดยตรง ชุดขอบเขตที่ผู้เรียกขอยังคงเป็นค่าหลัก ขอบเขตที่แคชไว้จะถูก นำกลับมาใช้เฉพาะเมื่อไคลเอนต์กำลังนำโทเค็นที่จัดเก็บไว้แยกตามอุปกรณ์กลับมาใช้
• โทเค็นอุปกรณ์สามารถหมุนเวียน/เพิกถอนได้ผ่าน device.token.rotate และ device.token.revoke (ต้องมี operator.pairing) การหมุนเวียนหรือเพิกถอน โทเค็นของ Node หรือบทบาทอื่นที่ไม่ใช่ผู้ปฏิบัติงานต้องมี operator.admin ด้วย
• device.token.rotate ส่งคืนข้อมูลเมตาการหมุนเวียน โดยจะส่งโทเค็นผู้ถือสิทธิ์ ตัวใหม่กลับมาเฉพาะสำหรับการเรียกจากอุปกรณ์เดียวกันที่ตรวจสอบสิทธิ์ด้วยโทเค็น ของอุปกรณ์นั้นแล้ว เพื่อให้ไคลเอนต์ที่ใช้เฉพาะโทเค็นสามารถเก็บโทเค็นตัวใหม่ก่อน เชื่อมต่อใหม่ การหมุนเวียนโดยใช้ข้อมูลลับร่วม/ผู้ดูแลระบบจะไม่ส่งโทเค็นผู้ถือสิทธิ์กลับมา
• การออก การหมุนเวียน และการเพิกถอนโทเค็นยังคงจำกัดอยู่ภายในชุดบทบาทที่อนุมัติ ซึ่งบันทึกไว้ในรายการจับคู่ของอุปกรณ์นั้น การแก้ไขโทเค็นไม่สามารถขยายหรือ กำหนดเป้าหมายไปยังบทบาทอุปกรณ์ที่การอนุมัติการจับคู่ไม่เคยให้สิทธิ์
• สำหรับเซสชันโทเค็นของอุปกรณ์ที่จับคู่แล้ว การจัดการอุปกรณ์จะจำกัดอยู่ที่ตนเอง เว้นแต่ ผู้เรียกจะมี operator.admin ด้วย: ผู้เรียกที่ไม่ใช่ผู้ดูแลระบบสามารถจัดการได้เฉพาะ โทเค็นผู้ปฏิบัติงานสำหรับรายการอุปกรณ์ของตนเอง การจัดการโทเค็นของ Node และบทบาทอื่น ที่ไม่ใช่ผู้ปฏิบัติงานสงวนไว้สำหรับผู้ดูแลระบบเท่านั้น แม้จะเป็นอุปกรณ์ของผู้เรียกเองก็ตาม
• device.token.rotate และ device.token.revoke ยังตรวจสอบชุดขอบเขต ของโทเค็นผู้ปฏิบัติงานเป้าหมายกับขอบเขตเซสชันปัจจุบันของผู้เรียก ผู้เรียกที่ไม่ใช่ผู้ดูแลระบบไม่สามารถหมุนเวียนหรือเพิกถอนโทเค็นผู้ปฏิบัติงานที่มีขอบเขตกว้างกว่า ที่ตนถืออยู่ได้
• ความล้มเหลวในการตรวจสอบสิทธิ์มี error.details.code พร้อมคำแนะนำการกู้คืน:
  • error.details.canRetryWithDeviceToken (บูลีน)
  • error.details.recommendedNextStep: ค่าใดค่าหนึ่งจาก retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts)
• พฤติกรรมไคลเอนต์สำหรับ AUTH_TOKEN_MISMATCH:
  • ไคลเอนต์ที่เชื่อถือได้อาจลองใหม่แบบจำกัดหนึ่งครั้งด้วยโทเค็นที่แคชไว้แยกตามอุปกรณ์
  • หากการลองใหม่นั้นล้มเหลว ให้หยุดวงรอบการเชื่อมต่อใหม่อัตโนมัติและแสดง คำแนะนำการดำเนินการสำหรับผู้ปฏิบัติงาน
• AUTH_SCOPE_MISMATCH หมายความว่าระบบรู้จักโทเค็นอุปกรณ์ แต่โทเค็นนั้นไม่ ครอบคลุมบทบาท/ขอบเขตที่ร้องขอ อย่าแสดงว่านี่เป็นโทเค็นที่ไม่ถูกต้อง ให้แจ้ง ผู้ปฏิบัติงานให้จับคู่ใหม่หรืออนุมัติข้อตกลงขอบเขตที่แคบกว่า/กว้างกว่า

ข้อมูลระบุตัวตนและการจับคู่อุปกรณ์

• Node ควรมีข้อมูลระบุตัวตนอุปกรณ์ที่คงที่ (device.id) ซึ่งได้มาจาก ลายนิ้วมือของคู่กุญแจ
• Gateway ออกโทเค็นแยกตามอุปกรณ์ + บทบาท
• ต้องอนุมัติการจับคู่สำหรับรหัสอุปกรณ์ใหม่ เว้นแต่เปิดใช้ การอนุมัติอัตโนมัติภายในเครื่อง
• การอนุมัติการจับคู่อัตโนมัติมุ่งเน้นที่การเชื่อมต่อลูปแบ็กภายในเครื่องโดยตรง
• OpenClaw ยังมีเส้นทางเชื่อมต่อตนเองภายในแบ็กเอนด์/คอนเทนเนอร์แบบจำกัด สำหรับ โฟลว์ตัวช่วยที่เชื่อถือได้ซึ่งใช้ข้อมูลลับร่วม
• การเชื่อมต่อผ่าน tailnet หรือ LAN บนโฮสต์เดียวกันยังถือว่าเป็นการเชื่อมต่อระยะไกลสำหรับการจับคู่ และต้องได้รับอนุมัติ
• โดยปกติไคลเอนต์ WS จะมีข้อมูลระบุตัวตน device ระหว่าง connect (ผู้ปฏิบัติงาน + Node) ข้อยกเว้นสำหรับผู้ปฏิบัติงานที่ไม่มีอุปกรณ์มีเฉพาะเส้นทางที่เชื่อถือได้ซึ่งระบุชัดเจน:
  • gateway.controlUi.allowInsecureAuth=true สำหรับความเข้ากันได้กับ HTTP ที่ไม่ปลอดภัยและจำกัดเฉพาะ localhost
  • การตรวจสอบสิทธิ์ Control UI ของผู้ปฏิบัติงานผ่าน gateway.auth.mode: "trusted-proxy" ที่สำเร็จ
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (ทางเลือกฉุกเฉิน เป็นการลดระดับ ความปลอดภัยอย่างรุนแรง)
  • RPC แบ็กเอนด์ gateway-client ผ่านลูปแบ็กโดยตรงบนเส้นทางตัวช่วย ภายในที่สงวนไว้
• การละเว้นข้อมูลระบุตัวตนอุปกรณ์มีผลต่อขอบเขต เมื่ออนุญาตให้การเชื่อมต่อ ของผู้ปฏิบัติงานที่ไม่มีอุปกรณ์ผ่านเส้นทางที่เชื่อถือได้ซึ่งระบุชัดเจน OpenClaw จะยังคงล้างขอบเขตที่ประกาศเองให้เป็นชุดว่าง เว้นแต่เส้นทางนั้นจะมี ข้อยกเว้นการรักษาขอบเขตที่ระบุชื่อไว้ จากนั้นเมธอดที่มีการจำกัดขอบเขตจะล้มเหลวด้วย missing scope
• gateway.controlUi.dangerouslyDisableDeviceAuth=true เป็นเส้นทางรักษาขอบเขต แบบฉุกเฉินของ Control UI โดยไม่ได้ให้ขอบเขตแก่แบ็กเอนด์แบบกำหนดเองหรือ ไคลเอนต์ WebSocket ที่มีรูปแบบ CLI โดยพลการ
• เส้นทางตัวช่วยแบ็กเอนด์ gateway-client ผ่านลูปแบ็กโดยตรงที่สงวนไว้จะรักษา ขอบเขตเฉพาะสำหรับ RPC ของระนาบควบคุมภายในเครื่องเท่านั้น รหัสแบ็กเอนด์แบบกำหนดเองจะ ไม่ได้รับข้อยกเว้นนี้
• การเชื่อมต่อทั้งหมดต้องลงนาม nonce connect.challenge ที่เซิร์ฟเวอร์ให้มา

การวินิจฉัยการย้ายระบบการตรวจสอบสิทธิ์อุปกรณ์

สำหรับไคลเอนต์รุ่นเก่าที่ยังคงใช้พฤติกรรมการลงนามก่อนมีการท้าทาย connect จะส่งคืนรหัสรายละเอียด DEVICE_AUTH_* ภายใต้ error.details.code พร้อม error.details.reason ที่คงที่

ความล้มเหลวในการย้ายระบบที่พบบ่อย:

เป้าหมายการย้ายระบบ:

• รอ connect.challenge เสมอ
• ลงลายมือชื่อเพย์โหลด v2 ที่มี nonce ของเซิร์ฟเวอร์
• ส่ง nonce เดียวกันใน connect.params.device.nonce
• เพย์โหลดลายมือชื่อที่แนะนำคือ v3 (buildDeviceAuthPayloadV3 ใน packages/gateway-client/src/device-auth.ts), ซึ่งผูก platform และ deviceFamily เพิ่มเติมจาก ฟิลด์อุปกรณ์/ไคลเอนต์/บทบาท/ขอบเขตสิทธิ์/โทเค็น/nonce
• ลายมือชื่อ v2 แบบเดิมยังคงได้รับการยอมรับเพื่อความเข้ากันได้ แต่การตรึง เมทาดาทาของอุปกรณ์ที่จับคู่ยังคงควบคุมนโยบายคำสั่งเมื่อเชื่อมต่อใหม่

TLS และการตรึง

• รองรับ TLS สำหรับการเชื่อมต่อ WS (การกำหนดค่า gateway.tls)
• ไคลเอนต์สามารถเลือกตรึงลายนิ้วมือใบรับรองของ Gateway ผ่าน gateway.remote.tlsFingerprint หรือ CLI --tls-fingerprint

ขอบเขต

โปรโตคอลนี้เปิดเผย API ทั้งหมดของ Gateway ได้แก่ สถานะ ช่อง โมเดล แชต เอเจนต์ เซสชัน โหนด การอนุมัติ และอื่นๆ พื้นผิวที่แน่นอนกำหนดโดย สคีมา TypeBox ที่ส่งออกซ้ำจาก packages/gateway-protocol/src/schema.ts

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

• การสร้างไคลเอนต์ Gateway
• การฝัง OpenClaw
• โปรโตคอลบริดจ์
• คู่มือปฏิบัติงาน Gateway