OpenClaw Gateway 障害の9割を解決：ポート競合と doctor 診断実践 というテーマで、現場で効く復旧順序を整理します。EADDRINUSE、another gateway instance is already listening、そして「Runtime: running なのに UI に入れない」。Nuvcloud の運用相談をまとめると、Gateway 異常の約9割は ポート競合・supervisor 設定ずれ・auth/bind 不整合 の3系統で説明できます。再インストールより、まず診断の順序を固定する方が圧倒的に早いです。
この記事は「導入」ではなく「復旧」専用です。OpenClaw をまだデプロイしていない場合は 導入実践ガイド を先に確認してください。OpenHuman との役割分担は OpenHuman 運用記事 に分けています。公式ドキュメントは Gateway runbook と Gateway troubleshooting が基準です。
1）まず切り分け：Gateway はどのフェーズで詰まっているか
最初にやることは「再起動連打」ではなく、症状をフェーズに落とすことです。OpenClaw の Gateway は supervisor 管理の常駐プロセスで、CLI 側の probe 結果とは別軸で見えることがあります。ここが噛み合わないと、対処を誤ります。
| フェーズ | よく出る症状 | 最初に打つコマンド |
|---|---|---|
| A. 起動失敗 | gateway start blocked / EADDRINUSE |
openclaw logs --follow → lsof -i :18789 |
| B. プロセスは生存 | Runtime: running だが Listening が空 |
openclaw gateway status --deep |
| C. ポート疎通はOK | UI で unauthorized / WS 401 | openclaw doctor で auth を確認 |
| D. リモート経路問題 | リモート端末では成功、手元ブラウザはタイムアウト | bind と SSH トンネルの組み合わせを確認 |
2）18789 ポート競合：何が実際に listen しているか
デフォルトポートは 18789。解決順序は --port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789 です。衝突時は「他ソフト」より先に「OpenClaw 自己競合（重複起動）」を疑うのが実務的です。
# 1) 18789 の LISTEN を確認 lsof -nP -iTCP:18789 -sTCP:LISTEN # 2) OpenClaw 側の認識と突き合わせ openclaw gateway status --deep # 3) 残留 PID が確定したら（慎重に） kill <PID> openclaw gateway restart
| 対処方針 | 適するケース | 注意点 |
|---|---|---|
| 18789 を維持して解放 | 重複 launchd / 残留 Gateway が原因 | openclaw doctor --fix で supervisor 情報も整合 |
| ポート変更（例: 18790） | 同居プロセスが多く共存が必要 | クライアント URL・トンネル・ブックマークを同時更新 |
| 環境を分離 | 本番と検証の混在で再発する | Runner や用途単位でマシン/プロファイルを分ける |
lsof の実体が openclaw なら、先に「停止 → doctor --fix → 再起動」。いきなり kill -9 連打は、launchd 二重管理を悪化させがちです。3）openclaw doctor を中心に据える
openclaw doctor は、設定妥当性・サービス状態・auth/port 整合を一気に点検するための入口です。まず浅く見て、必要時に --deep / --fix を使う運用が安定します。公式 FAQ もこの順序を推奨しています（OpenClaw FAQ）。
openclaw status openclaw gateway status openclaw doctor openclaw doctor --deep openclaw doctor --fix openclaw gateway restart
| doctor 出力 | 意味 | 次アクション |
|---|---|---|
Gateway service port does not match... |
supervisor が旧ポートを保持 | doctor --fix または gateway install --force |
Gateway start blocked... |
mode 不一致または local 設定破損 | openclaw config set gateway.mode local |
refusing to bind gateway without auth |
非 loopback で有効 token 不足 | openclaw doctor --generate-gateway-token |
System-level ... service detected |
system レベルと user レベルが衝突 | 管理レイヤーを1つに統一 |
4）gateway status --deep で「生存」と「接続可能」を分ける
Runtime: running だけでは不十分です。復旧判断は Probe target / Listening / Last gateway error / Connectivity probe の4点で行います。
openclaw gateway status --json | jq . openclaw logs --follow # 別ターミナルで restart して Last gateway error の変化を確認
「gateway 風サービスが他にもある」という警告が出たら、過去の手動 install 残骸を疑ってください。ここを放置すると、再起動のたびに再発します。
5）auth と bind：起動するのに繋がらない時の本丸
ポート競合がなくても UI が開かない場合、原因は auth と bind の組み合わせであることが多いです。特に loopback 以外へ bind するなら token 前提で考えるべきです。
| bind 設定 | 公開範囲 | 実務での使い方 |
|---|---|---|
loopback |
127.0.0.1 のみ |
SSH ログイン後にローカルで UI を開く |
lan / custom |
LAN または広域 | token 必須 + FW 制御が前提 |
gateway.mode: remote |
クライアントは遠隔 URL 接続 | 役割分離には有効だが遠隔側ポート管理は必要 |
curl -sS http://127.0.0.1:18789/health curl -sS -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \ http://127.0.0.1:18789/health
ssh -N -L 18789:127.0.0.1:18789 user@your-remote-mac # 手元ブラウザで http://127.0.0.1:18789/ を開く
6）リモート Mac 運用で競合が増える理由
クラウド Mac では、VS Code Remote・tmux 前景実行・launchd 常駐が混ざりやすく、結果として自己競合が起こりやすくなります。運用ルールを先に決めるのが再発防止の近道です。
- 常駐は launchd に一本化し、長時間の前景実行を禁止。
gateway.port変更時は必ずdoctor --fix実行。- ログ確認は
openclaw logs --followに集約。 - CI 連携時は Runner 側で 18789 を奪わないように設計（Runner 運用記事）。
リージョン選定で迷う場合は、香港比較記事 Japan vs Hong Kong も参考になります。価格とプランは 料金ページ で確認できます。
7）15分 Runbook：毎回同じ手順で潰す
チームで共通化するなら、次の手順をそのまま貼るのが有効です。ポイントは「同時に3箇所変更しない」ことです。
| 時間 | アクション | 合格条件 |
|---|---|---|
| 0-2分 | openclaw gateway status --deep |
Runtime/Listening/Last error/Probe を記録 |
| 2-5分 | lsof -nP -iTCP:18789 -sTCP:LISTEN |
リスナー PID と実体を確定 |
| 5-8分 | openclaw doctor --fix |
blocking issue が消える |
| 8-10分 | openclaw gateway restart + logs --follow |
EADDRINUSE/auth 拒否が再発しない |
| 10-12分 | curl http://127.0.0.1:18789/health |
200 または想定レスポンス |
| 12-15分 | SSH トンネル経由で UI 確認 | Control UI と WS probe が安定 |
結論：まず3点を揃える
EADDRINUSEは、まずlsofとstatus --deepで事実確認。runningでも未接続なら、Listeningと auth/bind を再点検。- port/mode を触ったら必ず
doctor --fixで supervisor 整合を戻す。
クラウド Mac で Gateway を安定運用するなら
Gateway は「CPU 性能」より「運用の再現性」で差が出ます。Nuvcloud の専有 Mac なら、同じ端末で openclaw doctor と gateway status --deep を毎回同条件で回せるため、障害の切り分けが速くなります。
検証を日次で回してから月額へ移行する流れが最も安全です。料金プランを見る
8）FAQ（よくある質問）
OpenClaw Gateway のデフォルトポートは？
18789 です。優先順は --port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789。
EADDRINUSE は必ず他アプリが原因？
いいえ。実際には OpenClaw の二重起動（前景 + launchd）で起こるケースが多いです。
openclaw gateway --force は使ってよい？
開発環境の緊急復旧には有効ですが、本番では先に status --deep で影響確認を推奨します。
doctor と security audit --deep の違いは？
doctor は可用性・整合性、security audit は露出面と認証強度の点検が主目的です。
なぜ channels status --probe も必要？
Gateway 正常化後でも channel transport 側で失敗することがあるため、切り分けに有効です。
gateway.mode: remote なら 18789 競合は消える？
クライアント側競合は減りますが、遠隔で Gateway を実行しているマシン側の競合は残ります。
Nginx で 18789 をリバースプロキシしても大丈夫？
可能ですが、WebSocket ヘッダ・タイムアウト・auth 転送の3点を誤ると不安定になります。
障害時に再インストールは必要？
多くの場合不要です。Runbook に沿って doctor --fix と supervisor 整合を取る方が再発を防げます。