トラブルシューティング
既知の制限事項
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 サーバーに接続できない。
原因： MCP サーバーの起動に失敗したか、Node.js がインストールされていない/バージョンが古い。
解決策：
npx -y @hmcs/mcp-server@latestがエラーなく実行できることを確認- Node.js 22 以上がインストールされていることを確認（
node --version）
ツールが予期しないエラーを返す
症状： ツールがエラーレスポンスを返す。
原因： Desktop Homunculus の HTTP API に到達できない。
解決策： アプリが想定されるポート（デフォルト：3100）で起動していることを確認してください。デフォルト以外のポートを使用している場合は、HOMUNCULUS_HOST 環境変数を設定してください。
ヘルプを求める
ここに記載されていない問題が発生した場合は、GitHub で Issue を作成してください。