Clawnet 重構（協定 + 驗證統一）

嗨

嗨 Peter — 方向很棒；這能讓 UX 更簡潔、安全性更強。

用途

單一嚴謹的文件，涵蓋：

  • 現狀：協定、流程、信任邊界。
  • 痛點：核准、多跳路由、UI 重複。
  • 提議的新狀態：統一協定、有範圍的角色、統一的驗證/配對、TLS pinning。
  • 身分模型：穩定 ID + 可愛的 slug。
  • 遷移計畫、風險、待決問題。

目標（來自討論）

  • 所有用戶端使用一個協定（mac 應用、CLI、iOS、Android、headless 節點）。
  • 每個網路參與者都經過驗證 + 配對。
  • 角色清晰：節點 vs 操作者。
  • 核准集中路由至使用者所在位置。
  • 所有遠端流量使用 TLS 加密 + 選用 pinning。
  • 最小程式碼重複。
  • 同一台機器只顯示一次（不出現 UI/節點重複項目）。

非目標（明確）

  • 移除能力分離（仍需最小權限）。
  • 不經範圍檢查就公開完整 gateway 控制平面。
  • 讓驗證依賴人類標籤（slug 維持非安全性質）。

現狀（as-is）

兩個協定

1) Gateway WebSocket（控制平面）

  • 完整 API 介面：設定、頻道、模型、session、代理執行、日誌、節點等。
  • 預設綁定：迴路。遠端存取透過 SSH/Tailscale。
  • 驗證：token/密碼透過 connect。
  • 無 TLS pinning（依賴迴路/通道）。
  • 程式碼：
    • src/gateway/server/ws-connection/message-handler.ts
    • src/gateway/client.ts
    • docs/gateway/protocol.md

2) Bridge（節點傳輸）

  • 窄白名單介面、節點身分 + 配對。
  • TCP 上的 JSONL；選用 TLS + 憑證指紋 pinning。
  • TLS 在探索 TXT 中公告指紋。
  • 程式碼：
    • src/infra/bridge/server/connection.ts
    • src/gateway/server-bridge.ts
    • src/node-host/bridge-client.ts
    • docs/gateway/bridge-protocol.md

目前的控制平面用戶端

  • CLI -> Gateway WS 透過 callGateway（src/gateway/call.ts）。
  • macOS 應用 UI -> Gateway WS（GatewayConnection）。
  • Web Control UI -> Gateway WS。
  • ACP -> Gateway WS。
  • 瀏覽器控制使用自己的 HTTP 控制伺服器。

目前的節點

  • macOS 應用的節點模式連接至 Gateway bridge（MacNodeBridgeSession）。
  • iOS/Android 應用連接至 Gateway bridge。
  • 配對 + 逐節點 token 儲存在 gateway。

目前的核准流程（exec）

  • 代理透過 Gateway 使用 system.run。
  • Gateway 透過 bridge 呼叫節點。
  • 節點執行時決定核准。
  • UI 提示顯示在 mac 應用（當節點 == mac 應用時）。
  • 節點回傳 invoke-res 至 Gateway。
  • 多跳，UI 綁定在節點主機上。

目前的線上狀態 + 身分

  • Gateway 線上狀態項目來自 WS 用戶端。
  • 節點線上狀態項目來自 bridge。
  • mac 應用可能為同一台機器顯示兩個項目（UI + 節點）。
  • 節點身分儲存在配對儲存區；UI 身分分開。

問題 / 痛點

  • 兩套協定堆疊需維護（WS + Bridge）。
  • 遠端節點的核准：提示出現在節點主機上，而非使用者所在處。
  • TLS pinning 僅存在於 bridge；WS 依賴 SSH/Tailscale。
  • 身分重複：同一台機器顯示為多個實例。
  • 角色模糊：UI + 節點 + CLI 的能力未清楚分離。

提議的新狀態（Clawnet）

一個協定，兩種角色

單一 WS 協定搭配角色 + 範圍。

  • 角色：節點（能力主機）
  • 角色：操作者（控制平面）
  • 操作者的選用範圍：
    • operator.read（狀態 + 檢視）
    • operator.write（代理執行、傳送）
    • operator.admin（設定、頻道、模型）

角色行為

節點

  • 可註冊能力（caps、commands、權限）。
  • 可接收 invoke 指令（system.run、camera.*、canvas.*、screen.record 等）。
  • 可傳送事件：voice.transcript、agent.request、chat.subscribe。
  • 不可呼叫設定/模型/頻道/session/代理控制平面 API。

操作者

  • 完整控制平面 API，依範圍閘門。
  • 接收所有核准。
  • 不直接執行 OS 操作；路由至節點。

關鍵規則

角色為逐連線的，非逐裝置。一個裝置可分別開啟兩種角色。

統一的驗證 + 配對

用戶端身分

每個用戶端提供：

  • deviceId（穩定，衍生自裝置金鑰）。
  • displayName（人類名稱）。
  • role + scope + caps + commands。

配對流程（統一）

  • 用戶端在未驗證的狀態下連接。
  • Gateway 為該 deviceId 建立配對請求。
  • 操作者收到提示；核准/拒絕。
  • Gateway 核發綁定至以下項目的憑證：
    • 裝置公鑰
    • 角色
    • 範圍
    • 能力/指令
  • 用戶端持久化 token，重新連接並完成驗證。

裝置綁定的驗證（避免 bearer token 重播）

偏好：裝置金鑰對。

  • 裝置一次性生成金鑰對。
  • deviceId = fingerprint(publicKey)。
  • Gateway 傳送 nonce；裝置簽名；gateway 驗證。
  • Token 核發給公鑰（持有證明），而非字串。

替代方案：

  • mTLS（用戶端憑證）：最強，但營運複雜度更高。
  • 短期 bearer token 僅作為臨時階段（早期輪換 + 撤銷）。

靜默核准（SSH 啟發式）

精確定義以避免弱環節。偏好其一：

  • 僅限本地：用戶端透過迴路/Unix socket 連接時自動配對。
  • 透過 SSH 挑戰：gateway 發出 nonce；用戶端透過取得 nonce 證明 SSH。
  • 實體在場視窗：在 gateway 主機 UI 進行本地核准後，允許短視窗（如 10 分鐘）內自動配對。

一律記錄 + 記載自動核准。

TLS 全面覆蓋（開發 + 正式）

重用既有 bridge TLS

使用現有的 TLS 執行時 + 指紋 pinning：

  • src/infra/bridge/server/tls.ts
  • src/node-host/bridge-client.ts 中的指紋驗證邏輯

套用至 WS

  • WS 伺服器支援使用相同 cert/key + 指紋的 TLS。
  • WS 用戶端可 pin 指紋（選用）。
  • 探索為所有端點公告 TLS + 指紋。
    • 探索僅為定位器提示；永非信任錨點。

為何

  • 降低對 SSH/Tailscale 的機密性依賴。
  • 讓遠端行動連線預設安全。

核准重新設計（集中化）

現狀

核准發生在節點主機上（mac 應用節點執行時）。提示出現在節點執行的位置。

提議

核准為 gateway 託管，UI 投遞至操作者用戶端。

新流程

  1. Gateway 接收 system.run 意圖（代理）。
  2. Gateway 建立核准記錄：approval.requested。
  3. 操作者 UI 顯示提示。
  4. 核准決定傳送至 gateway：approval.resolve。
  5. Gateway 若核准則呼叫節點指令。
  6. 節點執行，回傳 invoke-res。

核准語義（強化）

  • 廣播至所有操作者；僅活躍 UI 顯示模態（其他收到 toast）。
  • 首先解決的為準；gateway 拒絕後續的解決為已結案。
  • 預設逾時：N 秒後拒絕（如 60s），記錄原因。
  • 解決需要 operator.approvals 範圍。

效益

  • 提示出現在使用者所在處（mac/手機）。
  • 遠端節點的核准一致。
  • 節點執行時保持 headless；無 UI 依賴。

角色清晰範例

iPhone 應用

  • 節點角色用於：麥克風、相機、語音聊天、定位、按鍵通話。
  • 選用 operator.read 用於狀態和聊天檢視。
  • 選用 operator.write/admin 僅在明確啟用時。

macOS 應用

  • 預設為操作者角色（控制 UI）。
  • 啟用「Mac 節點」時為節點角色（system.run、螢幕、相機）。
  • 兩個連線使用相同 deviceId -> UI 中合併為單一項目。

CLI

  • 一律為操作者角色。
  • 範圍依子指令衍生：
    • status、logs -> read
    • agent、message -> write
    • config、channels -> admin
    • 核准 + 配對 -> operator.approvals / operator.pairing

身分 + slug

穩定 ID

驗證所需；永不改變。 偏好：

  • 金鑰對指紋（公鑰雜湊）。

可愛的 slug（龍蝦主題）

僅為人類標籤。

  • 範例：scarlet-claw、saltwave、mantis-pinch。
  • 儲存在 gateway 登錄檔，可編輯。
  • 碰撞處理：-2、-3。

UI 群組

跨角色的相同 deviceId -> 單一「實例」列：

  • 標記：operator、node。
  • 顯示能力 + 最後上線。

遷移策略

第 0 階段：文件 + 對齊

  • 發布本文件。
  • 盤點所有協定呼叫 + 核准流程。

第 1 階段：為 WS 新增角色/範圍

  • 擴展 connect 參數加入 role、scope、deviceId。
  • 為節點角色新增白名單閘門。

第 2 階段：Bridge 相容

  • 保持 bridge 運行。
  • 平行新增 WS 節點支援。
  • 以設定旗標閘門功能。

第 3 階段：集中核准

  • 在 WS 中新增核准請求 + 解決事件。
  • 更新 mac 應用 UI 以提示 + 回應。
  • 節點執行時停止提示 UI。

第 4 階段：TLS 統一

  • 使用 bridge TLS 執行時為 WS 新增 TLS 設定。
  • 為用戶端新增 pinning。

第 5 階段：淘汰 bridge

  • 將 iOS/Android/mac 節點遷移至 WS。
  • 保留 bridge 作為回退；穩定後移除。

第 6 階段：裝置綁定驗證

  • 所有非本地連線需要基於金鑰的身分。
  • 新增撤銷 + 輪換 UI。

安全備註

  • 角色/白名單在 gateway 邊界強制。
  • 無操作者範圍的用戶端不取得「完整」API。
  • _所有_連線都需要配對。
  • TLS + pinning 降低行動裝置的 MITM 風險。
  • SSH 靜默核准是便利功能；仍被記錄 + 可撤銷。
  • 探索永非信任錨點。
  • 能力聲明依平台/型別對照伺服器白名單驗證。

串流 + 大型 payload（節點媒體）

WS 控制平面適合小型訊息，但節點也處理：

  • 相機片段
  • 螢幕錄製
  • 音訊串流

選項：

  1. WS 二進位 frame + 分塊 + 背壓規則。
  2. 獨立的串流端點（仍 TLS + 驗證）。
  3. 為媒體密集的指令保留 bridge 更久，最後遷移。

實作前選定一個方案以避免偏差。

能力 + 指令策略

  • 節點回報的 caps/commands 視為聲明。
  • Gateway 強制逐平台白名單。
  • 任何新指令需要操作者核准或明確的白名單變更。
  • 附帶時間戳稽核變更。

稽核 + 速率限制

  • 記錄：配對請求、核准/拒絕、token 核發/輪換/撤銷。
  • 速率限制配對濫發和核准提示。

協定衛生

  • 明確的協定版本 + 錯誤碼。
  • 重連規則 + 心跳策略。
  • 線上狀態 TTL 和最後上線語義。

待決問題

  1. 同一裝置運行兩種角色：token 模型

    • 建議每角色獨立 token（節點 vs 操作者）。
    • 相同 deviceId；不同範圍；更清晰的撤銷。

  2. 操作者範圍粒度

    • read/write/admin + 核准 + 配對（最小可行）。
    • 之後考慮逐功能範圍。

  3. Token 輪換 + 撤銷 UX

    • 角色變更時自動輪換。
    • 依 deviceId + 角色撤銷的 UI。

  4. 探索

    • 擴展現有 Bonjour TXT 以包含 WS TLS 指紋 + 角色提示。
    • 僅視為定位器提示。

  5. 跨網路核准

    • 廣播至所有操作者用戶端；活躍 UI 顯示模態。
    • 首先回應的為準；gateway 強制原子性。

摘要（TL;DR）

  • 現狀：WS 控制平面 + Bridge 節點傳輸。
  • 痛點：核准 + 重複 + 兩套堆疊。
  • 提議：一個 WS 協定搭配明確角色 + 範圍、統一配對 + TLS pinning、gateway 託管的核准、穩定裝置 ID + 可愛 slug。
  • 成果：更簡潔的 UX、更強的安全性、更少重複、更好的行動路由。
下一頁
Overview
arrow_forward