OpenClaw macOS トラブルシューティング 2026
OpenClaw はデーモンが安定しているとき魔法のように感じられますが、macOS アップデート後に静かに終了したり、TCC 権限を失ったり、ゲートウェイポートで衝突すると途端に苛立たしくなります。本稿はベースラインインストールを終えたエンジニア（詳しくはインストール／デプロイ完全ガイド）向けに、再現性のあるインシデント対応をまとめます。最初の 15 分で何を確認すべきか、どのログが重要か、ヘッドレス構成の VmMac Mac mini M4 ノードをどう堅牢化すれば夜間の長時間ワークロードでもエージェントが生き残るかを扱います。
症状マトリクス、launchd チェックリスト、ポートと権限の具体的な修復手順に加え、ヘルプドキュメント、GUI のみで完結するプロンプト用のVNC アクセス、単一デーモンを超えてスケールする際のマルチエージェントオーケストレーションへのリンクも示します。
最初の 15 分：デーモンが「突然止まった」ときのトリアージ
次の順で確認してください。レンタル Mac mini の本番退行のおよそ 80% を拾えます。
openclaw status（またはパッケージ固有のゲートウェイ状態コマンド）——標準出力と標準エラーをチケットにそのまま貼り付けます。launchctl list | grep -i openclaw——LaunchAgent が読み込まれているか、直近の終了コードがあれば記録します。lsof -nP -iTCP -sTCP:LISTEN | grep -i openclaw——失敗した再起動後の重複リスナーを検出します。node --version——LaunchAgent を所有する同一 macOS ユーザー（管理者アカウントではない）で v22 以上であることを確認します。- ディスク圧迫：
df -h ~——大きなトレースを書き込むエージェントは空き容量が 5 GB 未満だと即座に失敗します。
OPENCLAW_STATE_DIR を iCloud Drive、Dropbox、OneDrive 内に置かないでください。ファイルプロバイダのロックは「デーモン再起動ループ」を引き起こし、メモリリークのように見えますが実際は同期競合です。
Node.js、PATH、「SSH では動くが launchd では動かない」
LaunchAgent は最小限の環境しか継承しません。対話式 SSH では動くのに plist ログに command not found: node が出る、という症状が典型です。定着する修正策：
- エージェントを実行する同一 macOS ユーザーの下で
nvmにより Node をインストールする。セキュリティ方針が許す場合のみ、既知の Node バイナリを/usr/local/bin/nodeへシンボリックリンクする。 - LaunchAgent plist の
PATH先頭に/Users/ci/.nvm/versions/node/v22.x.x/binと/usr/bin:/bin:/usr/sbin:/sbinを追加する。 - 本番では OpenClaw のパッケージバージョンを固定する（
npm install -g [email protected]）。「常に latest」に自動 npm アップデートを重ねると、水曜朝のアウトージが起きやすくなります。
対話的ログインシェルと、sudo -u ci -H bash -lc 'which node' で生成した非対話シェルの両方で、which node && node -p "process.execPath" の結果が一致している必要があります。
launchd 診断：ThrottleInterval、終了コード、サイレントクラッシュループ
ジョブが短時間で終了しすぎると Apple の launchd は積極的にバックオフします。デバッグ中はログを読みやすくするため ThrottleInterval を少なくとも 10 秒に設定してください。直近のクラッシュは次で確認します。
log show --style syslog --predicate 'process == "launchd"' --last 30m | grep -i openclaw
高速な再起動が見える場合は一時的にエージェントを unload し、120 秒ほどフォアグラウンドでデーモンを実行して原因を直してから reload します。
launchctl unload ~/Library/LaunchAgents/ai.openclaw.daemon.plist
openclaw daemon start --foreground
ゲートウェイポートの衝突とリバースプロキシの競合
症状：ヘルスチェックがフラップする、WebSocket クライアントが 1006 で切断される、CI が断続的に「ゲートウェイ到達不能」と報告する。2026 年によくある重複要因には、ローカルの Prometheus exporter、放置された Docker Desktop のプロキシポート、以前のユーザーアカウントに残った 2 つ目の OpenClaw インストールなどがあります。
| シグナル | 想定される衝突 | 対処 | 検証 |
|---|---|---|---|
| 起動時の Bind EADDRINUSE | 重複デーモンまたは迷子の node プロセス | すべてのエージェントを停止；安全が確認できれば古い PID ファイルを削除；設定で新しいポートを割り当てる | lsof -i :PORT が単一の所有者のみを返す |
| リバースプロキシから 502 | 上流 TLS の不一致または HTTP/2 ダウングレード | TLS はプロキシ側で終端；localhost にはプレーン HTTP で話す | curl -sv http://127.0.0.1:PORT/healthz |
| CI からのみタイムアウト | Runner の NAT ヘアピン | ゲートウェイを 127.0.0.1 にバインドし SSH -L でトンネルする |
CI がトンネル経由の curl を 200 ms 未満で完了 |
| スリープ後に不安定 | macOS の Power Nap またはディスプレイスリープ | caffeinate ラッパー、またはディスクスリープを防ぐシステム設定 |
ウォッチドッグ再起動なしで稼働時間が 48 時間超 |
TCC：画面収録、アクセシビリティ、更新後の権限取り消し
macOS Sequoia ではマイナーなセキュリティパッチの後に再確認プロンプトが頻繁に出ます。OpenClaw がアクセシビリティや画面収録を失うと、GUI 自動化は分かりにくいスタックトレースで失敗します。復旧手順：
- システム設定 → プライバシーとセキュリティで影響カテゴリごとに確認する。
- 古いエントリを削除し、
which openclawが示す正確なバイナリパスを再追加する。 - SSH からデーモンを再起動し、簡単なスクリーンショットタスクで検証する。
- バイナリパスを社内 Wiki に記録する——ここを飛ばすチームは次の再ビルド後に必ず再発させます。
状態ディレクトリ、ディスク増加、破損した WAL
中程度の負荷の単一エージェントホストでは、ログとタスク成果物で週 300–800 MB を見込んでください。マルチエージェントフリートは倍になることもあります。logging.retainDays をコンプライアンスに応じ 7〜21 日に保ち、成果物は VmMac インスタンスに付属するローカル NVMe に置き、ネットワークマウントは使わないでください。
ハードリブート後に SQLite や WAL が破損した場合は破損ディレクトリを退避し、最後に正常だった tarball から復元（~/.openclaw は毎晩スナップショットすべきです）、git に入れた IaC スクリプトから設定を再生します。
24/7 エージェント向けログ保持プレイブック
| 重大度 | ページするタイミング | オーナーアクション |
|---|---|---|
| P1 — デーモン終了 | 営業時間中の計画外終了はいずれも | plist とユニファイドログのスライスを収集；直近の設定変更をロールバック |
| P2 — 20 分でタスク失敗率 15% 超 | 持続的な API またはディスクエラー | 同時実行を抑制；プロバイダのステータスページを確認 |
| P3 — タスク遅延 | P95 が 6 時間にわたりベースラインの 2 倍超 | 古いワークスペースを GC；2 台目の VmMac ノードへシャーディング |
VmMac クラウド Mac mini 上での OpenClaw ハードニング
ノート PC の概念実証から、香港・日本・韓国・シンガポール、米国の VmMac 本番ノードへ移行するときは、他サーバーと同様に扱います。不要な共有サービスを無効化し、SSH は鍵のみに限定し、ステージングと本番で環境ごとに重ならないポートレンジをエージェントフリートに割り当てます。
メモリ選定は料金ページを参照してください。24 GB のユニファイドメモリなら、重いエージェントを 3 つ同時に回しつつ Xcode 周辺タスクの余裕もあります。16 GB でも可能ですが maxConcurrentTasks をより厳しく制限する必要があります。
FAQ：サポートが本当に欲しい短い答え
デーモンは root で動かすべき？ いいえ。最小権限の専用 openclaw または ci ユーザーを使います。root は TCC プロンプトを壊し監査も難しくなります。
SSH だけで全部直せる？ ほぼはい——ただし初回の TCC 承認と一部の Safari 駆動自動化は除きます。短い VNC 枠を確保してください。
アップグレードを安全に試すには？ 状態をスナップショットし、設定をステージング VmMac ノードにクローンし、合成ワークロードで 72 時間走らせてから昇格します。
2026 年も OpenClaw にとって Mac mini M4 がスイートスポットである理由
OpenClaw はサブプロセス生成、リポジトリ読み取り、ときどきネイティブツールチェーンのコンパイルに時間を費やします。Mac mini M4 のユニファイドメモリはこれらを高速に保ち、旧世代 Intel mini で起きがちな PCIe ボトルネックを避けられます。サードパーティ API に出したくないプロンプトをオンデバイスに留めたい場合、Neural Engine による MLX 実験も可能です。
VmMac でレンタルすれば、ハード調達・通関待ち・クローゼットへのラック設置なしに Apple Silicon の性能を得られます。本トラブルシュートと初回インストール手順、マルチエージェント拡張の指針を組み合わせ、モデルプロバイダへの RTT を最小化するリージョンを料金ページから選んでください。
