OpenClawを使っていてAPI呼び出しが失敗したり、接続がタイムアウトした経験はありませんか？この記事では、よく発生するエラーの原因と実際の解決手順をまとめました。作業をすぐに再開できるよう、具体的な対処法を紹介します。
API 401 認証エラー：APIキーと権限を確認
401エラーは、リクエストに有効な認証情報がないことを示します。まず、APIキーが環境変数や設定ファイルに正しく貼り付けられているか確認してください。特に前後の余分なスペースや改行に注意。コンソールからコピー＆ペーストした場合は、手動で再入力することをおすすめします（コピー時に文字が欠落するケースが多いため）。また、一部のモデルやエンドポイントでは追加の権限設定が必要です。開発者コンソールで「アクセス許可」が有効になっているか確認しましょう。
429 リクエスト制限：呼び出し間隔とクォータを調整
短時間に大量のリクエストを送信すると、レート制限が発生し429コードが返ります。この場合、むやみにリトライせず、まず5〜10秒待ってから指数バックオフ戦略で再試行してください。リクエストキューを設定したり、sleep機構を追加すればレート制限を回避しやすくなります。頻繁に発生する場合は、アカウントが試用期間中でないか確認しましょう（試用枠は通常低めです）。プランをアップグレードするか、クォータの引き上げを申請すれば根本的に解決します。また、他のアプリケーションが同じAPI Keyを同時に使用していないかも確認。キーの共有は制限に引っかかりやすくなります。
接続タイムアウトやSocket Hang Up：ネットワークとプロキシを調査
「Connection Timeout」や「Socket Hang Up」は、ネットワークが不安定か、プロキシ設定が適切でないことが原因です。まず、OpenClaw公式サーバーに直接接続できるか、pingやcurlでレイテンシを確認してみてください。プロキシを使っている場合は、プロトコルとポートが正しいか、プロキシがトラフィックをブロックしていないか確認。企業内ネットワークでは非標準ポートが遮断されることがあるため、HTTPSポート（443）に変更すると回避できる場合があります。また、タイムアウト時間が短すぎると誤検出が起こることも。リクエストのタイムアウトパラメータをデフォルトの10秒から30秒に増やしてみてください。
500 Internal Server Error：リクエストボディの形式を優先チェック
サーバーから500エラーが返ってきたら、まずサーバー障害を疑う前に、送信したリクエストの形式に問題がないか確認しましょう。JSONが有効か、フィールド名のスペルは正しいか（例："model"を"module"と書いていないか）。特に、ブール値や数値に引用符が付いていないか注意。例えば"temperature": trueのように書くとエラーになります。リクエストボディが大きい場合は、分割して送信するか、メッセージ配列にサポートされていないロール（例：モデルが対応していないfunctionロール）が含まれていないか確認してください。
403 アクセス拒否：アカウント状態と地域制限
403エラーは、アカウントがロックされているか、地域制限が原因である可能性があります。まずOpenClaw公式サイトにログインし、アカウントの状態を確認。未払いや利用規約違反の警告がないかチェックしてください。一部のモデルは特定の地域でのみ利用可能です。サポートされていない地域のIPを使っている場合は、ノードを変更するかグローバルモードで再試行しましょう。また、無料試用アカウントでは時間経過とともにアクセス権限が低下するケースもあります。継続課金や有料プランへのアップグレードで403が解除されることが多いです。
