สถาปัตยกรรม Gateway

ภาพรวม

• Gateway ที่ทำงานต่อเนื่องระยะยาวเพียงตัวเดียวเป็นเจ้าของพื้นผิวการรับส่งข้อความทั้งหมด (WhatsApp ผ่าน Baileys, Telegram ผ่าน grammY, Slack, Discord, Signal, iMessage, WebChat)

• ไคลเอนต์ระนาบควบคุม (แอป macOS, CLI, UI เว็บ, ระบบอัตโนมัติ) เชื่อมต่อกับ Gateway ผ่าน WebSocket บนโฮสต์ที่ผูกไว้ตามการกำหนดค่า (ค่าเริ่มต้น 127.0.0.1:18789)

• Node (macOS/iOS/Android/แบบไม่มีส่วนติดต่อ) เชื่อมต่อผ่าน WebSocket เช่นกัน แต่ ประกาศ role: node พร้อมความสามารถ/คำสั่งอย่างชัดเจน

• มี Gateway หนึ่งตัวต่อหนึ่งโฮสต์ และเป็นจุดเดียวที่เปิดเซสชัน WhatsApp

• โฮสต์แคนวาส ให้บริการโดยเซิร์ฟเวอร์ HTTP ของ Gateway ภายใต้:

  • /__openclaw__/canvas/ (HTML/CSS/JS ที่เอเจนต์แก้ไขได้)
  • /__openclaw__/a2ui/ (โฮสต์ A2UI)

  โดยใช้พอร์ตเดียวกับ Gateway (ค่าเริ่มต้น 18789)

องค์ประกอบและโฟลว์

Gateway (ดีมอน)

• ดูแลการเชื่อมต่อกับผู้ให้บริการ
• เปิดเผย API แบบ WS ที่มีชนิดข้อมูลกำกับ (คำขอ การตอบกลับ เหตุการณ์ที่เซิร์ฟเวอร์พุช)
• ตรวจสอบความถูกต้องของเฟรมขาเข้าตาม JSON Schema
• ปล่อยเหตุการณ์ เช่น agent, chat, presence, health, heartbeat, cron

ไคลเอนต์ (แอป Mac / CLI / ผู้ดูแลผ่านเว็บ)

• ใช้การเชื่อมต่อ WS หนึ่งรายการต่อไคลเอนต์
• ส่งคำขอ (health, status, send, agent, system-presence)
• สมัครรับเหตุการณ์ (tick, agent, presence, shutdown)

Node (macOS / iOS / Android / แบบไม่มีส่วนติดต่อ)

• เชื่อมต่อกับ เซิร์ฟเวอร์ WS เดียวกัน โดยใช้ role: node
• ระบุข้อมูลประจำตัวอุปกรณ์ใน connect การจับคู่จะ อิงตามอุปกรณ์ (บทบาท node) และ การอนุมัติจะอยู่ในที่เก็บข้อมูลการจับคู่อุปกรณ์
• เปิดเผยคำสั่ง เช่น canvas.*, camera.*, screen.record, location.get

รายละเอียดโปรโตคอล: โปรโตคอล Gateway

WebChat

• UI แบบสแตติกที่ใช้ API แบบ WS ของ Gateway สำหรับประวัติการสนทนาและการส่งข้อความ
• ในการตั้งค่าระยะไกล จะเชื่อมต่อผ่านทันเนล SSH/Tailscale เดียวกับ ไคลเอนต์อื่น

วงจรการเชื่อมต่อ (ไคลเอนต์เดียว)

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: or res error + close
    Note left of Client: payload=hello-ok<br>snapshot: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(streaming)
    Gateway-->>Client: res:agent<br>final {runId, status, summary}

โปรโตคอลผ่านสายสื่อสาร (สรุป)

• การขนส่ง: WebSocket โดยใช้เฟรมข้อความที่มีเพย์โหลด JSON
• เฟรมแรก ต้อง เป็น connect
• หลังการจับมือ:
  • คำขอ: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • เหตุการณ์: {type:"event", event, payload, seq?, stateVersion?}
• hello-ok.features.methods / events เป็นเมทาดาทาสำหรับการค้นพบ ไม่ใช่ รายการที่สร้างขึ้นจากเส้นทางตัวช่วยทั้งหมดที่เรียกใช้ได้
• การยืนยันตัวตนด้วยข้อมูลลับร่วมใช้ connect.params.auth.token หรือ connect.params.auth.password ขึ้นอยู่กับโหมดการยืนยันตัวตนของ Gateway ที่กำหนดค่าไว้
• โหมดที่มีข้อมูลประจำตัว เช่น Tailscale Serve (gateway.auth.allowTailscale: true) หรือ gateway.auth.mode: "trusted-proxy" ที่ไม่ใช่ลูปแบ็ก จะดำเนินการยืนยันตัวตนจากส่วนหัวคำขอ แทน connect.params.auth.*
• gateway.auth.mode: "none" สำหรับทางเข้าภายในส่วนตัวจะปิดใช้การยืนยันตัวตน ด้วยข้อมูลลับร่วมทั้งหมด อย่าใช้โหมดนี้กับทางเข้าสาธารณะ/ที่ไม่น่าเชื่อถือ
• เมธอดที่ก่อให้เกิดผลข้างเคียง (send, agent) ต้องมีคีย์ idempotency เพื่อ ให้ลองใหม่ได้อย่างปลอดภัย เซิร์ฟเวอร์จะเก็บแคชขจัดรายการซ้ำอายุสั้น
• Node ต้องระบุ role: "node" พร้อมความสามารถ/คำสั่ง/สิทธิ์ใน connect

การจับคู่และความเชื่อถือภายในเครื่อง

• ไคลเอนต์ WS ทั้งหมด (ผู้ควบคุม + Node) ระบุ ข้อมูลประจำตัวอุปกรณ์ ใน connect
• รหัสอุปกรณ์ใหม่ต้องได้รับการอนุมัติการจับคู่ จากนั้น Gateway จะออก โทเค็นอุปกรณ์ สำหรับการเชื่อมต่อครั้งถัดไป
• การเชื่อมต่อ local loopback โดยตรงสามารถได้รับการอนุมัติโดยอัตโนมัติ เพื่อให้ประสบการณ์ใช้งาน บนโฮสต์เดียวกันราบรื่น
• OpenClaw ยังมีเส้นทางการเชื่อมต่อกลับเข้าตนเองแบบจำกัดภายในแบ็กเอนด์/คอนเทนเนอร์ สำหรับโฟลว์ตัวช่วยที่เชื่อถือได้ซึ่งใช้ข้อมูลลับร่วม
• การเชื่อมต่อผ่านเครือข่ายส่วนตัว Tailscale และ LAN รวมถึงการผูกเครือข่ายส่วนตัว Tailscale บนโฮสต์เดียวกัน ยังคงต้อง ได้รับการอนุมัติการจับคู่อย่างชัดเจน
• การเชื่อมต่อทั้งหมดต้องลงนาม nonce ของ connect.challenge เพย์โหลดลายเซ็น v3 จะผูก platform และ deviceFamily ด้วย โดย Gateway จะตรึงเมทาดาทาที่จับคู่ไว้เมื่อ เชื่อมต่อใหม่ และกำหนดให้จับคู่ซ่อมแซมเมื่อเมทาดาทาเปลี่ยนแปลง
• การเชื่อมต่อที่ ไม่ได้มาจากภายในเครื่อง ยังคงต้องได้รับการอนุมัติอย่างชัดเจน
• การยืนยันตัวตนของ Gateway (gateway.auth.*) ยังคงมีผลกับการเชื่อมต่อ ทั้งหมด ไม่ว่าจะเป็นภายในเครื่องหรือ ระยะไกล

รายละเอียด: โปรโตคอล Gateway, การจับคู่, ความปลอดภัย

การกำหนดชนิดข้อมูลโปรโตคอลและการสร้างโค้ด

• สคีมา TypeBox กำหนดโปรโตคอล
• JSON Schema สร้างขึ้นจากสคีมาเหล่านั้น
• โมเดล Swift สร้างขึ้นจาก JSON Schema

การเข้าถึงระยะไกล

• แนะนำ: Tailscale หรือ VPN

• ทางเลือก: ทันเนล SSH

  ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

• การจับมือและโทเค็นยืนยันตัวตนเดียวกันมีผลเมื่อเชื่อมต่อผ่านทันเนล

• สามารถเปิดใช้ TLS และการตรึงใบรับรองแบบเลือกได้สำหรับ WS ในการตั้งค่าระยะไกล

ภาพรวมการดำเนินงาน

• เริ่มต้น: openclaw gateway (ทำงานเบื้องหน้า บันทึกล็อกไปยัง stdout)
• สถานะความพร้อม: health ผ่าน WS (รวมอยู่ใน hello-ok ด้วย)
• การควบคุมดูแล: launchd/systemd สำหรับการเริ่มใหม่อัตโนมัติ

ค่าคงที่ของระบบ

• มี Gateway เพียงหนึ่งตัวที่ควบคุมเซสชัน Baileys หนึ่งเซสชันต่อโฮสต์
• ต้องทำการจับมือเสมอ เฟรมแรกที่ไม่ใช่ JSON หรือไม่ใช่ connect จะทำให้ปิดการเชื่อมต่อทันที
• เหตุการณ์จะไม่ถูกเล่นซ้ำ ไคลเอนต์ต้องรีเฟรชเมื่อมีช่วงข้อมูลขาดหาย

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

• ลูปเอเจนต์ — วงจรการทำงานของเอเจนต์โดยละเอียด
• โปรโตคอล Gateway — สัญญาโปรโตคอล WebSocket
• คิว — คิวคำสั่งและการทำงานพร้อมกัน
• ความปลอดภัย — โมเดลความเชื่อถือและการเพิ่มความแข็งแกร่ง