AI自動化 2026年6月1日

ターミナル落ちを openclaw doctor で復旧：ゲートウェイ未稼働・モデル認証と6段階レスキュー runbook（2026 Mac）

KvmZone 編集部 · 2026年6月1日 · 約 14 分
Mac mini で OpenClaw doctor コマンドによりゲートウェイ接続とターミナル落ちをトラブルシュート

ショートカットをダブルクリックするか、ターミナルで openclaw と入力すると、ウィンドウが消えます。 スタックトレースも、親切なダイアログもなく、ただ沈黙だけです。一方で Slack には依然として「gateway not active」と表示され、モデル選択は延々と回り続け、昨日却下した権限ポップアップが赤い文字で戻ってきます。これは「パソコンが苦手」という話ではなく、環境ドリフトです。Node が違う、ユーザーが違う、設定ファイルが違う、あるいは launchd を生き延びられなかったゲートウェイプロセス——のいずれかです。

openclaw doctor は OpenClaw 公式の自己診断コマンドです。 PATH 上の CLI、設定の読み取り可否、ゲートウェイ到達性、認証プロファイル、ディスク余裕など、構造化されたチェックリストを出力するので、ブログ記事からの再インストールではなく一行ずつ直せます。本チュートリアルは初心者向けレスキューレーンです。doctor が何を見るか、黄と赤の行の読み方、チケットに貼れる6 ステップのランブック、そして初心者が実際に見るエラー向けのトラブルシュート 2 本を扱います。レンタル Mac でオンボード後の SLA 級受け入れは、別記事のオンボード後 doctor マトリクスを参照してください。本記事は「今日また落ちた」向けです。

初出では OpenClaw 第ゼロ時間インストール契約（Node 22+ 下限）、レート制限と予算アラート（リトライがクラッシュに見えないように）、クラウドキーの代わりにローカルモデルを使う場合は OpenClaw + Ollama と併読してください。上流のインストール参照: OpenClaw インストールスクリプト、ゲートウェイ設定例。ハードウェア文脈: Apple Mac mini 仕様。

開示: KvmZone の記載は、初心者がレンタル Mac のクリーンな SSH シェルで openclaw doctor を実行できる場合に限ります。手順の大半は、すでにお持ちの任意の Mac で動作します。

doctor がゼロから再インストールに勝る理由

初心者が言う症状doctor が通常示すもの
起動直後にターミナルが「一瞬で終わる」シェルプロファイルの不整合；非ログインシェルで CLI が PATH にない
UI で「gateway not active」デーモン未起動；ポート競合；古い plist のユーザー
モデルが接続しないAPI キー環境変数欠落；認証プロファイルが誤ったファイルを指す
macOS アップデート後の権限エラーTCC プロンプト拒否；doctor が Keychain / フルディスクの欠落を示す
引用ルール: rm -rf ~/.openclaw の前に openclaw doctor を実行する。PATH や launchd のユーザ不一致を直さず再インストールすると、10 分以内に同じクラッシュが再現します。

中国本土では、npm ミラーへの遅い・フィルタされた出口が「OpenClaw が壊れた」ように見えることがありますが、実際はレジストリタイムアウトのことが多いです。doctor のネットワーク/TLS 行が最初の証拠になります。香港・シンガポールのレンタル Mac ホストは doctor 自体には不要です。

アーキテクチャ: openclaw doctor が検査するもの

Terminal / launchd → openclaw CLI → doctor module → reads ~/.openclaw/* → probes gateway HTTP → prints PASS/WARN/FAIL lines

ファイルと役割

要素パス / コマンド目的
稼働中の設定~/.openclaw/openclaw.jsonゲートウェイポート、認証プロファイル、モデルルート
ログ~/.openclaw/logs/（典型）doctor が緑のあとのクラッシュ証拠
CLI バイナリwhich openclawlaunchd が使うものと一致必須
Node ランタイムnode -v → 2026 年時点で v22.x 下限Node 不一致は「即終了」の第 1 原因
ゲートウェイプローブdoctor 後の openclaw status設定構文だけでなくプロセスを確認
非ログイン整合sudo -u <daemon-user> openclaw doctor「ターミナルだけで動く」を検出

Doctor は負荷試験や webhook POP 計画の代替にはなりません——それは オンボード後マトリクス の領域です。一方で、モデルベンダーを責める資格があるかどうかは教えてくれます。

意思決定マトリクス: クラッシュ種別 → 最初のコマンド

見えるもの…最初に実行doctor が PATH で WARN のときマージ方針
<2 秒でウィンドウが閉じるTerminal.app で openclaw doctor~/.zprofile / ~/.zshrc を修正；nvm または Homebrew で Node を 1 本化PATH が緑になるまでゲートウェイを開かない
UI: gateway not activeopenclaw doctor + openclaw statuslaunchd plist を再読み込み；UserName を一致status が 90 秒 OK になるまでデモを止める
モデルチャットで 401/403doctor の認証セクションplist の EnvironmentVariables にキーをエクスポートキーをローテーション；doctor を再実行
>60 秒ハング後に終了doctor + df -h /空き < 18GB → npm/skills を整理新 skills の前にディスク拡張

推奨パス: シェルが一瞬で閉じるなら、まず対話的に doctor を実行——GUI ショートカットでデバッグしない。doctor が緑でもメニューバーが inactive なら、 LLM API キーではなく launchd ユーザーとポートを直す。

6 ステップ openclaw doctor レスキューランブック

ステップ 1 — 本物のシェルを開く（ダブルクリックのエイリアスではない）

# macOS: use Terminal.app or iTerm — note the user name
whoami
echo $SHELL

出力を保存する。ログインシェルを飛ばすショートカットは PATH 修正を隠します。

ステップ 2 — Node 22+ と PATH 上の CLI を確認

node -v
which openclaw
openclaw --version

合格: node が v22 以降；which openclaw が /opt/homebrew または文書化したグローバル prefix 配下の単一パスを返す。

ステップ 3 — doctor を実行しトランスクリプトを保存

openclaw doctor 2>&1 | tee ~/openclaw-doctor-$(date +%Y%m%d).log

このファイルをサポートチケットに添付する。修正のたびに再実行——推測を積み重ねない。

ステップ 4 — 最初の FAIL を直す（多くは PATH か設定 JSON）

# Example: validate JSON before restart
python3 -m json.tool < ~/.openclaw/openclaw.json > /dev/null && echo "JSON OK"

JSON が失敗したらバックアップから復元:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

ステップ 5 — デーモンユーザーを一致（gateway inactive 対策）

# See which user launchd uses (label varies by install)
launchctl print system/com.openclaw.gateway 2>/dev/null | head -20
# Run doctor as that user if different from Step 1
sudo -u _openclaw openclaw doctor 2>&1 | tee ~/openclaw-doctor-daemon.log

合格: 対話用とデーモン用のトランスクリプトが一致するか、差分がすべて文書化されている。

ステップ 6 — ゲートウェイを再起動し status を検証

openclaw gateway restart   # or launchctl kickstart per your install doc
sleep 5
openclaw status
openclaw doctor

合格: status がリスンポートを示す；doctor に説明のつかない FAIL 行がない。その後——その時点でのみ——エージェントやショートカットを再試行する。

SSH のみのレンタルホストでは、文書化された GUI ゲートがない限り、ピクセルツールより リモート Mac SSH ワークフロー を使います。

トラブルシューティング

エラーパターン: zsh: command not found: openclaw（またはウィンドウが即終了）

症状: スクリプトや .app ラッパーが UI の前に終了；doctor が一度も動かない。

修正:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zprofile
npm install -g openclaw@latest
openclaw doctor

同じ PATH を launchd plist の EnvironmentVariables に揃える（第ゼロ時間契約参照）。

エラーパターン: gateway not active / ECONNREFUSED 127.0.0.1

症状: CLI は存在する；UI や openclaw status がローカルゲートウェイに届かない。

修正:

lsof -iTCP -sTCP:LISTEN | grep -i openclaw
openclaw doctor
openclaw gateway restart

ポートが別ユーザーに占有されている場合は孤児プロセスを止めるか、~/.openclaw/openclaw.json の gateway.port を変更し、doctor を再実行する。ゲートウェイが安定したら レート制限 を設定——リトライ嵐はクラッシュに感じられます。

FAQ

openclaw doctor はエージェントや skills を削除しますか？+
いいえ。Doctor は読み取り専用の診断と推奨修正です。~/.openclaw/openclaw.json の編集やディスク解放を促すことはありますが、別のアンインストールコマンドを実行しない限り ~/.openclaw を消しません。
ターミナルでは合格なのに cron/launchd では失敗するのはなぜ？+
非ログインシェルは別のプロファイルを読み込みます。修正は plist に PATH と API キーのエクスポートを複製するか、launchctl config user path を使うこと——ステップ 5 に記載があります。
「gateway not active」は常にネットワーク問題ですか？+
多くはローカルです。デーモン停止、誤ポート、誤 macOS ユーザー。doctor と openclaw status が緑になってから CDN/リージョンを追う；webhook 地理は オンボード後 POP マトリクス を参照。
初心者はどのくらいの頻度で doctor を実行すべき？+
macOS アップデート、OpenClaw アップグレード、謎のクラッシュのたび——加えて、チームにデモする前にデーモンユーザーから 1 回。ホストが健全なら 1 回90 秒未満です。
東京やソウルでレンタルした Apple Silicon Mac mini でも doctor は使えますか？+
はい。Doctor は同じ CLI です。リージョンはその後の webhook レイテンシに効きます。APAC 発のコールバックでは東京ノードが役立つことがありますが、任意であり、doctor には必須ではありません。

クリーンな SSH ラボが必要なときだけリージョンを Compare

多くの doctor 手順は手元の Mac で実行できます。daemon ユーザー照合にレンタルが必要な場合のみ、6リージョンの Mac mini M4 料金を Compare してください。