openclaw 実行ファイルを監督し、Gateway WebSocket プロトコルを制御プレーンとして使用し、子プロセスを交換可能なランタイムとして扱う必要があります。これにより、OpenClaw の非公開の状態レイアウトに依存せず、プロセスの所有権、準備完了状態、障害復旧、アップグレードを明示的に管理できます。
クライアント認証と再接続状態については、
Gateway クライアントの構築を参照してください。
埋め込みプリセットで子プロセスを起動する
実際のnode_modules インストールを使用し、パッケージの実行ファイルを起動します。検出、再起動、チャネルのライフサイクルを所有するホストには、次の構成が有用なベースラインとなります。
openclaw バイナリがホストプロセスの PATH に存在すると想定しないでください。この例では出力を継承するため、stdout または stderr のパイプが満杯になって子プロセスがブロックすることはありません。代わりにホストがこれらのストリームをキャプチャする場合は、起動直後にコンシューマーを接続してください。
--allow-unconfigured がバイパスするのは gateway.mode=local 起動ガードだけです。設定の書き込みや無効なファイルの修復は行いません。埋め込みアプリがオンボーディング、設定 CLI、または Gateway RPC を通じて通常のローカル設定をプロビジョニングする場合は、省略してください。
Electron のシェルスナップショットに関する警告
シェルスナップショットの取得では、ログインシェルからprocess.execPath -e <script> を実行します。通常の Node プロセスでは、process.execPath は Node 実行ファイルです。Electron 環境では Electron バイナリとなり、この呼び出しをアプリケーションの起動として解釈して「Unable to find Electron app」というポップアップを表示する場合があります。OPENCLAW_EXEC_SHELL_SNAPSHOT=0 はレンダラープロセスだけでなく、Gateway 子プロセスの環境にも設定してください。同じ理由から、hostNodeExecutable は Electron の process.execPath ではなく、実際の Node ランタイムを指す必要があります。
終了コードで無効な設定を処理する
Gateway の起動では、無効な設定を含む設定関連の起動エラーに終了コード78(EX_CONFIG)を使用します。人間向けの stderr を解析するのではなく、終了コードで分岐してください。
- Gateway 子プロセスと同じ設定および状態環境に対して
openclaw doctor --fix --yes --non-interactiveを実行します。 - doctor が正常終了した後、Gateway の起動を 1 回再試行します。
- 子プロセスが再び
78で終了した場合は、修復ループを停止し、設定エラーをユーザーに提示します。
プロトコルの準備完了を待つ
ログの部分文字列ではなく、WebSocket シグナルを使用します。- Gateway WebSocket を開きます。
connect.challengeイベントを待ちます。これは、リスナーが WebSocket を受け入れ、チャレンジハンドシェイクを開始できることを示します。- チャレンジに紐づけられたデバイス署名を付けて
connectを送信します。 - 認証済み RPC におけるアプリケーションの準備完了状態として
hello-okを扱います。
connect は details.reason: "startup-sidecars" と、上限のある retryAfterMs を含む再試行可能な UNAVAILABLE エラーを返し、その後コード 1013、理由 gateway starting で接続を閉じます。@openclaw/gateway-protocol/startup-unavailable の resolveGatewayStartupRetryAfterMs またはリファレンスクライアントに組み込まれたポリシーを使用してから、再接続してください。
再起動とシャットダウンを解釈する
正常に接続を閉じる前に、Gateway はreason と restartExpectedMs を含む shutdown イベントをブロードキャストします。null ではない restartExpectedMs は、プロセス内または監督下での再起動が予定されていることを意味します。null は最終的なシャットダウンを意味します。
その後の WebSocket 終了コードは、どちらの場合も 1012 です。通常のクライアント終了理由も、どちらの場合も service restart であるため、終了コードと理由のどちらでも再起動とシャットダウンを区別できません。先行する shutdown ペイロードを受信した場合は保持し、ホスト自身の停止意図および子プロセスの終了ステータスと組み合わせて判断してください。イベントなしで接続が消失した場合は、通常の上限付き再接続および子プロセス監督ポリシーを使用してください。
状態ファイルではなく RPC を使用する
OpenClaw の状態は Gateway だけが所有するようにしてください。一般的な埋め込み操作には、すでに RPC メソッドが用意されています。config.get は、スナップショットを返す前に機密値と SecretRef 識別子を秘匿化します。書き込みメソッドも秘匿化された設定を返します。クライアントは秘匿化センチネルを不透明な値として扱い、文書化された設定書き込み契約を使用する必要があります。Gateway が平文のシークレットを返すことを決して期待してはいけません。
アプリ機能を実装するために、~/.openclaw 配下のファイル、SQLite テーブル、トランスクリプトファイル、キャッシュディレクトリを読み取ったり変更したりしないでください。これらのレイアウトは非公開のランタイム実装詳細であり、プロトコル互換性を維持したまま移動または変更される可能性があります。
フラット化せずにインストールする
ルートのopenclaw パッケージは、単一ファイルとしてベンダー化するためのものではありません。dist/extensions 配下のバンドル済みランタイムファイルには、openclaw/plugin-sdk/* のようなベアな自己インポートが残っている一方、npm パッケージは拡張機能ごとの node_modules ツリーを意図的に除外しています。
Node がパッケージの exports とルート依存関係ツリーを解決できるように、npm、pnpm、またはその他の通常の Node パッケージインストール方法で OpenClaw をインストールしてください。インストール済みの openclaw 実行ファイルを起動します。dist だけをコピーしたり、パッケージをアプリバンドルへフラット化したり、選択した拡張機能ファイルをベンダー化したりしないでください。