حل المشكلات

كل مدخل في هذه الصفحة بدأ حياته كتقرير خطأ حقيقي. وإذا لم تجد مشكلتك هنا، افتح مشكلة — وستنتهي على الأرجح في هذه الصفحة.

`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 بقائمة سماح):

# 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 كعملية فرعية، لذا فهو يحتاج إلى نظام الملفات المحلي — ولا يمكنه العمل مع هدف بعيد أو هدف --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 لديك):

[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 البعيد):

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

ثم انقر «اتصال» في اللوحة. ولا حاجة إلى تشغيل أي شيء على جهاز ComfyUI سوى ComfyUI وعقدة اللوحة المخصّصة. وفي حالة ComfyUI عبر https (وسيط RunPod)، يرقّي المنسّق الجسر تلقائيًا إلى نفق wss:// آمن — بالأمر نفسه. أو شغّل المنسّق على جانب الخادم (0.24.5 أو أحدث) — وهذا مناسب لجهاز يعمل بلا شاشة على مدار الساعة (مثل خادم Ollama/OpenClaw مستقل) حيث يُفترض أن يعيش الوكيل بجوار ComfyUI وتتصل المتصفحات من أي مكان على الشبكة المحلية:

# 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.

# 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):

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 ستكون مكشوفة). مرّر رمزًا، أو ألغِ هذا التحقق صراحةً:

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) فلا يحتاج إلى أي من ذلك.

الوكيل لا يستدعي أي أداة إطلاقًا — بلا خطأ، يكتفي بالكلام

يصف سير العمل لديك بدلًا من قراءته، أو يعرض عليك كتابة سكربت. ولا يظهر أي خطأ لأن شيئًا لم يفشل: فإمّا أن الأدوات لم تصل إلى عميلك أصلًا، أو أن عميلك يوقف الاستدعاءات، أو أن القدرة موجودة تحت اسم لم يرد ذكره قط. وهذه الحالات الثلاث تبدو متطابقة من الخارج ولها حلول متعاكسة، لذا فالتخمين أسوأ من التحقّق. وسؤالان توجّههما إلى وكيلك يكفيان للتمييز بينها — راجع عندما لا يقول شيئًا. وانتبه إلى أن حجب الأذونات من جانب العميل لا يصل إلى هذا الخادم إطلاقًا، لذا لن يُظهره أي من السجلات المذكورة أدناه.

النماذج المحلية: استدعاءات الأدوات تفشل أو النموذج «لا يرى» الأدوات

أول خطوة: استخدم نموذجنا المضبوط — 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+.
فعّل وضع الأدوات المضغوط مع النماذج الصغيرة — فهو ليس الافتراضي، لذا شغّل الخادم بالخيار --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 وقائمة الانتظار وأدلة النماذج والأخطاء الأخيرة.

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

​عقدة مخصّصة مثبَّتة من رابط git لا تظهر أبدًا

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

​اللوحة تقول «لا يوجد وكيل يستمع على الجسر (ws://127.0.0.1:9180)»

​صدر إصدار جديد لكنني ما زلت أرى السلوك القديم

​ComfyUI بعيد مُمرَّر عبر منفذ يُكتشف خطأً كمحلي (dstack، أنفاق SSH)

​Docker: الحاوية تنتهي فورًا في وضع HTTP

​الوكيل لا يستدعي أي أداة إطلاقًا — بلا خطأ، يكتفي بالكلام

​النماذج المحلية: استدعاءات الأدوات تفشل أو النموذج «لا يرى» الأدوات

​أين تبحث عن السجلات