Gateway Lock（ロック）

Last updated: 2025-12-11

• 同一ホスト上の同一ベースポートでは Gateway を 1 つだけ動かせるようにします。追加の Gateway は分離された profile とユニークなポートが必要です。
• クラッシュ/SIGKILL でも古いロックファイルを残しません。
• 制御ポートが占有されている場合に、明確なエラーで即座に失敗します。

• Gateway は起動直後に排他的な TCP リスナーで WebSocket リスナーをバインドします（デフォルト ws://127.0.0.1:18789）。
• バインドが <code>EADDRINUSE</code> で失敗すると、起動時に <code>GatewayLockError("another gateway instance is already listening on ws://127.0.0.1:<port>")</code> を投げます。
• OS はプロセス終了時に（クラッシュや SIGKILL を含め）リスナーを自動解放します。別途ロックファイルやクリーンアップは不要です。
• 終了時は WebSocket サーバーと下層の HTTP サーバーを閉じ、ポートを即時解放します。

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

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