> ## 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.

# 雲端工作程序

雲端工作器可讓工作階段在一次性的雲端機器上執行代理程式迴圈，同時工作階段的一切仍保留在原本的位置：顯示於側邊欄、即時串流，且逐字稿由閘道擁有。閘道會租用一台機器、在其上安裝固定版本的 OpenClaw、同步工作階段的工作區，並將回合迴圈交給受限的 `openclaw worker` 程序。模型呼叫會透過閘道代理回傳，因此提供者認證資訊絕不會離開你的機器；由於提供者看到的是單一連續串流，提示快取也能繼續運作。

工作完成（或機器故障）後，該機器便會被丟棄。持久狀態（逐字稿、工作區提交、配置記錄）則由閘道保存。

<Note>
  雲端工作器採選用制，在設定設定檔之前不會顯示。未設定的安裝不會看到任何新的 RPC、設定或 UI。
</Note>

## 各項作業的執行位置

| 項目                                        | 位置                             |
| ----------------------------------------- | ------------------------------ |
| 代理程式迴圈與工具（`exec`、`read`、`write`、`edit`、…） | 雲端工作器機器                        |
| 模型推論和提供者認證資訊                              | 閘道（由 `{provider, model}` 參照代理） |
| 逐字稿（持久、工作階段儲存區）                           | 閘道                             |
| 即時串流至側邊欄                                  | 閘道扇出，由工作器可重播的事件串流提供            |
| 工作區 Git 歷史                                | 在機器上以無認證資訊方式建立；閘道接管提交並負責推送／PR  |

除了 `sshd`，該機器不需要任何連入連接埠：閘道透過固定的 SSH 向外連線，而反向通道會將工作器的 WebSocket 傳回。隨附的 Crabbox 提供者會強制使用公用 SSH 路由，並停用受管理的 Tailscale 註冊。對外網際網路存取由提供者政策決定；除非你限制其網路或安全群組，否則預設 AWS 設定檔可以存取網際網路。

## 需求

* 工作器提供者外掛。隨附的 `crabbox` 外掛會驅動 [Crabbox](https://github.com/openclaw/crabbox) 命令列介面，由它代理跨雲端後端（AWS、Hetzner 及其他後端）的租用作業。`crabbox` 二進位檔必須位於 `PATH`（或設定 `settings.binary`），且提供者認證資訊必須已設定完成。AWS 准入需要 Crabbox 0.38.1 或更新版本。
* 對於 Crabbox AWS 工作器，有效的 `aws.instanceProfile` 必須為空。提供者會在配置前檢查 `crabbox config show --json`，接著要求 `crabbox inspect --json` 回報來自 EC2 `DescribeInstances` 的 `providerMetadata.instanceProfileAttached: false`。具有執行個體角色或缺少權威中繼資料的租用項目會被停止並拒絕。
* 租用機器上的 Node.js。基本雲端映像通常不包含它，請在設定檔的 `setup` 命令中安裝。
* 具有工作階段自有受管理工作樹的工作階段（使用 `worktree: true` 建立）。派送會移動該工作樹的內容；一般目錄則會同步為資訊清單鏡像。

## 設定

在 `openclaw.json` 的 `cloudWorkers.profiles` 下新增設定檔：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "cloudWorkers": {
    "profiles": {
      "aws": {
        "provider": "crabbox",
        "install": "bundle",
        "settings": {
          "provider": "aws",
          "class": "standard",
          "ttl": "8h",
          "idleTimeout": "45m",
          "setup": "test -x /usr/bin/node || (curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - && sudo apt-get install -y nodejs)"
        }
      }
    }
  }
}
```

設定檔欄位：

| 鍵          | 意義                                                                                                                                                             |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider` | 由外掛註冊的工作器提供者 ID（隨附外掛為 `crabbox`）。                                                                                                                              |
| `install`  | `bundle`（預設）會傳送執行中閘道的組建；`npm` 會使用固定的完整性資訊，安裝與閘道完全相同的已發布版本。`npm` 要求閘道必須從封裝的發行版本執行。                                                                              |
| `settings` | 由提供者擁有的 JSON。對於 crabbox：`provider`（後端）、`class`（機器類別）、`ttl`、`idleTimeout`（Go 持續時間），以及選用的 `setup` 和絕對 `binary` 路徑。OpenClaw 會對這些租用項目強制使用公用 SSH，並停用受管理的 Tailscale。 |
| `lifetime` | 選用的已儲存政策（`idleTimeoutMinutes`、`maxLifetimeMinutes`）。                                                                                                           |

### 設定命令

`settings.setup` 會在租用機器可透過 SSH 連線後、安裝 OpenClaw 前執行。它會在**每次**配置嘗試時執行（包括派送中斷後的重播），因此必須具備冪等性——請如範例所示，使用 `command -v`/`test -x` 檢查來保護安裝作業。如果設定失敗，提供者會停止租用項目，且派送會以封閉方式失敗；不會留下僅完成部分設定且仍在執行的機器。

### 安裝管道

* **`bundle`** 會封裝執行中閘道的 `dist`、經裁剪的 `package.json`，以及組建所參照的所有工作區套件，並以內容雜湊涵蓋全部內容。機器會根據該雜湊驗證未修改的套件組，接著安裝生產環境 npm 相依套件（停用指令碼）。這是你在工作器上執行開發組建的方式。
* **`npm`** 會證明該發行版本存在於公用登錄檔、固定其 SHA-512 完整性，並安裝與閘道完全相符的 `openclaw@<version>`。

## 派送工作階段

在控制 UI 中，開啟 **New Session**，選擇已設定 OpenClaw 執行階段的代理程式，從 **Where** 選單中選取已設定的 **Cloud · profile** 目標，然後開始工作。選取雲端會自動啟用必要的受管理工作樹；閘道會建立工作階段、完成派送，然後才傳送第一個回合。工作階段側邊欄中的伺服器徽章會顯示持久配置狀態。外部命令列介面工作階段目錄不會提供雲端目標。

對等的 RPC 流程如下：

使用受管理工作樹建立工作階段，然後派送它（RPC 需要 `operator.admin`，且僅在已設定設定檔時存在）：

雲端工作器會執行 OpenClaw 代理程式執行階段。請選擇可解析至該執行階段的 `openai/*` 或其他模型；設定為外部命令列介面執行階段（例如 `claude-cli`）的工作階段無法派送。

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway call sessions.create \
  --params '{"key":"agent:main:big-refactor","worktree":true,"cwd":"/path/to/repo","worktreeName":"big-refactor"}'

openclaw gateway call sessions.dispatch \
  --timeout 1500000 \
  --params '{"key":"agent:main:big-refactor","profileId":"aws"}'
```

`sessions.dispatch` 會關閉本機回合准入、排空進行中的工作、配置租用項目、執行設定、啟動 OpenClaw、同步工作區，並在配置達到 `active` 工作器擁有權後傳回。第一次派送請預留數分鐘；若提供者支援，租用項目和安裝內容會被快取。之後只要照常與工作階段互動，回合便會自動路由至工作器。

工作器回合完成後，會在釋放回合宣告權之前，將符合資格且大小受限的工作區檔案協調回工作階段的受管理工作樹。終止工作器事件會在獲得確認前建立持久的待處理結果柵欄。接著，閘道會先將完整的雲端結果暫存為 `refs/openclaw/worker-results/` 下的 Git 參照，再套用結果，因此即使閘道在套用期間停止，雲端版本仍可復原。工作區結果採用 Git 檔案語意：一般檔案、可執行位元、符號連結、新增、變更和刪除都會保留，但空目錄及其他目錄模式不會保留。產生的檔案變更會留在受管理工作樹中，以供正常審查和提交。

套用作業會使用派送時的資訊清單作為合併基底。僅存在於雲端的變更會被套用，僅存在於本機的變更會留在原處，而雙方皆有變更的路徑則採用三向保留本機政策。即使回合發生衝突仍會完成：逐字稿會回報受限的路徑摘要與已暫存結果參照，配置會公開相同的衝突供控制 UI 使用，而沒有衝突的雲端變更仍會套用。通知包含 `git show <ref>:<path>`，可用來檢查存在的雲端檔案，以及可從任何工作區目錄取得該檔案的頂層常值 pathspec `git checkout <ref> -- <path>` 命令。請在 Bash 或 zsh（Windows 上使用 Git Bash）中執行這些命令。如果檢查指出路徑不存在，表示雲端結果已刪除該路徑；請驗證後手動移除保留的本機路徑。如果簽出回報檔案／目錄阻礙，請移動或移除造成阻礙的本機路徑，然後重試。如果已暫存參照本身已不存在，請將通知視為過時，且不要變更本機路徑。發生衝突的已暫存參照會在一般回合柵欄釋放後繼續保留；後續乾淨的結果會清除通知並淘汰舊參照，而明確移除柵欄則是最後的清理邊界。

當具有柵欄的結果仍在協調時，新回合最多會等待 15 秒，讓先前的宣告權釋放。如果仍在忙碌，該回合會失敗並顯示可採取行動的“前一個雲端回合的工作區結果仍在協調”訊息，稍後即可重試。重新啟動時，復原程序會在清理過期宣告權前找出待處理及已暫存的結果、完成或重試其本機套用，並只在保留結果後回收失效環境。受限的 SQLite 回復日誌可讓中斷的檔案系統套用作業復原，而無須重播已接受的變動。

工作完成且沒有回合正在執行時，開啟工作階段選單並選擇 **Stop cloud worker…**。閘道會在銷毀環境前執行最後一次工作區協調。已處於 `draining` 或 `reconciling` 的配置正在完成拆除；請等其徽章變成 `reclaimed` 後，再刪除工作階段。

對於故障或失控且仍連接的工作器，操作者可呼叫 `environments.destroy` 並搭配 `{ "force": true }`，作為最後手段。強制拆除會以持久方式將配置標記為失敗、放棄任何尚未協調的遠端結果，然後銷毀環境。

對等的管理 RPC 如下：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway call sessions.reclaim \
  --timeout 600000 \
  --params '{"key":"agent:main:big-refactor"}'
```

配置會透過持久狀態機（`local → requested → provisioning → syncing → starting → active`）流轉，因此在分派期間重新啟動閘道時，系統會進行協調，而不會洩漏機器。模型回合失敗時，會保留作用中的配置以供重試。工作區路徑衝突時，會保留本機版本、套用雲端結果的其餘部分，並保留已暫存的雲端參照以供檢查；其他協調或生命週期失敗則會保留其持久復原柵欄和診斷尾端，直到復原程序能安全地重試或回收環境。

## 安全性模型

* **封閉的工作節點輸入。** 工作節點會透過隧道通訊端上的專用協定進行通訊，且方法允許清單為封閉式，因此工作節點無法呼叫操作員 RPC。
* **由閘道掌控的工具權限。** 在每個回合前，閘道會依據工作節點的固定程式設計工具目錄，套用目前的設定檔、供應商、代理程式、群組、傳送者、沙箱、委派、繼承及執行階段上限原則。啟動封套只會攜帶最終的封閉詞彙子集。明確設有上限的排程回合會重複使用其受信任的擁有者群組情境，而不會將該身分傳送至機器，也不會重新套用新的傳送者覆疊。工作節點目錄以外的工具仍無法使用；若結果為空，則不使用任何工具執行。
* **即時鑄造認證資訊，靜態儲存時採雜湊處理。** 每次分派都會鑄造一組工作節點認證資訊；閘道只儲存其雜湊值。認證資訊輪替與擁有者世代柵欄可確保每個工作階段最多只有一個作用中的擁有者；過時的工作節點重新連線時會遭到隔離，絕不會被合併。
* **主機金鑰釘選。** 供應商必須在佈建時提供機器的 SSH 主機金鑰；啟動程序會使用嚴格釘選進行連線，若未提供金鑰則以封閉方式失敗。
* **機器上不留存模型、程式碼代管平台或雲端認證資訊。** 模型驗證保留在閘道上（推論透過 `{provider, model}` 參照傳輸），工作區 Git 提交不使用程式碼代管平台認證資訊建立，而在設定前，系統會以權威方式檢查 Crabbox AWS 租用中繼資料是否具有執行個體角色。設定命令也應避免使用認證資訊。
* **由供應商掌控的輸出流量。** 反向隧道讓 OpenClaw 不需要直接存取模型，但 OpenClaw 不會改寫供應商防火牆。若工作需要，請在工作節點供應商中限制輸出流量。
* **持久且恰好一次的逐字記錄。** 工作節點會針對工作階段的葉節點，透過比較並交換協定提交逐字記錄批次；若基底過時，系統會讓執行立即停止，而不會複製付費輸出或重新建立其基底。

## 疑難排解

* **`sessions.dispatch` 是未知的方法** — 未設定任何 `cloudWorkers.profiles`，或呼叫者缺少 `operator.admin`。
* **“雲端工作節點回合需要 OpenClaw 執行階段”** — 請選擇已將執行階段設定為 OpenClaw 的模型。`claude-cli` 等外部命令列介面執行階段不支援工作節點推論。
* **“工作節點啟動程序要求租用主機上安裝 Node.js”** — 在 `settings.setup` 中加入 Node 安裝步驟（請參閱上文）。
* **AWS 執行個體角色證明失敗** — 清除 `aws.instanceProfile`（若已設定，也請清除 `CRABBOX_AWS_INSTANCE_PROFILE`）。請安裝 Crabbox 0.38.1 或更新版本；較舊的二進位檔不會公開 AWS 准入所需的權威 `providerMetadata.instanceProfileAttached` 合約。
* **分派因供應商錯誤而失敗** — 配置記錄與 `environments.list` 會保留最後一次錯誤，包括設定／啟動程序的 stderr 尾端。失敗時會銷毀機器，因此該尾端是主要的鑑識資料。
* **分派時用戶端逾時** — `openclaw gateway call` 預設逾時時間為 10 秒；請為 `--timeout` 傳入充足的值（無論如何，分派都會繼續在伺服器端執行，而在佈建期間重試會遭到拒絕，並回傳 `session cannot dispatch from placement provisioning`）。
* **從 2026.7.2 Beta 版升級後回收工作節點** — 這些 Beta 版使用較舊的工作節點啟動合約。重新啟動時，OpenClaw 會銷毀閒置且不相容的工作節點、保留工作階段與工作區、將配置標示為已回收，並在下一次分派或回合時佈建目前版本的工作節點。若 Beta 版工作節點在仍處於啟動階段時中斷，清理完成後會標示為失敗；請重試分派，以使用目前的合約進行佈建。
* **雲端工作區衝突通知** — 回合已完成，且已保留每個列出路徑的本機版本。請使用通知中的暫存參照命令檢查或採用雲端版本；非衝突的變更已套用，無需重試。
* **“上一個雲端回合的工作區結果仍在協調中”** — 閘道已短暫等待先前結果的持久柵欄，但無法取得工作階段宣告。請等待協調完成，然後重試該回合；重新啟動閘道是安全的，因為復原程序會先保留暫存結果，再回收已停止運作的工作節點。
* **租用維護** — `crabbox list --provider <backend>` 會顯示作用中的租用；`crabbox stop --provider <backend> --id <lease>` 可手動釋放其中一個。閒置租用會依設定檔的 `idleTimeout` 到期。

## 相關內容

* [沙箱化](/zh-TW/gateway/sandboxing) — 縮小本機工具執行的影響範圍
* [工作階段命令列介面](/zh-TW/cli/sessions) — 檢查已儲存的工作階段
* [設定參考](/zh-TW/gateway/configuration-reference)