[UPDATE] 2026-08-24 初版。随時追記します。ここにないエラーは、エラー文で公式ドキュメントとGitHub Issuesを検索するか、その画面のスクショをAIに貼って聞くのが早道です。

ここに並ぶのは想定問答ではなく、筆者が半年で実際に踏んだエラーです。症状から探してください。

症状別さくいん

インストールできない1. EACCES
コマンドが見つからない2. command not found
モデルが使えない3. Unknown model
突然エラーを返すようになった4. 429 / 使用上限
「入力中」のまま返事がない5. 半死に状態の切り分け
Botがオフラインになった6. オフライン復旧
久しぶりに使ったら動かない7. 放置後の復活

1. EACCES — インストールで権限エラー

原因: npmのグローバルインストール先がシステム領域で書き込めない。対処: sudoで強行しない。ユーザー配下へ変更:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm i -g openclaw

2. command not found — コマンドが見つからない

原因: 壊れたのではなく、実行ファイルへのPATHが通っていないだけ。

ls -la ~/.npm-global/bin | grep openclaw   # 実体はあるか
which openclaw                              # PATHから見えているか

実体があるのにwhichが空ならPATHの問題。~/.zshrcにPATHを追記してsource ~/.zshrc。急ぎならフルパス(~/.npm-global/bin/openclaw ...)で直接叩けます。

3. Unknown model — モデル名が通らない

原因: ①綴り違い ②providerの取り違え ③許可リスト漏れ。対処: 一覧を出して、表示された名前をコピーして使う:

openclaw models list
openclaw models set <一覧にある名前をそのまま>

providerは別物です: google/...=APIキー従量課金 / google-antigravity/...=OAuth連携 / google-gemini-cli/...=ローカルCLI。どれを選ぶかで課金のされ方が変わります。

4. HTTP 429 / 使用上限 — 突然エラーを返す

原因: AI側の使用上限(クォータ)到達。再起動では上限はリセットされません。openclaw models status --probeで残量・cooldownを確認し、回復を待つか別モデルへ一時切り替え。恒久策はフォールバック設定。

⚠️ 上限回避のためにAPIキー(従量課金)側へ逃がすのは、上限のない枠への退避です。筆者はこれで月2万円の請求を受け取りました。従量側を使うなら先に予算アラートを。

5. 「入力中…」のまま返事がない — 半死に状態

openclaw gateway status              # ① 本体は生きているか
openclaw models status --probe       # ② AI認証は生きているか(expired)
openclaw channels status --probe     # ③ Discord接続は生きているか
openclaw logs --follow               # ④ ログを流したまま送信
ログが流れて、返事なし→ モデル・認証側の問題
(probe/expired/429を見る)
ログが流れない→ Discord接続・権限側の問題
(Bot権限・Intent・チャンネル設定)
推測で直さない。ログが真実

チャット抜きの切り分けも有効: openclaw agent --message "ping。OKだけ返して" --thinking low — 返る→Discord側、返らない→モデル・認証側。

6. Botがオフラインになった

二大原因: ①Gatewayが落ちた ②マシンがスリープした。まずopenclaw gateway restart。直らなければopenclaw logs --followでエラー本文を見る。本文を特定する前に初期化・再インストールをしないこと(筆者はこの原則で、起動失敗1394回という重症からもデータ無傷で復旧しています)。

7. 久しぶりに使ったら動かない

原因: 放置中に認証トークンの期限切れ/本体が古くなり接続先の仕様と合わなくなった。

openclaw update
openclaw models auth login --provider <使っているprovider>
openclaw doctor --fix
openclaw gateway restart

予防: 週1回、5番の定点4コマンドを叩くだけでほぼ防げます。

それでも直らないとき

直す前にログを読む。消す前に退避する。データ本体には触らない——この3原則だけは守ってください。直せない状態より、戻せない状態のほうが重症です。