Gateway protocol

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

การส่งข้อมูล

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

Handshake (connect)

Gateway → ไคลเอนต์ (pre-connect challenge):

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

ไคลเอนต์ → 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 → ไคลเอนต์:

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

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

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

เมื่อไม่ได้ออก device token, hello-ok.auth จะรายงาน permissions ที่ negotiate แล้ว โดยไม่มีฟิลด์ token:

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

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

เมื่อมีการออก device token, hello-ok จะรวมสิ่งต่อไปนี้ด้วย:

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

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

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

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

ตัวอย่างโหนด

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

การจัด frame

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

method ที่มี side effect ต้องใช้ idempotency keys (ดู schema)

บทบาท + ขอบเขต

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

บทบาท

• operator = ไคลเอนต์ control plane (CLI/UI/automation)
• node = host ความสามารถ (camera/screen/canvas/system.run)

ขอบเขต (operator)

ขอบเขตที่พบบ่อย:

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

talk.config พร้อม includeSecrets: true ต้องใช้ operator.talk.secrets (หรือ operator.admin)

method RPC ของ gateway ที่ plugin ลงทะเบียนอาจขอขอบเขต operator ของตนเองได้ แต่ prefix admin หลักที่สงวนไว้ (config.*, exec.approvals.*, wizard.*, update.*) จะ resolve เป็น operator.admin เสมอ

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

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

• คำขอที่ไม่มี command: operator.pairing
• คำขอที่มี command โหนดที่ไม่ใช่ exec: operator.pairing + operator.write
• คำขอที่รวม system.run, system.run.prepare หรือ system.which: operator.pairing + operator.admin

Caps/commands/permissions (โหนด)

โหนดประกาศ capability claims ตอน connect:

• caps: หมวดหมู่ความสามารถระดับสูง เช่น camera, canvas, screen, location, voice และ talk
• commands: allowlist ของ command สำหรับ invoke
• permissions: toggle แบบละเอียด (เช่น screen.record, camera.capture)

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

Presence

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

เหตุการณ์โหนดยังทำงานอยู่เบื้องหลัง

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

{  "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 เป็น closed enum: background, silent_push, bg_app_refresh, significant_location, manual หรือ connect string trigger ที่ไม่รู้จักจะถูก normalize เป็น background โดย gateway ก่อน persistence เหตุการณ์นี้ durable เฉพาะสำหรับเซสชันอุปกรณ์โหนด ที่ยืนยันตัวตนแล้วเท่านั้น; เซสชันที่ไม่มีอุปกรณ์หรือไม่ได้จับคู่จะส่งคืน handled: false

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

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

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

การกำหนดขอบเขตเหตุการณ์ broadcast

เหตุการณ์ broadcast ผ่าน WebSocket ที่ server push จะถูก gate ด้วยขอบเขต เพื่อไม่ให้เซสชันที่มีขอบเขตเฉพาะ pairing หรือเฉพาะโหนดรับเนื้อหาเซสชันแบบ passive

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

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

ตระกูล method RPC ที่พบบ่อย

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

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

• chat: การอัปเดตแชท UI เช่น chat.inject และเหตุการณ์แชทอื่นที่เป็นทรานสคริปต์เท่านั้น ในโปรโตคอล v4 เพย์โหลดเดลตาจะมี deltaText; message ยังคงเป็น สแนปช็อตผู้ช่วยแบบสะสม การแทนที่ที่ไม่ใช่คำนำหน้าจะตั้ง replace=true และใช้ deltaText เป็นข้อความแทนที่
• session.message, session.operation และ session.tool: การอัปเดตทรานสคริปต์, การดำเนินการเซสชันที่กำลังทำงาน และสตรีมเหตุการณ์สำหรับเซสชัน ที่สมัครรับไว้
• sessions.changed: ดัชนีเซสชันหรือเมทาดาทาเปลี่ยนแปลง
• presence: การอัปเดตสแนปช็อตสถานะระบบ
• tick: เหตุการณ์ keepalive / liveness เป็นระยะ
• 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: การกำหนดค่าทริกเกอร์คำปลุกเปลี่ยนแปลง
• exec.approval.requested / exec.approval.resolved: วงจรชีวิตการอนุมัติการ exec
• plugin.approval.requested / plugin.approval.resolved: วงจรชีวิตการอนุมัติ Plugin

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

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

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 งานที่ขาดหายจะส่งคืนรูปแบบข้อผิดพลาดไม่พบของ 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 เอเจนต์ของเซสชันที่ resolve แล้วต้องตรงกับ agentId
  • ตัวครอบคอร์เฉพาะเจ้าของ เช่น cron, gateway และ nodes ต้องมีตัวตนเจ้าของ/ผู้ดูแลระบบ (operator.admin) แม้ว่าเมธอด tools.invoke เองจะเป็น operator.write
  • การตอบกลับเป็น envelope สำหรับ SDK ที่มี ok, toolName, output ที่ไม่บังคับ และฟิลด์ error แบบมีชนิด การอนุมัติหรือการปฏิเสธตามนโยบายจะส่งคืน ok:false ในเพย์โหลด แทนที่จะข้ามไปป์ไลน์นโยบายเครื่องมือของ Gateway
• ผู้ปฏิบัติงานสามารถเรียก skills.status (operator.read) เพื่อดึงรายการ skill ที่มองเห็นได้สำหรับเอเจนต์
  • 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 ที่ระบุชัดเจน โดยถอยกลับไปใช้แค็ตตาล็อกเต็มเฉพาะเมื่อไม่มีแถวโมเดลที่กำหนดค่าไว้
• "all": แค็ตตาล็อก Gateway แบบเต็ม โดยข้าม agents.defaults.models ใช้สิ่งนี้สำหรับการวินิจฉัยและ UI การค้นพบ ไม่ใช่ตัวเลือกโมเดลตามปกติ

การอนุมัติ Exec

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

ทางเลือกสำรองการส่งมอบของเอเจนต์

• คำขอ agent สามารถรวม deliver=true เพื่อขอการส่งมอบออกภายนอกได้
• bestEffortDeliver=false คงพฤติกรรมแบบเข้มงวด: เป้าหมายการส่งมอบที่ resolve ไม่ได้หรือเป็นภายในเท่านั้นจะส่งคืน INVALID_REQUEST
• bestEffortDeliver=true อนุญาตให้ถอยกลับไปดำเนินการเฉพาะเซสชันเมื่อไม่สามารถ resolve เส้นทางที่ส่งมอบภายนอกได้ (เช่น เซสชันภายใน/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.params.auth.*
• gateway.auth.mode: "none" สำหรับ private-ingress จะข้ามการยืนยันตัวตนขณะเชื่อมต่อแบบ shared-secret ทั้งหมด อย่าเปิดใช้โหมดนั้นบน ingress สาธารณะ/ไม่น่าเชื่อถือ
• หลังจากจับคู่แล้ว Gateway จะออก device token ที่จำกัดตามบทบาทการเชื่อมต่อ
  • ขอบเขต โทเค็นนี้จะถูกส่งกลับใน hello-ok.auth.deviceToken และไคลเอนต์ควร คงไว้ใช้สำหรับการเชื่อมต่อในอนาคต
• ไคลเอนต์ควรคง hello-ok.auth.deviceToken หลักไว้หลังจากเชื่อมต่อสำเร็จทุกครั้ง
• การเชื่อมต่อใหม่ด้วย device token ที่ จัดเก็บไว้ ควรนำชุดขอบเขตที่อนุมัติแล้วและจัดเก็บไว้ สำหรับโทเค็นนั้นกลับมาใช้ด้วย วิธีนี้จะรักษาสิทธิ์อ่าน/probe/status ที่ได้รับอนุญาตแล้ว และหลีกเลี่ยงการยุบการเชื่อมต่อใหม่อย่างเงียบๆ ไปเป็น ขอบเขต implicit แบบ admin-only ที่แคบกว่า
• การประกอบการยืนยันตัวตนขณะเชื่อมต่อฝั่งไคลเอนต์ (selectConnectAuth ใน src/gateway/client.ts):
  • auth.password เป็นอิสระจากส่วนอื่น และจะถูกส่งต่อเสมอเมื่อตั้งค่าไว้
  • auth.token จะถูกเติมตามลำดับความสำคัญ: shared token แบบชัดเจนก่อน จากนั้น deviceToken แบบชัดเจน แล้วจึงเป็นโทเค็นต่ออุปกรณ์ที่จัดเก็บไว้ (อ้างอิงด้วย deviceId + role)
  • auth.bootstrapToken จะถูกส่งเฉพาะเมื่อไม่มีรายการข้างต้นใด resolve เป็น auth.token shared token หรือ device token ใดๆ ที่ resolve ได้จะระงับการส่งค่านี้
  • การเลื่อนใช้ device token ที่จัดเก็บไว้โดยอัตโนมัติในการลองใหม่แบบครั้งเดียว เมื่อเจอ AUTH_TOKEN_MISMATCH ถูกจำกัดไว้เฉพาะ ปลายทางที่เชื่อถือได้เท่านั้น — loopback หรือ wss:// ที่มี tlsFingerprint แบบ pinned wss:// สาธารณะ ที่ไม่มี pinning จะไม่เข้าเกณฑ์
• bootstrap ด้วย setup-code ในตัวจะส่งคืน Node หลัก hello-ok.auth.deviceToken พร้อมโทเค็นผู้ปฏิบัติการแบบมีขอบเขตจำกัดใน hello-ok.auth.deviceTokens สำหรับการส่งต่อไปยังมือถือที่เชื่อถือได้ โทเค็นผู้ปฏิบัติการ มี operator.talk.secrets สำหรับอ่านการกำหนดค่า Talk แบบ native และ ไม่รวม operator.admin กับ operator.pairing
• ขณะที่ bootstrap ด้วย setup-code ที่ไม่ใช่ baseline กำลังรอการอนุมัติ รายละเอียด PAIRING_REQUIRED จะมี recommendedNextStep: "wait_then_retry", retryable: true, และ pauseReconnect: false ไคลเอนต์ควรเชื่อมต่อใหม่ต่อไปด้วย bootstrap token เดิมจนกว่าคำขอจะได้รับอนุมัติหรือโทเค็นจะใช้ไม่ได้
• คง hello-ok.auth.deviceTokens ไว้เฉพาะเมื่อการเชื่อมต่อใช้ bootstrap auth บน transport ที่เชื่อถือได้ เช่น wss:// หรือการจับคู่ผ่าน loopback/local
• หากไคลเอนต์ระบุ deviceToken หรือ scopes แบบ ชัดเจน ชุดขอบเขตที่ ผู้เรียกขอจะยังคงเป็นแหล่งอ้างอิงหลัก ขอบเขตที่แคชไว้จะถูกนำกลับมาใช้ เฉพาะเมื่อไคลเอนต์กำลังนำโทเค็นต่ออุปกรณ์ที่จัดเก็บไว้กลับมาใช้
• สามารถหมุนเวียน/เพิกถอน device token ได้ผ่าน device.token.rotate และ device.token.revoke (ต้องมีขอบเขต operator.pairing) การหมุนเวียนหรือ เพิกถอน Node หรือบทบาทอื่นที่ไม่ใช่ผู้ปฏิบัติการต้องมี operator.admin ด้วย
• device.token.rotate ส่งคืนเมทาดาทาการหมุนเวียน โดยจะ echo bearer token ตัวแทน เฉพาะสำหรับการเรียกจากอุปกรณ์เดียวกันที่ยืนยันตัวตนด้วย device token นั้นอยู่แล้ว เพื่อให้ไคลเอนต์แบบ token-only สามารถคงตัวแทนไว้ก่อนเชื่อมต่อใหม่ได้ การหมุนเวียนแบบ shared/admin จะไม่ echo bearer token
• การออกโทเค็น การหมุนเวียน และการเพิกถอนจะยังคงจำกัดอยู่ภายในชุดบทบาทที่อนุมัติแล้ว ซึ่งบันทึกในรายการจับคู่ของอุปกรณ์นั้น การเปลี่ยนโทเค็นไม่สามารถขยายหรือ กำหนดเป้าหมายบทบาทอุปกรณ์ที่การอนุมัติการจับคู่ไม่เคยให้ไว้
• สำหรับเซสชันโทเค็นของอุปกรณ์ที่จับคู่แล้ว การจัดการอุปกรณ์จะจำกัดอยู่กับตนเอง เว้นแต่ ผู้เรียกจะมี operator.admin ด้วย: ผู้เรียกที่ไม่ใช่ admin สามารถจัดการได้เฉพาะ โทเค็นผู้ปฏิบัติการสำหรับรายการอุปกรณ์ของ ตนเอง เท่านั้น การจัดการโทเค็นของ Node และโทเค็นอื่นที่ไม่ใช่ผู้ปฏิบัติการเป็น admin-only แม้จะเป็นอุปกรณ์ของผู้เรียกเองก็ตาม
• device.token.rotate และ device.token.revoke ยังตรวจสอบชุดขอบเขตของโทเค็นผู้ปฏิบัติการ เป้าหมายเทียบกับขอบเขตเซสชันปัจจุบันของผู้เรียกด้วย ผู้เรียกที่ไม่ใช่ admin ไม่สามารถหมุนเวียนหรือเพิกถอนโทเค็นผู้ปฏิบัติการที่กว้างกว่าที่ตนมีอยู่แล้ว
• ความล้มเหลวในการยืนยันตัวตนมี 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:
  • ไคลเอนต์ที่เชื่อถือได้อาจลองใหม่แบบมีขอบเขตหนึ่งครั้งด้วยโทเค็นต่ออุปกรณ์ที่แคชไว้
  • หากการลองใหม่นั้นล้มเหลว ไคลเอนต์ควรหยุดลูปการเชื่อมต่อใหม่อัตโนมัติและแสดงคำแนะนำการดำเนินการสำหรับผู้ปฏิบัติการ
• AUTH_SCOPE_MISMATCH หมายความว่า device token ถูกจดจำได้แต่ไม่ครอบคลุม บทบาท/ขอบเขตที่ร้องขอ ไคลเอนต์ไม่ควรแสดงสิ่งนี้ว่าเป็นโทเค็นไม่ถูกต้อง ให้แจ้งผู้ปฏิบัติการให้จับคู่ใหม่ หรืออนุมัติสัญญาขอบเขตที่แคบกว่า/กว้างกว่า

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

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

การวินิจฉัยการย้ายข้อมูล device auth

สำหรับไคลเอนต์ legacy ที่ยังใช้พฤติกรรมการลงนามก่อนมี 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
• ลายเซ็น legacy v2 ยังคงยอมรับเพื่อความเข้ากันได้ แต่การ pin เมทาดาทา paired-device ยังคงควบคุมนโยบายคำสั่งเมื่อเชื่อมต่อใหม่

TLS + pinning

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

ขอบเขต

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

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

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