設定と運用
ゲートウェイロック
最終更新日: 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>")をスローします。 - クラッシュやSIGKILLを含むプロセス終了時には、OSがリスナーを自動的に解放します。別個のロックファイルやクリーンアップ手順は不要です。
- シャットダウン時、ゲートウェイは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バインドによって強制されます。