クラウドワーカー

​

どこで何が実行されるか

​

要件

• ワーカープロバイダー Plugin。同梱の crabbox Plugin は、クラウドバックエンド（AWS、Hetzner など）間のリースを仲介する 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 で作成）。ディスパッチではそのワークツリーの内容が移動されます。通常のディレクトリはマニフェストミラーとして同期されます。

​

設定

{
  "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)"
        }
      }
    }
  }
}

​

セットアップコマンド

​

インストールチャネル

• bundle は、実行中の Gateway の dist、不要部分を除いた package.json、およびビルドが参照するすべてのワークスペースパッケージをパックし、全体をコンテンツハッシュで保護します。ボックスはそのハッシュに対して未変更のバンドルを検証した後、本番用 npm 依存関係をインストールします（スクリプトは無効）。これは、ワーカー上で開発ビルドを実行する方法です。
• npm は、リリースが公開レジストリに存在することを証明し、その SHA-512 整合性を固定して、Gateway と完全に一致する openclaw@<version> をインストールします。

​

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

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"}'

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

​

セキュリティモデル

• 閉じたワーカー受信経路。 ワーカーは、メソッドの許可リストが閉じられた専用プロトコルを使用して、トンネル化されたソケット上で通信します。ワーカーがオペレーター 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 に基づいて期限切れになります。

​

関連項目

• サンドボックス化 — ローカルでのツール実行による影響範囲の縮小
• セッション CLI — 保存されたセッションの検査
• 設定リファレンス