> ## 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.
# Локальные LLM и другие агенты
> Поддержка первого класса для Hermes Agent, OpenClaw и Copilot CLI — плюс любой MCP-клиент на локальной (Ollama) или размещённой модели. Настройка одной командой и компактный режим инструментов, который сворачивает ~200 схем инструментов в 3 мета-инструмента.
comfyui-mcp — стандартный stdio MCP-сервер, поэтому **им может управлять любой
агент, умеющий MCP**, не только Claude Code. Эта страница покрывает обвязки,
которые мы поддерживаем как первый класс (**Hermes Agent, OpenClaw, Copilot
CLI**), что должна принести ваша модель, и **компактный режим инструментов**,
который делает небольшие/локальные модели жизнеспособными.
## Требования к модели
Будьте честны с собой насчёт модели, которую приносите. Минимальная
спецификация для *полного* опыта — модель с \*\*вызовом инструментов + мышлением
* vision\*\*:
| Возможность | Без неё |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Вызов инструментов** (нативный function calling) | **Не будет работать.** Каждое действие comfyui-mcp — это вызов инструмента. Эмулированный промптом вызов инструментов в некоторых обвязках технически бежит, но надёжность рушится — считайте это неподдерживаемым. |
| **Мышление / рассуждение** | Работает, деградировано. Многошаговые цепочки (выбрать инструмент → взять схему → собрать args → восстановиться после ошибок) заметно хуже; ждите, что агенту понадобятся повторные промпты/подталкивания. |
| **Vision** | Работает, деградировано. Агент может генерировать, но не может *видеть* — циклы критики `get_image (action:"view")`, `get_workflow (action:"from_image")` и визуальные сравнения недоступны, так что он летит вслепую по своим выходам. |
Размещённые модели, которые влезают в полную спецификацию, меняются ежемесячно
— проверяйте карточку модели у провайдера на три возможности, а не доверяйте
списку. На середину 2026: **Xiaomi MiMo-V2.5** (vision + инструменты + длинный
контекст) влезает в полную спецификацию дёшево; модели класса **DeepSeek-V3.x /
GLM / MiniMax** имеют сильный вызов инструментов + мышление, но текстовые
варианты теряют цикл vision; небольшие локальные модели (ниже) обычно держат
вызов инструментов и бросают остальное.
## Компактный режим инструментов
Полная поверхность — 37 инструментов с богатыми JSON-схемами (\~200 КБ, примерно
50k токенов, на `tools/list`). Большинство обвязок не-Claude впрыскивают каждую
зарегистрированную схему прямо в контекст модели — нормально для передовых
моделей, смертельно для локальной 4B. **Компактный режим инструментов**
регистрирует ровно **три мета-инструмента** и держит настоящий каталог за ними:
| Мета-инструмент | Что делает |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_tools` | Каталог, лёгкий по токенам: каждое имя инструмента + однострочное резюме, сгруппировано по категории. Поддерживает фильтры `category` и `search`. |
| `describe_tool` | Полное описание + JSON Schema одного инструмента, забирается только когда нужно. |
| `call_tool` | Запускает любой каталогизированный инструмент: `{"name": "generate_image", "args": {...}}`. Возвращает ровно то, что возвращает нижележащий инструмент. |
Цикл модели: `list_tools` → выбрать → `describe_tool` → `call_tool`.
Схемы входят в контекст по одному инструменту. Мета-инструменты нарочно
прощают странности небольших моделей: `args` может быть объектом **или**
JSON-строкой, принимаются обычные алиасы полей (`tool_name`, `arguments`), а
ошибки валидации возвращаются с ожидаемой схемой, чтобы модель могла себя
поправить вместо того, чтобы умирать на непрозрачной ошибке протокола.
Компактный режим — **opt-in**: прямая поверхность стоит по умолчанию, поэтому
небольшой модели нужно одно из этого (флаг побеждает переменную окружения):
```bash theme={null}
npx -y comfyui-mcp --compact
# or
COMFYUI_MCP_TOOL_MODE=compact npx -y comfyui-mcp
```
Значение по умолчанию подходит обвязкам передовых моделей (Claude Code /
Cursor / Claude Desktop), чьи клиенты хорошо держат большие списки
инструментов. `--full` по-прежнему принимается и теперь no-op.
### Автовыбор: по модели, не по провайдеру
В локальных LLM-бэкендах панели (Ollama / LM Studio / llama.cpp /
совместимый с OpenAI), когда **вы не выбрали режим**, *модель* выбирает один:
* модель, чей id несёт число параметров **70B** или выше
(`llama3.3:70b`, `gpt-oss:120b`, `mixtral:8x22b`), получает **полную**
поверхность;
* всё меньшее остаётся **компактным**;
* id модели без читаемого числа параметров (`moonshotai/kimi-k2.5`)
считается **неизвестным**, а не маленьким, и получает задокументированный
компактный запасной вариант.
«Ollama ⇒ компактный» было бы неверно в обе стороны — локальная 70B модель
держит полную поверхность и её незачем калечить, а некоторым небольшим
размещённым моделям нужен компактный. Поэтому сигнал — модель.
**Ваш выбор всегда побеждает, в обе стороны.** `COMFYUI_MCP_TOOL_MODE=full`
навязывает полную поверхность 4B-модели; `COMFYUI_MCP_TOOL_MODE=compact`
навязывает роутер 405B. Автовыбор заполняет только пробел, где ничего не
выбрано.
Порог 70B нарочно консервативен: это единственная цифра, которую кто-либо
реально утверждал по этой оси, поэтому ничто не повышается наугад.
`COMFYUI_MCP_FULL_SURFACE_MIN_PARAMS_B=30` снижает его, если хотите найти,
где на самом деле потолок вашего железа.
**Системный промпт следует за режимом.** Компактный промпт говорит модели, что
у неё шесть инструментов и ComfyUI идёт через `call_tool`; когда выбрана
полная поверхность, это просто неправда, поэтому промпт полного режима говорит,
что инструменты ComfyUI объявлены напрямую, и держит описание роутера только
для `panel_*`. Автовыбрать полный, отрицая, что инструменты существуют, было
бы хуже значения по умолчанию, которое он заменил.
Активный режим **и его причина** печатаются в строке готовности бэкенда,
например `Tool mode: compact — chosen for this MODEL: "qwen3:4b" is ~4B
parameters, below the 70B full-surface threshold…`, так что рычаг больше
никогда не невидим.
Этот автовыбор покрывает полосу локальных LLM панели. Полоса HTTP Codex /
Gemini / Grok / Copilot остаётся прибитой к компактному по другой причине —
их собственные бюджеты инструментов иначе вытесняют инструменты `panel_*` —
а значение по умолчанию автономного MCP-сервера не меняется.
## Вход аудио
**На бэкенде `ollama` (нативный `/api/chat`)** аудио доходит до модели только
там, где модель реально сообщает, что умеет слышать. Перед отправкой бэкенд
спрашивает `POST /api/show` возможности этой модели:
```bash theme={null}
ollama pull gemma4:e2b # capabilities: completion, vision, audio, tools, thinking
```
Если у выбранной модели нет возможности `audio`, вложение **отклоняется вслух**
— со списком возможностей, который сообщил сервер, и командой pull модели,
которая умеет слышать — а не бросается в запрос, где модель ответила бы только
из вашего текста. То же относится к файлу, который не аудиоформат, или который
есть, но нулевого размера.
Доставить байты — ещё не вся работа. Измерено вживую против `gemma4:e2b`: WAV
демонстративно в контексте (555 токенов промпта, `/api/show` сообщает
`audio`), модель всё равно ответила *«I do not have the capability to
transcribe audio — my functions are limited to operating ComfyUI»*. Системный
промпт панели рисует её как оператора графа, и небольшая модель сама себя
выговаривает из чувства, которое у неё на самом деле есть. Поэтому ход, чьё
аудио проверили по возможностям и прикрепили, ещё несёт короткую заметку,
говорящую модели, что аудио здесь и что она должна отвечать из того, что
слышит. С этой заметкой та же модель транскрибировала правильно в четырёх
прогонах из четырёх.
**На OpenAI-совместимых бэкендах** (LM Studio, llama.cpp, OpenRouter, свой)
нет эндпоинта возможностей, чтобы спросить. Аудио отправляется как часть
содержимого `input_audio`, и ход несёт явную строку *«I cannot confirm the
model actually receives them»*. Отказывать значило бы отказать в аудио каждому
эндпоинту, у которого просто нет API возможностей; страж, который не может
сработать, — не вердикт, но это и не подтверждение, и формулировка так и
говорит.
См. [Бэкенды → Вход аудио](/docs/docs/ru/backends#вход-аудио--какие-бэкенды-честно)
про то, что делает каждый другой провайдер.
## Настройка одной командой
`comfyui-mcp setup ` записывает запись сервера в собственный конфиг-
файл обвязки (сливаясь с тем, что уже там — существующие серверы, комментарии
в YAML, всё сохраняется):
```bash theme={null}
npx -y comfyui-mcp setup hermes # → ~/.hermes/config.yaml (compact by default)
npx -y comfyui-mcp setup openclaw # → ~/.openclaw/openclaw.json (compact by default)
npx -y comfyui-mcp setup copilot # → ~/.copilot/mcp-config.json (full by default)
```
Флаги: `--compact` / `--full` переопределяют значение по умолчанию на агента,
`--comfyui-url ` встраивает вашу цель ComfyUI (локальную, LAN или proxy
URL RunPod), `--dry-run` печатает слитый конфиг вместо записи.
## Hermes Agent
```bash theme={null}
npx -y comfyui-mcp setup hermes --comfyui-url http://127.0.0.1:8188
```
что даёт это в `~/.hermes/config.yaml` (добавьте руками, если предпочитаете):
```yaml theme={null}
mcp_servers:
comfyui:
command: "npx"
args: ["-y", "comfyui-mcp", "--compact"]
env:
COMFYUI_URL: "http://127.0.0.1:8188"
```
Перезагрузите через `/reload-mcp` (или перезапустите Hermes). Hermes ставит
префикс инструментам, так что модель видит `mcp_comfyui_list_tools`,
`mcp_comfyui_describe_tool` и `mcp_comfyui_call_tool` — три определения в
контексте вместо двухсот.
На передовой модели (через Nous Portal / OpenRouter) можно перезапустить
setup с `--full` и по желанию использовать собственный белый список
`tools.include` Hermes. Компактный — правильное значение по умолчанию для
всего меньшего.
Hermes также поставляет бандленный *скилл* `comfyui`, который ведёт ComfyUI
по сырому REST из Python-скриптов. Он работает, но старше этого сервера —
MCP-маршрут даёт вам создание/валидацию воркфлоу, управление моделями и
кастомными узлами, установочные пакеты, управление очередью и самодиагностику.
Отключите скилл, если агент продолжает тянуться к нему вместо MCP-инструментов.
## OpenClaw
```bash theme={null}
npx -y comfyui-mcp setup openclaw
```
что даёт это в `~/.openclaw/openclaw.json`:
```json theme={null}
{
"mcpServers": {
"comfyui": {
"command": "npx",
"args": ["-y", "comfyui-mcp", "--compact"],
"transport": "stdio"
}
}
}
```
Перезапустите шлюз OpenClaw, чтобы подхватить сервер. Документация OpenClaw
рекомендует держать число MCP-инструментов низким — именно для этого
компактный режим, и поэтому он здесь по умолчанию.
## Copilot CLI
```bash theme={null}
npx -y comfyui-mcp setup copilot
# or use Copilot's own command:
copilot mcp add comfyui -- npx -y comfyui-mcp
```
что даёт это в `~/.copilot/mcp-config.json`:
```json theme={null}
{
"mcpServers": {
"comfyui": {
"type": "stdio",
"command": "npx",
"args": ["-y", "comfyui-mcp"],
"env": {},
"tools": ["*"]
}
}
}
```
Copilot CLI гоняет передовые модели, поэтому setup по умолчанию ставит
**полную** поверхность инструментов (передайте `--compact`, если направляете
Copilot на меньшую модель). Проверьте через `/mcp show` внутри `copilot`.
## Наши дообученные локальные модели (бесплатно, рекомендуем)
Если хотите гонять агента **локально бесплатно**, начните здесь. Мы
дообучили семейство Gemma 4 специально под comfyui-mcp: QLoRA на **1055
проверенных сервером траекториях вызова инструментов**, синтезированных против
живого ComfyUI — покрывая **полную поверхность из 178 инструментов** (113 MCP
* 65 панели) — так что модель знает этот точный набор инструментов нативно,
вместо того чтобы встречать его холодной.
```bash theme={null}
# 1. Install Ollama (once): https://ollama.com/download
# 2. Pull the size that fits your GPU:
ollama pull artokun/gemma4-comfyui-mcp:e4b # default — ~3.5 GB VRAM at q4
ollama pull artokun/gemma4-comfyui-mcp:12b # ~8 GB VRAM
ollama pull artokun/gemma4-comfyui-mcp:e2b # smallest — ~2 GB VRAM (see caveat)
```
**Измерено, не обещано** — баллы [LLM Arena](/docs/docs/ru/arena) на настоящей
лестнице из 10 сценариев (лучшее из 3, каждый результат проверен против живого
сервера ComfyUI, RTX 4090):
| Тег | VRAM (q4) | Балл арены | vs. сток |
| ----------- | --------- | ------------------------------------------------------------------- | ---------------------- |
| `:e4b` | \~3,5 ГБ | **14/20** (13–14) — лучшая локальная модель, которую мы тестировали | сток gemma4:e4b: 12/20 |
| `:12b` | \~8 ГБ | 13/20 (12–13) | сток 12b без бенчмарка |
| `:e2b` (v2) | \~2 ГБ | 10/20 (7–10) | сток gemma4:e2b: 8/20 |
Каждая ступень теперь обыгрывает свою стоковую базу. Переобучение `:e2b` v2
(обучение с двух видов: прямые вызовы инструментов И конверт развёрнутого
роутера) исправило регрессию формата `call_tool` v1 — ноль кривых конвертов
по вердиктным прогонам. Рекомендации по размеру стоят: `:e4b` — сладкая точка
(всего \~1,5 ГБ больше e2b и +4 на арене); `:e2b` теперь легитимный выбор для
тесная VRAM; `:12b` покупает стабильность на длинных многошаговых задачах, а
не сырой балл.
| Тег | База | VRAM (q4) | Заметки |
| ------ | ----------- | --------- | ---------------------------------------------------------- |
| `:e4b` | Gemma 4 E4B | \~3,5 ГБ | **Значение по умолчанию** — лучший баланс размера/качества |
| `:e2b` | Gemma 4 E2B | \~2 ГБ | Думает многословно — дайте щедрый `max_tokens` (≥512) |
| `:12b` | Gemma 4 12B | \~8 ГБ | Самая сильная ступень |
Бэкенд Ollama панели **по умолчанию на `:e4b`** — выберите **Ollama
(локально)** в выборе бэкенда, и это просто работает, как только модель
подтянута. Без аккаунта, без API-ключа, без стоимости за токен.
**Окно контекста:** теги поставляют запечённое окно **65 536 токенов**, и
оркестратор ему уступает (стоковые модели получают 16K). Архитектура
поддерживает до **128K** (`:e2b`/`:e4b`) и **256K** (`:12b`) — поднимите через
`COMFYUI_MCP_OLLAMA_NUM_CTX=131072`, если есть VRAM (KV-кэш растёт с
окном). Если агент начинает «забывать» посреди разговора, смотрите лог
оркестратора: он предупреждает, когда ход заполняет ≥85% окна. Веса, LoRA-
адаптеры и конвейер обучения открыты: [`artokun/gemma4-comfyui-mcp`](https://huggingface.co/artokun/gemma4-comfyui-mcp)
(датасет: [`artokun/comfyui-mcp-trajectories`](https://huggingface.co/datasets/artokun/comfyui-mcp-trajectories)).
## LM Studio
Панель говорит с LM Studio нативно: выберите **LM Studio** в выборе бэкенда,
и оркестратор ведёт его локальный сервер (`http://127.0.0.1:1234/v1`,
переопределяется через `COMFYUI_MCP_LMSTUDIO_HOST`). Настройка в два клика:
установите с [lmstudio.ai](https://lmstudio.ai), затем **Developer → Start
Server** с загруженной **моделью с вызовом инструментов**. Выбор модели
зеркалирует то, что предлагает сервер; без заданного значения по умолчанию
первая отданная модель принимается автоматически. Оркестратор ведёт
**полный жизненный цикл** без рук: сам стартует сервер, когда нужно,
JIT-загружает вашу модель, освобождает её VRAM, пока идёт рендер ComfyUI
(чат держится и отвечает, когда рендер закончится), выгружает уходящую
модель при смене модели и отпускает всё, когда вы переключаетесь на другого
провайдера.
Наши дообученные GGUF работают и здесь — ищите `artokun/gemma4-comfyui-mcp` в
загрузчике моделей LM Studio и берите `model-q4_k_m.gguf`. Ждите ту же паузу
холодной JIT-загрузки на первом сообщении, что и у Ollama (30 с+ нормально).
## llama.cpp (llama-server)
Гоняете сырой `llama.cpp`? Выберите **llama.cpp** в выборе бэкенда —
оркестратор ведёт OpenAI-совместимый эндпоинт `llama-server`
(`http://127.0.0.1:8080/v1`, переопределяется через `COMFYUI_MCP_LLAMACPP_HOST`):
```bash theme={null}
llama-server -m gemma4-comfyui-mcp-e2b.Q4_K_M.gguf -c 16384
```
Заметки с поля: контекст — это **флаг запуска** (`-c`) — агент предупреждает,
если сервер работает ниже 16K (полезная нагрузка инструментов это требует).
Вызов инструментов включён по умолчанию в текущих сборках; **старым сборкам
нужен `--jinja`** (панель обнаруживает неспособный к инструментам сервер при
подключении и говорит именно это). Единственная загруженная модель
принимается автоматически — выбирать не нужно.
На коробке с одним GPU **локальный** llama-server (или llama-swap перед ним)
входит в ту же передачу VRAM, что Ollama и LM Studio: пока идёт рендер
ComfyUI, ваш чат держится и отвечает в момент окончания рендера. Поскольку
у llama-server нет API выгрузки (а llama-swap меняет модели апстрим по
запросу), передача только держит — явно ничего не выгружается и не греется.
**Удалённый** `COMFYUI_MCP_LLAMACPP_HOST` — чужой GPU и никогда не
гейтится. Передача включена по умолчанию для всех трёх локальных бэкендов;
откажитесь через `COMFYUI_MCP_PAUSE_LOCAL_ON_GEN=0` (устаревший
`COMFYUI_MCP_OLLAMA_PAUSE_ON_GEN=0` всё ещё чтится).
## Свой эндпоинт (любой OpenAI-совместимый сервер)
Всё, что говорит на `/v1/chat/completions` — vLLM, DeepSeek, Together, Azure
OpenAI, llama-server на другой коробке, корпоративный шлюз — втыкается как
провайдер **Свой эндпоинт**:
1. Настройки ComfyUI → **Comfy MCP Agent → Свой эндпоинт** → задайте
**базовый URL эндпоинта** (включите `/v1`, например `http://192.168.1.20:8000/v1`).
2. Если серверу нужен ключ: **Задать ключ API…** — маскированный ввод; ключ
хранится `0600` оркестратором в `~/.comfyui-mcp`, никогда в настройках
ComfyUI или чате.
3. Выберите **Свой эндпоинт** в выборе бэкенда и нажмите «Подключить».
Список моделей приходит из `/v1/models` сервера; серверы с одной моделью
принимаются автоматически, или задайте id **модели по умолчанию** явно для
эндпоинтов, которые не перечисляют модели. Аварийные люки env:
`COMFYUI_MCP_CUSTOM_BASE_URL`, `COMFYUI_MCP_CUSTOM_MODEL`,
`COMFYUI_MCP_CUSTOM_API_KEY`. Модель должна поддерживать **вызов
инструментов**.
## Ollama и локальные модели — LLM Arena
Любая MCP-обвязка, которая говорит с Ollama (или OpenAI-совместимым
эндпоинтом), может вести компактный режим с локальной моделью. Две
повторяемые обвязки едут в репозитории: `npm run test:local-llm` (быстрая
проверка одной модели) и `node scripts/llm-arena.mjs` — **ComfyUI LLM Arena**,
которая гоняет поле моделей через идентичный набор задач против *живого*
ComfyUI и проверяет каждый исход против сервера, никогда против заявлений
модели.
Баллы локального яруса на полной лестнице из 10 сценариев (RTX 4090, ComfyUI
0.27, температура 0 — см. [страницу Арены](/docs/docs/ru/arena) про лестницу задач
и таблицу лидеров всех ярусов, включая передовые и размещённые модели):
| Модель | Размер | Балл /20 |
| ----------------------- | ------ | ------------------------------------------------------- |
| `qwen3:4b` | 2,6 ГБ | **13** |
| `gemma4:e4b` | 9,6 ГБ | **12** |
| `qwen3:8b` | 5,2 ГБ | **11** |
| `gemma4:e2b` | 7,2 ГБ | **8** |
| `llama3.1:8b` | 4,9 ГБ | **2** |
| `gemma3` (любой размер) | — | ❌ нет нативного вызова инструментов — не поддерживается |
Выводы: класс qwen3/gemma4 уверенно закрывает одноинструментные задачи
(здоровье, установленные модели, поиск в реестре, очередь) и набирает баллы
на более трудных полосах, но многостадийная композиция графа (один граф с
двумя связанными выходами, двухступенчатый конвейер img2img) всё ещё
территория передовых/B-tier. Дисциплина формата инструментов llama3.1:8b
рушится на этом каталоге (она выдумывает имена инструментов и печатает JSON
вызова инструментов как текст). Gemma 4 поставила нативный function calling
по всему семейству (Ollama ≥ v0.20); `e4b` или больше — сладкая точка.
Помните лестницу возможностей выше: эти небольшие модели держат вызов
инструментов, но имеют ограниченный/никакой vision и мышление, так что они
могут генерировать и управлять воркфлоу, но не могут визуально критиковать
результаты.
## Боковая панель на локальной модели
[Агент панели](/docs/docs/ru/panel) получает **бэкенд Ollama** рядом с Claude /
ChatGPT / Gemini: выберите **Ollama (локально)** в выборе бэкенда, и
оркестратор ведёт ваш живой граф локальной моделью — без аккаунта, без
API-ключа, полностью офлайн. Модель видит роутер из 6 инструментов (3
компактных мета-инструмента comfyui плюс `panel_list_tools` /
`panel_describe_tool` / `panel_call_tool` для живого холста), так что даже
4B-модель не тонет в схемах. Модель по умолчанию:
**`artokun/gemma4-comfyui-mcp:e4b`** — [наш дообученный gemma4](#наши-дообученные-локальные-модели-бесплатно-рекомендуем),
обученный на этом точном наборе инструментов (сменяет стоковый `gemma4:e4b`,
прежнего лидера Арены); переопределите через `COMFYUI_MCP_OLLAMA_MODEL` или
выбор модели панели, который перечисляет то, что вы подтянули локально. Ждите
честных компромиссов против передовых бэкендов: более медленные ходы
(особенно первый, пока модель грузится), нет vision, нет отката разговора.
## Что вы получаете (и не получаете)
Любой MCP-клиент получает **полную поверхность инструментов** — генерацию,
создание воркфлоу, модели, кастомные узлы, очередь, диагностику — в любом
режиме инструментов. **Дополнения плагина** Claude Code (скиллы,
слэш-команды, хуки, установочные пакеты, агент боковой панели) — возможности
плагина и не едут в другие обвязки. Каталог `list_tools` спроектирован нести
достаточно ориентации, чтобы агенты без этого слоя знаний всё равно находили
дорогу.
## Устранение неполадок
* **Модель вызывает `call_tool` со строковым `args`** — поддерживается;
сервер автоматически разбирает JSON-строки.
* **Модель выдумывает имена инструментов** — неизвестные имена возвращают
предложения близких совпадений плюс указатель обратно на `list_tools`.
* **Неверные/отсутствующие параметры** — ошибка включает JSON Schema
инструмента; способные модели себя правят на следующей попытке.
* **Модель отвечает из каталога, ничего не запуская** — известный режим
отказа небольших моделей; подтолкните её («записи каталога — имена
инструментов, а не данные — запусти инструмент через call\_tool»).
* **ComfyUI недоступен** — компактный режим меняет только *регистрацию*
инструментов; конфиг подключения идентичен любой другой настройке (см.
[Настройки](/docs/docs/ru/configuration)).