OpenClaw 日常運用 Runbook：Gateway 18789 ヘルスチェック・段階的アップグレードとログディスク設計（2026）

この記事が答える一つの問い

OpenClaw のインストールスクリプトを実行し、Gateway 18789 が初めてグリーンになった後、多くのチームは「動いているうちは触らない」フェーズに入る。そして散発的な 401 エラー、アップグレード後に 1 台だけ挙動が違う、またはルートディスクが埋まって Gateway がサイレント終了する、という事態に直面する。これらはインストールガイドがカバーする問題ではない。

この記事が答える問いは一つ：OpenClaw の日常運用動作を標準化し、チームの誰でも 15 分以内にヘルスチェックやロールバックを完了できる Runbook をどう作るか。対象範囲は Gateway ヘルスプローブ → 段階的アップグレード → ロールバック手順 → Tailscale / SSH 選択 → ログディスク設計。インストールと初期セットアップは別記事を参照してほしい。

1. Gateway 18789 ヘルスプローブ

多くのチームの「ヘルスチェック」は curl 一発だが、それでは足りない。ポートが別プロセスに占有されていたり launchd が正しく再起動していなかったりすると、curl はすぐ失敗するのではなくハングアップする。適切なプローブは HTTP レスポンスとポートの帰属を同時に確認する必要がある。

# 1. HTTP 死活監視：200 を期待、失敗時に警告
curl -fsS --max-time 3 http://127.0.0.1:18789/health \
  && echo "gateway OK" || echo "GATEWAY FAIL"

# 2. ポート帰属確認：PID が node/openclaw に属するか確認
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 3. 直近のエラーログ（パスはインストール先に合わせて調整）
tail -n 50 ~/.openclaw/logs/gateway.log | grep -i "error\|warn\|exit"

curl が 200 を返しても Dashboard が重い場合は、まずディスク I/O を確認しよう：iostat -d 1 5 で書き込みのスパイクを見る。ログ大量書き込みを Gateway 障害と誤判断するのが最も多い偽アラートの原因だ。「ゴールデンノード」を本番と同じバージョンで維持しておくと、異常が発生した際にすぐ比較対照できる。

2. アップグレード前の三つの確認事項

OpenClaw は頻繁にアップデートが出る。最新バージョンを盲目的に追うと、設定キーの変更で Gateway が起動しない、または既存 Channel 設定と非互換になるという二つのリスクが生まれる。段階的アップグレードが標準的な手法だが、「一台で試してから」と解釈してバージョン記録やディスク空き確認を省くチームが多い。

バージョン記録に含めるべき三つの情報：現在の npm パッケージバージョン（npm list -g openclaw）、plist の絶対パス、設定の tarball。これらをチーム wiki か Notion に保存しておけば、インシデント中に慌てて探す必要がなくなる。

# 現在バージョンを記録
npm list -g openclaw --depth=0 > .upgrade-memo

# 設定をアーカイブ
tar czf openclaw-config-$(date +%Y%m%d).tar.gz \
  ~/.openclaw/config/ \
  ~/Library/LaunchAgents/com.openclaw.gateway.plist

# ディスク空き確認 ≥15%
df -h / | awk 'NR==2 {print "空き："$4, "使用率："$5}'

3. ロールバック：tarball + plist の二段階復元

ロールバックが失敗する最大の原因はバイナリのバージョンではなく、設定キーの非互換だ。新バージョンが必須フィールドを追加していた場合、バイナリを戻しても新しい設定が残っていると Gateway 起動エラーになる。正しい順序は bootout → tarball 復元 → バイナリダウングレード → bootstrap だ。

# ステップ 1：サービス停止
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# ステップ 2：設定 tarball を復元
tar xzf openclaw-config-20260604.tar.gz -C /

# ステップ 3：npm パッケージをダウングレード
npm install -g openclaw@1.x.x   # 記録したバージョンタグに置き換える

# ステップ 4：サービス再起動
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.gateway.plist

# ステップ 5：確認（起動に約 10 秒かかる）
sleep 10 && curl -fsS http://127.0.0.1:18789/health && echo "ロールバック完了"

注意すべきは plist パスのズレだ。新バージョンのインストーラーが ProgramArguments のパスを書き換えた場合、bootout は新しい plist パスで実行し、bootstrap は復元した旧 plist パスで実行する必要がある。この二つのパスが一致しないことがある——だからこそ、アップグレード前に新旧 plist を diff して差分を upgrade-memo に残しておくことが重要だ。

4. Tailscale と SSH/rsync：どちらをいつ使うか

「Tailscale を使うべきか直接 SSH か」というチーム内の議論はよくあるが、これは二択の問題ではない。それぞれ最適なユースケースが異なる。Tailscale はファイアウォールルール不要でマルチデバイス・クロスリージョンのアクセスに強い。SSH/rsync はボトルネックがプロトコルオーバーヘッドではなく出口帯域になる大量ファイル転送に向いている。

推奨の組み合わせ：日常の Dashboard 確認や運用操作には Tailscale の tailnet を使い、定期的なログやアーカイブの取得には SSH + rsync に --bwlimit=50000（約 50 MB/s 上限）を設定して使う。二つの経路を常時維持し、互いの代替として機能させる。

# カナダノードからログアーカイブを取得、50 MB/s 制限、中断再開対応
rsync -avz --bwlimit=50000 --partial \
  user@canada-m4.hashvps.com:~/.openclaw/logs/archive/ \
  ./local-logs/

# Tailscale が直接接続を使っているか確認（DERP 中継ではないか）
tailscale ping canada-m4 --until-direct

5. ログディスク設計：logrotate 設定とパーティション推奨

Gateway の予期せぬ終了は、ルートディスクが埋まることに起因するケースが意外と多い。OpenClaw はデフォルトでユーザーホームディレクトリにログを書き込む——npm グローバルキャッシュと同じボリュームだ。Xcode のエクスポートや CI の一時ファイルが重なると、512 GB のディスクが数週間で静かに満杯になる。定期的な rm ではなく、logrotate が正しい解決策だ。

/Users/mac/.openclaw/logs/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
    dateext
    copytruncate
}

# crontab に追加（毎朝 3 時に実行）：
# crontab -e で以下を追加：
# 0 3 * * * /usr/local/bin/logrotate /Users/mac/.openclaw/logrotate.conf

npm キャッシュには npm config set cache-max 10240 で 10 GB の上限を設定し、アップグレード後に npm cache clean --force で旧パッケージのキャッシュを整理する。1 TB ノードでは ~/.openclaw/logs と npm キャッシュを独立したボリュームに移すことを推奨する。ログが急増してもルートディスクに影響せず、Gateway プロセスへの影響もない。

6. FAQ：よくある運用上の疑問

Gateway 18789 のヘルスチェックが 200 以外を返す。最初にどこを見ればよい？

lsof -nP -iTCP:18789 -sTCP:LISTEN を実行してリスニング状態を確認する。出力がなければプロセスが起動していない。launchctl list | grep openclaw で launchd 状態を確認し、~/.openclaw/logs/gateway.log の直近 50 行のエラー原因を調べる。ポートはリスニングしているが HTTP が 500 を返す場合は設定キーのエラーが多い——アップグレード前の tarball と照合する。

ロールバック後、plist のパスを手動で修正する必要があるか？

新バージョンのインストーラーが plist を書き換えた場合のみ必要だ。純粋な npm バージョンアップでインストーラーが変更されていなければ、tarball 復元後もパスは変わらない。バイナリパスが変わっていた場合は、bootstrap の前に plist の ProgramArguments を旧バイナリのパスに修正する——アップグレード前に新旧 plist を diff しておく理由がここにある。

複数ノードを同時にアップグレードすべきか、一台ずつか？

必ず一台ずつ。ゴールデンノードを先行させ、24 時間 Gateway の健全性と Channel の SLA を観察する。問題がなければ本番ノードを 30 分以上の間隔をあけて順次展開する。一斉アップグレードは、何か問題があった際に比較対照がなくなり、すべてのノードが同時にダウンする。

Dashboard が CPU 100% を示している。OpenClaw 自体のバグか？

とは限らない。まず top -o cpu または Activity Monitor で実際に CPU を消費している PID を特定する。正常な OpenClaw Gateway プロセスの CPU 使用率は定常時 1〜5% が目安だ。node プロセスがスパイクしているなら、Channel リクエストの積滞またはログ書き込みの異常を確認する。専有 Mac mini では renice で Xcode ビルドプロセスの優先度を下げ、OpenClaw と競合しないようにできる。

Tailscale が接続済みなのに Dashboard にアクセスできない。原因は？

Tailscale の ACL ポリシーでポート 18789 が許可されているか確認する。次に tailscale ip -4 で tailnet IP を取得し、curl http://<tailnet-ip>:18789/health で直接テストする。IP で到達できるが MagicDNS のホスト名で届かない場合は DNS 解決の問題であり、Gateway の問題ではない。

logrotate 実行後も Gateway はログファイルに書き続けるか？

copytruncate を使用している場合、logrotate はファイルをコピーしてから元ファイルをゼロ埋めする。Gateway のファイルディスクリプタはそのまま有効なので、サービス中断なくログの継続書き込みが可能だ。デフォルトの create モードを使う場合は、SIGHUP シグナルを送るか、postrotate スクリプトで launchctl kickstart を実行してログハンドルを再オープンさせる必要がある。copytruncate の方がシンプルでサービス中断がない。