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

# クラウドワーカー

クラウドワーカーを使用すると、セッションに関するすべてを従来どおりの場所（サイドバーに表示され、ライブストリーミングされ、トランスクリプトは Gateway が所有）に維持しながら、使い捨てのクラウドマシン上でセッションのエージェントループを実行できます。Gateway はボックスをリースし、固定された OpenClaw のコピーをインストールしてセッションのワークスペースを同期し、制限付きの `openclaw worker` プロセスにターンループを引き渡します。モデル呼び出しは Gateway 経由でプロキシされるため、プロバイダーの認証情報がマシンの外へ出ることはありません。また、プロバイダーには単一の連続したストリームとして認識されるため、プロンプトキャッシュも引き続き機能します。

作業が完了すると（またはボックスが停止すると）、マシンは破棄されます。永続的な状態（トランスクリプト、ワークスペースのコミット、配置レコード）は Gateway 側に保持されます。

<Note>
  クラウドワーカーはオプトイン機能であり、プロファイルを設定するまでは表示されません。未設定のインストール環境には、新しい RPC、設定、UI は表示されません。
</Note>

## どこで何が実行されるか

| 対象                                            | 場所                                                |
| --------------------------------------------- | ------------------------------------------------- |
| エージェントループとツール（`exec`、`read`、`write`、`edit`、…） | クラウドワーカーボックス                                      |
| モデル推論とプロバイダーの認証情報                             | Gateway（`{provider, model}` 参照によってプロキシ）           |
| トランスクリプト（永続、セッションストア）                         | Gateway                                           |
| サイドバーへのライブストリーミング                             | ワーカーの再生可能なイベントストリームを受信する Gateway のファンアウト          |
| ワークスペースの Git 履歴                               | ボックス上で認証情報なしに作成され、Gateway がコミットを取り込んで push/PR を所有 |

ボックスに必要な受信ポートは `sshd` のみです。Gateway は固定された SSH 経由で外向きに接続し、リバーストンネルがワーカーの WebSocket を戻します。同梱の Crabbox プロバイダーは公開 SSH ルートを強制し、管理対象の Tailscale 登録を無効にします。外向きのインターネットアクセスはプロバイダーのポリシーに従います。デフォルトの AWS プロファイルは、ネットワークまたはセキュリティグループで制限しない限り、インターネットにアクセスできます。

## 要件

* ワーカープロバイダー Plugin。同梱の `crabbox` Plugin は、クラウドバックエンド（AWS、Hetzner など）間のリースを仲介する [Crabbox](https://github.com/openclaw/crabbox) CLI を操作します。`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` | Plugin によって登録されたワーカープロバイダー ID（同梱 Plugin の場合は `crabbox`）。                                                                                                                          |
| `install`  | `bundle`（デフォルト）は実行中の Gateway のビルドを配布します。`npm` は整合性を固定した、正確に同じリリース済み Gateway バージョンをインストールします。`npm` では、Gateway がパッケージ化されたリリースから実行されている必要があります。                                      |
| `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`** は、実行中の Gateway の `dist`、不要部分を除いた `package.json`、およびビルドが参照するすべてのワークスペースパッケージをパックし、全体をコンテンツハッシュで保護します。ボックスはそのハッシュに対して未変更のバンドルを検証した後、本番用 npm 依存関係をインストールします（スクリプトは無効）。これは、ワーカー上で開発ビルドを実行する方法です。
* **`npm`** は、リリースが公開レジストリに存在することを証明し、その SHA-512 整合性を固定して、Gateway と完全に一致する `openclaw@<version>` をインストールします。

## セッションのディスパッチ

Control UI で **New Session** を開き、設定済みランタイムが OpenClaw であるエージェントを選択し、**Where** メニューから設定済みの **Cloud · profile** ターゲットを選択して、タスクを開始します。クラウドを選択すると、必要な管理対象ワークツリーが自動的に有効になります。Gateway はセッションを作成し、ディスパッチを完了してから、最初のターンを送信します。セッションのサイドバーにあるサーバーバッジには、永続的な配置状態が表示されます。外部 CLI セッションカタログでは、クラウドターゲットは提供されません。

同等の RPC フローは次のとおりです。

管理対象ワークツリー付きのセッションを作成してからディスパッチします（RPC には `operator.admin` が必要であり、プロファイルが設定されている場合にのみ存在します）。

クラウドワーカーは OpenClaw エージェントランタイムを実行します。そのランタイムに解決される `openai/*` またはその他のモデルを選択してください。`claude-cli` などの外部 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` のワーカー所有権に達すると戻ります。最初のディスパッチには数分を見込んでください。プロバイダーが対応している場合、リースとインストールはキャッシュされます。それ以降は、通常どおりセッションとやり取りできます。ターンは自動的にワーカーへルーティングされます。

完了したワーカーターンでは、ターンのクレームが解放される前に、対象となるサイズ制限内のワークスペースファイルがセッションの管理対象ワークツリーへ反映されます。終端ワーカーイベントは、確認応答される前に、永続的な保留結果フェンスを作成します。その後 Gateway は、適用前に完全なクラウド結果を `refs/openclaw/worker-results/` 配下の Git ref としてステージングするため、適用中に Gateway が停止してもクラウド版を復旧できます。ワークスペースの結果には Git のファイルセマンティクスが使用されます。通常ファイル、実行可能ビット、シンボリックリンク、追加、変更、削除は保持されますが、空のディレクトリやその他のディレクトリモードは保持されません。結果として生じたファイル変更は、通常のレビューとコミットのために管理対象ワークツリーに残ります。

適用では、ディスパッチ時のマニフェストをマージベースとして使用します。クラウド側のみの変更は適用され、ローカル側のみの変更はそのまま残り、両側で変更されたパスには 3-way のローカル優先ポリシーが使用されます。競合したターンも完了します。トランスクリプトには制限付きのパス概要とステージング済み結果 ref が報告され、配置には Control UI 向けに同じ競合が表示され、競合しないクラウド変更は適用されたままになります。通知には、存在するクラウドファイルを確認するための `git show <ref>:<path>` と、任意のワークスペースディレクトリからそのファイルを取得するためのトップレベルのリテラル pathspec `git checkout <ref> -- <path>` コマンドが含まれます。コマンドは Bash または zsh（Windows では Git Bash）で実行してください。確認時にパスが存在しないと表示された場合、クラウド結果ではそのパスが削除されています。確認のうえ、保持されたローカルパスを手動で削除してください。checkout でファイル/ディレクトリの障害が報告された場合は、妨げになっているローカルパスを移動または削除して再試行してください。ステージング済み ref 自体がなくなっている場合は、通知が古いものとして扱い、ローカルパスを変更しないでください。競合したステージング済み ref は、通常のターンフェンスが解放された後も使用できます。後続の正常な結果によって通知が消去され、古い ref が廃止されます。一方、明示的なフェンスの削除が最終的なクリーンアップ境界となります。

フェンスされた結果がまだ反映中の場合、新しいターンは前のクレームが解放されるまで最大 15 秒待機します。それでも処理中であれば、ターンは「前のクラウドターンのワークスペース結果がまだ反映中です」という対応可能なメッセージとともに失敗し、少し待ってから再試行できます。再起動時には、復旧処理が古いクレームをクリーンアップする前に保留中およびステージング済みの結果を検出し、ローカルへの適用を完了または再試行し、結果を保全してから停止した環境を回収します。サイズ制限された SQLite ロールバックジャーナルにより、すでに受理された変更を再実行することなく、中断されたファイルシステムへの適用を復旧できます。

作業が完了し、実行中のターンがない場合は、セッションメニューを開いて **Stop cloud worker…** を選択します。Gateway は環境を破棄する前に、ワークスペースの最終反映を 1 回実行します。すでに `draining` または `reconciling` になっている配置では終了処理が進行中です。セッションを削除する前に、バッジが `reclaimed` になるまで待ってください。

接続中のワーカーが故障または暴走した場合、オペレーターは最終手段として `{ "force": true }` を指定して `environments.destroy` を呼び出せます。強制終了では、環境を破棄する前に、配置を失敗として永続的に記録し、未反映のリモート結果を破棄します。

同等の管理用 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`）を通じて遷移するため、ディスパッチ中に Gateway が再起動しても、マシンをリークせずに整合処理が行われます。モデルターンが失敗しても、アクティブな配置は再試行に利用できる状態で維持されます。ワークスペースのパス競合が発生した場合はローカル版を維持し、クラウド結果の残りを適用して、検査用にステージ済みクラウド ref を保持します。その他の整合処理またはライフサイクルの失敗では、復旧処理が安全に再試行または環境を回収できるようになるまで、耐久性のある復旧フェンスと診断出力の末尾が保持されます。

## セキュリティモデル

* **閉じたワーカー受信経路。** ワーカーは、メソッドの許可リストが閉じられた専用プロトコルを使用して、トンネル化されたソケット上で通信します。ワーカーがオペレーター RPC を呼び出すことはできません。
* **Gateway が所有するツール権限。** 各ターンの前に、Gateway はワーカーの固定されたコーディングツールカタログに対し、現在のプロファイル、プロバイダー、エージェント、グループ、送信者、サンドボックス、委任、継承、およびランタイム上限のポリシーを適用します。起動エンベロープには、最終的に得られた閉じた語彙のサブセットのみが含まれます。上限が明示的に設定されたスケジュール済みターンは、信頼された所有者グループのコンテキストを再利用し、その ID をボックスに送信したり、新しい送信者オーバーレイを再適用したりしません。ワーカーカタログ外のツールは引き続き使用できません。結果が空の場合はツールなしで実行されます。
* **発行され、保存時にハッシュ化される認証情報。** ディスパッチごとにワーカー認証情報が発行され、Gateway はそのハッシュのみを保存します。認証情報のローテーションと所有者エポックによるフェンシングにより、セッションごとに同時に存在できる有効な所有者は最大 1 つに制限されます。古いワーカーが再接続した場合はフェンシングされ、決してマージされません。
* **ホストキーのピン留め。** プロバイダーはプロビジョニング時にボックスの SSH ホストキーを提示する必要があります。ブートストラップは厳密なピン留めを使用して接続し、ホストキーがない場合は安全側に倒して失敗します。
* **ボックスに常駐するモデル、forge、クラウドの認証情報なし。** モデル認証は Gateway 上に保持され（推論は `{provider, model}` 参照によって転送されます）、ワークスペースの git コミットは forge の認証情報なしで作成されます。また、セットアップ前に Crabbox AWS リースメタデータがインスタンスロールについて信頼できる情報源に照らして確認されます。セットアップコマンドにも認証情報を含めないでください。
* **プロバイダーが所有する外向き通信。** リバーストンネルにより、OpenClaw がモデルへ直接アクセスする必要はなくなりますが、OpenClaw はプロバイダーのファイアウォールを書き換えません。タスクで必要な場合は、ワーカープロバイダーで外向きトラフィックを制限してください。
* **耐久性があり、正確に 1 回だけ記録されるトランスクリプト。** ワーカーはセッションのリーフに対する比較交換プロトコルを通じてトランスクリプトのバッチをコミットします。ベースが古い場合、有料出力を重複またはリベースするのではなく、実行を即座に停止します。

## トラブルシューティング

* **`sessions.dispatch` は不明なメソッドです** — `cloudWorkers.profiles` が設定されていないか、呼び出し元に `operator.admin` がありません。
* **「クラウドワーカーのターンには OpenClaw ランタイムが必要です」** — 設定されたランタイムが OpenClaw であるモデルを選択してください。`claude-cli` などの外部 CLI ランタイムは、ワーカー推論をサポートしていません。
* **「ワーカーのブートストラップには、リースされたホスト上の Node.js が必要です」** — `settings.setup` に Node のインストールを追加してください（上記参照）。
* **AWS インスタンスロールの証明に失敗する** — `aws.instanceProfile`（設定されている場合は `CRABBOX_AWS_INSTANCE_PROFILE` も）をクリアしてください。Crabbox 0.38.1 以降をインストールしてください。古いバイナリは、AWS の受け入れに必要な信頼できる `providerMetadata.instanceProfileAttached` コントラクトを公開しません。
* **プロバイダーエラーによりディスパッチが失敗する** — 配置レコードと `environments.list` には、セットアップ／ブートストラップの標準エラー出力末尾を含む最後のエラーが保持されます。失敗時にはボックスが破棄されるため、この末尾が主要なフォレンジック情報となります。
* **ディスパッチ中のクライアントタイムアウト** — `openclaw gateway call` のデフォルトタイムアウトは 10s です。`--timeout` には十分に余裕のある値を渡してください（どちらの場合でもディスパッチはサーバー側で実行を継続し、プロビジョニング中の再試行は `session cannot dispatch from placement provisioning` により拒否されます）。
* **2026.7.2 ベータからのアップグレード後にワーカーが回収される** — これらのベータ版では、以前のワーカー起動コントラクトが使用されていました。再起動時に OpenClaw は、アイドル状態の互換性のないワーカーを破棄し、セッションとワークスペースを維持したまま配置を回収済みとしてマークし、次のディスパッチまたはターンで現行のワーカーをプロビジョニングします。起動中に中断されたベータ版ワーカーは、クリーンアップ後に失敗としてマークされます。ディスパッチを再試行し、現行のコントラクトでプロビジョニングしてください。
* **クラウドワークスペースの競合通知** — ターンは完了しており、一覧に記載された各パスのローカル版が維持されています。通知に記載されたステージ済み ref のコマンドを使用して、クラウド版を検査または取得してください。競合していない変更はすでに適用されているため、再試行は不要です。
* **「前回のクラウドターンのワークスペース結果は、まだ整合処理中です」** — Gateway は前回の結果の耐久性のあるフェンスを短時間待機しましたが、セッションのクレームを取得できませんでした。整合処理が完了するまで待ってから、ターンを再試行してください。復旧処理では停止したワーカーを回収する前にステージ済みの結果が保持されるため、Gateway を再起動しても安全です。
* **リースの保守管理** — `crabbox list --provider <backend>` は稼働中のリースを表示し、`crabbox stop --provider <backend> --id <lease>` はリースを手動で解放します。アイドル状態のリースは、プロファイルの `idleTimeout` に基づいて期限切れになります。

## 関連項目

* [サンドボックス化](/ja-JP/gateway/sandboxing) — ローカルでのツール実行による影響範囲の縮小
* [セッション CLI](/ja-JP/cli/sessions) — 保存されたセッションの検査
* [設定リファレンス](/ja-JP/gateway/configuration-reference)