クラスター環境とノード準備
複数ノードで同一 OS・同一 Xcode バージョンを揃え、内網から相互に SSH できるようにします。手順は次のとおりです。
- ノードの選定：MeshMac で複数 Mac（例：Mac mini M4）をレンタルし、OS と Xcode を統一する。
- ネットワーク：全ノードが低遅延で通信できる内網（推奨 10Gbps）を確保する。
- SSH 有効化：システム環境設定 → 共有 → リモートログインを有効にし、必要に応じて鍵認証を設定する。
- State Server ノードの決定：状態同期用に 1 台を「State Server 用」に決め、そのノードの IP と gRPC ポートをメモする。
名前解決は /etc/hosts または DNS で統一し、ノード間でホスト名で相互アクセスできるようにしておくと運用が楽です。
各ノードのインストールと統一設定
全ノードに同一バージョンの OpenClawをインストールし、設定を揃えます。
- 各ノードに OpenClaw を同一バージョンでインストールする（公式手順に従う）。
- State Server 用ノードで State Server を起動する。例：
openclaw state-server --port 50051 - 他ノードのエージェント用に、State Server のアドレスとポートを記載した同一の YAML プロファイルを用意する。
- その YAML を全ノードの同じパスに配布する（Ansible・scp・共有ストレージなどで一括配布可）。
YAML 内の state_server のホスト・ポートが全ノードで同じであることを確認してください。設定の差があると状態が正しく同期されません。
多ユーザー権限隔離
複数メンバーが同一ノードやクラスターを共有する場合、ユーザーごとの作業ディレクトリと権限を分離し、ビルドの競合や誤操作を防ぎます。
- ユーザー別ディレクトリ：例
/Users/build/user_aと/Users/build/user_bを用意し、各ユーザーは自分のディレクトリのみ書き込み可能にする。 - SSH 鍵とグループ：メンバーごとに SSH 鍵を発行し、グループで書き込み範囲を制限する。
- OpenClaw の実行ユーザー：エージェントをどの Unix ユーザーで動かすかをノードごとに揃え、そのユーザーが上記ディレクトリにのみアクセスするようにする。
共有ビルド機での権限設計の詳細はリモート Mac FAQ（権限隔離）を参照してください。
故障転送と高可用性設定
State Server にタスク・状態を集約することで、1 台が落ちても他ノードがタスクを引き継ぐ構成にできます。
- State Server の起動確認：State Server 用ノードでプロセスが起動していること、gRPC ポートが開放されていることを確認する。
- 全エージェントの接続：各ノードの OpenClaw エージェントが State Server に gRPC で接続していることをログで確認する。
- 引き継ぎテスト：1 ノードでタスクを投入したあと、そのノードを停止し、別ノードで同じタスクキュー・状態が参照・継続できることを検証する。
ファイアウォールで gRPC 用ポート（例 50051）をクラスター内に開放し、他ノードから State Server へ確実に到達できるようにしてください。
よくあるエラーとトラブルシューティング
- 接続拒否（Connection refused）：State Server が起動しているか、ポートが正しいか、ファイアウォールで許可されているかを確認する。
- タイムアウト：ノード間の
ping・tracerouteで到達性を確認し、gRPC ポートが開いているかnc -zv <host> <port>で確認する。 - 状態が同期しない：全ノードの YAML が同一か、State Server への接続が成功しているかをログで確認する。gRPC のエラーが出ていないかも確認する。
- 権限エラー（Permission denied）：エージェントの実行ユーザーと、作業ディレクトリの所有者・パーミッションを確認する。