> ## 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 المؤقتة القديمة، والأجهزة البعيدة المُمرَّرة عبر المنافذ التي تُكتشف خطأً كأجهزة محلية.

كل مدخل في هذه الصفحة بدأ حياته كتقرير خطأ حقيقي. وإذا لم تجد مشكلتك هنا،
[افتح مشكلة](https://github.com/artokun/comfyui-mcp/issues) — وستنتهي على الأرجح
في هذه الصفحة.

## `install_custom_node` يفشل بالخطأ `405 Method Not Allowed` عند `/v2/manager/queue/task`

**السبب:** يوجد جيلان من ComfyUI-Manager. فواجهة `/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`، كما يحتاج إلى توجيه `COMFYUI_PYTHON`
إلى مفسّر بيئة venv الخاصة بـ ComfyUI عندما لا يكون `python` ضمن PATH. أمّا
للأهداف البعيدة، فمسار Manager عبر HTTP (وهو الافتراضي) هو الآلية الصحيحة.

## عقدة مخصّصة مثبَّتة من رابط 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` في بيئة الـ Pod. ولا تخفّف هذا الإعداد إلا على جهاز
تتحكّم فيه أنت — فهو يزيل حواجز الأمان التي يفرضها Manager على التثبيت.

## RunPod: تبويب لوحة الوكيل فارغ — ملفاته موجودة لكنها كلها بحجم 0 بايت

يُدرج ComfyUI الحزمة `comfyui-mcp-panel` لكن تبويب الشريط الجانبي لا يُحمَّل
أبدًا؛ ويُظهر `ls -la /workspace/custom_nodes/comfyui-mcp-panel` كل ملف بحجم
**0 بايت**. وقد تكون العقد التي ثبّتها المستخدم فارغة بالطريقة نفسها.

**السبب:** نفدت **المساحة** على وحدة التخزين الشبكية في وقت ما (غالبًا بسبب نسخ
نموذج الفحص السريع بحجم \~7 غيغابايت عند أول إقلاع على وحدة تخزين صغيرة، أو بسبب
تنزيل نموذج كبير). وعند حدوث ENOSPC يظل `cp`/`git` *ينشئان* كل ملف دون كتابة أي
شيء بداخله — وبما أن وحدة التخزين تبقى محفوظة، فإن هذه القوالب الفارغة تنجو من
كل عملية نشر جديدة.

**الحل:** حرّر مساحة على وحدة التخزين أو وسّعها، ثم أعد تشغيل الـ Pod. واعتبارًا
من الصورة `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 أو أحدث)** — وهذا مناسب لجهاز يعمل بلا
شاشة على مدار الساعة (مثل خادم 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=…` — ضعه في
**الإعدادات → خيارات متقدّمة → عنوان الجسر** داخل اللوحة على أي جهاز، ثم انقر
«اتصال». والربط على عنوان غير محلي **يرفض البدء بدون رمز**، ويُفحص كل اتصال عند
ترقية 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) يُربك الاستدلال المبني على الاسترجاع المحلي:
إذ يفترض 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

الربط على مضيف غير محلي بدون مصادقة **يفشل فشلًا قاطعًا بحكم التصميم** (لأن نقطة
النهاية `/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")`، أو تدفّق سجلات الـ Pod على RunPod.
* **‏JS اللوحة**: وحدة تحكّم أدوات المطوّر في المتصفح (يسجّل عميل الجسر
  انتقالات الاتصال/إعادة الاتصال).
* **الحالة في استدعاء واحد**: تجمع أداة `get_system_stats (action:"health")`
  معلومات الإصدار وGPU وVRAM وقائمة الانتظار وأدلة النماذج والأخطاء الأخيرة.