> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 雲端工作節點方案

## 狀態

提案，第 3 次修訂。尚未實作。方向已於 2026-07 議定；第 2 次修訂納入了對抗性審查的發現（專用工作節點協定、放置位置／環境狀態機、感知 git 的入站同步、單向 v1 交接、受控輸出的安全性措辭）。第 3 次修訂確定同步所有權模型（工作節點撰寫提交，閘道採納並發布）、新增無 git 的純同步模式、修正工作節點在機器內具完整權限的執行方式、將網際網路政策移至佈建時設定，並將代理程式派送恢復至里程碑 3。

## 問題

OpenClaw 代理程式工作階段會在單一機器的閘道程序內執行其迴圈、工具與推論。運算能力受限於該機器，長時間任務會占用它，而平行工作則會彼此競爭資源。託管產品（Cursor 雲端代理程式、網頁版 Claude Code、Codex cloud）透過每個任務各自使用的臨時雲端沙箱解決此問題，但它們需要供應商基礎架構，也必須信任供應商。

已經擁有閒置機器（或能以低成本租用）的操作人員，無法指定：在那台機器上執行此工作階段、像任何其他工作階段一樣顯示在我的側邊欄中，然後在完成後丟棄該機器。

## 目標

* 在臨時遠端機器（「雲端工作節點」）上執行完整的代理程式工作階段（迴圈 + 工具），同時讓該工作階段在 Control UI 中的顯示與串流行為完全如同本機工作階段。
* 工作節點上不存放常駐認證資訊（無供應商驗證、無程式碼代管平台權杖），且不可直接對外連線；該機器只需具有可連線的 sshd。
* 佈建、同步、執行、收集、銷毀——全程自動化且可插拔供應商（第一個供應商：Crabbox 形式的租用命令列介面）。
* 在回合邊界將正在執行的工作從閘道派送至工作節點，不遺失逐字稿、工作階段身分，或（當請求位元組維持等價時）供應商快取親和性；並安全地拉回結果。
* 人類（UI）與代理程式（工具）都能將工作派送至雲端工作節點。
* 支援持續數日的工作階段；存續時間由政策決定，而非硬編碼上限。

## 非目標（v1）

* 工作節點上不使用外部程式設計工具框架（Claude Code、Codex CLI）。工作節點工作階段只執行 OpenClaw 的內嵌執行器。工具框架支援是 v2 的選用功能，因為工具框架會使用自己的認證資訊自行執行推論。
* 不進行 N 取優／平行嘗試扇出。
* 不依賴 VPN／tailnet。傳輸僅使用 SSH。
* 不新增沙箱執行環境。工作節點機器即為隔離邊界；之後可再疊加機器內的作業系統沙箱。
* v1 不支援對稱式即時遷移：派送方向為本機 → 工作節點；工作節點 → 本機則要求工作階段已停止且工作區協調已完成。日後的即時雙向交接將建構於相同的屏障機制之上。
* 閘道上不使用 JSON 側邊狀態；環境、放置位置、游標與授權狀態皆存放於 SQLite。

## 先例（我們仿效什麼、反轉什麼）

* Cursor 雲端代理程式：代理程式迴圈在其雲端執行；VM 是工具執行目標；僅附加的對話儲存區串流至所有用戶端；安裝後建立快照以供暖啟動；自架工作節點是僅對外連線的工作程序。我們仿效「對話的唯一真實來源保留在協調器上」及其串流模型；但反轉迴圈的放置位置（請參閱下方決策）。
* Codex cloud：兩階段執行環境——可連網的設定階段，接著是移除機密資訊的離線代理程式階段。我們仿效此階段切分作為輸出連線立場，並將快取概念用於 v2 暖映像。
* 網頁版 Claude Code：每個工作階段各有一台 VM；隔離認證資訊的 git Proxy（真實權杖絕不進入沙箱，推送僅限工作階段分支）；設定後建立檔案系統快照；瞬移交接 = 已推送分支 + 已重播歷程。我們仿效認證資訊隔離及交接的框架，但出站同步由閘道透過 rsync 執行，因此未清理的工作樹仍可運作，且機器附近完全不存在程式碼代管平台權杖。
* Copilot 程式設計代理程式：預設拒絕輸出連線，僅允許套件登錄檔白名單。我們的穩定狀態預設更嚴格（完全不可直接輸出連線），因為推論與網頁搜尋會經由 SSH 通道送達——但請參閱「安全性」，了解為何這是「受控輸出」，而非「零輸出」。

## 架構決策：迴圈位於工作節點，推論經由閘道

曾考慮三種放置方式：

1. 迴圈保留在閘道，工作節點執行工具（Cursor 模型）。這是最安全的故障域（逐字稿、推論、核准與重新啟動復原皆保留在本機），也是審查者偏好的第一個里程碑。未採用作為產品架構：OpenClaw 的非執行類工具是程序內檔案系統操作，因此每次檔案讀取／編輯／grep 都會變成網路往返，或需要將大範圍工具介面重構為粗粒度工作區 RPC；執行環境行為頻繁且受延遲限制。我們在已建置的部分沿用其精神（將執行工作卸載至節點），但不建置工具遠端化層。
2. 迴圈與推論皆位於工作節點。故障域最簡單，但模型認證資訊（包括 OAuth 設定檔）必須傳送至用完即丟的機器，閘道也會失去政策／路由／稽核控制，而遷移會切換呼叫供應商的身分，使供應商快取失效。
3. 迴圈 + 工具位於工作節點，模型呼叫則透過閘道 Proxy。採用此方案。每個模型回合只需一次往返，而不是每次工具呼叫都需往返；工具在程式碼旁執行；閘道仍是驗證設定檔、供應商路由與政策的唯一擁有者；工作節點不持有任何機密資訊。

方案 3 的代價是每個模型回合期間都同步依賴閘道，因此其耐久性規則是決策的一部分，而非事後補強：

* 在回合進行中失去閘道會使作用中的供應商呼叫失敗。該回合會標記為失敗，並在重新連線後作為新回合重試；不會透明重播進行中的供應商串流（有重複計費／重複工具呼叫的風險）。
* 工作節點↔閘道之間的每項操作都帶有持久身分（請參閱「工作節點協定」），使重新連線時能恢復操作或擷取已快取的終止結果，而不會懸置。
* 閘道是受容量管理的元件：並行工作節點限制、流量控制與負載卸除皆屬於 v1 範圍（請參閱「容量」）。

由於閘道同時儲存逐字稿並發起所有供應商流量，工作階段與位置無關：在閘道與工作節點之間移動迴圈，不會改變供應商端的任何內容，也不會改變 UI 資料路徑。正因如此，派送與拉回的成本很低。

## 元件

### 1. 環境狀態機 + 供應商合約

閘道協定中的 `environments.*` 目前只是狀態投影。持久核心是由 SQLite 擁有的環境記錄與狀態機，並先於 RPC 結構進行設計：

`requested → provisioning → bootstrapping → ready → (attached|idle) → draining → destroying → destroyed | failed | orphaned`

* 佈建具備當機安全性：在呼叫供應商之前，會先以確定性的操作 ID 保存意圖資料列，因此閘道重新啟動時可接管進行中的租用，而不會重複佈建或遺留無主的付費機器。
* 重新啟動協調與孤兒清除程式（供應商 `inspect` 與本機記錄的比對）是 v1 的必要條件，而非強化措施。

供應商合約（由外掛實作；核心中不含供應商名稱或政策）：

```ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
type WorkerProvider = {
  id: string;
  provision(profile: WorkerProfile, opId: string): Promise<WorkerLease>; // → ssh 主機／連接埠／使用者／金鑰資料
  inspect(lease: { leaseId: string; profile: WorkerProfile }): Promise<LeaseStatus>; // 接管／健康狀態／孤兒清除
  renew?(leaseId: string): Promise<void>; // 長期工作階段與供應商 TTL 的協調
  destroy(lease: { leaseId: string; profile: WorkerProfile }): Promise<void>; // 冪等，僅在確認已拆除後回傳
};
```

RPC：`environments.create`、`environments.destroy`、擴充的 `environments.list/status`（供應商、租用 ID、狀態、存續時間、閒置時間、附加的工作階段）。首批供應商：Crabbox 形式的租用命令列介面包裝器（產品路徑），以及標記為僅限開發的靜態 SSH 主機供應商——共享主機上的工作節點可以讀取主機上不相關的資料，因此靜態主機僅供功能開發使用，並非預設安全立場。

### 2. 工作節點啟動程序：在機器上安裝 OpenClaw

不使用特製的工作節點成品，也不依賴 npm 是否可用：

* 所有模式的標準安裝方式：由閘道產生並以內容雜湊識別的工作節點套件（將閘道自身的建置輸出封裝為 tarball），經由 SSH 推送並安裝至機器。如此一來，開發建置與未發布提交自然都能涵蓋。
* 當閘道執行已發布版本時，`npm i -g openclaw@<exact gateway version>` 是一項最佳化；絕不使用 `latest`。
* 啟動程序具冪等性；若暖租用的套件雜湊相符，便略過安裝。全新機器可能需要可連網的工具鏈階段（Node 執行環境）——這屬於設定階段的一部分，完成後即關閉網路。
* 交握會驗證工作節點建置雜湊、協定功能集與執行環境相容性。現有的閘道版本／協定檢查不足以處理此需求（經 SSH 通道連線的節點不受精確版本拒絕規則限制），因此工作節點准入會自行執行精確建置檢查。

工作節點模式（`openclaw worker`）是一個進入點，而非分支：其包含連線處理與內嵌代理程式執行器，工作階段持久性與模型呼叫則由閘道 RPC 支援。它不得啟動閘道功能介面：不啟動任何頻道、除工作階段工具集外不自動啟動任何外掛、使用拋棄式狀態目錄，且不使用本機驗證設定檔。

### 3. 傳輸：所有內容皆經由 SSH

閘道擁有連線能力；工作節點除 sshd 外不需要任何其他服務：

* 閘道開啟與工作節點之間的 SSH 連線（認證資訊來自供應商租用，主機金鑰根據佈建輸出固定——不使用 `StrictHostKeyChecking=no`），並建立反向通道，將工作節點本機通訊端轉送至閘道的 WS 端點。
* 控制／模型流量與工作區傳輸使用不同的 SSH 連線，但採用相同的固定信任資料，因此 rsync 不會造成權杖串流的隊首阻塞。
* 通道生命週期（keepalive、以退避策略重新連線）由閘道上的環境執行環境擁有。短暫的通道中斷對工作階段層級不可見：下述持久協定狀態可讓工作節點重新附加並恢復。

### 4. 工作節點協定（專用；非節點協定）

針對目前節點接合面的對抗性審查排除了直接重複使用的可能性：待處理的節點叫用是程序本機的 Promise，會隨連線中斷而消失；節點冪等性金鑰雖會解析，卻不會去重；而最關鍵的是，已連線節點可以發出一般節點事件（包括代理程式執行請求），因此「節點種類 + 能力上限」並非入站安全邊界。因此，工作節點會取得經驗證的 `worker` 角色，並使用封閉且具版本控制的 RPC／事件允許清單；工作節點連線無法觸及任何舊版節點事件處理常式。

身分與認證資訊：佈建程序會鑄造短期工作節點認證資訊，並綁定至環境 ID、工作節點金鑰、套件雜湊、唯一允許的工作階段、允許的 RPC 集合與到期時間。經 SSH 驗證的配對仍然適用（機器由我們佈建，金鑰由我們持有），但授權來自鑄造的認證資訊，而非宣告的節點功能介面。

持久操作語意（結構借鑑現有的 ACP 執行環境及其事件帳本——穩定控制代碼、每個工作階段序列化、持久的 `(session, seq)` 重播）：

* 每個操作的範圍都限定於 `(sessionId, lifecycleRevision, runId, ownerEpoch, streamKind, seq)`。
* 擁有權世代會隔離過時的工作程式：替代工作程式會推進世代；舊世代延遲送達的結果會以確定性方式遭到拒絕。
* 使用持久化 ACK 游標及 SQLite 中快取的終止結果，提供至少一次傳遞；重複資料刪除具確定性。不承諾恰好一次。
* 為取消、關閉、恢復及終止結果提供明確訊框；串流採用以額度／視窗為基礎的流量控制。
* 協定功能協商獨立於一般節點協定版本。

### 5. 工作階段後端 RPC

兩種不同的契約——目前的程式碼庫將持久逐字記錄變更（由工作階段管理器擁有，使用具父項／葉節點狀態的 JSONL 樹狀結構）與程序本機即時事件（串流差異、工具生命週期、核准）分開，而工作程式協定必須維持此區分：

* 持久逐字記錄提交：工作程式使用 `runEpoch` 加上基準葉節點比較並交換，提交語意附加批次；閘道工作階段管理器會產生項目 ID 與父項 ID。工作程式絕不能提供受信任的逐字記錄資料列、項目 ID、父項 ID 或外部工作階段 ID。
* 可重播的即時事件：具工作程式序號、閘道 ACK、有限保留及延遲事件隔離的型別化事件聯集，饋入現有的代理程式事件扇出，使聊天檢視、工具資料列及未讀／狀態邏輯的行為與本機工作階段完全相同。

推論 Proxy：重複使用現有執行階段 Proxy 串流用戶端（`src/agents/runtime/proxy.ts`）的事件詞彙，但移動信任邊界。工作程式僅傳送工作階段／執行身分、已核准的模型參照、情境及受限的產生選項；閘道會從自身目錄解析供應商、端點、驗證、標頭、路由及成本政策。工作程式提供的模型物件（例如由攻擊者控制的 `baseUrl`）會遭到拒絕。套用要求大小限制、取消、稽核及終止結果重播。常駐於閘道的工具（websearch）會在閘道上執行，並透過相同通道傳回結果。

### 6. 工作區同步

同步錨點是具有獨佔配置擁有權的閘道本機工作區：對 git 工作區而言，是專用的受管理 worktree（現有的受管理 worktree 中繼資料——分支、基準、快照擁有權——是其基礎）；對非 git 工作區而言，則是閘道擁有的目標目錄。絕不使用使用者的即時 checkout。工作階段遠端配置期間的獨佔擁有權，從結構上確保傳入同步不會發生衝突。

擁有權區分——提交與發布：

* 工作程式端代理程式會如常在其副本中建立提交（`git commit` 是不使用認證資訊的本機操作；作者身分由閘道設定投射）。這些提交在閘道採用前都只是惰性物件。
* 閘道執行所有需要信任的操作：驗證傳入提交是以記錄的基準為基礎、以快轉方式更新本機 worktree、推送、建立 PR，以及選用的簽署／重新簽署——全部使用閘道本機的認證資訊。工作程式絕不持有 git 或程式碼託管平台的認證資訊，也絕不接觸遠端。

依工作區是否為 git 儲存庫選擇兩種同步模式：

* Git 模式。傳出：透過通道的 SSH 身分使用 rsync 同步 worktree（包含未提交及符合條件的未追蹤檔案；使用 crabbox 風格的包含／排除規則，並遵循 `.worktreeinclude`），並記錄為不可變的基準資訊清單（內容雜湊 + 基準提交）。傳入：新提交會以 git bundle 或相對於記錄基準的暫存 ref 傳回；未追蹤成品則透過明確的資訊清單傳回，並進行大小／類型／符號連結範圍限制檢查。採用時會驗證基準祖先關係，並在分歧時停止——不會默默覆寫任何一方。刪除、重新命名、子模組及符號連結逸出由資訊清單規則處理，而非 rsync 啟發式規則。
* 純文字模式（無 git——例如在該執行環境中從頭建立專案）。傳出方式相同，使用 rsync + 基準資訊清單。傳入則以資訊清單差異比對的方式鏡像回閘道擁有的目標目錄，並傳播刪除操作。其安全原因與 git 模式相同：獨佔擁有權代表不存在會造成衝突的並行本機編輯；基準資訊清單仍會偵測非預期的本機偏移，並停止而非覆寫。

檢查點可防止持續數日的工作階段因租用中斷而受損：定期建立傳入檢查點（git 模式使用工作階段分支提交，純文字模式使用資訊清單快照）；頻率由設定檔政策決定（預設以輪次為基礎）。

### 7. 配置狀態機、工作階段及 UI

執行階段配置是由 SQLite 擁有、以工作階段為鍵的狀態機，而不是一對鬆散的資料列欄位：

`local → requested → provisioning → syncing → starting → active(worker) → draining → reconciling → local | reclaimed | failed`

它會持久保存環境 ID、轉換世代、作用中擁有者世代、工作區基準資訊清單、工作程式套件組合雜湊及最後 ACK 游標。輪次准入會在任一迴圈開始輪次前，以不可分割的方式宣告配置，因此依據過時快照准入的本機訊息絕不可能與工作程式輪次競爭——任何時候都恰好只有一個迴圈擁有該工作階段。

UI：

* 工作程式工作階段是一般工作階段資料列加上配置中繼資料。它位於一般儲存區，透過 `sessions.list` 列出，並透過現有訂閱進行串流——側邊欄和聊天不需要新的資料路徑，只需呈現工作程式徽章及配置／環境狀態（`provisioning / syncing / running / idle / reconciling / reclaimed`）。
* 建立 UX：工作階段目標列（重新設計的工作階段側邊欄）會在閘道與節點旁加入雲端工作程式目的地。需要已設定的供應商設定檔；在完成設定前，此功能不可見。
* 代理程式分派：工作階段工具可讓代理程式像人類一樣將工作交給雲端工作程式（由工作程式支援、採子代理程式形式的子工作階段）。與人工分派在同一里程碑推出，並由相同的選用供應商設定控管。遞迴由結構限制（在 v1 中，工作程式工作階段本身不能再分派工作程式）；支出控制採用各環境的會計／稽核，而非配額機制。

## 分派與交接

v1 刻意採用非對稱設計：

* 本機 → 工作程式（分派）：通過下述遷移屏障、佈建或重複使用工作程式、同步、切換配置，下一輪會在遠端執行。
* 工作程式 → 本機（拉回）：停止工作階段（依相同屏障排空工作程式）、完成傳入協調，並將配置切換為本機。這不是即時遷移。
* 對稱即時交接（在不停止的情況下，將作用中的工作階段雙向移動）會重複使用相同的屏障與協調機制，並在故障注入測試證明該屏障後推出。

遷移屏障（僅有「輪次邊界」並不足夠——核准、背景程序及釋放鎖定後的逐字記錄合併可能跨越此邊界）：

1. 停止新輪次准入（配置宣告）。
2. 取消或排空作用中的執行。
3. 撤銷待處理的執行核准及執行授權。
4. 排空逐字記錄旁路寫入及即時事件 ACK。
5. 終止工作程式子程序。
6. 透過推進擁有者世代來隔離舊擁有者。
7. 協調工作區（傳入、可感知衝突）。
8. 啟用新擁有者。

快取親和性：由於兩種配置下的供應商要求都源自閘道，因此只要序列化的供應商要求維持等價，即可保留快取親和性——相同的工具順序、系統指示、供應商包裝器及快取中繼資料（這些資料會保留在閘道端）。這是可測試的特性，而非假設：針對每種支援的供應商傳輸方式進行本機／工作程式配置間的位元組等價測試，是引入工作程式迴圈之里程碑的一部分。

## 安全性模型

精確而言：工作程式沒有直接網路對外連線，也沒有常駐的供應商／程式碼託管平台認證資訊。這並非「零對外連線」——推論及由閘道執行的工具是受控對外通道（遭提示詞注入的工作程式仍可將工作區位元組放入模型情境或 websearch 查詢）。因此：

* 受控對外連線計量：針對推論 Proxy 及閘道工具，提供各環境的稽核及操作人員可見的計量。速率／位元組限制是協定流量控制（容量），而非支出配額機制。
* 工作程式對閘道的傳入存取僅限封閉的工作程式協定允許清單；逐字記錄寫入受到結構性限制（由閘道產生 ID、僅限單一繫結工作階段）。
* 工作程式在執行環境中擁有完整執行權限。執行環境可拋棄且不含認證資訊，因此逐指令核准只會增加阻力，無法提供任何保護；受防護的邊界是傳入協調及稽核。執行絕不經過閘道節點核准路徑。
* 網際網路政策是在佈建時由供應商決定：環境設定檔會在建立執行環境時決定（防火牆／安全性群組／無對外連線網路），並可選擇提供具網路連線的設定階段，由供應商在代理程式階段前關閉。核心不實作執行階段網路切換。
* 佈建時的執行環境衛生：封鎖或確認不存在雲端中繼資料端點、無執行個體設定檔、無繼承的 SSH 代理程式、無 Docker socket，並使用乾淨的環境／家目錄。從佈建輸出固定 SSH 主機金鑰。
* 任何閘道端操作（推送、PR、供應商呼叫）的核准及政策仍會在閘道上執行。

遭入侵的工作程式工作階段之影響範圍：同步的工作區副本，加上經稽核的 Proxy 通道所允許的內容——無認證資訊、無直接網路，且除了允許清單外無法存取任何閘道介面。

## 容量

閘道會轉送 N 個工作程式的每個提示詞及權杖串流，因此 v1 會明定容量模型，而非等到正式環境才發現問題：每個閘道的並行工作程式限制、每個串流的額度視窗（目前事件串流佇列沒有上限，而節點 socket 緩衝區達到上限時會強制關閉慢速消費者——兩者均不適合直接沿用）、用於突發流量的有限磁碟暫存，以及在 UI 中顯示可見背壓狀態的負載卸除。工作區傳輸仍使用獨立的 SSH 通道。

## 生命週期

* 閒置自動停止及 TTL 是供應商設定檔政策，而非固定常數。預設值寬裕且提供明確的保持連線機制；持續數日的工作屬於一級使用情境（租用型後端已有供應商 `renew`）；具有進行中輪次或近期活動的工作階段絕不會遭到回收。
* 工作程式終止或遭回收時：配置會移至 `reclaimed`，工作階段資料列會保留，下一則訊息會佈建新的工作程式，並從最後一個檢查點重新同步。對話絕不會遺失（位於閘道端儲存區）；最後一個檢查點之後的工作區變更會遺失，且 UI 會明確告知。
* 從第一天起重複使用溫熱租用環境（適用於支援此功能的供應商）；啟動程序完成後建立映像快照，是 v2 的快速啟動路徑。

## 設定介面

最小化且採選用方式：供應商設定檔區塊（供應商 ID、認證資訊／命令列介面參照、同步規則、存續期政策、預算、選用的設定階段），加上各工作階段的配置選擇。不新增環境變數。未設定的安裝環境不會看到任何相關功能。

## 里程碑

實作會以小型、可獨立合併的 PR 形式加入；下列每個里程碑都是一系列 PR，而非單一變更。

1. 基礎：環境狀態機 + 提供者合約 + crabbox 形式的提供者（以靜態 SSH 作為開發測試框架）、工作節點套件啟動程序 + 准入交握、SSH 通道 + 主機金鑰釘選、受管理工作樹快照 + 向外同步（git + 純文字模式）。孤立項目清除 + 重新啟動接管。
2. 工作節點協定 + 工作節點迴圈：經驗證的工作節點角色、持久化操作／epoch／ACK 游標、逐字稿提交 + 即時事件合約、使用閘道解析模型的推論代理、流量控制。單一提供者，僅允許由人工分派新工作階段，不進行移交。以故障注入測試（通道分割、閘道重新啟動、工作節點終止）作為退出門檻。
3. 分派 + 拉回 + 代理程式分派：遷移屏障、連接至 UI 目標列的放置狀態機、傳入資料協調 + 檢查點、各環境稽核、容量限制、代理程式分派工具（工作節點工作階段不可遞迴）。提示詞快取位元組等價性測試。
4. 在里程碑 3 的故障注入驗證後，進行對稱式即時移交。

後續：工作節點上的 ACP 測試框架，作為各環境認證資訊注入的選擇性啟用項目；快照／暖映像快速啟動；扇出（N 個租約、相同提示詞）；工作箱內的作業系統沙箱；透過成品結構描述擷取更豐富的成品。

## 待釐清問題

* 工作節點上的外掛／skill 可用性：儲存庫隨附的 skills 可隨工作區免費同步；閘道設定的代理程式 skills／外掛則需要明確決定要同步或排除（無論如何，工具／外掛資訊清單都是准入交握的一部分）。
* 檢查點頻率預設值：對話非常頻繁的工作階段應採用以輪次為基礎，還是以時間為基礎。
* 環境設定檔如何與多代理程式路由互動（各代理程式的預設設定檔，或僅限各工作階段選取）。