トラブルシューティング

このページの項目はすべて、実際のバグ報告から生まれたものです。お困りの問題がここにない場合は Issue を登録してください — おそらくこのページに追加されることになります。

`install_custom_node` が `/v2/manager/queue/task` で `405 Method Not Allowed` になる

原因: ComfyUI-Manager には 2 つの世代が存在します。/v2/manager/* API は v4 系（pip パッケージ comfyui_manager ≥ 4.x）のもので、ComfyUI-Manager が既定でインストールするリリース版の Manager 3.x は、同じキューを別のルートで提供しています。 対処: comfyui-mcp を 0.24.3 以上に更新してください — 接続先ごとに Manager の世代を自動判別し、どちらの方言も話せます。Manager 側の変更は不要です。 任意ですが推奨 — Manager v4 へのアップグレード。3.x がリモートでは実行できない機能（特に、3.x がホワイトリストで制限している任意 URL からのモデルダウンロード）が使えるようになります:

# in your ComfyUI python environment
pip install -U comfyui_manager
# then remove/disable the old custom_nodes/ComfyUI-Manager clone and restart

RunPod イメージには Manager v4 が同梱済みです。 useCmCli: true についての補足: cm-cli フォールバックは Manager の CLI をサブプロセスとして実行するため、ローカルのファイルシステムが必要です — リモートや --tunnel の接続先には使えません。また、python が PATH にない場合は COMFYUI_PYTHON に ComfyUI の venv のインタープリターを指定する必要があります。リモートの接続先には、Manager の HTTP 経路（既定）が適切な仕組みです。

git URL からインストールしたカスタムノードがいつまでも表示されない

レジストリ ID でのインストールは動作しますが、GitHub の生の URL によるインストールは成功と報告されるのに、パックがいつまでも現れません。 原因: Manager は任意の git URL からのインストールを高リスクとみなし、緩いセキュリティレベルに達していない場合は黙ってスキップします（それでもキューのタスクは「done」と記録されます）。Manager 3.x にはさらに、専用の allow_git_url_install 設定フラグがあります。 対処: Manager の config.ini（ComfyUI のユーザーディレクトリ配下）で次のように設定します:

[default]
security_level = weak          ; Manager v4: allows git-URL installs
allow_git_url_install = True   ; Manager 3.x: additionally required

そのあと ComfyUI を再起動してください。RunPod イメージでは、イメージ 1.6 以降これが既定です（環境変数 COMFY_SECURITY_LEVEL が優先され、レベルは起動のたびに設定し直されます）。イメージ 1.4/1.5 もそう意図されていましたが、焼き込まれた COMFY_SECURITY_LEVEL=normal- の環境変数が起動スクリプトの既定値を上書きしていました — これらのイメージではポッドの環境変数に COMFY_SECURITY_LEVEL=weak を設定してください。緩和するのは自分が管理しているマシンだけにしてください — Manager のインストール時のガードレールを外すことになります。

RunPod: エージェントパネルのタブが空 — ファイルは存在するのにすべて 0 バイト

ComfyUI には comfyui-mcp-panel が表示されるのに、サイドバーのタブがいつまでも読み込まれません。ls -la /workspace/custom_nodes/comfyui-mcp-panel を実行すると、すべてのファイルが 0 バイトになっています。ユーザーがインストールしたノードも同じように空になっていることがあります。 原因: ネットワークボリュームがどこかの時点で容量不足になったのです（小さなボリュームでの初回起動時、約 7 GB のスポットチェックモデルのコピーや、大きなモデルのダウンロードでよく起こります）。ENOSPC の状態でも cp/git は各ファイルを作成だけはしますが、中身をまったく書き込みません — そしてボリュームは永続するため、この抜け殻は再デプロイのたびに残り続けます。 対処: ボリュームの空きを作るか容量を増やしてから、ポッドを再起動してください。イメージ 1.6 以降、起動スクリプトはボリュームの残量が少ない／満杯のときに警告を出し、収まらない場合はスポットチェックモデルのコピーをスキップし、0 バイトのパネルを自動的に 自己修復します（GitHub から再クローンし、オフラインならイメージのシードを使います）。さらに、他に壊れているノードがあれば WARN: custom nodes with 0-byte __init__.py とその名前をログに出します — それらは Manager から再インストールしてください。イメージ <= 1.5 では、パネルのフォルダーを削除して再起動してください: rm -rf /workspace/custom_nodes/comfyui-mcp-panel。

パネルに「ブリッジ（ws://127.0.0.1:9180）で待ち受けているエージェントがありません」と表示される

オーケストレーターが動いているマシンとは別のマシンのブラウザーで ComfyUI を開いています。ブリッジは設計上ループバック専用で、ブラウザーでの 127.0.0.1 はサーバーではなくブラウザー側のマシンを指します。 対処 — ブラウザーがあるマシンでオーケストレーターを実行してください（これがサポートされている構成です。エージェントはあなたのマシンで動き、リモートの ComfyUI を操作します）:

npx -y comfyui-mcp@latest connect http://<comfyui-host>:8188

そのあとパネルで「接続」をクリックします。ComfyUI 側のマシンでは、ComfyUI とパネルのカスタムノード以外に動かすものはありません。https の ComfyUI（RunPod のプロキシ）の場合、オーケストレーターはブリッジを安全な wss:// トンネルへ自動的に切り替えます — コマンドは同じです。 あるいはオーケストレーターをサーバー側で実行する（0.24.5 以上） — エージェントを ComfyUI の隣に常駐させ、LAN 上のどこからでもブラウザーで接続したい 24/7 のヘッドレスマシン（例: 単独の Ollama/OpenClaw サーバー）向けの構成です:

# on the SERVER — bind the bridge on the LAN, token-gated (mandatory)
COMFYUI_MCP_BRIDGE_HOST=0.0.0.0 \
COMFYUI_MCP_BRIDGE_TOKEN=<pick-a-long-secret> \
npx -y comfyui-mcp@latest --panel-orchestrator

そのまま貼り付けられる ws://<server-ip>:9180/?token=… が出力されます — これを任意のマシンでパネルの設定 → 詳細設定 → ブリッジ URL に入力し、「接続」をクリックしてください。ループバック以外へのバインドは、トークンがないと起動を拒否します。また、すべての接続は WebSocket のアップグレード時に検査されます（定数時間比較）。この URL はパスワードと同じように扱ってください: 手にした人は誰でもエージェントを操作できます。

新しいリリースが出たのに、まだ以前の動作のまま

npx はパッケージを積極的にキャッシュします — npx -y comfyui-mcp@latest が ~/.npm/_npx にある数週間前のビルドをそのまま使ってしまうことがあります。

# clear it, then relaunch
npx clear-npx-cache
# or on Windows:
#   Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

パネルのカスタムノードも確認してください。以前のインストールでネットワークボリューム （RunPod の /workspace）に置かれたものが残っていると、そのコピーがイメージ側の自動更新されるものを覆い隠します。git -C <panel-dir> fetch && git -C <panel-dir> reset --hard origin/main を実行するか、ComfyUI-Manager から comfyui-agent-panel を再インストールし、そのあと ComfyUI を再起動してブラウザーのタブをハードリロード（Ctrl+Shift+R）してください。

ポートフォワードしたリモートの ComfyUI がローカルと誤検出される（dstack、SSH トンネル）

localhost:8188 で到達できるリモートの ComfyUI（dstack、ssh -L、kubectl port-forward）は、ループバックのヒューリスティックを誤作動させます。comfyui-mcp がローカルインストールだと判断し、ComfyUI が存在しないファイルシステムに対してローカル専用のツールを有効にしてしまいます。 対処（0.24.1 以上）: --force-remote（または COMFYUI_MCP_FORCE_REMOTE=1）を指定してください:

npx -y comfyui-mcp@latest connect http://localhost:8188 --force-remote

リモートの接続先の生成履歴は ~/.comfyui-mcp/instances/<host_port>/ の下に保存されます（COMFYUI_MCP_DATA_DIR で変更できます）。

Docker: HTTP モードでコンテナがすぐに終了する

認証なしでループバック以外のホストにバインドすると、設計上その場で失敗します （0.0.0.0 上の /mcp エンドポイントが無防備に公開されてしまうため）。トークンを渡すか、明示的にオプトアウトしてください:

docker run --rm -p 9100:9100 -e COMFYUI_MCP_HTTP_TOKEN=changeme comfyui-mcp \
  --http --host 0.0.0.0 --port 9100
# or (trusted networks only):
#   ... --http --host 0.0.0.0 --port 9100 --allow-unauthenticated-non-loopback

stdio モード（既定であり、MCP クライアントが使う方式）には、これらは一切不要です。

エージェントがツールをまったく呼び出さない — エラーも出ず、ただ話すだけ

ワークフローを読み取る代わりに説明したり、スクリプトを書きましょうかと提案したりします。何も失敗していないのでエラーは出ません。原因は、ツールがそもそもクライアントに届いていないか、クライアントが呼び出しを止めているか、その機能が一度も話題に出ていない名前で存在しているか、のいずれかです。この 3 つは外から見ると同じに見えるうえ、対処は正反対なので、推測するより確認したほうが確実です。エージェントに 2 つ質問すれば見分けられます — 何も言わないときを参照してください。なお、クライアント側の権限によるブロックはこのサーバーまで届かないため、以下のどのログにも現れません。

ローカルモデル: ツール呼び出しが失敗する、またはモデルがツールを「認識できない」

まず試すこと: 当プロジェクトのファインチューニング済みモデルを使う — ollama pull artokun/gemma4-comfyui-mcp:e4b（パネルの Ollama の既定値）。 comfyui-mcp のツール群そのもので学習させた Gemma 4 で、「ツールの選択ミス／引数の形式不正」による失敗のほとんどを、そのままの状態で解消します（VRAM 約 2 GB なら :e2b、約 8 GB なら :12b — どの段もアリーナで素のベースモデルを上回っており、:e4b が最適点のままです）。
gemma3 は Ollama でネイティブのツール呼び出しに対応していません — 非対応です。上のファインチューニング済みモデルか、素の gemma4（e4b 以上）、qwen3、 llama3.1+ を使ってください。
小さいモデルではコンパクトツールモードを有効にしてください — これは既定ではオフなので、サーバーを --compact（または COMFYUI_MCP_TOOL_MODE=compact）付きで起動します。有効にしないと、スキーマ全体が小さいコンテキストからあふれ、モデルがツール名を作り出し始めます。
コールド状態からのモデル読み込みは、最初のトークンが出るまで 30 秒以上かかることがあります — パネルのウォッチドッグはこれを見込んでいますが、リクエストが即座に落ちる場合はたいてい、そのモデルタグをまだ取得していないだけです（ollama pull <tag>）。
急にすべてのリクエストが失敗する／11434 で接続が拒否される — Ollama のアプリ／デーモンが動いていません。トレイのアプリを終了すると API も一緒に止まりますが、これはエージェントの実行中にうっかりやってしまいがちです（ローカルのバックエンドが使われていることをパネルは警告しません）。アプリを起動し直して（または ollama serve）、接続し直してください — セッションは再開され、パネルの再起動は不要です。

ログの確認場所

オーケストレーター: connect / --panel-orchestrator を実行しているターミナル。
ComfyUI 側: get_system_stats (action:"logs") の MCP ツール、または RunPod ではポッドのログストリーム。
パネルの JS: ブラウザーの devtools コンソール（ブリッジクライアントが接続／再接続の遷移をログに出します）。
1 回の呼び出しで健全性を確認: get_system_stats (action:"health") ツールが、バージョン/GPU/VRAM/キュー/モデルディレクトリ/最近のエラーをまとめて返します。

​install_custom_node が /v2/manager/queue/task で 405 Method Not Allowed になる

​git URL からインストールしたカスタムノードがいつまでも表示されない

​RunPod: エージェントパネルのタブが空 — ファイルは存在するのにすべて 0 バイト

​パネルに「ブリッジ（ws://127.0.0.1:9180）で待ち受けているエージェントがありません」と表示される

​新しいリリースが出たのに、まだ以前の動作のまま

​ポートフォワードしたリモートの ComfyUI がローカルと誤検出される（dstack、SSH トンネル）

​Docker: HTTP モードでコンテナがすぐに終了する

​エージェントがツールをまったく呼び出さない — エラーも出ず、ただ話すだけ

​ローカルモデル: ツール呼び出しが失敗する、またはモデルがツールを「認識できない」

​ログの確認場所