$cd ../troubleshooting/
High📦 Installation
アップグレード後ゲートウェイクラッシュ — openclaw.jsonの古いパス
// 大規模OpenClawアップグレード（Clawdbot→OpenClaw改名やnpmグローバルパス変更など）後、~/.openclaw/openclaw.jsonのsourcePathとinstallPathが存在しないディレクトリを指したまま残ります。ゲートウェイは起動直後に終了し、ENOENTまたはinstall path invalidをログに出します。openclaw doctor --fixが現在のバイナリ位置に合わせてこれらのキーを書き換えます。
diagnose.sh
🔍 これがあなたの問題ですか？
?openclaw gateway startまたはsystemctl restart直後にゲートウェイ終了
?ログにENOENT、install path invalid、sourcePath not found
?openclaw.jsonがclawdbot、古いnvmパス、削除済みホームディレクトリを参照
doctor_fix.sh
✅ 修正1 — openclaw doctor --fixを実行（最速）
推奨修正 — 書き込み前に設定をバックアップ
# 現在のパスとバイナリを確認 openclaw doctor # 古いパスとschemaドリフトを自動修正 openclaw doctor --fix # ゲートウェイ検証 openclaw gateway restart openclaw gateway status
openclaw.json
✅ 修正2 — openclaw.jsonのパスを手動更新
installPath = openclawのpackage.jsonを含むディレクトリ
# liveインストール場所を特定
which openclaw
# 例 /home/you/.nvm/versions/node/v22.4.0/bin/openclaw
# ~/.openclaw/openclaw.json を編集
{
"installPath": "/home/you/.nvm/versions/node/v22.4.0/lib/node_modules/openclaw",
"sourcePath": null
}
openclaw gateway restartgateway_install.sh
✅ 修正3 — ゲートウェイサービスを再インストール
現在のバイナリパスでサービス再生成
# Linux systemd openclaw gateway stop openclaw gateway uninstall openclaw gateway install systemctl --user daemon-reload systemctl --user restart openclaw-gateway # macOS openclaw gateway install --force # Windows（タスク用に一度昇格の場合あり） openclaw gateway install
💡 プロのヒント：アップグレード前に設定をバックアップ
npm update -g openclawの前に~/.openclaw/openclaw.jsonをopenclaw.json.bakにコピー。ゲートウェイが起動しない場合、バックアップと新ファイルをdiff — 古いパスキーが唯一の破壊的変更であることが多いです。
🛡️ 予防チェックリスト
- • アップグレードのたびにopenclaw doctor（--fixなし）— クラッシュ前に警告を読む
- • カスタムcheckoutをsymlinkしない限りsourcePath/installPathを手編集しない
- • マシン移行時は~/.openclaw/をrsyncするが新ホストでdoctor --fixを再実行
- • npm prefixを安定させる（Windows EACCESガイド参照）installPathの静かなドリフトを防ぐ
- • ゲートウェイインストール方法（systemd/launchd/Scheduled Task）をREADMEメモに記録
❓ FAQ
Q1. sourcePathとinstallPathは何に使われますか？
installPathは実行中のopenclaw CLIとバンドルアセットを含むディレクトリです。sourcePath（設定時）はdevプラグインやローカルパッチ用git checkoutを指します。ゲートウェイは起動時に両方を検証し、スキル、デフォルト設定、自動更新フックが正しく解決されます。古い値は静かな誤ルーティングではなく即座の起動失敗を引き起こします。
Q2. npm update -gでパスが自動修正されない理由は？
npmはグローバルprefix下のパッケージを置き換えますが~/.openclaw/のユーザー設定は編集しません。パスキーはopenclaw setupまたはgateway install時に一度書き込まれアップグレードを跨いで残ります。doctor --fixはliveバイナリ位置（npmが更新済み）と設定を比較し不一致をパッチします。
Q3. sourcePathを完全に削除しても安全ですか？
OpenClawをソースから開発していなければはい — sourcePathを削除またはnullにしinstallPathのみに依存。古いClawdbot cloneへの死んだsourcePathを残すのは移行後のよくある罠。本番インストールはinstallPathがグローバルnpmツリーまたはnvmスロットを指せば十分。
Q4. doctor --fixが他の設定も変更した — 正常ですか？
doctorはschemaバージョン正規化、改名キー移行、gateway.authプレースホルダ更新も行うことがあります。diffを確認：可能ならopenclaw doctor --fix --dry-run、または先にバックアップ。パス修正が重要部分；手動ローテした秘密以外の良性移行は受け入れ。
Q5. 修正1後もゲートウェイがクラッシュ — 次は？
ログ確認：journalctl --user -u openclaw-gateway -n 50（Linux）またはopenclaw gateway logs。別のENOENT（skills dir、チャンネルauth）を探す。修正3でサービスユニット再生成。サービスが呼ぶopenclawバイナリを確認 — /usr/local/binの古いシャドウバイナリは別問題（dual-installガイド）。
Q6. Docker利用時 — このガイドは必要？
コンテナ内bind-mountされた~/.openclaw/openclaw.jsonがコンテナFSに存在しないホストパス（/home/user/.nvm/...等）を持つことがあります。一貫パスをマウント、コンテナ内installPath（/app等）を設定、またはentrypointで起動時doctor --fix。