โปรโตคอล Gateway

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

การขนส่ง

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

​

Handshake (connect)

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

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

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

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

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

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

​

ตัวอย่าง 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": "…"
    }
  }
}

​

การจัดเฟรม

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

​

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

​

บทบาท

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

​

ขอบเขต (operator)

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

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

​

Caps/commands/permissions (node)

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

​

Presence

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

​

เหตุการณ์ Node background 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\"}"
}

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

​

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

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

​

กลุ่มเมธอด RPC ทั่วไป

​

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

• chat: การอัปเดตแชตใน UI เช่น chat.inject และเหตุการณ์แชตอื่นๆ ที่มีเฉพาะบันทึกการสนทนา
• session.message และ 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: การกระจายคำขอ invoke ของ 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 เพื่อดึงรายการปัจจุบันของไฟล์ปฏิบัติการ Skill สำหรับการตรวจสอบ auto-allow

​

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 รายงานว่ารันไทม์ยอมรับหรือบันทึกการยกเลิกหรือไม่

​

เมธอดตัวช่วยของผู้ปฏิบัติงาน

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

​

มุมมอง models.list

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

​

การอนุมัติ exec

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

​

fallback การส่งมอบของ agent

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

​

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

• PROTOCOL_VERSION อยู่ใน src/gateway/protocol/version.ts
• ไคลเอนต์ส่ง minProtocol + maxProtocol; เซิร์ฟเวอร์ปฏิเสธช่วงที่ ไม่รวม protocol ปัจจุบันของตน ไคลเอนต์ native ใช้ขอบเขตล่าง v3 เพื่อให้ ไคลเอนต์ v4 แบบเพิ่มได้ยังคงเข้าถึง gateway v3 ได้
• Schema + model ถูกสร้างจากนิยาม TypeBox:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

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

​

การยืนยันตัวตน

• การยืนยันตัวตน Gateway แบบ shared-secret ใช้ connect.params.auth.token หรือ connect.params.auth.password ขึ้นอยู่กับโหมดการยืนยันตัวตนที่กำหนดค่าไว้
• โหมดที่มีข้อมูลระบุตัวตน เช่น Tailscale Serve (gateway.auth.allowTailscale: true) หรือ gateway.auth.mode: "trusted-proxy" ที่ไม่ใช่ loopback จะผ่านการตรวจสอบการยืนยันตัวตนสำหรับ connect จาก request headers แทน connect.params.auth.*
• gateway.auth.mode: "none" สำหรับ private-ingress จะข้ามการยืนยันตัวตนแบบ shared-secret สำหรับ connect ทั้งหมด; อย่าเปิดเผยโหมดนั้นบน ingress สาธารณะหรือไม่น่าเชื่อถือ
• หลังการจับคู่ Gateway จะออก device token ที่จำกัดขอบเขตตาม role + scopes ของการเชื่อมต่อ ค่านี้จะถูกส่งคืนใน hello-ok.auth.deviceToken และ client ควร เก็บไว้เพื่อใช้ในการเชื่อมต่อในอนาคต
• client ควรเก็บ hello-ok.auth.deviceToken หลักหลังจาก connect สำเร็จทุกครั้ง
• การเชื่อมต่อใหม่ด้วย device token ที่ เก็บไว้ นั้นควรใช้ชุด scope ที่อนุมัติแล้วซึ่งเก็บไว้ สำหรับ token นั้นซ้ำด้วย วิธีนี้จะรักษาสิทธิ์เข้าถึง read/probe/status ที่ได้รับอนุญาตแล้ว และหลีกเลี่ยงการย่อขอบเขตการเชื่อมต่อใหม่อย่างเงียบ ๆ เป็น scope แบบ admin-only โดยนัยที่แคบกว่า
• การประกอบการยืนยันตัวตนสำหรับ connect ฝั่ง client (selectConnectAuth ใน src/gateway/client.ts):
  • auth.password เป็นอิสระจากส่วนอื่นและจะถูกส่งต่อเสมอเมื่อมีการตั้งค่า
  • auth.token ถูกเติมค่าตามลำดับความสำคัญ: shared token ที่ระบุอย่างชัดเจนก่อน, จากนั้น deviceToken ที่ระบุอย่างชัดเจน, แล้วจึงเป็น per-device token ที่เก็บไว้ (ผูกด้วย deviceId + role)
  • auth.bootstrapToken จะถูกส่งเฉพาะเมื่อไม่มีรายการข้างต้นแก้เป็น auth.token ได้ shared token หรือ device token ใด ๆ ที่แก้ได้จะระงับค่านี้
  • การเลื่อนขั้นอัตโนมัติของ device token ที่เก็บไว้ในการลองซ้ำแบบ one-shot AUTH_TOKEN_MISMATCH ถูกจำกัดให้ทำได้กับ endpoint ที่เชื่อถือได้เท่านั้น — loopback หรือ wss:// ที่มี tlsFingerprint แบบ pinned wss:// สาธารณะที่ไม่มีการ pin จะไม่เข้าเกณฑ์
• รายการ hello-ok.auth.deviceTokens เพิ่มเติมคือ token สำหรับ bootstrap handoff เก็บรายการเหล่านี้ไว้เฉพาะเมื่อ connect ใช้ bootstrap auth บน transport ที่เชื่อถือได้ เช่น wss:// หรือการจับคู่แบบ loopback/local
• หาก client ระบุ deviceToken หรือ scopes อย่าง ชัดเจน ชุด scope ที่ ผู้เรียกขอยังคงเป็นแหล่งอ้างอิงหลัก; cached scopes จะถูกนำกลับมาใช้เฉพาะ เมื่อ client กำลังใช้ per-device token ที่เก็บไว้ซ้ำ
• device token สามารถหมุนเวียน/เพิกถอนได้ผ่าน device.token.rotate และ device.token.revoke (ต้องมี scope operator.pairing)
• device.token.rotate ส่งคืน metadata การหมุนเวียน โดยจะ echo replacement bearer token เฉพาะสำหรับการเรียกจากอุปกรณ์เดียวกันที่ยืนยันตัวตนด้วย device token นั้นอยู่แล้ว เพื่อให้ client แบบ token-only สามารถเก็บ replacement ของตนก่อน เชื่อมต่อใหม่ การหมุนเวียนแบบ shared/admin จะไม่ echo bearer token
• การออก token การหมุนเวียน และการเพิกถอนยังคงถูกจำกัดไว้กับชุด role ที่อนุมัติแล้ว ซึ่งบันทึกไว้ในรายการ pairing ของ device นั้น; การเปลี่ยนแปลง token ไม่สามารถขยายหรือ กำหนดเป้าหมาย role ของ device ที่การอนุมัติ pairing ไม่เคยให้ไว้
• สำหรับ paired-device token sessions การจัดการ device จะจำกัดขอบเขตกับตนเอง เว้นแต่ ผู้เรียกจะมี operator.admin ด้วย: ผู้เรียกที่ไม่ใช่ admin สามารถลบ/เพิกถอน/หมุนเวียน ได้เฉพาะรายการ device ของตนเอง เท่านั้น
• device.token.rotate และ device.token.revoke ยังตรวจสอบชุด scope ของ operator token เป้าหมายเทียบกับ scopes ของ session ปัจจุบันของผู้เรียก ผู้เรียกที่ไม่ใช่ admin ไม่สามารถหมุนเวียนหรือเพิกถอน operator token ที่กว้างกว่าที่ตนมีอยู่แล้ว
• ความล้มเหลวในการยืนยันตัวตนมี 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)
• พฤติกรรมของ client สำหรับ AUTH_TOKEN_MISMATCH:
  • client ที่เชื่อถือได้อาจลองซ้ำแบบจำกัดหนึ่งครั้งด้วย cached per-device token
  • หากการลองซ้ำนั้นล้มเหลว client ควรหยุดวงวนการเชื่อมต่อใหม่อัตโนมัติและแสดงคำแนะนำการดำเนินการสำหรับ operator
• AUTH_SCOPE_MISMATCH หมายความว่า device token ถูกจดจำได้แต่ไม่ครอบคลุม role/scopes ที่ขอ client ไม่ควรนำเสนอเรื่องนี้ว่าเป็น token ที่ไม่ถูกต้อง; ให้แจ้ง operator ให้จับคู่ใหม่หรืออนุมัติสัญญา scope ที่แคบกว่า/กว้างกว่า

​

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

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

​

diagnostics การย้าย device auth

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

​

TLS + การ pin

• รองรับ TLS สำหรับการเชื่อมต่อ WS
• client อาจ pin fingerprint ของใบรับรอง Gateway ได้ตามต้องการ (ดู config gateway.tls รวมถึง gateway.remote.tlsFingerprint หรือ CLI --tls-fingerprint)

​

ขอบเขต

​

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

• protocol ของ Bridge
• runbook ของ Gateway