> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# رفع اشکال

> راه‌حل مشکل‌هایی که کاربران واقعاً با آن‌ها روبه‌رو می‌شوند: ناسازگاری نسل‌های ComfyUI-Manager (خطای 405)، نصب از نشانی git که بی‌صدا رد می‌شود، در دسترس نبودن پنل از مرورگر راه دور، کش کهنهٔ npx، و ComfyUI راه دورِ پورت‌فورواردشده که اشتباهاً محلی تشخیص داده می‌شود.

هر مدخل این صفحه از یک گزارش خطای واقعی آغاز شده است. اگر مورد شما اینجا نیامده،
[گزارشش کنید](https://github.com/artokun/comfyui-mcp/issues) — احتمالاً سر از همین
صفحه درمی‌آورد.

## `install_custom_node` با خطای `405 Method Not Allowed` روی `/v2/manager/queue/task` شکست می‌خورد

**علت:** دو نسل از ComfyUI-Manager وجود دارد. API با مسیر `/v2/manager/*` متعلق به
**نسل v4** است (بستهٔ pip با نام `comfyui_manager` ≥ 4.x)؛ اما **نسخهٔ منتشرشدهٔ
Manager 3.x** — همان چیزی که ComfyUI-Manager به‌صورت پیش‌فرض نصب می‌کند — همان صف
را روی مسیرهای دیگری ارائه می‌دهد.

**راه‌حل:** `comfyui-mcp` را به **0.24.3** یا بالاتر به‌روزرسانی کنید — نسل Manager
را برای هر هدف به‌طور خودکار تشخیص می‌دهد و هر دو گویش را می‌فهمد. نیازی به تغییر
Manager نیست.

**اختیاری اما توصیه‌شده — به Manager v4 ارتقا دهید** تا امکاناتی را داشته باشید که
3.x از راه دور نمی‌تواند انجام دهد (به‌ویژه **دانلود مدل از هر نشانی دلخواه**، که
3.x آن را با فهرست سفید محدود می‌کند):

```bash theme={null}
# in your ComfyUI python environment
pip install -U comfyui_manager
# then remove/disable the old custom_nodes/ComfyUI-Manager clone and restart
```

[ایمیج RunPod](/docs/docs/cloud-deployment) از پیش Manager v4 را همراه دارد.

**نکته دربارهٔ `useCmCli: true`:** مسیر جایگزین cm-cli، ابزار خط فرمان Manager را
به‌صورت زیرفرایند اجرا می‌کند، پس به **فایل‌سیستم محلی** نیاز دارد — روی هدف راه
دور یا هدف `--tunnel` کار نمی‌کند، و وقتی `python` روی PATH نیست باید
`COMFYUI_PYTHON` را به مفسر venv مربوط به ComfyUI بگیرید. برای هدف‌های راه دور،
مسیر HTTP مربوط به Manager (که پیش‌فرض است) سازوکار درست است.

## گره سفارشی نصب‌شده از نشانی git هرگز ظاهر نمی‌شود

نصب با شناسهٔ رجیستری کار می‌کند، اما نصب با نشانی خام GitHub موفقیت را گزارش
می‌کند و بسته هرگز پیدایش نمی‌شود.

**علت:** Manager نصب از نشانی git دلخواه را پرخطر می‌داند و اگر سطح امنیتی از حد
سهل‌گیرانه پایین‌تر باشد **بی‌صدا از آن می‌گذرد** (با این حال کار صف را «done»
علامت می‌زند). در Manager 3.x افزون بر این، یک گزینهٔ پیکربندی اختصاصی به نام
`allow_git_url_install` هم هست.

**راه‌حل:** در فایل `config.ini` مربوط به Manager (زیر پوشهٔ کاربر ComfyUI شما):

```ini theme={null}
[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 گیگابایتی
مدل وارسی سریع در اولین بوت روی والیومی کوچک، یا دانلود یک مدل بزرگ). در حالت
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 را **در مرورگری روی دستگاهی غیر از دستگاهی که ارکستریتور روی آن اجرا
می‌شود** باز کرده‌اید. پل بنا بر طراحی فقط روی loopback کار می‌کند، و `127.0.0.1`
در مرورگر شما یعنی دستگاه خودِ مرورگر — نه دستگاه سرور.

**راه‌حل — ارکستریتور را روی همان دستگاهی اجرا کنید که مرورگر روی آن است** (این
همان چیدمان پشتیبانی‌شده است؛ عامل روی دستگاه *خودتان* اجرا می‌شود و ComfyUI راه
دور را هدایت می‌کند):

```bash theme={null}
npx -y comfyui-mcp@latest connect http://<comfyui-host>:8188
```

بعد در پنل «اتصال» را بزنید. روی ماشین ComfyUI جز خودِ ComfyUI و گره سفارشی پنل،
لازم نیست چیزی اجرا شود. برای ComfyUI روی **https** (پروکسی RunPod)، ارکستریتور
خودش پل را به تونل امن `wss://` ارتقا می‌دهد — با همان فرمان.

**یا ارکستریتور را سمت سرور اجرا کنید (0.24.5 یا بالاتر)** — مناسب ماشینی
بی‌نمایشگر که 24/7 روشن است (مثلاً یک سرور مستقل Ollama/OpenClaw) و قرار است عامل
کنار ComfyUI بماند و مرورگرها از هر جای شبکهٔ محلی وصل شوند:

```bash theme={null}
# 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=…` چاپ می‌کند — آن را
روی هر دستگاهی در **تنظیمات ← پیشرفته ← نشانی پل** پنل بگذارید و «اتصال» را بزنید.
بایند روی نشانی غیر loopback **بدون توکن اصلاً راه نمی‌افتد**، و هر اتصال هنگام
ارتقای WebSocket بررسی می‌شود (با مقایسهٔ زمان‌ثابت). این نشانی را مثل رمز عبور
بدانید: هر کسی آن را داشته باشد می‌تواند عامل را هدایت کند.

## نسخهٔ تازه منتشر شده اما هنوز رفتار قدیمی را می‌بینم

`npx` بسته‌ها را با سماجت کش می‌کند — ممکن است `npx -y comfyui-mcp@latest` نسخه‌ای
چند هفته‌ای را از `~/.npm/_npx` به شما بدهد.

```bash theme={null}
# clear it, then relaunch
npx clear-npx-cache
# or on Windows:
#   Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"
```

گره سفارشی پنل را هم بررسی کنید: اگر از نصبی قدیمی‌تر روی یک **والیوم شبکه**
(`/workspace` در RunPod) مانده باشد، آن نسخه جلوی نسخهٔ خودبه‌روزشوندهٔ ایمیج را
می‌گیرد. `git -C <panel-dir> fetch && git -C <panel-dir> reset --hard origin/main`
را اجرا کنید، یا `comfyui-agent-panel` را از ComfyUI-Manager دوباره نصب کنید، بعد
ComfyUI را دوباره راه‌اندازی کنید و زبانهٔ مرورگر را با تازه‌سازی اجباری به‌روز
کنید (Ctrl+Shift+R).

## ComfyUI راه دورِ پورت‌فورواردشده اشتباهاً محلی تشخیص داده می‌شود (dstack، تونل‌های SSH)

یک ComfyUI راه دور که روی `localhost:8188` در دسترس است (dstack، `ssh -L`، kubectl
port-forward) اکتشاف مبتنی بر loopback را گمراه می‌کند: comfyui-mcp فرض می‌کند نصب
محلی است و ابزارهای فقط-محلی را روی فایل‌سیستمی فعال می‌کند که اصلاً ComfyUI روی
آن نیست.

**راه‌حل (0.24.1 یا بالاتر):** گزینهٔ `--force-remote` (یا
`COMFYUI_MCP_FORCE_REMOTE=1`) را بدهید:

```bash theme={null}
npx -y comfyui-mcp@latest connect http://localhost:8188 --force-remote
```

تاریخچهٔ تولید برای هدف‌های راه دور در
`~/.comfyui-mcp/instances/<host_port>/` نگهداری می‌شود (با `COMFYUI_MCP_DATA_DIR`
قابل تغییر است).

## Docker: کانتینر در حالت HTTP بی‌درنگ خارج می‌شود

بایند کردن روی میزبانی غیر loopback بدون احراز هویت **بنا بر طراحی قاطعانه شکست
می‌خورد** (چون یک نقطهٔ اتصال `/mcp` باز روی `0.0.0.0` در معرض دید قرار می‌گرفت).
یک توکن بدهید، یا صریحاً از این بررسی صرف‌نظر کنید:

```bash theme={null}
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 از آن استفاده می‌کنند) به هیچ‌کدام از
این‌ها نیاز ندارد.

## عامل هرگز ابزاری را فراخوانی نمی‌کند — بدون خطا، فقط حرف می‌زند

به‌جای خواندن گردش‌کار شما آن را توصیف می‌کند، یا پیشنهاد می‌دهد اسکریپتی بنویسد.
خطایی نمایش داده نمی‌شود چون چیزی شکست نخورده است: یا ابزارها اصلاً به کلاینت شما
نرسیده‌اند، یا کلاینت شما جلوی فراخوانی‌ها را می‌گیرد، یا آن قابلیت زیر نامی وجود
دارد که هرگز مطرح نشده است. این سه از بیرون کاملاً شبیه هم‌اند و راه‌حل‌هایشان
متضاد است، پس حدس زدن از بررسی کردن بدتر است.

با دو پرسش از عامل خودتان می‌توانید آن‌ها را از هم تشخیص دهید —
[وقتی چیزی نمی‌گوید](/docs/docs/using-tools#when-it-says-nothing) را ببینید. توجه کنید
که مسدود شدن دسترسی در سمت کلاینت هرگز به این سرور نمی‌رسد، پس هیچ‌کدام از
لاگ‌های زیر آن را نشان نمی‌دهند.

## مدل‌های محلی: فراخوانی ابزار شکست می‌خورد یا مدل ابزارها را «نمی‌بیند»

* **اولین کار: از [مدل فاین‌تیون‌شدهٔ ما](/docs/docs/local-llms#our-fine-tuned-local-models-free-recommended) استفاده کنید** —
  `ollama pull artokun/gemma4-comfyui-mcp:e4b` (پیش‌فرض Ollama در پنل). این همان
  Gemma 4 است که روی خودِ مجموعه‌ابزار comfyui-mcp آموزش دیده، و بیشتر خطاهای
  «ابزار اشتباه / آرگومان بدشکل» را از همان ابتدا از بین می‌برد (`:e2b` برای حدود
  2 گیگابایت VRAM، `:12b` برای حدود 8 گیگابایت — هر پله در آرنا از مدل پایهٔ
  استاندارد خودش بهتر است؛ و `:e4b` همچنان نقطهٔ بهینه است).
* **‏gemma3 در Ollama فراخوانی ابزار بومی ندارد** — پشتیبانی نمی‌شود؛ از
  فاین‌تیون بالا، یا `gemma4` استاندارد (e4b و بالاتر)، `qwen3` یا `llama3.1+`
  استفاده کنید.
* برای مدل‌های کوچک [حالت ابزار فشرده](/docs/docs/local-llms) را روشن کنید — این
  **پیش‌فرض نیست**، پس سرور را با `--compact` (یا
  `COMFYUI_MCP_TOOL_MODE=compact`) اجرا کنید. بدون آن، کل سطح اسکیمای ابزارها از
  یک زمینهٔ کوچک سرریز می‌کند و مدل شروع به ساختن نام ابزار می‌کند.
* بارگذاری سرد یک مدل ممکن است بیش از 30 ثانیه طول بکشد تا اولین توکن بیاید —
  نگهبان پنل این را در نظر می‌گیرد، اما درخواستی که بی‌درنگ می‌میرد معمولاً یعنی
  برچسب آن مدل هنوز دانلود نشده است (`ollama pull <tag>`).
* **همهٔ درخواست‌ها ناگهان شکست می‌خورند / اتصال روی 11434 رد می‌شود** — اپ یا
  سرویس Ollama در حال اجرا نیست. بستن اپِ سینی سیستم، API را هم با خودش می‌کشد، و
  این کاری است که وسط اجرای عامل به‌راحتی سهواً انجام می‌شود (پنل هیچ هشداری
  نمی‌دهد که یک بک‌اند محلی در حال استفاده است). اپ را دوباره اجرا کنید (یا
  `ollama serve`) و دوباره وصل شوید — نشست‌ها از سر گرفته می‌شوند؛ نیازی به
  راه‌اندازی دوبارهٔ پنل نیست.

## لاگ‌ها را کجا ببینیم

* **ارکستریتور**: ترمینالی که `connect` / `--panel-orchestrator` را اجرا می‌کند.
* **سمت ComfyUI**: ابزار MCP با نام `get_system_stats (action:"logs")`، یا جریان لاگ پاد در RunPod.
* **‏JS پنل**: کنسول devtools مرورگر (کلاینت پل، گذارهای اتصال/اتصال دوباره را
  لاگ می‌کند).
* **وضعیت سلامت در یک فراخوانی**: ابزار `get_system_stats (action:"health")`
  نسخه/GPU/VRAM/صف/پوشه‌های مدل/خطاهای اخیر را یک‌جا جمع می‌کند.