OpenClaw EADDRINUSEエラー完全解決2026:ポート18789が起動できない全パターン対処法
🚨 このエラーメッセージが出ていますか?
Error: listen EADDRINUSE: address already in use 127.0.0.1:18789
at Server.setupListenHandle [as _listen2] (node:net:xxx)
Gateway failed to start: port 18789 is already in use
OpenClawのGatewayが使用するポート18789が他のプロセスに占有されているために発生するこのエラーは、起動・再起動時に最も頻繁に遭遇するトラブルの一つです。原因はゾンビプロセス、多重起動、他アプリの競合など様々で、このガイドで全パターンを解決します。
目次
- EADDRINUSEエラーとは何か?ポート18789の役割
- ポート18789を占有しているプロセスを特定する
- 【即効】ゾンビプロセスを強制終了する方法
- OpenClawの多重起動を防ぐ方法
- Macスリープ・再起動後のGateway復帰失敗
- 他アプリがポート18789を使っている場合の対処
- ポートを変更してGatewayを別ポートで起動する
- LaunchAgent設定の修正でゾンビを防ぐ
- Windows・Linux環境でのEADDRINUSE対処法
- VPN環境でのポート競合の追加パターン
EADDRINUSEエラーとは?ポート18789の役割
EADDRINUSEは "Error: Address Already In Use"(アドレスがすでに使用中)の略です。TCPポートはOSが管理するリソースであり、1つのポート番号には1つのプロセスしかバインドできません。OpenClaw Gatewayはデフォルトでポート18789を使用してローカルサーバーを立ち上げますが、このポートがすでに別のプロセスに使われている場合に起動に失敗します。
🔧 ポート18789の役割
何のためのポート?
- OpenClaw CLI↔Gatewayの内部通信
- ブラウザ拡張↔Gatewayの接続
- health checkのHTTPエンドポイント
- WebSocket接続のリスニング
なぜ18789番?
- 一般的なウェルノウンポート範囲(0-1023)外
- よく使われる開発ポートと被らない
- OpenClaw専用として設計
- 変更可能(openclaw.jsonで設定)
ポート18789を占有しているプロセスを特定する
EADDRINUSEエラーを解決する最初のステップは、ポート18789を占有しているプロセスを特定することです。OS別のコマンドを紹介します。
macOSでポート占有プロセスを確認
# 方法1:lsofコマンド(最も詳細) lsof -i :18789 # 出力例: # COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME # node 12847 user 20u IPv4 54321 0t0 TCP localhost:18789 (LISTEN) # 方法2:netstatコマンド netstat -anv | grep 18789 # 方法3:ssコマンド(macOS Ventura以降) ss -tlnp | grep 18789 # PIDだけ素早く取得したい場合 lsof -ti :18789
Windowsでポート占有プロセスを確認
# コマンドプロンプト(管理者) netstat -ano | findstr :18789 # 出力例: # TCP 127.0.0.1:18789 0.0.0.0:0 LISTENING 12847 # PIDからプロセス名を特定 tasklist | findstr "12847" # 出力例: node.exe 12847 Console 1 45,568 K # PowerShellでより詳細に確認 Get-NetTCPConnection -LocalPort 18789 | Select-Object OwningProcess Get-Process -Id (Get-NetTCPConnection -LocalPort 18789).OwningProcess
Linuxでポート占有プロセスを確認
# ss コマンド(推奨) ss -tlnp | grep 18789 # lsofコマンド lsof -i :18789 # fuser コマンド(PIDを直接取得) fuser 18789/tcp # より詳細な情報 cat /proc/$(fuser 18789/tcp 2>/dev/null)/cmdline | xargs -0 echo
【即効】ゾンビプロセスを強制終了する方法
ポート18789を占有しているプロセスが前回起動したOpenClaw Gateway(ゾンビプロセス)であることが最も多いパターンです。以下のコマンドで強制終了できます。
macOS:ゾンビプロセスの強制終了(3段階)
# 段階1:openclaw専用の停止コマンド(推奨) openclaw gateway --stop # 段階2:PIDを特定して強制終了 kill -9 $(lsof -ti :18789) # 段階3:プロセス名で全て終了(最終手段) pkill -9 -f "openclaw" pkill -9 -f "openclaw-gateway" # 終了確認 lsof -i :18789 # 何も表示されなければOK echo $? # 0以外ならまだ残っている
Windows:ゾンビプロセスの強制終了
# PowerShell(管理者) # PIDを特定 $pid = (Get-NetTCPConnection -LocalPort 18789).OwningProcess # 強制終了 Stop-Process -Id $pid -Force # または taskkillコマンド netstat -ano | findstr :18789 # PIDが12847の場合 taskkill /PID 12847 /F # openclaw.exeをプロセス名で全終了 taskkill /IM "openclaw-gateway.exe" /F taskkill /IM "node.exe" /F # ※Node.jsの他のプロセスも終了するので注意
OpenClawの多重起動を防ぐ方法
EADDRINUSEエラーの最もよくある原因は、OpenClawを複数回起動してしまうことです。特にMacのログイン時にLaunchAgentで自動起動する設定をしている場合、手動でも起動すると多重起動になります。
❌ 多重起動を引き起こすパターン
- LaunchAgent自動起動 + 手動でopenclaw startを実行
- Terminal.app + iTerm2の両方でopenclaw startを実行
- openclaw updateが失敗して旧プロセスが残存
- macOS再起動後にLaunchAgentが2回起動
- スクリプトの誤った実装でループ起動
✅ 多重起動の防止策
- LaunchAgentを使うなら手動起動は一切しない
- 起動前に
lsof -i :18789で確認 - openclaw.jsonに
singleInstance: trueを設定 - PIDファイルを使って多重起動を検出
- 起動スクリプトに既存プロセス確認を追加
#!/bin/bash
# /usr/local/bin/openclaw-safe-start.sh
PORT=18789
PID_FILE="/tmp/openclaw-gateway.pid"
# 既存プロセスの確認
if lsof -ti :$PORT > /dev/null 2>&1; then
EXISTING_PID=$(lsof -ti :$PORT)
echo "⚠️ ポート $PORT はすでに PID $EXISTING_PID に使用されています"
echo "既存のOpenClaw Gatewayかどうか確認中..."
if ps -p $EXISTING_PID -o comm= | grep -q "node\|openclaw"; then
echo "✅ 既存のOpenClaw Gatewayが動作しています。起動をスキップします。"
exit 0
else
echo "❌ 他のプロセスがポートを占有しています"
echo "プロセス情報: $(ps -p $EXISTING_PID -o comm=)"
exit 1
fi
fi
# プロセスが存在しない場合は起動
echo "🚀 OpenClaw Gatewayを起動します..."
openclaw gateway --start
echo $! > $PID_FILE
echo "✅ 起動完了(PID: $(cat $PID_FILE))"
Macスリープ・再起動後のGateway復帰失敗
MacがスリープからWakeした時にOpenClaw Gatewayが正常に再接続できずゾンビ化するパターンは特に多く報告されています。macOS Sonomaおよびsequoiaではさらにこの問題が頻発します。
#!/bin/bash
# /usr/local/bin/openclaw-wake-handler.sh
# このスクリプトをスリープ復帰時に自動実行
# 復帰後10秒待機(Networkが安定するまで)
sleep 10
# ポート18789の状態確認
if lsof -ti :18789 > /dev/null 2>&1; then
# ゾンビプロセスを終了
ZOMBIE_PID=$(lsof -ti :18789)
# openclaw関連か確認
if ps -p $ZOMBIE_PID -o args= | grep -q "openclaw"; then
echo "$(date): ゾンビ化したGateway(PID:$ZOMBIE_PID)を終了中..."
kill -9 $ZOMBIE_PID
sleep 2
fi
fi
# Gatewayを再起動
echo "$(date): OpenClaw Gatewayを再起動..."
launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist 2>/dev/null
sleep 1
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist
# 起動確認
sleep 5
if lsof -i :18789 > /dev/null 2>&1; then
echo "$(date): Gateway再起動成功"
else
echo "$(date): Gateway再起動失敗 - 手動確認が必要"
fi
他アプリがポート18789を使っている場合の対処
OpenClaw Gateway以外のアプリケーションがポート18789を使用している場合、単純にゾンビを終了するだけでは解決しません。どのアプリが競合しているかを特定して対処する必要があります。
🐍 Python開発サーバー
Flask・FastAPIのデフォルトが5000・8000だが、カスタム設定で18789を使うことがある
lsof -i :18789 | grep python
⚡ Vite・Node開発
ViteやNode.js開発ツールが自動でポートを選ぶ際に18789を選択する場合がある
lsof -i :18789 | grep node
🐳 Dockerコンテナ
Dockerのポートフォワードでホスト側18789が使われる場合がある
docker ps --format "{{.Ports}}" | grep 18789
ポートを変更してGatewayを別ポートで起動する
競合するアプリが常時使用するポートとOpenClawが衝突する場合、OpenClawのポートを別の番号に変更するのが根本的な解決策です。
# ~/.openclaw/openclaw.json を編集
{
"gateway": {
"port": 18790, // デフォルト18789から変更
"host": "127.0.0.1", // localhostのみリッスン(セキュリティ)
"fallbackPorts": [18791, 18792, 18793] // フォールバックポート候補
}
}
# ポート変更後にGatewayを再起動
openclaw gateway --restart
# 新しいポートで動作確認
lsof -i :18790
# openclaw doctorでも確認
openclaw doctor --check gateway
⚠️ ポート変更時の注意点
- ブラウザ拡張のOpenClaw設定でもポート番号を変更する必要あり
- LaunchAgent(macOS)やWindowsサービスの設定も更新が必要
- fallbackPortsを設定しておくと次回衝突時に自動で代替ポートを使用
- 1024〜49151の範囲でよく使われないポートを選ぶ推奨
LaunchAgent設定の修正でゾンビを根本的に防ぐ
macOSのLaunchAgent設定を適切に行うことで、ゾンビプロセスの発生を根本的に防げます。特にKeepAliveとThrottleIntervalの設定が重要です。
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.openclaw.gateway</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/openclaw</string>
<string>gateway</string>
<string>--start</string>
</array>
<!-- ゾンビ防止の重要設定 -->
<key>KeepAlive</key>
<dict>
<key>SuccessfulExit</key>
<false/> <!-- 正常終了時は再起動しない -->
</dict>
<key>ThrottleInterval</key>
<integer>30</integer> <!-- 30秒以内の再起動を防ぐ -->
<key>RunAtLoad</key>
<true/> <!-- ログイン時に自動起動 -->
<key>StandardOutPath</key>
<string>/tmp/openclaw-gateway.log</string>
<key>StandardErrorPath</key>
<string>/tmp/openclaw-gateway-error.log</string>
</dict>
</plist>
Windows・Linux環境でのEADDRINUSE対処法
Windows:PowerShellで完全対処
# PowerShell管理者権限で実行
# ポート18789を使用するプロセスを特定して終了
$connection = Get-NetTCPConnection -LocalPort 18789 -ErrorAction SilentlyContinue
if ($connection) {
$pid = $connection.OwningProcess
$process = Get-Process -Id $pid -ErrorAction SilentlyContinue
Write-Host "占有プロセス: $($process.Name) (PID: $pid)"
Stop-Process -Id $pid -Force
Write-Host "プロセス終了完了"
} else {
Write-Host "ポート18789は使用されていません"
}
# OpenClaw Gatewayサービスを再起動
Restart-Service -Name "OpenClawGateway" -Force
Get-Service -Name "OpenClawGateway" # 確認
Linux:systemdサービスで管理
# ポートを占有しているプロセスを終了 sudo fuser -k 18789/tcp # OpenClaw systemdサービスを再起動 sudo systemctl restart openclaw-gateway # サービスの状態確認 sudo systemctl status openclaw-gateway # journalでログ確認 sudo journalctl -u openclaw-gateway -n 50 --no-pager
VPN環境でのポート競合の追加パターン
VPNを使用している環境では、VPNクライアント自体がポートを使う場合や、VPNの仮想NIC上でポートバインドが競合するケースが追加で発生します。
💡 VPN環境特有の競合パターンと対処法
- VPN接続・切断時のIPアドレス変更:OpenClaw GatewayがバインドしているIPが変わり、既存のソケットが無効化→ゾンビ化。対処:openclaw.jsonで
host: 0.0.0.0に変更してすべてのインターフェースでリッスン - Killswitchが内部通信もブロック:一部のVPNのKillswitchがlocalhostの通信までブロックして18789へのアクセスを遮断。対処:VPN Killswitchのローカル通信除外設定を確認
- VPN再接続時の多重起動:VPNの再接続フックでOpenClawが再起動され二重起動になる。対処:前述の安全起動スクリプトを使用
VPN07 - ポート競合を起こさないVPN
VPN07はローカルポートへの干渉が最小限の設計。Killswitch使用時もlocalhost通信を自動除外し、OpenClawのポート18789競合を引き起こしません。1000Mbps千兆回線で10年の安定実績。
よくある質問
Q:kill -9でプロセスを終了しても、すぐに18789エラーが再発します。なぜですか?
A:LaunchAgent(macOS)またはWindowsサービスがプロセスを自動再起動しているためです。KeepaliveやRestart設定が有効な場合、プロセスを終了しても即座に再起動されます。launchctl unloadまたはStop-Serviceでサービス自体を停止してからプロセスを終了してください。
Q:openclaw doctor --fixを実行してもEADDRINUSEが解決されません。
A:doctor --fixはポート競合の「部分修復」のみ対応しています。競合プロセスがOpenClaw自身のゾンビの場合は自動終了を試みますが、他アプリとの競合や権限不足の場合は手動対処が必要です。lsof -i :18789でプロセスを特定して手動終了してください。
Q:毎回Macを起動するたびにEADDRINUSEエラーが出ます。永続的な解決策はありますか?
A:LaunchAgentのThrottleIntervalを適切に設定し、安全起動スクリプトをRunAtLoadに設定することで恒久的に解決できます。本記事のセクション8で紹介したplist設定を適用してください。また、openclaw.jsonのgateway.fallbackPortsを設定すると、18789が使えない場合に自動で代替ポートを使用します。
📌 EADDRINUSEエラー解決の優先順位
- まず確認:
lsof -i :18789で何が占有しているか確認 - ゾンビなら:
kill -9 $(lsof -ti :18789)で即座に終了 - 他アプリなら:そのアプリを終了するか、OpenClawのポートを変更
- 多重起動なら:安全起動スクリプトを導入
- 再発防止に:LaunchAgentのThrottleIntervalとfallbackPortsを設定
VPN07でOpenClawを安定起動
ポート競合を起こさない設計の1000Mbps VPN
OpenClawのEADDRINUSEエラーに悩まされるなら、ローカルポートへの干渉を最小限に設計されたVPN07が最適です。1000Mbps千兆回線と70か国以上の拠点で安定稼働。月額$1.5・30日間返金保証付き。