Gateway ロック

最終更新: 2025-12-11

理由

• 同一ホスト上の基本ポートごとに1つのGatewayインスタンスのみが実行されることを保証します。追加のGatewayは隔離されたプロファイルと一意のポートを使用する必要があります。
• 古いロックファイルを残さずにクラッシュ/SIGKILLに耐えます。
• 制御ポートがすでに占有されている場合、明確なエラーで高速に失敗します。

メカニズム

• Gatewayは起動時にWebSocketリスナー(デフォルト ws://127.0.0.1:18789)を排他的TCPリスナーを使用して即座にバインドします。
• バインドが EADDRINUSE で失敗した場合、起動時に GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>") をスローします。
• OSはクラッシュやSIGKILLを含むプロセス終了時にリスナーを自動的に解放します。別のロックファイルやクリーンアップステップは不要です。
• シャットダウン時、GatewayはWebSocketサーバーと基盤のHTTPサーバーを閉じて、ポートを速やかに解放します。

エラーサーフェス

• 別のプロセスがポートを保持している場合、起動時に GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>") をスローします。
• 他のバインド失敗は GatewayLockError("failed to bind gateway socket on ws://127.0.0.1:<port>: …") として表面化します。

運用上の注意事項

• ポートが別のプロセスによって占有されている場合、エラーは同じです。ポートを解放するか、openclaw gateway --port <port> で別のポートを選択してください。
• macOSアプリは、Gatewayを起動する前に独自の軽量なPIDガードを維持していますが、ランタイムロックはWebSocketバインドによって強制されます。