Gatewayロック

最終更新日：2025-12-11

目的

• 同一ホストのベースポートごとに1つのゲートウェイインスタンスのみが実行されることを保証。追加のゲートウェイは分離されたプロファイルと一意のポートを使用する必要があります。
• クラッシュ/SIGKILLを生き延びても古いロックファイルが残らない。
• コントロールポートが既に使用されている場合、明確なエラーで即座に失敗。

メカニズム

• ゲートウェイは起動時に排他的TCPリスナーを使用してWebSocketリスナー（デフォルトws://127.0.0.1:18789）を即座にバインドします。
• バインドがEADDRINUSEで失敗した場合、起動はGatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")をスローします。
• OSはクラッシュやSIGKILLを含むあらゆるプロセス終了時にリスナーを自動的に解放します。個別のロックファイルやクリーンアップ手順は不要です。
• シャットダウン時、ゲートウェイは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アプリはゲートウェイを起動する前に独自の軽量PIDガードを維持しています。ランタイムロックはWebSocketバインドによって強制されます。