トラブルシューティング
既知の制限事項
AI 連携は現在動作していますが、一部のワークフローにはパフォーマンス上の制約があります。
WebView 生成のレイテンシ
AI が推論中にフル HTML コンテンツをインラインで生成する場合、WebView パネルの表示が遅くなります。これはリアルタイムのコンテンツ生成に固有のものです。AI が完全な HTML を生成し終わるまで表示できません。
TTS 音声レイテンシ
VoiceVox を通じた音声生成は、特に長いテキストで顕著な遅延があります。各発話は再生前に合成処理が必要です。
今後の方向性：テンプレート MOD
両方の制限事項は、ビルド済みの WebView アセットを同梱する専用のテンプレート MOD を作成することで対処できます。AI がゼロから HTML を生成する代わりに、MOD コマンドを通じてデータを埋め込みます。これによりレイテンシが大幅に低減されます。
テンプレート MOD の作成や MCP ツールの改善に貢献したい場合は、コントリビューティングガイドをご覧ください。
よくある問題
接続が拒否される
症状： MCP ツールが接続エラーを返す。
原因： Desktop Homunculus が起動していない。
解決策： AI 連携を使用する前に Desktop Homunculus を起動してください。MCP サーバーは localhost:3100 の HTTP 経由でアプリと通信します。
VoiceVox エラー
症状： speak_message が失敗するかエラーを返す。
原因： VoiceVox MOD がインストールされていない、または VoiceVox エンジンが起動していない。
解決策： VoiceVox MOD をインストールし、VoiceVox エンジンが起動していることを確認してください。セットアップ方法は VoiceVox MOD のドキュメントをご覧ください。
キャラクターが見つからない
症状： homunculus://characters が空のリストを返す。
原因： Desktop Homunculus に VRM モデルがロードされていない。
解決策： キャラクター関連のツールを使用する前に、Desktop Homunculus で VRM キャラクターをロードしてください。
MCP サーバーが接続できない
症状： AI クライアントが MCP サーバーに接続できない。
原因： Desktop Homunculus が起動していない、またはクライアントの URL 設定が間違っている。
解決策：
- Desktop Homunculus が起動していることを確認
- MCP の URL が
http://localhost:3100/mcp（またはカスタムポート）であることを確認 - エンドポイントをテスト：
curl http://localhost:3100/mcpがレスポンスを返すこと（接続拒否でないこと）
ツールが予期しないエラーを返す
症状： ツールがエラーレスポンスを返す。
原因： Desktop Homunculus の HTTP API に到達できない、または内部エラー。
解決策： アプリが想定されるポート（デフォルト：3100）で起動していることを確認してください。詳細は ~/.homunculus/Logs/log.txt のログを確認してください。
ヘルプを求める
ここに記載されていない問題が発生した場合は、GitHub で Issue を作成してください。