OpenClawのゲートウェイ起動エラーを解決：ポート競合の回避策

開発中に「プロセスが二重に起動してしまった」「クラッシュした後に残ったロックファイルのせいで再起動できない」といった問題に直面したことはありませんか？こうしたトラブルは、開発の効率を下げ、運用の安定性を損なう原因になります。

Gatewayでは、こうした事態を防ぎ、常にクリーンな状態で動作するように設計されたロック機構を採用しています。

なぜ必要なのか

• 同一ホスト上で、1つのポートに対して起動できるGatewayインスタンスを1つだけに制限するためです。追加で起動する場合は、個別のプロファイルとユニークなポートを使用する必要があります。
• クラッシュやSIGKILLが発生しても、古いロックファイルに悩まされることなく、迅速な再起動とエラー特定を可能にします。

仕組み

• Gatewayは起動時に、排他的な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が自動的にリスナーを解放します。そのため、個別のロックファイルやクリーンアップの手順は不要です。
• シャットダウン時には、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のバインドによって強制されます。

関連情報

• Multiple Gateways — ユニークなポートを使用して複数のインスタンスを実行する方法
• Troubleshooting — EADDRINUSE やポート競合の診断方法

次のステップ

• Multiple Gateways
• Troubleshooting

AI Setup Assistant