---
read_when:
    - 設計或實作雲端工作節點佈建、工作節點模式或工作階段交接
    - 變更 environments.*、工作程式通訊協定、對話記錄匯入或推論代理 RPC 呼叫
    - 檢視遠端代理程式執行的安全態勢
summary: 在可透過 SSH 連線的臨時機器上執行代理工作階段，並透過閘道代理推論及即時串流至側邊欄。
title: 雲端工作程序計畫
x-i18n:
    generated_at: "2026-07-11T21:29:56Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 134c3f6e486837607225d95d12a3153525b14237b362b9f9957313d9bc379dc4
    source_path: plan/cloud-workers.md
    workflow: 16
---

## 狀態

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

## 問題

OpenClaw 代理工作階段在單一機器的閘道程序內執行其迴圈、工具與推論。運算能力受限於該機器，長時間任務會持續占用它，而平行工作也會競爭其資源。託管式產品（Cursor 雲端代理、網頁版 Claude Code、Codex cloud）以每項任務配置暫時性雲端沙箱來解決此問題，但這些方案需要供應商基礎設施，且必須信任供應商。

已經擁有閒置機器（或能以低廉價格租用機器）的營運者，目前無法指定：在那台機器上執行此工作階段、像其他工作階段一樣顯示於我的側邊欄，並在完成後銷毀該機器。

## 目標

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

## 非目標（v1）

- 工作節點上不使用外部程式開發工具框架（Claude Code、Codex CLI）。工作節點工作階段只執行 OpenClaw 的內嵌執行器。工具框架支援是 v2 的選用功能，因為工具框架會以自身憑證自行執行推論。
- 不進行 N 選一最佳化／平行嘗試扇出。
- 不依賴 VPN／尾網。傳輸僅使用 SSH。
- 不新增沙箱執行環境。工作節點機器本身就是隔離邊界；之後可以再疊加機器內的作業系統沙箱。
- v1 不支援對稱式即時遷移：分派方向為本機 → 工作節點；工作節點 → 本機則需要已停止的工作階段，且工作區協調已完成。之後的雙向即時移交將建構於相同的屏障機制上。
- 閘道上不使用 JSON 輔助狀態；環境、配置位置、游標與授權狀態均儲存於 SQLite。

## 既有方案（我們沿用與反轉的部分）

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

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

曾考慮三種配置位置：

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

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

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

由於閘道同時儲存逐字稿並發起所有供應商流量，因此工作階段不受位置約束：在閘道與工作節點之間移動迴圈，不會改變供應商端的任何行為，也不會改變介面資料路徑。這正是分派與取回成本低廉的原因。

## 元件

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

閘道協定中的 `environments.*` 目前只是狀態投影。耐久核心是由 SQLite 管理的環境記錄與狀態機，會先完成設計，再定義 RPC 形態：

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

- 佈建具備當機安全性：在呼叫供應商之前，會先以確定性的操作 ID 持久化意圖資料列，因此閘道重新啟動後可接管進行中的租用，而不會重複佈建或使付費機器成為孤兒。
- 重新啟動協調與孤兒清理程式（供應商 `inspect` 對照本機記錄）是 v1 的必要需求，而非額外強化措施。

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

```ts
type WorkerProvider = {
  id: string;
  provision(profile: WorkerProfile, opId: string): Promise<WorkerLease>; // → ssh host/port/user/key material
  inspect(lease: { leaseId: string; profile: WorkerProfile }): Promise<LeaseStatus>; // adopt/health/orphan sweep
  renew?(leaseId: string): Promise<void>; // long-lived sessions vs provider TTLs
  destroy(lease: { leaseId: string; profile: WorkerProfile }): Promise<void>; // idempotent, returns only on proof of teardown
};
```

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 不會因隊首阻塞而妨礙權杖串流。
- 通道生命週期（持續連線、以退避機制重新連線）由閘道上的環境執行環境管理。通道短暫中斷對工作階段層級不可見：下述耐久協定狀態可讓工作節點重新連結並恢復執行。

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

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

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

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

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

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

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

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

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

### 6. 工作區同步

同步錨點是由閘道在本機擁有、具排他配置所有權的工作區：對 git 工作區而言，是專用的受管理工作樹（以現有受管理工作樹中繼資料——分支、基礎、快照所有權——為基礎）；對非 git 工作區而言，則是閘道擁有的目標目錄。絕不使用使用者的即時簽出目錄。工作階段遠端配置期間的排他所有權，從設計上確保輸入同步不會發生衝突。

所有權劃分——提交與發布：

- 工作器端代理程式在其副本中照常建立提交（`git commit` 是不需要憑證的本機操作；作者身分由閘道設定投射）。在閘道採納這些提交之前，它們只是無作用的物件。
- 閘道執行一切需要信任的操作：驗證輸入提交建立於所記錄的基礎之上、快速前移本機工作樹、推送、建立 PR，以及選用的簽署／重新簽署——全都使用閘道本機憑證。工作器絕不持有 git 或程式碼託管平台憑證，也絕不接觸遠端。

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

- Git 模式。輸出：透過通道的 SSH 身分使用 rsync 同步工作樹（包括未提交及符合條件的未追蹤檔案；採用 crabbox 形式的包含／排除規則，並遵循 `.worktreeinclude`），記錄為不可變的基礎資訊清單（內容雜湊＋基礎提交）。輸入：新提交以相對於所記錄基礎的 git bundle 或暫存參照傳回；未追蹤成品透過明確資訊清單傳回，並接受大小／類型／符號連結範圍限制檢查。採納時驗證基礎祖先關係，若發生分歧則停止——絕不默默覆寫任一端。刪除、重新命名、子模組與符號連結逸出由資訊清單規則處理，而非依賴 rsync 啟發式規則。
- 純目錄模式（無 git——例如在機器上從頭建立專案）。輸出採用相同的 rsync＋基礎資訊清單。輸入則依資訊清單差異鏡像回閘道擁有的目標目錄，並傳播刪除。其安全理由與 Git 模式相同：排他所有權表示不存在可能衝突的並行本機編輯；基礎資訊清單仍會偵測非預期的本機漂移，並停止而非覆寫。

檢查點可保護持續數日的工作階段免受租期遺失影響：定期建立輸入檢查點（Git 模式使用工作階段分支提交，純目錄模式使用資訊清單快照）；頻率由設定檔政策決定（預設以回合為基準）。

### 7. 配置狀態機、工作階段與使用者介面

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

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

它會持久保存環境 ID、轉換世代、目前擁有者紀元、工作區基礎資訊清單、工作器套件雜湊及最後 ACK 游標。回合准入會在任一迴圈開始回合前，以不可分割操作宣告配置所有權，因此依過時快照准入的本機訊息絕不可能與工作器回合競爭——任何時刻都只有一個迴圈擁有該工作階段。

使用者介面：

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

## 派送與移交

v1 刻意採用非對稱設計：

- 本機 → 工作器（派送）：通過下述遷移屏障、佈建或重用工作器、同步、切換配置，下一回合在遠端執行。
- 工作器 → 本機（拉回）：停止工作階段（依相同屏障排空工作器）、完成輸入協調、將配置切換至本機。這不是即時遷移。
- 對稱即時移交（在不停止的情況下，雙向移動正在工作的工作階段）重用相同的屏障與協調機制，並在故障注入測試證實屏障有效後推出。

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

1. 停止新的回合准入（配置宣告）。
2. 取消或排空進行中的執行。
3. 撤銷待處理的執行核准與執行授權。
4. 排空逐字記錄旁路寫入與即時事件 ACK。
5. 終止工作器子程序。
6. 推進擁有者紀元，以隔離舊擁有者。
7. 協調工作區（輸入，具衝突感知能力）。
8. 啟用新擁有者。

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

## 安全模型

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

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

工作器工作階段遭入侵的影響範圍：同步的工作區副本，加上經稽核代理通道所允許的內容——無憑證、無直接網路、除允許清單外無其他閘道介面。

## 容量

閘道會為 N 個工作器轉送每個提示與權杖串流，因此 v1 明確定義容量模型，而非等到正式環境才發現問題：每個閘道的並行工作器限制、每個串流的信用額度視窗（目前的事件串流佇列無上限，而節點通訊端緩衝區達上限時會強制關閉慢速消費者——兩者都不適合未經修改直接使用）、用於突發流量的有界磁碟暫存，以及在使用者介面中顯示明確背壓狀態的負載卸除。工作區傳輸維持使用獨立的 SSH 通道。

## 生命週期

- 閒置自動停止與 TTL 是供應商設定檔政策，而非固定常數。預設值寬裕，並提供明確的保持運作設定；持續數日的工作是一等使用情境（以租期為基礎的後端可使用供應商 `renew`）；具有進行中回合或近期活動的工作階段絕不會被回收。
- 工作器死亡或遭回收時：配置移至 `reclaimed`，工作階段資料列保留，下一則訊息會佈建新的工作器，並從最後一個檢查點重新同步。對話絕不遺失（位於閘道端的儲存區）；最後一個檢查點之後的工作區變更會遺失，且使用者介面會明確告知。
- 從第一天起支援暖租期重用（限支援的供應商）；啟動程序完成後建立映像快照，是 v2 的快速啟動路徑。

## 設定介面

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

## 里程碑

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

1. 基礎：環境狀態機＋供應商契約＋crabbox 形式的供應商（以 static-SSH 作為開發測試框架）、工作器套件啟動程序＋准入交握、SSH 通道＋主機金鑰固定、受管理工作樹快照＋輸出同步（Git＋純目錄模式）。孤兒清理＋重新啟動後接管。
2. 工作器協定＋工作器迴圈：經驗證的工作器角色、持久操作／紀元／ACK 游標、逐字記錄提交＋即時事件契約、由閘道解析模型的推論代理、流量控制。一個供應商、僅支援人工派送新工作階段、不支援移交。必須通過故障注入測試（通道分割、閘道重新啟動、工作器死亡）才能完成此里程碑。
3. 派送＋拉回＋代理程式派送：遷移屏障、將配置狀態機連接至使用者介面目標列、輸入協調＋檢查點、各環境稽核、容量限制、代理程式派送工具（工作器工作階段無法遞迴）。提示快取位元組等價測試。
4. 對稱即時移交，在里程碑 3 的故障注入測試證實後推出。

後續：工作器上的 ACP 測試框架，作為各環境憑證注入的選用功能；快照／暖映像快速啟動；扇出（N 個租期、相同提示）；機器內作業系統沙箱；透過成品結構描述擷取更豐富的成品。

## 待確認問題

- 工作節點上的外掛／Skills 可用性：隨儲存庫提供的 Skills 會免費隨工作區同步；由閘道設定的代理程式 Skills／外掛則需要明確決定要同步或排除（無論採用哪種方式，工具／外掛資訊清單都是准入交握的一部分）。
- 檢查點頻率預設值：對話非常頻繁的工作階段應採用以輪次為準或以時間為準。
- 環境設定檔如何與多代理程式路由互動（每個代理程式的預設設定檔，或僅允許每個工作階段自行選取）。