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

อัปเดตล่าสุด: 2026-01-22

ภาพรวม¶

• Gateway เดียวที่ทำงานระยะยาวเป็นเจ้าของพื้นผิวการส่งข้อความทั้งหมด (WhatsApp ผ่าน Baileys, Telegram ผ่าน grammY, Slack, Discord, Signal, iMessage, WebChat)
• ไคลเอนต์ฝั่งคอนโทรลเพลน (แอปmacOS, CLI, เว็บUI, ระบบอัตโนมัติ) เชื่อมต่อกับ Gateway ผ่าน WebSocket บนโฮสต์ที่ผูกไว้ตามการตั้งค่า (ค่าเริ่มต้น 127.0.0.1:18789)
• โหนด (macOS/iOS/Android/headless) ก็เชื่อมต่อผ่าน WebSocket เช่นกัน แต่จะประกาศ role: node พร้อมความสามารถ/คำสั่งที่ระบุชัดเจน
• หนึ่งGatewayต่อหนึ่งโฮสต์; เป็นที่เดียวที่เปิดเซสชัน WhatsApp
• โฮสต์แคนวาส (ค่าเริ่มต้น 18793) ให้บริการ HTML ที่เอเจนต์แก้ไขได้และ A2UI

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

Gateway (เดมอน)¶

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

ไคลเอนต์ (แอปmac / CLI / เว็บแอดมิน)¶

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

โหนด (macOS / iOS / Android / headless)¶

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

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

• Gateway protocol

WebChat¶

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

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

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#ffffff',
    'primaryTextColor': '#000000',
    'primaryBorderColor': '#000000',
    'lineColor': '#000000',
    'secondaryColor': '#f9f9fb',
    'tertiaryColor': '#ffffff',
    'clusterBkg': '#f9f9fb',
    'clusterBorder': '#000000',
    'nodeBorder': '#000000',
    'mainBkg': '#ffffff',
    'edgeLabelBackground': '#ffffff'
  }
}}%%
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?}
• หากตั้งค่า OPENCLAW_GATEWAY_TOKEN (หรือ --token) ค่า connect.params.auth.token ต้องตรงกัน มิฉะนั้นซ็อกเก็ตจะถูกปิด
• คีย์ไอดีมโพเทนซีจำเป็นสำหรับเมธอดที่มีผลข้างเคียง (send, agent) เพื่อ ให้ลองซ้ำได้อย่างปลอดภัย; เซิร์ฟเวอร์เก็บแคชดีดิวป์ชั่วคราวอายุสั้น
• โหนดต้องรวม role: "node" พร้อมความสามารถ/คำสั่ง/สิทธิ์ใน connect

44. การจับคู่ + ความเชื่อถือในเครื่อง¶

• ไคลเอนต์ WS ทั้งหมด (ผู้ปฏิบัติการ + โหนด) ต้องรวม ตัวตนอุปกรณ์ ใน connect
• ID อุปกรณ์ใหม่ต้องได้รับการอนุมัติการจับคู่; Gateway จะออก โทเคนอุปกรณ์ สำหรับการเชื่อมต่อครั้งถัดไป
• การเชื่อมต่อแบบ ภายในเครื่อง (loopback หรือที่อยู่ tailnet ของโฮสต์Gatewayเอง) สามารถ อนุมัติอัตโนมัติเพื่อให้ประสบการณ์ใช้งานบนโฮสต์เดียวลื่นไหล
• การเชื่อมต่อแบบ ไม่ใช่ภายในเครื่อง ต้องเซ็น nonce connect.challenge และต้องการ การอนุมัติอย่างชัดเจน
• การยืนยันตัวตนของGateway (gateway.auth.*) ยังมีผลกับการเชื่อมต่อ ทั้งหมด ทั้งภายในและระยะไกล

รายละเอียด: Gateway protocol, Pairing, Security

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

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

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

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

• ทางเลือก: อุโมงค์SSH

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

• ใช้แฮนด์เชคและโทเคนยืนยันตัวตนเดียวกันผ่านอุโมงค์

• สามารถเปิดใช้ TLS + การปักหมุดเสริมสำหรับ WS ในการตั้งค่าแบบรีโมต

ภาพรวมการปฏิบัติการ¶

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

45. อินวาเรียนต์¶

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