トラブルシューティング15 分で読めます

OpenClaw よくあるエラーと解決方法

インストール問題、APIエラー、チャンネル問題、パフォーマンス問題を含むOpenClawの一般的なエラーを診断・修正するための包括的なガイド。

OpenClaw Guides

Tutorial Authors

2025-02-04

クイック診断

特定のエラーに取り組む前に、これらの診断を実行してください：

bash

# 全体的なステータスを確認
openclaw status

# 設定を検証
openclaw config validate

# 最近のエラーログを確認
openclaw logs --tail 50 --level error

# ヘルスチェックを実行
openclaw doctor

インストールエラー

エラー："Node.js version too old"

Error: OpenClaw requires Node.js >= 22.0.0
Current version: 18.17.0

解決方法：

bash

# nvm を使用（推奨）
nvm install 22
nvm use 22
nvm alias default 22

# または Homebrew を使用（macOS）
brew install node@22

# 確認
node --version  # v22.x.x と表示されるはず

エラー："EACCES permission denied"

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

解決方法： sudo を使用しないでください。代わりに npm の権限を修正：

bash

# オプション1：nvm を使用（推奨）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# オプション2：npm のデフォルトディレクトリを変更
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 再インストール
npm install -g openclaw@latest

エラー："Cannot find module"

Error: Cannot find module '@openclaw/core'

解決方法：

bash

# npm キャッシュをクリアして再インストール
npm cache clean --force
npm uninstall -g openclaw
npm install -g openclaw@latest

# またはインストールスクリプトを使用
curl -fsSL https://openclaw.ai/install.sh | bash

エラー："gyp ERR! build error"（ネイティブモジュール）

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

解決方法： ビルドツールをインストール：

bash

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential python3

# Windows
npm install -g windows-build-tools

API と認証エラー

エラー："401 Unauthorized"

Error: API request failed with status 401: Invalid API key

解決方法：

bash

# APIキーが設定されているか確認
openclaw config get api-key

# 空または間違っている場合、再設定
openclaw config set api-key

# キー形式を確認（Anthropic キーは sk-ant- で始まる）
# 余分なスペースや引用符がないことを確認

エラー："429 Rate Limited"

Error: Rate limit exceeded. Please retry after 60 seconds.

解決方法：

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "rateLimiting": {
      "retryOnRateLimit": true,
      "maxRetries": 3,
      "retryDelay": 5000,
      "maxRequestsPerMinute": 30
    }
  }
}

持続的なレート制限の場合、API ティアのアップグレードまたは別のモデルの使用を検討：

bash

openclaw config set default-model claude-3-5-haiku

エラー："402 Payment Required"

Error: API request failed: Insufficient credits

解決方法：

API プロバイダーの残高を確認
アカウントにクレジットを追加
または使用制限を設定：

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "quotas": {
      "daily": {
        "enabled": true,
        "maxTokens": 100000,
        "warningThreshold": 80000
      }
    }
  }
}

エラー："Connection Refused" to API

Error: connect ECONNREFUSED api.anthropic.com:443

解決方法：

bash

# インターネット接続を確認
ping api.anthropic.com

# プロキシの背後にいるか確認
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 必要に応じてプロキシを設定
openclaw config set proxy http://your-proxy:8080

# またはファイアウォール/VPN設定を確認

ゲートウェイエラー

エラー："EADDRINUSE: Port already in use"

Error: listen EADDRINUSE: address already in use :::18789

解決方法：

bash

# ポートを使用しているプロセスを見つける
lsof -i :18789

# プロセスを終了
kill -9 <PID>

# または別のポートを使用
openclaw gateway start --port 18790

# 新しいポートを使用するよう設定を更新
openclaw config set gateway-port 18790

エラー："Gateway failed to start"

Error: Gateway failed to start: Cannot read config file

解決方法：

bash

# 設定ファイルの構文を検証
openclaw config validate

# 破損している場合、デフォルトにリセット
openclaw config reset --confirm

# 再設定
openclaw onboard

エラー："Gateway not responding"

bash

# ゲートウェイが実行中か確認
openclaw status

# 停止している場合、理由を確認
openclaw logs --tail 100

# 再起動を試みる
openclaw gateway restart

# それでも失敗する場合、システムリソースを確認
free -h  # メモリ
df -h    # ディスク容量

チャンネル固有のエラー

WhatsApp："Session expired"

Error: WhatsApp session invalid or expired

解決方法：

bash

# 再認証
openclaw channel disconnect whatsapp
openclaw channel connect whatsapp
# 新しいQRコードをスキャン

WhatsApp："QR code not generating"

bash

# 他のセッションがアクティブか確認
pkill -f "openclaw.*whatsapp"

# 古いセッションデータをクリア
rm -rf ~/.openclaw/whatsapp-session

# 再試行
openclaw channel connect whatsapp

Telegram："Conflict: terminated by other getUpdates"

Error: Conflict: terminated by other getUpdates request

別のインスタンスが同じボットトークンを使用しています。

解決方法：

bash

# すべての OpenClaw インスタンスを停止
pkill -f openclaw

# 他の実行中のインスタンスを確認
ps aux | grep openclaw

# 新しく起動
openclaw gateway start

Discord："Invalid token"

Error: An invalid token was provided

解決方法：

bash

# Discord Developer Portal でトークンを再生成
# Bot → Reset Token

# OpenClaw を更新
openclaw config set discord-token NEW_TOKEN
openclaw gateway restart

Discord："Missing intents"

Error: Disallowed intents specified

解決方法：

Discord Developer Portal に移動
アプリケーション → Bot を選択
"Privileged Gateway Intents" で必要な intents を有効化
保存して OpenClaw を再起動

メモリとパフォーマンスエラー

エラー："JavaScript heap out of memory"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory

解決方法：

bash

# Node.js のメモリ制限を増加
export NODE_OPTIONS="--max-old-space-size=4096"

# 永続化のためシェルプロファイルに追加
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

# OpenClaw を再起動
openclaw gateway restart

エラー："Too many open files"

Error: EMFILE: too many open files

解決方法：

bash

# 現在の制限を確認
ulimit -n

# 制限を増加（一時的）
ulimit -n 65535

# 制限を増加（永続的 - Linux）
echo "* soft nofile 65535" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65535" | sudo tee -a /etc/security/limits.conf

# macOS
sudo launchctl limit maxfiles 65535 200000

応答時間が遅い

診断：

bash

# モデルのレイテンシーを確認
openclaw benchmark

# システムリソースを確認
openclaw stats

解決方法：

json

// ~/.openclaw/openclaw.json
{
  "model": {
    "default": "claude-3-5-haiku",
    "streaming": true,
    "maxContextTokens": 4096
  },
  "gateway": {
    "caching": {
      "enabled": true,
      "ttl": 300
    }
  }
}

設定エラー

エラー："Invalid YAML syntax"

Error: Config file has invalid YAML syntax at line 15

解決方法：

bash

# YAML を検証
openclaw config validate

# よくある問題：
# - スペースの代わりにタブ（2スペースを使用）
# - キーの後のコロン欠落
# - 引用符なしの特殊文字

# 修正またはリセット
openclaw config edit
# または
openclaw config reset --confirm

エラー："Unknown configuration key"

Warning: Unknown configuration key 'gateway.unknownOption'

解決方法：

bash

# 利用可能なオプションを確認
openclaw config list

# 不明なキーを削除
openclaw config edit

エラー："Environment variable not set"

Error: Required environment variable ANTHROPIC_API_KEY is not set

解決方法：

bash

# .env ファイルに追加
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> ~/.openclaw/.env

# またはシェルでエクスポート
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# 永続化のためシェルプロファイルに追加
echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.bashrc

データベースとストレージエラー

エラー："Database locked"

Error: SQLITE_BUSY: database is locked

解決方法：

bash

# OpenClaw を停止
openclaw gateway stop

# ロックファイルを確認
ls -la ~/.openclaw/*.lock

# 古いロックを削除
rm ~/.openclaw/*.lock

# 再起動
openclaw gateway start

エラー："Disk quota exceeded"

Error: ENOSPC: no space left on device

解決方法：

bash

# ディスク使用量を確認
df -h

# OpenClaw のログとキャッシュをクリア
openclaw cache clear
openclaw logs clear --older-than 7d

# 古いセッションをクリア
rm -rf ~/.openclaw/sessions/*.old

さらなるヘルプ

デバッグログを有効化

bash

# デバッグモードを設定
export OPENCLAW_DEBUG=true
openclaw gateway start

# または設定で設定
openclaw config set logLevel debug

診断レポートを生成

bash

openclaw doctor --report > diagnostic-report.txt

コミュニティサポート

Discord: discord.gg/openclaw
GitHub Issues: github.com/openclaw/openclaw/issues
ドキュメント: docs.openclaw.ai

バグレポートの提出

問題を報告する際は、以下を含めてください：

bash

# システム情報
openclaw --version
node --version
uname -a

# 設定（機密データを隠す）
openclaw config show --redact

# 最近のログ
openclaw logs --tail 100

クイック診断

インストールエラー

エラー："Node.js version too old"

エラー："EACCES permission denied"

エラー："Cannot find module"

エラー："gyp ERR! build error"（ネイティブモジュール）

API と認証エラー

エラー："401 Unauthorized"

エラー："429 Rate Limited"

エラー："402 Payment Required"

エラー："Connection Refused" to API

ゲートウェイエラー

エラー："EADDRINUSE: Port already in use"

エラー："Gateway failed to start"

エラー："Gateway not responding"

チャンネル固有のエラー

WhatsApp："Session expired"

WhatsApp："QR code not generating"

Telegram："Conflict: terminated by other getUpdates"

Discord："Invalid token"

Discord："Missing intents"

メモリとパフォーマンスエラー

エラー："JavaScript heap out of memory"

エラー："Too many open files"

応答時間が遅い

設定エラー

エラー："Invalid YAML syntax"

エラー："Unknown configuration key"

エラー："Environment variable not set"

データベースとストレージエラー

エラー："Database locked"

エラー："Disk quota exceeded"

さらなるヘルプ

デバッグログを有効化

診断レポートを生成

コミュニティサポート

バグレポートの提出

次のステップ