メインコンテンツまでスキップ

接続エラー

このページでは、Elftia におけるさまざまなネットワーク接続問題のトラブルシューティングに焦点を当てます。LLM API 呼び出しエラー、プロキシ関連の失敗、SSL/TLS の問題、MCP 接続失敗、Channel 接続の異常を扱います。

LLM API HTTP ステータスコード​

LLM API 呼び出しでエラーが返された場合、HTTP ステータスコードが最も重要なトラブルシューティングの手がかりです。各ステータスコードの意味と解決策は次のとおりです。

401 Unauthorized​

意味: API Key が無効、または提供されていません。

よくある原因:

  • API Key に余分なスペースや改行が含まれている
  • API Key が取り消された、または期限切れになっている
  • API Key の形式が正しくない（例: OpenAI のキーは sk- で始まる必要があります）
  • 間違ったプロバイダーのキーを使用している

解決手順:

  1. 設定 → プロバイダー設定 に移動し、API Key を再確認します。
  2. 完全なキーをコピーし、入力欄の既存の値を置き換えます。
  3. プロバイダーのコンソールに移動し、そのキーがまだ有効であることを確認します。
  4. API Key プールを使用している場合は、プール内に無効なキーがないか確認します（無効化されたキーは灰色で表示されます）。
備考

プール内の API Key が 401 を返した場合、そのキーは自動的に無効化され、システムはプール内の別の利用可能なキーへ自動的に切り替えます。

403 Forbidden​

意味: 認証には成功しましたが、権限が不足しています。

よくある原因:

  • アカウント残高が不足している、または支払い方法が紐付けられていない
  • API Key に要求したモデルへのアクセス権がない
  • IP アドレスまたは地域がプロバイダーによって制限されている
  • 組織またはプロジェクトの権限制限

解決手順:

  1. プロバイダーのコンソールにログインし、アカウント残高と支払い状況を確認します。
  2. API Key が選択したモデルにアクセスできることを確認します（一部の高度なモデルでは特別な権限が必要です）。
  3. プロキシを使用している場合は、別の地域のプロキシノードに切り替えてみます。
  4. プロバイダーのコンソールで組織とプロジェクトの設定を確認します。

429 Too Many Requests​

意味: リクエスト頻度が高すぎるため、レート制限が発動しています。

よくある原因:

  • 短時間に送信したリクエストが多すぎる
  • アカウントのレートクォータが低い（無料または低ティアのアカウント）
  • 複数のアプリケーションが同じ API Key を共有している

解決手順:

  1. しばらく待ってから再試行します。Elftia はクールダウン通知を表示します。
  2. 頻繁に発生する場合は、プロバイダーアカウントのティアをアップグレードすることを検討してください。
  3. 複数のキーを使用してリクエストを分散する API Key プール を設定します。

Elftia の自動処理:

  • 429 が発生すると、現在のキーはクールダウン期間に入ります（60 秒から開始し、指数バックオフで最大 15 分まで延長されます）。
  • API Key プールが設定されている場合、システムは別の利用可能なキーへ自動的に切り替えて再試行します。
  • クールダウン期間が終了すると、キーは自動的に回復します。

500 Internal Server Error​

意味: プロバイダーサーバーの内部エラーです。

解決手順:

  1. これはプロバイダー側の問題であり、通常は自然に解消されます。数分待ってから再試行してください。
  2. 既知の障害がないか、プロバイダーのステータスページを確認します。
  3. 問題が続く場合は、別のモデルまたはプロバイダーへの切り替えを試してください。

502 Bad Gateway​

意味: プロバイダーのゲートウェイまたはロードバランサーのエラーです。

解決手順:

  1. 通常は一時的な問題です。1〜5 分待ってから再試行してください。
  2. プロバイダーのステータスページを確認します。
  3. カスタム Base URL（サードパーティのリレー）を使用している場合は、リレーサービスが動作しているか確認します。

503 Service Unavailable​

意味: プロバイダーサービスが一時的に利用できません（メンテナンスまたは過負荷）。

解決手順:

  1. プロバイダーがサービスを復旧するまで待ちます。
  2. 作業を続けるためにバックアッププロバイダーへ切り替えます。
  3. 復旧予定時刻について、プロバイダーのステータスページやソーシャルメディアを確認します。

529 Overloaded​

意味: プロバイダーサーバーが過負荷です（Anthropic 固有のステータスコード）。

解決手順:

  1. しばらく待ってから再試行します。
  2. API Key プールが設定されている場合、システムは自動的にキーを切り替えて再試行します。
  3. サーバー負荷を下げるため、より小さいモデル（例: Claude Opus ではなく Claude Haiku）を使ってみます。

Elftia の自動処理: 429 と同様に、クールダウンと自動キー切り替えの仕組みが発動します。

プロキシ関連エラー​

ECONNREFUSED​

意味: 接続が拒否されました。通常はプロキシサービスが起動していません。

Error: connect ECONNREFUSED 127.0.0.1:7890

解決手順:

  1. プロキシクライアント（Clash、V2Ray、Shadowsocks など）が起動していることを確認します。
  2. プロキシのリッスンポートが Elftia で設定したポートと一致しているか確認します。
  3. プロキシが正しいアドレス（127.0.0.1 と 0.0.0.0 の違い）でリッスンしていることを確認します。
  4. プロキシが不要な場合は、設定 → 一般 → プロキシ で「プロキシなし」に切り替えます。

ETIMEDOUT​

意味: 接続タイムアウトです。プロキシがターゲットサーバーに到達できません。

Error: connect ETIMEDOUT api.openai.com:443

解決手順:

  1. プロキシの上流接続が動作しているか確認します（プロキシがターゲットドメインにアクセスできるか）。
  2. プロキシのルーティングルールに LLM API ドメインが含まれているか確認します。
  3. プロキシノードの切り替えを試します。
  4. ファイアウォールルールを確認します。

ECONNRESET​

意味: リモートによって接続がリセットされました。通常はプロキシがストリーム途中で切断しています。

解決手順:

  1. プロキシ接続の安定性を確認します。
  2. プロキシのタイムアウト設定を延長します。
  3. 長いストリーミングリクエスト（例: 大規模なコード生成）の場合、プロキシに接続時間の制限がある可能性があるため、調整が必要です。

SSL/TLS エラー​

UNABLE_TO_VERIFY_LEAF_SIGNATURE​

意味: サーバー証明書を検証できません。通常は自己署名証明書が原因です。

よくある状況:

  • 企業プロキシが HTTPS インスペクションのために自己署名 CA 証明書を使用している
  • 自前構築の LLM API リレーサービスが自己署名証明書を使用している

解決手順:

  1. プロキシまたはリレーサービスの証明書をインストールして信頼します。
    • Windows: 証明書ファイルをダブルクリック → 証明書のインストール → ローカルコンピューター → 信頼されたルート証明機関。
    • macOS: 証明書ファイルをダブルクリック → キーチェーンに追加 → 常に信頼。
    • Linux: /usr/local/share/ca-certificates/ にコピー → sudo update-ca-certificates を実行。
  2. 証明書の変更を反映するため、Elftia を再起動します。

CERT_HAS_EXPIRED​

意味: サーバーの SSL 証明書が期限切れです。

解決手順:

  1. 自前構築のサービスであれば、SSL 証明書を更新します。
  2. 公開サービスであれば、通常は一時的な問題です。後で再試行してください。
  3. システム時刻が正しいか確認します（システム時刻が誤っていると、有効な証明書が期限切れとして扱われることがあります）。

ERR_TLS_CERT_ALTNAME_INVALID​

意味: 証明書のドメインが実際にアクセスしているドメインと一致していません。

解決手順:

  1. プロバイダーの Base URL のスペルが正しいか確認します。
  2. カスタムエンドポイントを使用している場合は、サーバー証明書が使用中のドメインをカバーしていることを確認します。

MCP 接続エラー​

stdio mode — ENOENT​

意味: MCP サーバーの起動コマンドが見つかりません。

Error: spawn npx ENOENT

解決手順:

  1. command フィールドに指定したプログラムがインストールされていることを確認します。
    • npx / node: Node.js をインストールする必要があります。
    • uvx / python: Python と uv をインストールする必要があります。
  2. ターミナルでコマンドを手動実行し、実行可能か確認します。
  3. 設定 → 一般 → 環境 でツールのインストール状態を確認します。
  4. ツールがインストール済みでもエラーが続く場合は、PATH 環境変数を更新するために Elftia の再起動が必要なことがあります。

stdio mode — 起動直後にプロセスが終了する​

症状: MCP サーバーが短時間だけ接続済みになり、その後切断されます。

考えられる原因:

  • 必要な npm/pip 依存関係が不足している
  • 起動パラメーターが正しくない
  • 必要な環境変数が不足している

解決手順:

  1. ターミナルで MCP サーバーコマンドを手動実行し、エラー出力を確認します。 
    npx -y @modelcontextprotocol/server-filesystem /path
  2. 不足している依存パッケージを確認し、手動でインストールします。 
    npm install -g @modelcontextprotocol/server-filesystem
  3. MCP 設定内の env に、必要な環境変数がすべて含まれていることを確認します。

SSE/HTTP mode — 接続タイムアウト​

症状: リモート MCP サーバーへの接続がタイムアウトします。

解決手順:

  1. MCP サーバーが起動しており、現在のネットワークからアクセス可能であることを確認します。
  2. ブラウザーで MCP サーバーの URL にアクセスし、接続性を確認します。
  3. ファイアウォールが MCP サーバーのポートへのアクセスを許可しているか確認します。
  4. プロキシを使用している場合は、プロキシルールが MCP サーバーのアドレスへのアクセスを許可していることを確認します。

SSE mode — 接続が頻繁に切断される​

症状: SSE 接続が確立後に頻繁に切断され、再接続されます。

考えられる原因:

  • ネットワークが不安定
  • プロキシまたはロードバランサーの接続タイムアウト設定が短すぎる
  • MCP サーバー自体が不安定

解決手順:

  1. ネットワーク接続の安定性を確認します。
  2. プロキシまたはリバースプロキシを使用している場合は、接続タイムアウトとアイドルタイムアウトの設定を延長します。
  3. サービス状況を確認するため、MCP サーバーのメンテナーに連絡します。

Channel 接続エラー​

Discord Bot の接続に失敗する​

考えられる原因:

  • Bot Token が無効または期限切れ
  • Bot が対象サーバーに招待されていない
  • Bot に必要な権限がない
  • Discord API のレート制限

解決手順:

  1. Discord Developer Portal で Bot Token が正しいことを確認します。
  2. Bot が発言権限付きで対象の Discord サーバーに招待されていることを確認します。
  3. Bot の Privileged Gateway Intents が有効になっているか確認します。

Telegram Bot の接続に失敗する​

考えられる原因:

  • Bot Token が無効
  • ネットワークから Telegram API（api.telegram.org）にアクセスできない
  • 別のクライアントが同じ Bot Token を使用している

解決手順:

  1. @BotFather で Bot Token が正しいことを確認します。
  2. ネットワークから api.telegram.org にアクセスできることを確認します（プロキシが必要な場合があります）。
  3. 他のアプリケーションが同じ Bot Token を使用していないことを確認します。

レート制限とバックオフの仕組み​

Elftia には、レート制限を賢く処理する仕組みが組み込まれています。

API Key プールの自動切り替え​

単一のキーで 429/529 エラーが発生した場合:

  1. 現在のキーがクールダウン期間に入ります。
  2. システムはプール内の次の利用可能なキーを即座に試します。
  3. リクエストが成功すれば、ユーザーがほとんど気づくことはありません。
  4. クールダウンには指数バックオフが使用されます: 60s → 120s → 240s → ... → 最大 15 分。
  5. クールダウン終了後、キーは自動的に回復します。

セッションアフィニティ​

LLM プロバイダーのプロンプトキャッシュ効率を維持するため、同じチャットセッションでは同じ API Key を使うようにします。

  • 初回リクエストでは、重み付きラウンドロビンでキーを選択します。
  • 以降のリクエストでは、同じキーを優先します。
  • 紐付けられたキーが利用不可（クールダウン中または無効化済み）の場合のみ切り替えます。

永続的な失敗の処理​

キーが 401/403 を返した場合、そのキーは恒久的に無効です。

  • そのキーは自動的に無効化されます（利用不可としてマークされます）。
  • システムは別のキーへ切り替えます。
  • 無効化されたキーは、プロバイダー設定の API Key プールで確認できます。

ファイアウォールとウイルス対策ソフトウェア​

ファイアウォールが外向き接続をブロックする​

症状: すべての LLM API 呼び出しがタイムアウトする、または拒否されます。

解決手順:

  1. Elftia をファイアウォールの許可リストに追加します。
    • Windows Defender Firewall: コントロールパネル → Windows Defender Firewall → ファイアウォールによるアプリケーションの許可 → Elftia を追加。
    • macOS: システム環境設定 → セキュリティとプライバシー → ファイアウォール → Elftia を許可。
  2. 企業ファイアウォールを使用している場合は、以下への外向きアクセスを開放するよう IT 管理者に連絡してください。
    • api.openai.com (OpenAI)
    • api.anthropic.com (Anthropic)
    • generativelanguage.googleapis.com (Google Gemini)
    • api.deepseek.com (DeepSeek)

ウイルス対策ソフトウェアの誤検知​

症状: ウイルス対策ソフトウェアが Elftia の起動またはネットワーク接続をブロックします。

解決手順:

  1. Elftia のインストールディレクトリをウイルス対策ソフトウェアの除外または許可リストに追加します。
  2. 除外対象として一般的なパス:
    • Windows: C:\Users\<username>\AppData\Local\Elftia\
    • macOS: /Applications/Elftia.app

ネットワーク接続の簡易チェック​

接続問題が発生した場合は、次の順序でトラブルシューティングしてください。

  1. 基本ネットワーク: ブラウザーで任意の Web ページを開き、ネットワークが動作していることを確認します。
  2. DNS 解決: ping api.openai.com（または対応するプロバイダードメイン）を実行し、ドメイン解決を確認します。
  3. ポート接続性: curl -I https://api.openai.com を実行し、ポート 443 にアクセスできることを確認します。
  4. プロキシテスト: プロキシを使用している場合は、ターミナルでプロキシ環境変数を設定し、上記のコマンドを再試行します。
  5. Elftia テスト: Elftia のプロバイダー設定で「接続テスト」を使用します。

手順 1〜4 が成功して手順 5 が失敗する場合、Elftia のプロキシ設定に問題がある可能性があります。再設定については プロキシの使用 を参照してください。

このページで発生している接続問題を扱っていない場合は、診断ツール を使用して診断情報をエクスポートし、コミュニティで支援を求めてください。