โปรโตคอล Gateway

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

ทรานสปอร์ต

• WebSocket, text frames พร้อม payload JSON
• เฟรมแรก ต้อง เป็นคำขอ connect
• เฟรมก่อนเชื่อมต่อถูกจำกัดไว้ที่ 64 KiB หลังจาก handshake สำเร็จแล้ว ไคลเอนต์ ควรทำตามขีดจำกัด hello-ok.policy.maxPayload และ hello-ok.policy.maxBufferedBytes เมื่อเปิดใช้ diagnostics, เฟรมขาเข้าที่มีขนาดใหญ่เกินไปและบัฟเฟอร์ขาออกที่ช้าจะส่งอีเวนต์ payload.large ก่อนที่ gateway จะปิดหรือทิ้งเฟรมที่ได้รับผลกระทบ อีเวนต์เหล่านี้เก็บ ขนาด ขีดจำกัด พื้นผิว และรหัสเหตุผลที่ปลอดภัยไว้ แต่ไม่เก็บเนื้อหาข้อความ เนื้อหาไฟล์แนบ เนื้อหาเฟรมดิบ โทเค็น คุกกี้ หรือค่าลับ

Handshake (connect)

Gateway → Client (challenge ก่อนเชื่อมต่อ):

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

Client → Gateway:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "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 → Client:

{  "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    }  }}

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

server, features, snapshot และ policy ทั้งหมดเป็นค่าที่ schema กำหนดให้มี (packages/gateway-protocol/src/schema/frames.ts) auth ก็จำเป็นเช่นกันและรายงาน role/scopes ที่เจรจาได้ pluginSurfaceUrls เป็นตัวเลือกเสริมและแมปชื่อพื้นผิวของ plugin เช่น canvas ไปยัง URL ที่โฮสต์แบบมี scope

URL พื้นผิวของ plugin ที่มี scope อาจหมดอายุได้ Node สามารถเรียก node.pluginSurface.refresh พร้อม { "surface": "canvas" } เพื่อรับรายการใหม่ ใน pluginSurfaceUrls การรีแฟกเตอร์ Plugin Canvas แบบทดลองไม่รองรับเส้นทางความเข้ากันได้ canvasHostUrl, canvasCapability หรือ node.canvas.capability.refresh ที่เลิกใช้แล้ว; ไคลเอนต์ native และ gateway ปัจจุบันต้องใช้พื้นผิวของ plugin

เมื่อไม่มีการออกโทเค็นอุปกรณ์ hello-ok.auth จะรายงานสิทธิ์ที่เจรจาได้ โดยไม่มีฟิลด์โทเค็น:

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

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

เมื่อมีการออกโทเค็นอุปกรณ์ hello-ok จะรวมข้อมูลนี้ด้วย:

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

การบูตสแตรปด้วย QR/setup-code ในตัวเป็นเส้นทางส่งต่อมือถือแบบใหม่ เมื่อ การเชื่อมต่อด้วย setup-code baseline สำเร็จ จะส่งคืนโทเค็น Node หลักพร้อม โทเค็น operator แบบมีขอบเขตหนึ่งรายการ:

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

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

ตัวอย่าง Node

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "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": "…"    }  }}

การจัดเฟรม

• Request: {type:"req", id, method, params}
• Response: {type:"res", id, ok, payload|error}
• Event: {type:"event", event, payload, seq?, stateVersion?}

เมธอดที่มีผลข้างเคียงต้องใช้ idempotency keys (ดู schema)

Roles + scopes

สำหรับโมเดล scope ของ operator แบบเต็ม การตรวจสอบในช่วงอนุมัติ และ ความหมายของ shared-secret ดู Operator scopes

Roles

• operator = ไคลเอนต์ระนาบควบคุม (CLI/UI/automation)
• node = โฮสต์ความสามารถ (camera/screen/canvas/system.run)

Scopes (operator)

scope ที่พบบ่อย:

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

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

เมธอด Gateway RPC ที่ลงทะเบียนโดย plugin อาจขอ scope ของ operator ของตนเองได้ แต่ prefix ของ core admin ที่สงวนไว้ (config.*, exec.approvals.*, wizard.*, update.*) จะแปลงเป็น operator.admin เสมอ

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

node.pair.approve ยังมีการตรวจสอบ scope เพิ่มเติมในช่วงอนุมัติ นอกเหนือจาก scope ของเมธอดพื้นฐาน:

• คำขอที่ไม่มีคำสั่ง: operator.pairing
• คำขอที่มีคำสั่ง Node ที่ไม่ใช่ exec: operator.pairing + operator.write
• คำขอที่รวม system.run, system.run.prepare หรือ system.which: operator.pairing + operator.admin

Caps/commands/permissions (node)

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

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

Gateway ถือค่าสิ่งเหล่านี้เป็น claims และบังคับใช้ allowlist ฝั่งเซิร์ฟเวอร์

Presence

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

อีเวนต์ alive เบื้องหลังของ Node

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

{  "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 สตริง trigger ที่ไม่รู้จักจะถูก gateway ทำให้เป็น background ก่อนคงค่าไว้ อีเวนต์นี้คงทนเฉพาะสำหรับเซสชันอุปกรณ์ Node ที่ยืนยันตัวตนแล้ว เท่านั้น; เซสชันที่ไม่มีอุปกรณ์หรือยังไม่ได้จับคู่จะส่งคืน handled: false

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

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

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

การกำหนด scope ของอีเวนต์ broadcast

อีเวนต์ broadcast ของ WebSocket ที่เซิร์ฟเวอร์ push จะถูก gate ด้วย scope เพื่อไม่ให้เซสชันที่มี scope สำหรับการจับคู่หรือเฉพาะ Node รับเนื้อหาเซสชันแบบ passive

• เฟรม chat, agent และ tool-result (รวมถึงอีเวนต์ agent แบบ streamed และผลลัพธ์ tool call) ต้องมีอย่างน้อย operator.read เซสชันที่ไม่มี operator.read จะข้ามเฟรมเหล่านี้ทั้งหมด
• broadcast plugin.* ที่กำหนดโดย Plugin ถูก gate ไปยัง operator.write หรือ operator.admin ขึ้นอยู่กับวิธีที่ plugin ลงทะเบียนไว้
• อีเวนต์สถานะและทรานสปอร์ต (heartbeat, presence, tick, lifecycle การเชื่อมต่อ/ตัดการเชื่อมต่อ ฯลฯ) ยังคงไม่ถูกจำกัด เพื่อให้ทุกเซสชันที่ยืนยันตัวตนแล้วสังเกตสุขภาพของทรานสปอร์ตได้
• ตระกูลอีเวนต์ broadcast ที่ไม่รู้จัก ถูก gate ด้วย scope ตามค่าเริ่มต้น (fail-closed) เว้นแต่ handler ที่ลงทะเบียนไว้จะผ่อนคลายข้อจำกัดอย่างชัดเจน

การเชื่อมต่อไคลเอนต์แต่ละรายการเก็บหมายเลขลำดับต่อไคลเอนต์ของตนเอง เพื่อให้ broadcast รักษาลำดับแบบ monotonic บน socket นั้น แม้เมื่อไคลเอนต์ต่างกันเห็น subset ของสตรีมอีเวนต์ที่ถูกกรองด้วย scope แตกต่างกัน

ตระกูลเมธอด RPC ที่พบบ่อย

พื้นผิว WS สาธารณะกว้างกว่าตัวอย่าง handshake/auth ด้านบน นี่ ไม่ใช่ dump ที่สร้างขึ้น — hello-ok.features.methods เป็นรายการ discovery แบบอนุรักษ์นิยมที่สร้างจาก src/gateway/server-methods-list.ts รวมกับ export เมธอดของ plugin/channel ที่โหลดแล้ว ให้ถือเป็น feature discovery ไม่ใช่รายการแจกแจงแบบเต็ม ของ src/gateway/server-methods/*.ts

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

• chat: การอัปเดตแชท UI เช่น chat.inject และเหตุการณ์แชทอื่นที่เป็นเฉพาะทรานสคริปต์ ใน protocol v4 payload แบบ delta จะมี deltaText; message ยังคงเป็น สแนปช็อตผู้ช่วยแบบสะสม การแทนที่ที่ไม่ใช่ prefix จะตั้ง replace=true และใช้ deltaText เป็นข้อความแทนที่
• session.message, session.operation และ session.tool: ทรานสคริปต์, การดำเนินการเซสชันที่กำลังทำงาน และการอัปเดตสตรีมเหตุการณ์สำหรับเซสชัน ที่สมัครรับ
• sessions.changed: ดัชนีเซสชันหรือเมทาดาทาเปลี่ยนแปลง
• presence: การอัปเดตสแนปช็อต presence ของระบบ
• tick: เหตุการณ์ keepalive / liveness เป็นระยะ
• health: การอัปเดตสแนปช็อตสุขภาพของ Gateway
• heartbeat: การอัปเดตสตรีมเหตุการณ์ Heartbeat
• cron: เหตุการณ์การเปลี่ยนแปลงรัน/งาน Cron
• shutdown: การแจ้งเตือนการปิด Gateway
• node.pair.requested / node.pair.resolved: วงจรชีวิตการจับคู่ Node
• node.invoke.request: การ broadcast คำขอ invoke ของ Node
• device.pair.requested / device.pair.resolved: วงจรชีวิตอุปกรณ์ที่จับคู่
• voicewake.changed: การกำหนดค่า trigger wake-word เปลี่ยนแปลง
• exec.approval.requested / exec.approval.resolved: วงจรชีวิตการอนุมัติ exec
• plugin.approval.requested / plugin.approval.resolved: วงจรชีวิตการอนุมัติ Plugin

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

• Node อาจเรียก skills.bins เพื่อดึงรายการ executable ของ skill ปัจจุบัน สำหรับการตรวจสอบ auto-allow

RPC ของสมุดรายการงาน

ไคลเอนต์ผู้ปฏิบัติงานอาจตรวจสอบและยกเลิกระเบียนงานเบื้องหลังของ Gateway ผ่าน 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 }
  • id งานที่หายไปจะส่งคืนรูปแบบข้อผิดพลาด not-found ของ 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, timestamp, progress, สรุปสถานะสิ้นสุด และข้อความข้อผิดพลาดที่ผ่านการล้างข้อมูลแล้ว 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 อนุมานบริบทรันไทม์ที่เชื่อถือได้จากเซสชันฝั่งเซิร์ฟเวอร์ แทนการยอมรับบริบทการยืนยันตัวตนหรือการส่งมอบที่ผู้เรียกส่งมา
  • การตอบกลับเป็นการฉายภาพจากเซิร์ฟเวอร์ในขอบเขตเซสชันของคลังที่ใช้งานอยู่ รวมถึงเครื่องมือ core, Plugin, channel และเครื่องมือเซิร์ฟเวอร์ 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
  • แรปเปอร์ core สำหรับเจ้าของเท่านั้น เช่น 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) เพื่อจัดเตรียมอาร์ไคฟ์ Skill ส่วนตัวก่อนติดตั้ง นี่เป็นเส้นทางอัปโหลดผู้ดูแลแยกต่างหากสำหรับไคลเอนต์ที่เชื่อถือได้ ไม่ใช่โฟลว์ติดตั้ง Skill ของ ClawHub ตามปกติ และถูกปิดใช้งานโดยค่าเริ่มต้นเว้นแต่จะเปิดใช้ skills.install.allowUploadedArchives
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) สร้างการอัปโหลดที่ผูกกับ slug และค่า force นั้น
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) ต่อท้ายไบต์ที่ ออฟเซ็ตที่ถอดรหัสแล้วตรงกันทุกประการ
  • skills.upload.commit({ uploadId, sha256? }) ตรวจสอบขนาดสุดท้ายและ SHA-256 Commit จะสรุปการอัปโหลดเท่านั้น; ไม่ได้ติดตั้ง Skill
  • อาร์ไคฟ์ Skill ที่อัปโหลดเป็นอาร์ไคฟ์ zip ที่มีราก SKILL.md ชื่อไดเรกทอรีภายในของอาร์ไคฟ์ไม่เคยเป็นตัวเลือกเป้าหมายการติดตั้ง
• ผู้ปฏิบัติการอาจเรียก skills.install (operator.admin) ได้สามโหมด:
  • โหมด ClawHub: { source: "clawhub", slug, version?, force? } ติดตั้งโฟลเดอร์ Skill ลงในไดเรกทอรี skills/ ของเวิร์กสเปซเอเจนต์เริ่มต้น
  • โหมดอัปโหลด: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } ติดตั้งการอัปโหลดที่ commit แล้วลงในไดเรกทอรี skills/<slug> ของเวิร์กสเปซเอเจนต์เริ่มต้น ค่า slug และ force ต้องตรงกับคำขอ 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 ที่ไม่บังคับ:

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

การอนุมัติ Exec

• เมื่อคำขอ exec ต้องการการอนุมัติ 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 จะปฏิเสธการรันแทนการเชื่อถือเพย์โหลดที่ถูกแก้ไข

Fallback การส่งมอบเอเจนต์

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

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

• PROTOCOL_VERSION อยู่ใน packages/gateway-protocol/src/version.ts
• ไคลเอนต์ส่ง minProtocol + maxProtocol; เซิร์ฟเวอร์ปฏิเสธช่วงที่ ไม่รวมโปรโตคอลปัจจุบันของตน ไคลเอนต์และเซิร์ฟเวอร์ปัจจุบันต้องใช้ โปรโตคอล v4
• Schemas + models สร้างจากนิยาม TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

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

ไคลเอนต์อ้างอิงใน src/gateway/client.ts ใช้ค่าเริ่มต้นเหล่านี้ ค่าต่างๆ คงที่ตลอดโปรโตคอล v4 และเป็น baseline ที่คาดหวังสำหรับไคลเอนต์ภายนอก

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

Auth

• การยืนยันตัวตน Gateway ด้วย shared-secret ใช้ connect.params.auth.token หรือ connect.params.auth.password ขึ้นอยู่กับโหมดการยืนยันตัวตนที่กำหนดค่าไว้
• โหมดที่มีข้อมูลระบุตัวตน เช่น Tailscale Serve (gateway.auth.allowTailscale: true) หรือ non-loopback gateway.auth.mode: "trusted-proxy" จะผ่านการตรวจสอบการยืนยันตัวตนสำหรับ connect จาก ส่วนหัวคำขอแทน connect.params.auth.*
• private-ingress gateway.auth.mode: "none" จะข้ามการยืนยันตัวตน connect แบบ shared-secret ทั้งหมด อย่าเปิดเผยโหมดนั้นบน ingress สาธารณะ/ไม่น่าเชื่อถือ
• หลังจากจับคู่แล้ว Gateway จะออก device token ที่จำกัดขอบเขตตาม role + scopes ของการเชื่อมต่อ โดยส่งคืนใน hello-ok.auth.deviceToken และไคลเอนต์ควร เก็บไว้เพื่อใช้กับการเชื่อมต่อครั้งต่อไป
• ไคลเอนต์ควรเก็บ hello-ok.auth.deviceToken หลักหลังจาก connect สำเร็จทุกครั้ง
• การเชื่อมต่อใหม่ด้วย device token ที่ เก็บไว้ นั้นควรนำชุด scope ที่อนุมัติแล้ว ซึ่งเก็บไว้สำหรับ token นั้นกลับมาใช้ด้วย สิ่งนี้จะรักษาสิทธิ์เข้าถึง read/probe/status ที่ได้รับอนุญาตแล้ว และหลีกเลี่ยงการลดขอบเขตการเชื่อมต่อใหม่ อย่างเงียบ ๆ ให้เหลือเพียง scope admin-only โดยนัยที่แคบกว่า
• การประกอบการยืนยันตัวตน connect ฝั่งไคลเอนต์ (selectConnectAuth ใน src/gateway/client.ts):
  • auth.password แยกอิสระจากส่วนอื่นและจะถูกส่งต่อเสมอเมื่อตั้งค่าไว้
  • auth.token จะถูกเติมตามลำดับความสำคัญ: shared token ที่ระบุชัดเจนก่อน จากนั้น deviceToken ที่ระบุชัดเจน แล้วจึงเป็น token ต่ออุปกรณ์ที่เก็บไว้ (ผูกกับ deviceId + role)
  • auth.bootstrapToken จะถูกส่งเฉพาะเมื่อไม่มีรายการข้างต้นแก้เป็น auth.token ได้ shared token หรือ device token ใด ๆ ที่แก้ได้จะระงับการส่งค่านี้
  • การเลื่อนระดับ token ของอุปกรณ์ที่เก็บไว้โดยอัตโนมัติในการลองซ้ำแบบครั้งเดียว AUTH_TOKEN_MISMATCH ถูกจำกัดไว้สำหรับ ปลายทางที่เชื่อถือได้เท่านั้น — loopback หรือ wss:// ที่มี tlsFingerprint แบบปักหมุดไว้ wss:// สาธารณะที่ไม่มีการปักหมุดจะไม่เข้าเงื่อนไข
• bootstrap ด้วย setup-code ในตัวจะส่งคืน hello-ok.auth.deviceToken ของ node หลัก พร้อม token ของ operator ที่มีขอบเขตจำกัดใน hello-ok.auth.deviceTokens สำหรับการส่งต่อให้มือถือที่เชื่อถือได้ token ของ operator มี operator.talk.secrets สำหรับการอ่านค่ากำหนด native Talk แต่ไม่รวม scope สำหรับ การเปลี่ยนแปลงการจับคู่และ operator.admin
• ระหว่างที่ bootstrap ด้วย setup-code ที่ไม่ใช่ baseline กำลังรอการอนุมัติ รายละเอียด PAIRING_REQUIRED จะมี recommendedNextStep: "wait_then_retry", retryable: true, และ pauseReconnect: false ไคลเอนต์ควรเชื่อมต่อใหม่ต่อไปด้วย bootstrap token เดิม จนกว่าคำขอจะได้รับการอนุมัติหรือ token จะใช้งานไม่ได้
• เก็บ hello-ok.auth.deviceTokens เฉพาะเมื่อ connect ใช้ bootstrap auth บน transport ที่เชื่อถือได้ เช่น wss:// หรือการจับคู่แบบ loopback/local
• หากไคลเอนต์ระบุ deviceToken อย่างชัดเจน หรือระบุ scopes อย่างชัดเจน ชุด scope ที่ผู้เรียกขอยังคงเป็นแหล่งอ้างอิงหลัก scope ที่แคชไว้จะถูกนำกลับมาใช้ เฉพาะเมื่อไคลเอนต์กำลังนำ token ต่ออุปกรณ์ที่เก็บไว้กลับมาใช้
• Device tokens สามารถหมุนเวียน/เพิกถอนได้ผ่าน device.token.rotate และ device.token.revoke (ต้องใช้ scope operator.pairing) การหมุนเวียนหรือ เพิกถอน node หรือ role อื่นที่ไม่ใช่ operator ต้องใช้ operator.admin ด้วย
• device.token.rotate จะส่งคืน metadata การหมุนเวียน โดยจะสะท้อน bearer token ทดแทนเฉพาะสำหรับการเรียกจากอุปกรณ์เดียวกันที่ยืนยันตัวตนด้วย device token นั้นอยู่แล้ว เพื่อให้ไคลเอนต์ที่ใช้เฉพาะ token สามารถเก็บค่าทดแทนก่อนเชื่อมต่อใหม่ได้ การหมุนเวียนแบบ shared/admin จะไม่สะท้อน bearer token
• การออก token การหมุนเวียน และการเพิกถอนจะถูกจำกัดไว้กับชุด role ที่อนุมัติแล้ว ซึ่งบันทึกอยู่ในรายการจับคู่ของอุปกรณ์นั้น การเปลี่ยนแปลง token ไม่สามารถขยายหรือ กำหนดเป้าหมาย role ของอุปกรณ์ที่การอนุมัติการจับคู่ไม่เคยให้ไว้
• สำหรับเซสชัน token ของอุปกรณ์ที่จับคู่แล้ว การจัดการอุปกรณ์จะจำกัดขอบเขตไว้กับตนเอง เว้นแต่ผู้เรียกจะมี operator.admin ด้วย: ผู้เรียกที่ไม่ใช่ admin สามารถจัดการได้เฉพาะ token ของ operator สำหรับรายการอุปกรณ์ ของตนเอง เท่านั้น การจัดการ token ของ node และ token อื่นที่ไม่ใช่ operator เป็น admin-only แม้สำหรับอุปกรณ์ของผู้เรียกเอง
• device.token.rotate และ device.token.revoke ยังตรวจสอบชุด scope ของ token operator เป้าหมายเทียบกับ scope ของเซสชันปัจจุบันของผู้เรียกด้วย ผู้เรียกที่ไม่ใช่ admin ไม่สามารถหมุนเวียนหรือเพิกถอน token operator ที่มีขอบเขตกว้างกว่าที่ตนมีอยู่แล้ว
• ความล้มเหลวของการยืนยันตัวตนจะมี error.details.code พร้อมคำแนะนำการกู้คืน:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• พฤติกรรมไคลเอนต์สำหรับ AUTH_TOKEN_MISMATCH:
  • ไคลเอนต์ที่เชื่อถือได้อาจลองซ้ำแบบมีขอบเขตหนึ่งครั้งด้วย token ต่ออุปกรณ์ที่แคชไว้
  • หากการลองซ้ำนั้นล้มเหลว ไคลเอนต์ควรหยุดลูปเชื่อมต่อใหม่อัตโนมัติและแสดงคำแนะนำการดำเนินการสำหรับ operator
• AUTH_SCOPE_MISMATCH หมายความว่า device token ได้รับการจดจำแล้วแต่ไม่ครอบคลุม role/scopes ที่ร้องขอ ไคลเอนต์ไม่ควรนำเสนอสิ่งนี้ว่าเป็น token ที่ไม่ถูกต้อง ให้แจ้ง operator เพื่อจับคู่ใหม่หรืออนุมัติสัญญา scope ที่แคบกว่า/กว้างกว่า

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

• Nodes ควรมีข้อมูลระบุตัวตนอุปกรณ์ที่เสถียร (device.id) ซึ่งได้มาจาก fingerprint ของ keypair
• Gateway ออก token ต่ออุปกรณ์ + role
• ต้องมีการอนุมัติการจับคู่สำหรับ ID อุปกรณ์ใหม่ เว้นแต่จะเปิดใช้การอนุมัติอัตโนมัติแบบ local
• การอนุมัติการจับคู่อัตโนมัติมีศูนย์กลางอยู่ที่การเชื่อมต่อ local loopback โดยตรง
• OpenClaw ยังมีเส้นทาง self-connect แบบ backend/container-local ที่แคบสำหรับ helper flows แบบ shared-secret ที่เชื่อถือได้
• การเชื่อมต่อ tailnet หรือ LAN บนโฮสต์เดียวกันยังคงถือเป็นระยะไกลสำหรับการจับคู่และ ต้องได้รับการอนุมัติ
• โดยปกติไคลเอนต์ WS จะรวมข้อมูลระบุตัวตน device ระหว่าง connect (operator + node) ข้อยกเว้น operator ที่ไม่มีอุปกรณ์มีเฉพาะเส้นทางความเชื่อถือที่ระบุชัดเจน:
  • gateway.controlUi.allowInsecureAuth=true สำหรับความเข้ากันได้กับ HTTP ที่ไม่ปลอดภัยแบบ localhost-only
  • การยืนยันตัวตน Control UI ของ operator ผ่าน gateway.auth.mode: "trusted-proxy" ที่สำเร็จ
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, ลดระดับความปลอดภัยอย่างรุนแรง)
  • RPC backend ของ gateway-client แบบ direct-loopback บนเส้นทาง helper ภายในที่สงวนไว้
• การละเว้นข้อมูลระบุตัวตนอุปกรณ์มีผลต่อ scope เมื่ออนุญาตการเชื่อมต่อ operator ที่ไม่มีอุปกรณ์ผ่านเส้นทางความเชื่อถือที่ระบุชัดเจน OpenClaw ยังคงล้าง scope ที่ประกาศเองเป็นชุดว่าง เว้นแต่เส้นทางนั้นมีข้อยกเว้นการรักษา scope ที่มีชื่อกำกับ จากนั้นเมธอดที่ถูกควบคุมด้วย scope จะล้มเหลวด้วย missing scope
• gateway.controlUi.dangerouslyDisableDeviceAuth=true เป็นเส้นทางรักษา scope แบบ break-glass ของ Control UI ไม่ได้ให้ scope แก่ไคลเอนต์ WebSocket แบบ backend หรือ CLI-shaped ที่กำหนดเองโดยพลการ
• เส้นทาง helper backend ของ gateway-client แบบ direct-loopback ที่สงวนไว้จะรักษา scope เฉพาะสำหรับ RPC control-plane แบบ local ภายในเท่านั้น ID backend ที่กำหนดเอง จะไม่ได้รับข้อยกเว้นนี้
• การเชื่อมต่อทั้งหมดต้องลงนาม nonce connect.challenge ที่เซิร์ฟเวอร์ให้มา

การวินิจฉัยการย้ายการยืนยันตัวตนอุปกรณ์

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

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

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

• รอ connect.challenge เสมอ
• ลงนาม payload v2 ที่มี nonce ของเซิร์ฟเวอร์
• ส่ง nonce เดียวกันใน connect.params.device.nonce
• payload ลายเซ็นที่แนะนำคือ v3 ซึ่งผูก platform และ deviceFamily เพิ่มเติมจากฟิลด์ device/client/role/scopes/token/nonce
• ลายเซ็น v2 รุ่นเก่ายังคงได้รับการยอมรับเพื่อความเข้ากันได้ แต่การปักหมุด metadata ของอุปกรณ์ที่จับคู่แล้วยังคงควบคุมนโยบายคำสั่งเมื่อเชื่อมต่อใหม่

TLS + การปักหมุด

• รองรับ TLS สำหรับการเชื่อมต่อ WS
• ไคลเอนต์อาจเลือกปักหมุด fingerprint ของใบรับรอง Gateway ได้ (ดู config gateway.tls พร้อม gateway.remote.tlsFingerprint หรือ CLI --tls-fingerprint)

Scope

โปรโตคอลนี้เปิดเผย Gateway API เต็มรูปแบบ (status, channels, models, chat, agent, sessions, nodes, approvals เป็นต้น) พื้นผิวที่แน่นอนกำหนดโดย TypeBox schemas ใน packages/gateway-protocol/src/schema.ts

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

• โปรโตคอล Bridge
• runbook ของ Gateway