2026 OpenClaw ゲートウェイ排障：status→logs→doctor の段階手順（ポート 18789・チャネル側）
上級ユーザーが詰まるのはインストール失敗ではなく、プロセスは動くがチャネルが沈黙するケースです。本稿は openclaw status で制御面を固定し、openclaw logs で時間窓つき証拠を取り、openclaw doctor で設定を収束させ、その後に局所修正へ進む公式 troubleshooting 型の順序を強制します。18789 の競合、ペアリング期限、「接続したが無返信」、Mac クラウドでの SSH トンネルによる露出面の縮小までを一気通貫で扱います。
1. 段階順を守る理由
runtime: running の一行だけでは、18789 が正しく待ち受けていること、ペアリングがまだ有効であること、IM の webhook や long-poll が実際に届いていることを証明できません。status より先にモデル名を変えたり、JSONL を順に読まず doctor --fix を叩くと、チャネル権限の不具合を「モデルが怠い」と誤認し、リモート URL のドリフトをプロバイダのレート制限と取り違えがちです。2026 年の運用で最低限必要なのは、再起動の前に status と時間窓付きログ断片を残すことで、一時ノイズと設定ドリフトを切り分けられるようにすることです。
層を分ける意味は、同じタイムアウトでも発生源の平面が違うからです。チケットでは制御／データ／チャネルとタグ付けし、ポストモーテムがタイムスタンプと整合します。内部メモではどの平面が最初に壊れたかを残してください。
2. 痛みの三層：制御・データ・チャネル
- 制御面：
gateway.mode=remoteではローカルプロセスが空転しているのに稼働していると思い込むことがある。bind・リスナー・プローブを確認し、runtime だけ見ない。 - データ面：ログ探索の順序を固定しないと INFO のハートビートに埋もれる。WARN/ERROR を先に絞り、request id で広げる。構造化 JSONL を優先。
- チャネル面：「接続したが無音」はメンション規則・グループ範囲・期限切れペアリング・ボット権限に多く、
doctor単体では ERROR にならないこともある。
三層のレンズがあれば、webhook が届いていないのに temperature をいじる反射を止められます。OAuth スコープ不足はチャネル平面の証拠です。
3. 症状ルーティング表
| 症状 | 疑う層 | 先にやらないこと |
|---|---|---|
| ローカル curl が 18789 に失敗 | 制御 | モデル名の変更 |
| doctor が JSON5 の無効キーを報告 | 設定 | 状態ディレクトリ全削除 |
| DM は動くがグループが無反応 | チャネル | temperature 調整 |
| プロバイダの 429 が連続 | モデル／枠 | リスタートループ |
| ペアリングが数分で死ぬ | チャネル＋時計 | npm だけ再インストール |
エスカレーションでは表をガードレールに：curl がループバックで失敗しているなら、リスナー確認までトークンを回転させない。DM だけ動くならメンションとボット権限を比較する。
4. 5 ステップ以上：status→logs→doctor→局所修正
Linux・macOS・Mac クラウドで同じ順序。Docker は 同一ネームスペース で実行し、ホストとコンテナの結論が割れないようにする。比較時は両方で openclaw doctor を走らせマウントを確認してから diff。
- ベースライン
openclaw status：runtime・ゲートウェイモード・bind を記録。remote なら upstream URL とヘルスも。「running」だけでは足りない。 - 証拠
openclaw logs：アップグレード前後 10 分。WARN/ERROR を先にし request id で相関。TLS/DNS をトークンより前に。 openclaw doctor：最初は--fixなしで読む。~/.openclawやマウント設定をバックアップしてから自動修正。- ポート 18789：占有プロセスを特定。公網直開放より loopback＋SSH トンネルかリバプロ。
- チャネル：バージョンに応じた probe／status。期限切れなら再ペアリング。グループのスコープとメンション規則を検証。
- 回帰：最小 DM 探針→ツール→本番トラフィック。
週次障害なら runbook に正常時 status とマスクログを置き、ベースライン diff で退行を見える化する。
5. ポート・ペアリング・ログキー
- 18789：よくある既定ローカルポート。リリースノートで確認。競合は多重起動が多い。
- ペアリング TTL：コードは期限切れ。IM 側で速やかに更新し半ペア状態を避ける。
- 相関キー：request id・channel id・プロバイダエラーコードをトークン請求と突合。
- アップグレード／ロールバック：doctor が移行項目を出したらリリースノートに従ってからダウングレード。ログ抜粋はポストモーテム用に残す。
- 監査：JSONL パスとローテ。トリアージ用に最低 7 日分（ポリシーに合わせて調整）。
- Docker：ホストとコンテナで doctor が食い違うならボリュームと uid を先に。チャネル秘密に触る前に。
- 時計ずれ：VM やコンテナの時計がズレると TLS と OAuth 系トークルが壊れる。バイナリを疑う前にホストとコンテナの同期を確認。
- リトライ嵐：チャネルが不安定なとき無制限リトライはログを埋め、最初の有用行を隠す。復旧後は変更窓で制御付き再起動し、行数を前後比較。
- 組織横断の同時実行：同一 egress IP から複数エージェントが叩くと共有レート制限に当たる。ゲートウェイの同時実行を上げる前に他サービスとの 429 相関を見る。
6. Mac クラウドと安価ホストの限界
ノートと 24/7 Mac クラウドでは 監視・ログ永続・攻撃面 が変わる。18789 を公網に晒すのは危険。SSH トンネルやゼロトラストで絞り込む。ネイティブ macOS・launchd・同じ排障階段をそのまま使うなら VPSMAC 専用 Mac クラウドが予測しやすい。初回は 5 分デプロイ記事へ。
Docker on Linux は uid と二重設定の代償がある。
コンソールのレート制限グラフを JSONL の request id と突き合わせる。
イメージ更新のたびステージングで階段を再走。bind／認証リフレッシュのデフォルトに注意。