OpenClawエラーの修正方法：15個のよくある問題と解決策

TL;DR

OpenClawのトラブルシューティングは、接続切断、認証失敗、ルーティングエラー、パフォーマンスの問題をカバーしています。ほとんどの問題は、ネットワークの不安定性、誤ったAPIキー、またはチャネルの誤設定に起因します。このガイドでは、OpenClawで最も一般的な15のエラーに対する段階的な修正方法を提供します。

インストールとセットアップの問題

Node.jsのバージョン不一致

問題: openclaw コマンドが見つからないか、「サポートされていないNodeバージョン」というエラーで失敗します。

原因: OpenClawはNode.js 22以降が必要です。古いバージョンには必要な機能がありません。

修正:

Nodeのバージョンを確認します:

node --version

22未満の場合は、Nodeを更新します:

# Using nvm (recommended)
nvm install 22
nvm use 22

# Or download from nodejs.org

OpenClawを再インストールします:

npm install -g openclaw@latest

インストールを確認します:

openclaw --version

インストール中のパーミッション拒否

問題: npm install -g openclaw がEACCESまたはパーミッションエラーで失敗します。

原因: npmが適切なパーミッションなしにシステムディレクトリに書き込もうとします。

修正:

sudo を使用しないでください。代わりに、npmがユーザーディレクトリを使用するように設定します:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

シェルプロファイル (`~/.zshrc` または `~/.bashrc`) に追加します:

export PATH=~/.npm-global/bin:$PATH

シェルをリロードします:

source ~/.zshrc

OpenClawをインストールします:

npm install -g openclaw@latest

設定ファイルが見つかりません

問題: インストール後、OpenClawが ~/.openclaw/config.json を見つけられません。

原因: オンボーディングウィザードが実行されなかったか、サイレントに失敗しました。

修正:

オンボーディングを手動で実行します:

openclaw onboard

それが失敗した場合は、設定ディレクトリを作成します:

mkdir -p ~/.openclaw

最小限の設定ファイルを作成します:

cat > ~/.openclaw/config.json << 'EOF'
{
  "version": "1.0.0",
  "providers": {},
  "agents": {},
  "channels": {},
  "routing": []
}
EOF

もう一度オンボーディングを実行します:

openclaw onboard

チャネル接続の問題

WhatsAppのQRコードがスキャンできない

問題: QRコードは表示されるが、WhatsAppアプリが「無効なQRコード」と表示するか、応答しない。

原因: QRコードの有効期限が切れているか、電話とOpenClaw間のネットワークの問題。

修正:

1. お使いの電話とコンピュータが同じネットワーク上にあることを確認してください
2. QRコードを再生成します:

openclaw channels logout whatsapp
openclaw channels login whatsapp

1. 30秒以内にスキャンします (QRコードはすぐに期限切れになります)。
2. それがまだ失敗する場合は、ファイアウォール設定を確認してください:

# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/node

# Linux (ufw)
sudo ufw allow 18789/tcp

WhatsAppが数時間後に切断される

問題: WhatsAppは最初は動作するが、2〜4時間後に切断される。

原因: WhatsAppのプロトコルは定期的なハートビートを必要とします。ネットワークの変更やスリープモードが接続を中断します。

修正:

自動再接続を有効にします:

openclaw channels config whatsapp --auto-reconnect true --reconnect-interval 300

これは5分ごとに接続を確認し、必要に応じて再接続します。

ノートパソコンでOpenClawを実行している場合は、スリープを防止します:

# macOS
caffeinate -i openclaw gateway

# Linux
systemd-inhibit --what=sleep openclaw gateway

本番環境では、ノートパソコンではなくサーバーでOpenClawを実行してください。

Telegramボットがメッセージを受信しない

問題: ボットはオンラインだが、メッセージに応答しない。

原因: ボットに必要なパーミッションがないか、トークンが無効です。

修正:

ボットのトークンをテストします:

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

これがエラーを返す場合、トークンを再生成します:

1. Telegramを開き、@BotFatherにメッセージを送ります
2. /mybots を送信します
3. ボットを選択します
4. 「API Token」→「Regenerate Token」を選択します
5. OpenClawを更新します:

openclaw channels update telegram --token NEW_TOKEN

グループチャットの場合、「メッセージを読む」パーミッションを持つ管理者としてボットを追加してください。

Discordボットがオフラインと表示される

問題: ボットがDiscordサーバーリストでオフラインと表示される。

原因: 「メッセージコンテンツインテント」が欠落しているか、トークンが無効です。

修正:

1. Discord開発者ポータルにアクセスします
2. アプリケーションを選択します
3. 「Bot」タブに移動します
4. Privileged Gateway Intentsの下にある「Message Content Intent」を有効にします
5. 変更を保存します
6. OpenClawを再起動します:

openclaw gateway restart

ボットがまだオフラインの場合は、トークンを確認してください:

openclaw channels test discord

失敗した場合は、開発者ポータルでトークンを再生成し、OpenClawを更新してください。

iMessageブリッジが機能しない (macOS)

問題: iMessageチャネルが「切断済み」と表示されるか、メッセージを受信しない。

原因: アクセシビリティのパーミッションが欠落しているか、メッセージアプリが実行されていない。

修正:

1. システム設定 → プライバシーとセキュリティ → アクセシビリティを開きます
2. 許可されたリストにターミナル (またはお使いのターミナルアプリ) を追加します
3. OpenClawを再起動します:

openclaw gateway restart

1. メッセージアプリが実行中でサインインしていることを確認します
2. 自分自身にメッセージを送信してテストします

それがまだ機能しない場合は、ブリッジプロセスを確認してください:

ps aux | grep openclaw-imessage-bridge

実行されていない場合は、手動で起動します:

openclaw channels restart imessage

認証とAPIのエラー

無効なAPIキー

問題: ログに「認証失敗」または「無効なAPIキー」エラーが表示される。

原因: 間違ったAPIキー、期限切れのキー、または適切なパーミッションがないキー。

修正:

APIキーを確認します:

# For Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}'

# For OpenAI
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"Hi"}],"max_tokens":10}'

curlコマンドが失敗した場合、キーは無効です。プロバイダーのダッシュボードから新しいキーを取得してください。

OpenClawを更新します:

openclaw config set --provider anthropic --api-key NEW_KEY

ゲートウェイを再起動します:

openclaw gateway restart

レート制限を超過しました

問題: 「レート制限を超過しました」または「リクエストが多すぎます」エラー。

原因: AIプロバイダーに過剰なリクエストを送信しています。

修正:

使用状況を確認します:

openclaw stats --period 1h

レート制限を有効にします:

openclaw limits set --max-requests 50 --window 3600

これにより、1時間あたり50リクエストに制限されます。プロバイダーの制限に基づいて調整してください。

バーストトラフィックの場合、キューイングを有効にします:

openclaw config set --enable-queue true --queue-max-size 100

レート制限に達するとメッセージがキューに格納され、容量が利用可能になったときに処理されます。

モデルが見つかりません

問題: 「モデルが見つかりません」または「無効なモデル」エラー。

原因: 存在しないモデル、またはあなたのアカウントで利用できないモデルを指定しました。

修正:

利用可能なモデルをリストします:

# Anthropic
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: YOUR_KEY"

# OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

エージェント設定を更新します:

openclaw agents update default --model claude-sonnet-4-6

ゲートウェイを再起動します:

openclaw gateway restart

クレジット不足

問題: 「クレジット不足」または「支払いが必要です」エラー。

原因: AIプロバイダーのアカウントのクレジットがなくなったか、請求限度額に達しました。

修正:

プロバイダーのダッシュボードでアカウント残高を確認します:

• Anthropic: https://console.anthropic.com/settings/billing
• OpenAI: https://platform.openai.com/account/billing

クレジットを追加するか、支払い方法を更新してください。

待っている間、無料またはローカルモデルにルーティングします:

openclaw agents add fallback --provider ollama --model llama2
openclaw routing add --fallback fallback

メッセージルーティングの失敗

メッセージが誤ったエージェントに送信される

問題: ルーティングルールがあるにもかかわらず、メッセージが誤ったAIエージェントにルーティングされる。

原因: ルーティングルールが競合しているか、優先度が誤っています。

修正:

すべてのルーティングルールをリストします:

openclaw routing list

競合を確認します。優先度の高いルールが最初に一致します。次の場合:

Priority 5: channel=whatsapp → agent=default
Priority 10: sender=+1234567890 → agent=vip

WhatsAppの +1234567890 からのメッセージは vip に送信されます (優先度10が優先)。

競合するルールを削除します:

openclaw routing remove <rule-id>

正しい優先度でルールを追加します:

openclaw routing add --channel whatsapp --agent default --priority 1
openclaw routing add --sender +1234567890 --agent vip --priority 10

ルーティングをテストします:

openclaw routing test --channel whatsapp --sender +1234567890 --message "test"

これにより、メッセージを送信せずにどのエージェントが処理するかを表示します。

キーワードルーティングが機能しない

問題: 特定のキーワードを含むメッセージが、設定されたエージェントにルーティングされない。

原因: キーワードが大文字と小文字を区別するか、メッセージに正確なキーワードが含まれていません。

修正:

キーワードを大文字と小文字を区別しないようにします:

openclaw routing add --keyword "debug" --agent debugging --case-insensitive

柔軟なマッチングのために正規表現を使用します:

openclaw routing add --pattern "debug|error|bug" --agent debugging

これはメッセージ内のどこかに「debug」、「error」、「bug」のいずれかが一致します。

キーワードマッチングをテストします:

openclaw routing test --message "I found a debug issue"

カスタムルーティング関数のエラー

問題: カスタムルーティング関数がエラーをスローするか、実行されない。

原因: 構文エラー、依存関係の欠落、または誤った戻り値。

修正:

ルーティング関数をテストします:

openclaw routing test-custom ~/.openclaw/routing.js --message "test"

これにより、関数を実行し、結果またはエラーを表示します。

よくある問題:

1. 構文エラー: JavaScriptの構文を確認してください
2. returnの欠落: 常にエージェント名を返してください
3. 非同期関数: ルーティング関数でasync/awaitを使用しないでください (同期である必要があります)

正しい関数の例:

module.exports = function route(message) {
  // Always return a string (agent name)
  if (message.channel === 'whatsapp') {
    return 'whatsapp-agent';
  }
  return 'default';
};

誤った関数の例:

// DON'T DO THIS
module.exports = async function route(message) {
  const result = await someAsyncOperation();
  return result; // Async functions not supported
};

フォールバックエージェントがトリガーされない

問題: プライマリエージェントが失敗しても、メッセージがフォールバックにルーティングされない。

原因: フォールバックが設定されていないか、プライマリエージェントが正しく失敗を報告しない。

修正:

フォールバックを設定します:

openclaw routing set-fallback backup-agent

フォールバックをテストします:

# Temporarily disable primary agent
openclaw agents disable default

# Send a test message
openclaw routing test --message "test"

# Should show fallback agent

プライマリエージェントを再有効化します:

openclaw agents enable default

パフォーマンスとメモリの問題

高いメモリ使用量

問題: OpenClawが2GB以上のRAMを使用し、増加し続けます。

原因: セッションデータがクリーンアップされずに時間とともに蓄積されます。

修正:

メモリ使用量を確認します:

openclaw stats --memory

古いセッションをクリアします:

openclaw sessions clear --older-than 7d

セッションタイムアウトを短縮します:

openclaw config set --session-timeout 1800

セッションはデフォルトの1時間ではなく、30分間アクティビティがないと期限切れになります。

自動クリーンアップを有効にします:

openclaw config set --auto-cleanup true --cleanup-interval 3600

これは1時間ごとにクリーンアップを実行します。

遅い応答時間

問題: AI応答に30秒以上かかるか、タイムアウトする。

原因: ネットワーク遅延、AIプロバイダーの遅さ、またはキューのバックログ。

修正:

キューの状態を確認します:

openclaw queue status

キューに50以上のメッセージがある場合、同時実行数を増やします:

openclaw config set --max-concurrent-requests 10

これはデフォルトの3つではなく、10個のメッセージを同時に処理します。

AIプロバイダーへのネットワーク遅延を確認します:

# Anthropic
ping api.anthropic.com

# OpenAI
ping api.openai.com

遅延が高い場合 (>200ms)、別のプロバイダーまたはローカルモデルの使用を検討してください。

リクエストタイムアウトを有効にします:

openclaw config set --request-timeout 30000

30秒を超えるリクエストは失敗し、再試行されます。

ゲートウェイが応答しなくなる

問題: ゲートウェイがメッセージやAPI呼び出しに応答しなくなる。

原因: デッドロック、無限ループ、またはリソースの枯渇。

修正:

ゲートウェイのステータスを確認します:

openclaw gateway status

フリーズしている場合は、スレッドダンプを取得します:

kill -SIGUSR1 $(pgrep -f "openclaw gateway")

これはスレッドダンプを ~/.openclaw/gateway.log に書き込みます。スタックした操作を探してください。

ゲートウェイを再起動します:

openclaw gateway restart

ヘルスチェックを有効にします:

openclaw config set --health-check-interval 60

ゲートウェイは60秒ごとに自身のヘルスチェックを行い、応答しない場合は再起動します。

CPU使用率が急上昇する

問題: OpenClawが常にCPUを100%使用する。

原因: 無限ループ、過剰なロギング、またはメッセージの洪水。

修正:

CPUを消費しているものを確認します:

top -p $(pgrep -f "openclaw gateway")

ログレベルを下げます:

openclaw config set --log-level warn

これにより、デバッグログと情報ログが無効になり、I/Oが削減されます。

メッセージの洪水を確認します:

openclaw stats --messages --period 1h

1時間あたり1000件以上のメッセージを受信している場合は、チャネルごとにレート制限を有効にします:

openclaw channels config whatsapp --rate-limit 100 --rate-window 3600

ゲートウェイのクラッシュと再起動

ゲートウェイが起動時にクラッシュする

問題: openclaw gateway がエラーメッセージなしにすぐにクラッシュする。

原因: 設定ファイルの破損または依存関係の欠落。

修正:

デバッグモードで実行します:

openclaw gateway --debug

これにより、詳細なエラーメッセージが表示されます。

よくある原因:

1. 破損した設定: 設定をバックアップしてリセットします

cp ~/.openclaw/config.json ~/.openclaw/config.json.backup
openclaw config reset
openclaw onboard

1. 依存関係の欠落: OpenClawを再インストールします

npm uninstall -g openclaw
npm install -g openclaw@latest

1. ポートが既に使用中: ポートを変更します

openclaw gateway --port 18790

ゲートウェイが動作中にクラッシュする

問題: ゲートウェイがしばらく実行された後、予期せずクラッシュする。

原因: 未処理の例外、メモリリーク、または外部プロセスによる強制終了。

修正:

クラッシュログを確認します:

tail -100 ~/.openclaw/gateway.log

クラッシュ前のスタックトレースまたはエラーメッセージを探してください。

クラッシュダンプを有効にします:

openclaw config set --enable-crash-dumps true

次のクラッシュでダンプが ~/.openclaw/crashes/ に書き込まれます。デバッグのためにこれをOpenClawチームと共有してください。

自動再起動でゲートウェイを実行します:

openclaw gateway --auto-restart

ゲートウェイはクラッシュ後に自動的に再起動します。

本番環境では、プロセスマネージャーを使用します:

# Using pm2
npm install -g pm2
pm2 start openclaw -- gateway
pm2 save
pm2 startup

再起動後にセッションデータが失われる

問題: ゲートウェイの再起動後に会話がリセットされる。

原因: セッションがディスクに永続化されていないか、セッションファイルが破損している。

修正:

セッションの永続化を有効にします:

openclaw config set --persist-sessions true --session-file ~/.openclaw/sessions.db

セッションは30秒ごとにディスクに保存されるようになりました。

セッションファイルを確認します:

ls -lh ~/.openclaw/sessions.db

0バイトまたは欠落している場合、セッションは保存されていません。ディスクスペースを確認してください:

df -h ~

ディスクがいっぱいの場合、スペースを解放しゲートウェイを再起動してください。

バックアップから復元します:

cp ~/.openclaw/sessions.db.backup ~/.openclaw/sessions.db
openclaw gateway restart

プラットフォーム固有の問題

macOS: 「openclaw」を開けません

問題: macOSが「未確認の開発元」の警告でOpenClawをブロックする。

原因: macOS Gatekeeperのセキュリティ機能。

修正:

OpenClawを許可します:

xattr -d com.apple.quarantine $(which openclaw)

または、システム設定 → プライバシーとセキュリティに移動し、OpenClawの警告の横にある「とにかく許可」をクリックします。

Linux: inotifyのパーミッションが拒否されました

問題: 「ENOSPC: ファイルウォッチャーのシステム制限に達しました。」

原因: Linuxは、プロセスが監視できるファイルの数を制限しています。

修正:

制限を増やします:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

OpenClawを再起動します:

openclaw gateway restart

Windows: コマンドが見つかりません

問題: Windowsで openclaw コマンドが認識されない。

原因: npmのグローバルbinディレクトリがPATHに含まれていません。

修正:

npmのグローバルディレクトリを見つけます:

npm config get prefix

PATHに追加します:

1. システムのプロパティ → 環境変数を開きます
2. ユーザー変数の下の「Path」を編集します
3. C:\Users\YourName\AppData\Roaming\npm (または上記のパス) を追加します
4. OKをクリックし、ターミナルを再起動します

確認します:

openclaw --version

Docker: ネットワークの問題

問題: Docker内のOpenClawがメッセージングプラットフォームに接続できない。

原因: Dockerのネットワーク分離。

修正:

ホストネットワークで実行します:

docker run --network host openclaw/openclaw gateway

またはゲートウェイポートを公開します:

docker run -p 18789:18789 openclaw/openclaw gateway

WhatsAppの場合、QRコードスキャン用にさらにポートを公開する必要があります:

docker run -p 18789:18789 -p 3000:3000 openclaw/openclaw gateway

デバッグツールとログ

デバッグログを有効にする

詳細なログを取得します:

openclaw config set --log-level debug
openclaw gateway restart

ログはデフォルトで ~/.openclaw/gateway.log に出力されます。

リアルタイムでログを監視します:

tail -f ~/.openclaw/gateway.log

個々のコンポーネントをテストする

チャネルをテストします:

openclaw channels test whatsapp
openclaw channels test telegram
openclaw channels test discord

エージェントをテストします:

openclaw agents test default --message "Hello"

ルーティングをテストします:

openclaw routing test --channel whatsapp --sender +1234567890 --message "debug issue"

ゲートウェイの状態を検査する

現在の状態を取得します:

openclaw gateway inspect

これには以下が表示されます:

• アクティブなチャネルとそのステータス
• 設定済みエージェントとそのヘルス
• ルーティングルールと優先度
• キューサイズと保留中のメッセージ
• メモリ使用量と稼働時間

診断をエクスポートする

診断レポートを生成します:

openclaw diagnostics export > openclaw-diagnostics.json

これには以下が含まれます:

• 設定 (APIキーは編集済み)
• 最近のログ
• エラー数
• パフォーマンス指標
• システム情報

問題を報告する際に、これをサポートと共有してください。

ネットワークのデバッグ

AIプロバイダーへの接続をテストします:

openclaw network test anthropic
openclaw network test openai

これにより以下を確認します:

• DNS解決
• TLSハンドシェイク
• APIエンドポイントの到達可能性
• 遅延

いずれかのチェックが失敗した場合、ネットワークの問題があります。

FAQ

OpenClawはなぜそんなに多くのメモリを使用するのですか？

OpenClawは高速アクセス用にセッション履歴をメモリに保持します。各セッションは完全な会話コンテキストを保存します。それぞれ50メッセージの100のアクティブなセッションがある場合、それはメモリ内の5000メッセージになります。

メモリ使用量を削減します:

1. セッションタイムアウトを短縮する
2. 自動クリーンアップを有効にする
3. セッションごとのコンテキスト長を制限する

openclaw config set --session-timeout 1800 --auto-cleanup true --max-context-length 50

インターネットなしでOpenClawを実行できますか？

はい、ローカルAIモデルを使用する場合は可能です。Ollamaをインストールし、OpenClawがそれを使用するように設定します:

# Install Ollama
curl https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama2

# Configure OpenClaw
openclaw agents add local --provider ollama --model llama2 --endpoint http://localhost:11434

メッセージングプラットフォームにはインターネットが必要ですが、AI推論はローカルで実行されます。

新しいマシンに移行するにはどうすればよいですか？

設定をエクスポートします:

openclaw config export > openclaw-backup.json

openclaw-backup.json を新しいマシンにコピーします。

OpenClawをインストールします:

npm install -g openclaw@latest

設定をインポートします:

openclaw config import openclaw-backup.json

チャネルを再接続します (QRコードとトークンは転送されません):

openclaw channels login whatsapp
openclaw channels update telegram --token YOUR_TOKEN

メッセージが順不同で届くのはなぜですか？

OpenClawはメッセージを並行して処理します。3つのメッセージをすばやく送信した場合、ネットワークのタイミングによってはAIプロバイダーに異なる順序で到達する可能性があります。

順次処理を有効にします:

openclaw config set --max-concurrent-requests 1

これにより、一度に1つのメッセージを処理し、順序を保持します。処理は遅くなりますが、順序が保証されます。

OpenClawを本番環境で使用できますか？

はい、ただし以下のガイドラインに従ってください:

1. ノートパソコンではなくサーバーで実行する
2. プロセスマネージャー (pm2, systemd) を使用する
3. セッションの永続化を有効にする
4. モニタリングとアラートを設定する
5. レート制限を設定する
6. コントロールUIにリバースプロキシ (nginx) を使用する
7. HTTPSを有効にする
8. 設定を定期的にバックアップする

systemdサービスの例:

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/usr/bin/openclaw gateway --port 18789
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

バグを報告するにはどうすればよいですか？

1. 診断を生成します:

openclaw diagnostics export > diagnostics.json

1. GitHubでイシューを開きます
2. 以下を含めます:

• OpenClawバージョン (openclaw --version)
• Node.jsバージョン (node --version)
• オペレーティングシステム
• 再現手順
• 診断レポート (機密データは編集済み)

まとめ

OpenClawのほとんどの問題は、ネットワークの問題、誤った設定、またはプラットフォーム固有の癖に起因します。このガイドでは、最も一般的な15のエラーとその修正方法を説明しています。

主なトラブルシューティングの手順:

1. まずログを確認する (~/.openclaw/gateway.log)
2. コンポーネントを個別にテストする (チャネル、エージェント、ルーティング)
3. 詳細なエラーのためにデバッグモードを有効にする
4. 診断ツールを使用して状態をエクスポートする
5. コミュニティに参加して助けを求める

OpenClawと共にAPIワークフローを構築している場合、API設計、テスト、ドキュメント作成にはApidogをチェックしてください。これはOpenClawの会話型インターフェースを構造化されたAPI管理で補完します。

次のステップ:

• クイックリファレンスとしてこのガイドをブックマークする
• 問題を早期に検出するためにモニタリングを設定する
• リアルタイムのヘルプのためにOpenClaw Discordに参加する
• GitHubでプロジェクトに修正を貢献する