OpenClaw API接続エラーの完全トラブルシューティングガイド

はじめに

OpenClaw は各種AIモデルプロバイダーの API と通信する必要があります。使用中にさまざまな接続エラーに遭遇することがあるでしょう。本記事では、各エラーの原因と解決策を体系的にご紹介し、問題の迅速な特定と修正をお手伝いします。

一、クイック診断ツール

トラブルシューティングの前に、まず OpenClaw 内蔵の診断ツールを使用します：

# 総合診断の実行
openclaw doctor

# リアルタイムログでエラーを確認
openclaw logs | grep -i "error\|fail\|timeout"

# API 接続のテスト
curl -v 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-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

二、HTTP エラーコード詳細解説

2.1 401 Unauthorized — 認証失敗

症状：

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

原因と解決策：

# 設定ファイルの API Key を確認
cat ~/.config/openclaw/openclaw.json5 | grep -i "key\|token"

# Key のフォーマットが正しいか確認（Anthropic の場合は sk-ant- で始まる）
# 更新後に再起動
openclaw restart

2.2 403 Forbidden — 権限不足

症状：

Error: API request failed with status 403: Permission denied

よくある原因：

• API Key に対応モデルへのアクセス権限がない
• アカウントで特定のモデル（Claude Opus など）の使用資格が付与されていない
• IP アドレスが API プロバイダーによってブロックされている
• 所在地域がサービス対象外

# IP 制限の問題かどうか確認
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -w "\n%{http_code}" 2>&1

# プロキシを使用している場合、プロキシ設定が正しいか確認
echo $HTTP_PROXY
echo $HTTPS_PROXY

2.3 429 Too Many Requests — レート制限

症状：

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

各プロバイダーのレート制限の目安：

解決策：

// ~/.config/openclaw/openclaw.json5
{
  "rateLimiting": {
    // グローバルリクエスト間隔（ミリ秒）
    "minInterval": 1000,
    // レート制限時のリトライ戦略
    "retry": {
      "enabled": true,
      "maxRetries": 3,
      "backoffMultiplier": 2,
      "initialDelay": 5000
    }
  }
}

2.4 500 Internal Server Error — サーバー内部エラー

対処方法：

# 通常はプロバイダー側の問題です。サービスステータスページを確認してください
# Anthropic: https://status.anthropic.com
# OpenAI: https://status.openai.com

# バックアップモデルへの自動切り替えを設定

// ~/.config/openclaw/openclaw.json5
{
  "models": {
    "primary": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-20250514"
    },
    "fallback": {
      "provider": "openai",
      "model": "gpt-4o"
    }
  }
}

2.5 502/503 Bad Gateway / Service Unavailable

症状：

Error: 502 Bad Gateway
Error: 503 Service Unavailable - The server is temporarily overloaded

トラブルシューティング手順：

# 1. プロバイダーのサービス障害かどうか確認
curl -s -o /dev/null -w "%{http_code}" https://api.anthropic.com/v1/messages

# 2. ローカルネットワークが正常か確認
ping api.anthropic.com
traceroute api.anthropic.com

# 3. リバースプロキシを使用している場合、プロキシが正常か確認
nginx -t
systemctl status nginx

三、タイムアウト問題のトラブルシューティング

3.1 接続タイムアウト

Error: connect ETIMEDOUT 104.18.0.1:443

# API エンドポイントへの接続テスト
curl -v --connect-timeout 10 https://api.anthropic.com/v1/messages

# 接続がタイムアウトする場合、プロキシの設定が必要かもしれません

// ~/.config/openclaw/openclaw.json5
{
  "proxy": {
    "enabled": true,
    "url": "http://127.0.0.1:7890",
    // または SOCKS5 プロキシを使用
    // "url": "socks5://127.0.0.1:1080"
  },
  "timeout": {
    "connect": 30000,    // 接続タイムアウト 30秒
    "request": 120000    // リクエストタイムアウト 120秒
  }
}

3.2 リクエストタイムアウト

モデルが長文テキストを生成する際、デフォルトのタイムアウト時間を超える場合があります：

// タイムアウト時間を延長
{
  "timeout": {
    "request": 300000  // 5分
  }
}

四、DNS 解決の失敗

症状：

Error: getaddrinfo ENOTFOUND api.anthropic.com
Error: querySrv ESERVFAIL _http._tcp.api.openai.com

解決策：

# 1. DNS 解決の確認
nslookup api.anthropic.com
dig api.anthropic.com

# 2. パブリック DNS の使用を試す
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee -a /etc/resolv.conf

# 3. hosts レコードを手動で追加（一時的な対処）
echo "104.18.0.1 api.anthropic.com" | sudo tee -a /etc/hosts

# 4. 修正後の名前解決をテスト
nslookup api.anthropic.com

五、SSL 証明書エラー

症状：

Error: unable to verify the first certificate
Error: self signed certificate in certificate chain
Error: CERT_HAS_EXPIRED

トラブルシューティングと解決：

# 1. 証明書情報の確認
openssl s_client -connect api.anthropic.com:443 -servername api.anthropic.com </dev/null 2>/dev/null | openssl x509 -noout -dates

# 2. システム CA 証明書の更新
# Ubuntu/Debian
sudo apt update && sudo apt install -y ca-certificates
sudo update-ca-certificates

# CentOS/RHEL
sudo yum install -y ca-certificates
sudo update-ca-trust

# 3. プロキシの中間者証明書が原因の場合
# プロキシの CA 証明書を Node.js の信頼リストに追加
export NODE_EXTRA_CA_CERTS=/path/to/proxy-ca.crt

警告：本番環境では絶対に NODE_TLS_REJECT_UNAUTHORIZED=0 を設定しないでください。SSL 検証が完全に無効化され、深刻なセキュリティリスクとなります。

六、プロキシ設定の問題

6.1 HTTP プロキシ

// ~/.config/openclaw/openclaw.json5
{
  "proxy": {
    "enabled": true,
    "url": "http://127.0.0.1:7890"
  }
}

6.2 環境変数方式

# システム環境で設定
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1

# OpenClaw を再起動
openclaw restart

6.3 プロキシ接続テスト

# プロキシ経由で API アクセスをテスト
curl -x http://127.0.0.1:7890 -v https://api.anthropic.com/v1/messages

# SOCKS5 プロキシのテスト
curl -x socks5://127.0.0.1:1080 -v https://api.anthropic.com/v1/messages

七、各プロバイダー別トラブルシューティング

7.1 Anthropic (Claude)

# API Key の有効性を検証
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":5,"messages":[{"role":"user","content":"test"}]}'

よくある問題：API Key のフォーマットは sk-ant-api03-... です。OpenAI の Key と混同しないようご注意ください。

7.2 OpenAI (GPT)

# API Key の検証
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"test"}],"max_tokens":5}'

よくある問題：無料枠を使い切ると 429 エラーが返されます。有料プランへの登録が必要です。

7.3 Ollama（ローカルモデル）

# Ollama サービスが稼働しているか確認
curl http://localhost:11434/api/tags

# モデルがダウンロード済みか確認
ollama list

# モデル呼び出しのテスト
curl http://localhost:11434/api/generate \
  -d '{"model":"llama3","prompt":"test","stream":false}'

よくある問題：Ollama はデフォルトで localhost のみリッスンします。OpenClaw が別のマシンにある場合は OLLAMA_HOST=0.0.0.0 の設定が必要です。

7.4 OpenRouter

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-4-20250514","messages":[{"role":"user","content":"test"}]}'

八、エラートラブルシューティングチェックリスト

API 接続エラーが発生した場合、以下の順序でトラブルシューティングを行ってください：

1. ✅ openclaw doctor を実行して診断結果を確認
2. ✅ API Key が正しく、期限切れでないことを確認
3. ✅ ネットワーク接続を確認（ping、curl）
4. ✅ プロキシ設定が正しいことを確認（プロキシ使用時）
5. ✅ DNS 解決が正常に機能しているか確認
6. ✅ SSL 証明書が有効であるか検証
7. ✅ プロバイダーのサービスステータスページを確認
8. ✅ レート制限がトリガーされていないか確認
9. ✅ openclaw logs で詳細なエラー情報を確認
10. ✅ curl で直接 API を呼び出し、OpenClaw 自体の問題を除外

これらのトラブルシューティングスキルを身につけることで、大半の API 接続問題を迅速に特定・解決し、OpenClaw サービスの安定稼働を維持できるようになります。