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

よくある問題

このページでは、Elftia を使用する際に最もよく遭遇する問題とその解決策をまとめています。各問題には症状の説明、考えられる原因、および具体的なトラブルシューティング手順が含まれています。

起動とインターフェイスの問題​

アプリ起動後に白い画面が表示される​

症状： Elftia を開いた後、ウィンドウが空白または白い画面で、インターフェイスのコンテンツが何も表示されない。

考えられる原因：

  • GPU アクセラレーションとグラフィックカードドライバーの非互換性
  • フロントエンドのレンダラープロセスのクラッシュ
  • インストールファイルの破損

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

  1. Elftia を閉じ、コマンドラインから --disable-gpu パラメーターを付けて起動し、GPU の問題かどうかをテストします。
  2. グラフィックカードドライバーを最新バージョンに更新します。
  3. システムに残っている Elftia のプロセスがないか確認します。タスクマネージャーで関連するすべてのプロセスを終了してから再試行してください。
  4. 問題が続く場合は、Elftia を再インストールしてみてください。

アプリが起動直後にクラッシュする​

症状： ダブルクリックで起動すると、ウィンドウが一瞬表示されてすぐに閉じる。

考えられる原因：

  • システムのランタイム依存関係の欠如（Visual C++ Redistributable など）
  • ユーザーデータディレクトリの権限の問題
  • 古いバージョンの残留データによる競合

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

  1. Windows：最新バージョンの Visual C++ Redistributable をインストールします。
  2. ユーザーデータディレクトリへの書き込み権限があるか確認します。
  3. ユーザーデータディレクトリのキャッシュファイルを削除してから再起動してみます（会話データは失われません）。
  4. 管理者権限で Elftia を実行します。

インターフェイスの文字が文字化けしている​

症状： インターフェイスのテキストが四角いボックスや意味不明な文字として表示される。

考えられる原因：

  • カスタムフォント設定でシステムにインストールされていないフォントが指定されている
  • フォントファイルが破損している

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

  1. 設定 → 外観 を開き、UI フォントとコードフォントのカスタム入力フィールドをクリアします。
  2. 設定ページにアクセスできない場合は、ユーザーデータディレクトリのテーマ設定ファイルを手動で削除します。

LLM プロバイダーの問題​

プロバイダーのテスト接続失敗 — 401​

症状： テスト接続で 401 Unauthorized または Invalid API Key が表示される。

考えられる原因：

  • API Key の入力誤り（余分なスペース、プレフィックスの欠落など）
  • API Key の有効期限切れまたは失効
  • 別のプロバイダーの API Key を使用している

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

  1. API Key を再度コピーし、余分なスペースや改行がないことを確認します。
  2. プロバイダーのコンソールにアクセスして、Key がまだ有効であることを確認します。
  3. API Key が正しいプロバイダーと一致していることを確認します。

プロバイダーのテスト接続失敗 — 403​

症状： テスト接続で 403 Forbidden が表示される。

考えられる原因：

  • アカウントの残高不足または支払い方法が登録されていない
  • API Key に十分な権限がない（読み取り専用 Key など）
  • IP アドレスがプロバイダーによってブロックされている

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

  1. プロバイダーアカウントの残高と支払い状況を確認します。
  2. API Key にモデルを呼び出す権限があることを確認します。
  3. プロキシを使用している場合は、別のプロキシノードに切り替えてみてください。

プロバイダーのテスト接続タイムアウト​

症状： テスト接続で長時間応答がなく、最終的にタイムアウトする。

考えられる原因：

  • ネットワーク接続の問題
  • プロキシ設定の誤り
  • ファイアウォールが送信リクエストをブロックしている

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

  1. ネットワーク接続が正常かどうか確認します。
  2. プロキシを使用している場合は、プロキシが動作していて正しく設定されていることを確認します（プロキシを使用する を参照）。
  3. ファイアウォールが Elftia のインターネットアクセスを許可していることを確認します。
  4. ブラウザでプロバイダーの API ドメイン（例：api.openai.com）に直接アクセスし、ドメインが解決できることを確認します。

ストリーム返信が中断される​

症状： AI の返信が途中で止まり、メッセージが不完全になる。

考えられる原因：

  • ネットワーク接続が不安定で SSE ストリームが中断される
  • 応答がモデルの最大トークン上限に達した
  • プロキシの接続タイムアウト設定が短すぎる

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

  1. 返信を再生成してみてください。
  2. 繰り返し発生する場合は、ネットワーク接続の安定性を確認します。
  3. プロキシ（使用している場合）のタイムアウト設定が少なくとも 120 秒であることを確認します。
  4. モデルパラメーターの max_tokens の値を減らすか、長い返信リクエストを分割します。

Agent 関連の問題​

Agent ツールが実行できない​

症状： Agent がツール（Bash、Write など）を使用しようとすると、権限が拒否されると表示される。

考えられる原因：

  • GuardianAgent が厳格モードに設定されていて操作をブロックしている
  • 権限モードが「プランのみ」に設定されている
  • 実行ファイアウォールの確定的ルールによって操作がブロックされている

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

  1. 設定 → Clawia → GuardianAgent モード を確認し、必要に応じてセキュリティレベルを下げます。
  2. 権限モードが「プランのみ」に設定されていないか確認します。
  3. 監査ログ を確認し、どのセキュリティレイヤーが操作をブロックしたかを確認します。

Agent ツール実行失敗 — command not found​

症状： Agent が Shell コマンドを実行すると command not found と表示される。

考えられる原因：

  • 必要なコマンドラインツールがシステムにインストールされていない
  • 環境変数 PATH にツールのパスが含まれていない

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

  1. 設定 → 全般 → 環境 を開き、ツールのインストール状態を確認します。
  2. 不足しているツール（Node.js、Git など）をインストールします。
  3. ツールがインストール済みでも見つからない場合は、環境変数を更新するために Elftia を再起動する必要があるかもしれません。

MCP 関連の問題​

MCP サーバーに接続できない — stdio モード​

症状： 追加した MCP サーバーが stdio（サブプロセス）モードで接続失敗と表示される。

考えられる原因：

  • コマンドが存在しないかパスが誤っている
  • 依存関係がインストールされていない（Node.js パッケージが未インストールなど）
  • 環境変数が不足している

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

  1. MCP サーバーのコマンドがターミナルで直接実行できることを確認します（例：npx -y @modelcontextprotocol/server-filesystem /path）。
  2. Node.js（node --version）または Python（python --version）がインストールされているか確認します。
  3. MCP サーバーが追加の環境変数（API Key など）を必要とする場合は、MCP 設定の env に正しく設定されていることを確認します。
  4. Elftia を再起動してから再試行します。

MCP サーバーに接続できない — SSE/HTTP モード​

症状： リモート MCP サーバーへの接続がタイムアウトするか拒否される。

考えられる原因：

  • MCP サーバーが動作していない
  • URL またはポートが誤っている
  • ネットワーク / ファイアウォールが接続をブロックしている

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

  1. MCP サーバーが動作していてアクセス可能であることを確認します。
  2. URL のフォーマットが正しいか確認します（http:// または https:// プレフィックスが含まれているか）。
  3. プロキシを使用している場合は、プロキシのルールが MCP サーバーのアドレスへのアクセスを許可していることを確認します。

チャンネル関連の問題​

チャンネルボットが返信しない​

症状： Discord/Telegram などのプラットフォームからメッセージを送信しても、ボットが返信しない。

考えられる原因：

  • トリガールールが一致していない（例：@メンションが必要なのに @していない）
  • メッセージが PromptGuardian によってブロックされている
  • チャンネルが起動していないか、Token の設定が誤っている
  • レート制限が発動している

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

  1. メッセージがチャンネルのトリガールール（@メンション、キーワード、プレフィックスなど）を満たしていることを確認します。
  2. PromptGuardian のモードを確認し、インジェクション検知の誤検知かどうかをテストするために一時的に「オフ」に設定します。
  3. チャンネルの Bot Token が正しく、Bot がオンラインであることを確認します。
  4. 監査ログでブロックされたメッセージの記録がないか確認します。

メディア生成の問題​

画像 / 動画 / 音楽の生成が失敗する​

症状： メディアコンテンツの生成をリクエストするとエラーが発生する。

考えられる原因：

  • 対応するメディア生成プロバイダーが設定されていないか、残高が不足している
  • リクエストのコンテンツがプロバイダーのセキュリティフィルターによって拒否された
  • ネットワーク接続の問題

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

  1. メディア生成に使用するプロバイダーが正しく設定されていて残高が十分であることを確認します。
  2. 生成プロンプトを簡略化または変更して、センシティブなコンテンツを避けてみてください。
  3. ネットワーク接続とプロキシの設定を確認します。

表示の問題​

壁紙を設定したがテキストが読みにくい​

症状： 壁紙を設定した後、透明度が高すぎてインターフェイスの一部のテキストが読みにくい。

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

  1. マスク不透明度 の値を大きくします（70〜85 を推奨）。
  2. ブラーの強度 の値を大きくします（8〜15 を推奨）。
  3. 特定のエリアがまだ読みにくい場合は、カスタム CSS を使用して調整します。

ダークモードでインターフェイスの要素が見えない​

症状： ダークモードで、一部のボーダー、区切り線、またはテキストの色が薄すぎて読みにくい。

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

  1. 別のアクセントカラーに切り替えてみてください。ダークモードでコントラストが良いカラーがあります。
  2. カスタム CSS が色の表示に影響していないか確認し、カスタム CSS をクリアしてみてください。
  3. モニターの輝度を上げます。

パフォーマンスの問題​

メモリ使用量が高い​

症状： Elftia のメモリ使用量が継続的に増加する。

考えられる原因：

  • 会話タブが多すぎる
  • 1 つの会話に多数のメッセージが含まれている（数百件以上）
  • 添付ファイル（特に画像）が多すぎる

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

  1. 不要な会話タブを閉じます。
  2. 非常に長い会話の場合は、新しい会話を始めることを検討します。
  3. 設定 → システム を開き、キャッシュのクリア を実行してキャッシュをクリアします。
  4. Elftia を再起動してメモリを解放します。

データベース関連のエラー​

症状： データベース操作エラーまたはデータの不整合が発生する。

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

  1. 設定 → システム を開き、VACUUM を実行してデータベースを最適化します。
  2. 問題が続く場合は、診断情報をエクスポート（Export Diagnostics）してさらに調査します。
  3. 極端な場合、ユーザーデータディレクトリのデータベースファイル（.db）を安全にバックアップして置き換えることができます。

アップデート関連の問題​

アップデート後に異常が発生する​

症状： 新バージョンへのアップデート後、アプリの動作が異常になる。

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

  1. 設定 → システム を開き、キャッシュのクリア と VACUUM を順番に実行します。
  2. Elftia を再起動します。
  3. 問題が続く場合は、Elftia を更新する のロールバック手順を参照してください。

上記の解決策で問題が解決しない場合は、診断ツール を使用して詳細情報を収集するか、接続エラー を参照してネットワーク関連の問題の詳細なトラブルシューティング方法を確認してください。