OpenClawのインストールや使用の過程では、さまざまな問題に遭遇することがあります。この記事では、コミュニティで最もよく報告されるエラーと、それぞれの解決策をまとめています。問題を調査する前に、まずOpenClawの内蔵診断ツールを実行することを強くおすすめします。その他のサポートについてはOpenClawをご覧ください。
まずはopenclaw doctorを使う
OpenClawには強力な自己診断コマンドが用意されており、実行環境、設定ファイル、ネットワーク接続などの状態を自動的にチェックしてくれます。
openclaw doctor
このコマンドは以下の項目を含む詳細な診断レポートを出力します。
- Node.jsのバージョンが要件を満たしているか
- 設定ファイルが存在し、形式が正しいか
- Gatewayサービスが稼働しているか
- 各AIプロバイダーへの接続状態
- 設定済みチャンネルの接続状態
ほとんどの問題は openclaw doctor の出力から原因を素早く特定できます。問題が発生したら、まず一度実行してみることをおすすめします。
Node.jsのバージョンが要件を満たさない
エラーの例：
Error: OpenClaw requires Node.js >= 22.0.0, current version: 18.x.x
またはインストール時にシンタックスエラーやモジュールが見つからないなどの異常が発生する場合。
解決方法：
OpenClawにはNode.js 22以上が必要です。現在のバージョンを確認してください。
node --version
22未満の場合はアップグレードが必要です。
# NodeSourceリポジトリを使用（Ubuntu/Debian）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
# またはnvmを使用
nvm install 22
nvm use 22
nvm alias default 22
アップグレード後、OpenClawを再インストールします。
npm install -g openclaw@latest
GatewayのTokenが見つからない、または無効
エラーの例：
Error: Gateway token is missing or invalid
またはDashboardに「Unauthorized」と表示される場合。
解決方法：
GatewayのTokenは openclaw onboard の初回実行時に自動生成され、設定ファイルに保存されます。設定ファイルを確認してください。
cat ~/.config/openclaw/openclaw.json5
gateway セクションに有効な token フィールドがあることを確認します。Tokenが紛失または破損している場合は、再生成できます。
openclaw gateway reset-token
その後、Gatewayを再起動します。
openclaw gateway restart
systemdでサービスを管理している場合は以下を実行します。
sudo systemctl restart openclaw
ポート18789が使用中
エラーの例：
Error: listen EADDRINUSE: address already in use :::18789
解決方法：
まず、どのプロセスがポートを占有しているか確認します。
# Linux
sudo lsof -i :18789
# または
sudo ss -tlnp | grep 18789
考えられるケース：
- 既存のOpenClawインスタンスが稼働中： 古いインスタンスを停止する
openclaw gateway stop
# または強制終了
kill $(lsof -t -i:18789)
- 他のプログラムがポートを占有： OpenClawのポート設定を変更する
nano ~/.config/openclaw/openclaw.json5
{
gateway: {
port: 18790, // 別のポートに変更
}
}
ポートを変更した場合、Nginxリバースプロキシを設定済みであれば、Nginx設定のupstreamアドレスも忘れず更新してください。
APIキーのエラー
エラーの例：
Error: 401 Unauthorized - Invalid API key
またはAIモデルがメッセージに応答しない場合。
解決方法：
APIキーの設定を一つずつ確認します。
nano ~/.config/openclaw/openclaw.json5
Anthropic Claude：
- キーの形式は
sk-ant-api03-...であること - console.anthropic.com でキーが有効期限内で残高があることを確認
OpenAI：
- キーの形式は
sk-proj-...またはsk-...であること - アカウントに利用可能な残高があることを確認
Ollama（ローカルモデル）：
apiKeyには"ollama"のような任意の空でない文字列を設定- Ollamaサービスが稼働しているか確認：
curl http://localhost:11434/api/tags
よくあるミスとして、キーのコピー時に前後にスペースが入ったり、設定ファイルで引用符が抜けたりすることがあります。
チャンネル接続の失敗
Telegram接続の失敗：
Error: Telegram Bot API: 401 Unauthorized
解決方法：
- Bot Tokenが正しく、無効化されていないか確認する
- BotFatherでボットの状態を確認する：
/mybotsを送信 - Tokenが漏洩した場合は
/revokeで再生成する
Discord接続の失敗：
Error: Discord Gateway: Authentication failed
解決方法：
- Bot Tokenが正しいか確認する
- Discord Developer PortalでBotのMessage Content Intentが有効になっていることを確認する
- Botが対象サーバーに招待されていることを確認する
WhatsApp接続の失敗：
WhatsAppはQRコード認証を使用します。接続が切れた場合は以下を実行します。
openclaw channel reconnect whatsapp
表示される案内に従って再度スキャンしてください。
設定ファイルのフォーマットエラー
エラーの例：
Error: Failed to parse config file
SyntaxError: Unexpected token ...
解決方法：
OpenClawはJSON5形式の設定ファイルを使用します。標準のJSONより柔軟（コメントや末尾カンマに対応）ですが、構文上の要件はあります。よくあるミス：
- カンマの欠落
- 文字列値が引用符で囲まれていない
- 波括弧の対応が合っていない
以下のコマンドで設定を検証できます。
openclaw doctor
診断ツールが設定ファイル内の具体的なエラー箇所を指摘してくれます。設定が大幅に壊れている場合は、バックアップしてから再初期化できます。
cp ~/.config/openclaw/openclaw.json5 ~/.config/openclaw/openclaw.json5.bak
openclaw onboard
メモリ不足によるクラッシュ
エラーの例： Gatewayが頻繁に再起動し、ログに JavaScript heap out of memory が記録される。
解決方法：
Node.jsのメモリ上限を引き上げます。
export NODE_OPTIONS="--max-old-space-size=4096"
systemdでサービスを管理している場合は、serviceファイルに環境変数を追加します。
Environment=NODE_OPTIONS=--max-old-space-size=4096
設定を再読み込みして再起動します。
sudo systemctl daemon-reload
sudo systemctl restart openclaw
問題が続く場合は、サーバーのメモリ増設を検討してください。
さらにサポートが必要な場合
上記の方法で問題が解決しない場合は、以下の方法でサポートを受けられます。
- 公式ドキュメントを参照： OpenClaw公式ドキュメントに最も包括的な設定リファレンスがあります
- GitHub Issueを検索： OpenClaw GitHub リポジトリでエラーメッセージを検索すれば、同じ問題を経験した人が見つかることが多いです
- 新しいIssueを作成： バグと確認できた場合は、
openclaw doctorの完整な出力と関連ログを添えてIssueを送信してください - ログを確認： 詳細なログは深い原因の特定に役立ちます
# Gatewayのリアルタイムログを確認
sudo journalctl -u openclaw -f
# 直近100行のログを確認
sudo journalctl -u openclaw -n 100
OpenClawを常に最新バージョンに保つことも大切です。多くのバグは新しいバージョンで修正済みです。
npm update -g openclaw@latest