Clawnet 重構指南：統一通訊協定與驗證機制

如果你曾經開發過分散式系統，一定遇過這種煩惱：控制介面用一套通訊協定，節點傳輸又用另一套。當你想在遠端執行指令，結果確認視窗跳在遠端主機的螢幕上，而你人根本不在現場。這種架構不只難維護，還會讓身分驗證變得像拼布一樣混亂，難以確保每個環節都足夠安全。

Clawnet 的重構目標就是終結這種混亂。我們要將分散的通訊協定歸一，讓開發者能更專注於功能開發，而不是在多個通訊堆疊之間掙扎。

需要準備的東西

在開始之前，請確保你已經熟悉以下組件（源自現有架構）：

• Gateway: 負責控制平面的核心伺服器
• Node: 執行具體能力的節點（如 macOS app, iOS/Android, headless node）
• Operator: 控制端用戶（如 CLI, Web UI, macOS app UI）
• Discovery: 用於定位服務的發現機制

快速開始

Clawnet 的核心是將通訊簡化為單一的 WebSocket (WS) 協定。你只需要定義好 Role（角色） 與 Scope（權限範圍），就能快速接入系統。

1. 建立連線

客戶端連線時，在 connect 參數中帶入身分資訊：

// 範例：Node 角色連線
{
  "deviceId": "你的設備唯一識別碼",
  "displayName": "My Mac Node",
  "role": "node",
  "caps": ["system.run", "screen.record"]
}

2. 統一配對流程

1. 客戶端發起未驗證連線。
2. Gateway 產生 pairing request。
3. Operator 收到提示並核准。
4. Gateway 核發綁定設備公鑰的憑證，客戶端儲存 token 並重新連線。

核心設計：Clawnet 的新狀態

一個協定，兩種角色

我們不再區分 Gateway WS 與 Bridge 協定，改用單一 WS 協定並區分角色：

• Node (能力提供者): 註冊 caps 與 commands，接收 invoke 指令（如 system.run），但無法存取控制平面 API。
• Operator (控制平面): 擁有完整的 API 存取權（受 Scope 限制），接收所有審核請求，但不直接執行系統操作。

集中化審核機制

過去審核視窗會跳在 Node 執行端，現在改由 Gateway 代管，並推送到 Operator 客戶端：

1. Gateway 收到 system.run 意圖。
2. Gateway 建立 approval.requested 紀錄。
3. Operator UI 顯示彈窗供你點選核准。
4. 核准後，Gateway 才將指令發送給 Node 執行。

TLS 全面覆蓋

為了擺脫對 SSH 或 Tailscale 的依賴，我們將原本 Bridge 擁有的 TLS 指紋釘選（pinning）機制引入 WS。這能確保遠端行動裝置連線在預設狀態下就是安全的。

Migration Strategy

重構將分階段進行，確保系統穩定：

• Phase 1 & 2: 在 WS 中加入角色與權限判斷，同時保持 Bridge 協定運行以相容舊版本。
• Phase 3: 實作集中化審核，更新 UI 以支援遠端回應核准請求。
• Phase 4 & 5: 統一 TLS 配置，並將所有行動端與節點遷移至 WS，最後移除舊的 Bridge 代碼。
• Phase 6: 強制執行基於金鑰的身分驗證，提供完整的撤銷與輪轉 UI。

疑難排解

設備重複顯示

問題：在 UI 中看到同一個設備出現兩次（例如同時顯示為 UI 與 Node）。 解法：確保兩次連線使用相同的 deviceId（建議使用金鑰對的 fingerprint）。Gateway 會根據 deviceId 自動合併顯示，並標註多個角色標籤。

遠端 Node 無法跳出審核視窗

問題：在 CLI 執行指令後，遠端 Node 沒有反應。 解法：檢查你的 Operator 客戶端是否擁有 operator.approvals 權限。在新生態中，審核是發送到「你」面前的螢幕，而非 Node 所在的機器。

TLS 連線失敗

問題：遠端連線被拒絕。 解法：確認 Discovery 廣播的 TLS 指紋與伺服器實際憑證一致。Clawnet 使用 src/infra/bridge/server/tls.ts 相同的運行時邏輯。

---

想要更深入了解如何配置你的開發環境？請諮詢 AI Setup Assistant。

下一步

• Gateway Protocol 詳解
• Node 能力註冊指南
• 安全性與權限範圍配置