---
read_when: You want agent sessions to run on ephemeral cloud machines instead of the Gateway host, or you are configuring cloudWorkers profiles.
sidebarTitle: Cloud Workers
status: active
summary: 使い捨てのクラウドマシンにセッションをディスパッチ：プロビジョニング、ワーカーランタイム、プロキシ経由の推論、結果のストリーミング
title: クラウドワーカー
x-i18n:
    generated_at: "2026-07-16T11:34:17Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: c20b3b4f1408ed3ef0beb155a207f99476323cf67eba7b44931eec32c79e52be
    source_path: gateway/cloud-workers.md
    workflow: 16
---

クラウドワーカーを使用すると、セッションに関するすべてを従来どおりの場所に維持したまま、使い捨てのクラウドマシン上でセッションのエージェントループを実行できます。セッションはサイドバーに表示され、ライブストリーミングされ、トランスクリプトは 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
{
  "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 で **新しいセッション** を開き、設定済みランタイムが OpenClaw であるエージェントを選択し、**場所**メニューから設定済みの **クラウド · プロファイル** ターゲットを選択して、タスクを開始します。クラウドを選択すると、必要な管理対象ワークツリーが自動的に有効になります。Gateway はセッションを作成してディスパッチを完了し、その後にのみ最初のターンを送信します。セッションのサイドバーにあるサーバーバッジには、永続的な配置状態が表示されます。外部 CLI セッションカタログではクラウドターゲットを選択できません。

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

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

クラウドワーカーは OpenClaw エージェントランタイムを実行します。そのランタイムに解決される `openai/*` または別のモデルを選択してください。`claude-cli` などの外部 CLI ランタイム用に設定されたセッションはディスパッチできません。

```bash
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 の再起動からの復旧時には、古いターンのクリーンアップによって所有者が破棄される前に、リモートワークスペースが取得されます。反映処理ではワーカーのマニフェストを認証し、どちらかを上書きするのではなく、ローカルで差異がある場合に停止します。ファイルを変更する前に、Gateway はサイズ制限付きのロールバックジャーナルを SQLite 状態データベースに保存します。Gateway プロセスが中断された後の再試行では、そのジャーナルを使用して復旧します。ワークスペースの結果には Git のファイルセマンティクスが適用されます。通常ファイル、実行可能ビット、シンボリックリンク、追加、変更、削除は保持されますが、空のディレクトリやその他のディレクトリモードは保持されません。リモートのコミットオブジェクトは保持されません。生成されたファイル変更は、通常のレビューとコミットのために管理対象ワークツリーに残ります。

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

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

同等の管理用 RPC は次のとおりです。

```bash
openclaw gateway call sessions.reclaim \
  --timeout 600000 \
  --params '{"key":"agent:main:big-refactor"}'
```

配置は永続的なステートマシン（`local → requested → provisioning → syncing → starting → active`）を通じて遷移するため、ディスパッチ中に Gateway が再起動しても、マシンを放置するのではなく整合処理が行われます。モデルターンが失敗しても、アクティブな配置は再試行のために維持されます。受信ワークスペースの反映に失敗した場合もワーカーはアクティブなまま維持されるため、オペレーターはリモート結果を失うことなくローカル競合を解決して再試行できます。一方、ライフサイクル障害では配置がエラーまたは回収済み状態に移行し、診断ログ末尾が保持されます。

## セキュリティモデル

- **ワーカーへの受信接続を閉鎖。** ワーカーは、許可されたメソッドが限定された専用プロトコルを使用してトンネルソケット上で通信します。ワーカーがオペレーター RPC を呼び出すことはできません。
- **発行された認証情報をハッシュ化して保存。** ディスパッチごとにワーカー認証情報が発行され、Gateway はそのハッシュのみを保存します。認証情報のローテーションと所有者エポックによるフェンシングにより、セッションごとに有効な所有者が最大1つであることが保証されます。古いワーカーが再接続しても、マージされることはなく、フェンスされます。
- **ホストキーの固定。** プロバイダーは、プロビジョニング時にボックスの SSH ホストキーを提示する必要があります。ブートストラップは厳密な固定を使用して接続し、キーがなければフェイルクローズします。
- **ボックスにはモデル、フォージ、クラウドの常設認証情報を配置しない。** モデル認証は Gateway に残り（推論は `{provider, model}` 参照を通じて転送）、ワークスペースの Git コミットはフォージ認証情報なしで作成されます。また、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` で拒否されます）。
- **リースの管理** — `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)