> ## 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. # Как пользоваться инструментами > Что такое инструменты, почему вы никогда не вызываете их сами и что делать, когда один из них говорит «нет». Написано для людей, а не для инженеров. [Справочник инструментов](/docs/docs/tools/image-generation) перечисляет всё, что умеет этот проект, в той форме, в которой это читает ИИ. Эта страница — версия для вас. Здесь не нужно писать код, набирать JSON или учить API. Если вы когда-нибудь просили человека «открой мой портретный воркфлоу и подними steps до 30», интерфейс вы уже знаете. ## Инструмент — это то, что агент умеет делать, а не то, что вы набираете Сам по себе чат-модель умеет только производить текст. Она может описать воркфлоу; открыть его она не может. **Инструмент** — это конкретное именованное действие, которое мы даём модели, чтобы она реально дотянулась до вашего ComfyUI — загрузить файл, поставить рендер в очередь, установить пакет узлов, посмотреть получившуюся картинку. Модель не имеет права выдумывать эти действия. Она получает фиксированное меню, и каждый пункт меню говорит ровно то, что ему нужно. **Вы никогда не выбираете из этого меню.** Вы говорите, чего хотите, теми словами, которые приходят сами, а агент выбирает. | Вы говорите | Он тихо запускает | | ---------------------------------------------- | -------------------------------------------------------------- | | «Что у меня сохранено?» | `get_workflow` with `action: "list"` | | «Открой тот портретный и скажи, что он делает» | `get_workflow` with `action: "list"`, then `action: "analyze"` | | «Сделай мне рыжую лису в снегу» | `generate_image` (the `image` job) | | «Уже готово?» | `queue` (the `list` job) | | «Это упало, и я не понимаю почему» | `get_history` (the `diagnose` job) | | «Половина узлов красные» | `list_packs` (the `install_deps` job) | | «Место на диске кончилось, что большое?» | `list_local_models` | Обратите внимание на вторую строку: одна фраза, два инструмента, в порядке, который вам не нужно было знать. В этом и смысл всей схемы. От вас не ждут, что вы будете знать: найти файл и прочитать файл — это разные операции. Можно быть сколь угодно расплывчатым. «Что-то сломалось» — вполне нормальное начало: агент начнёт с `get_system_stats (action:"health")` и сузит круг. Конкретность ускоряет дело, но никогда не обязательна. ### Тогда зачем весь этот JSON на страницах справочника? Каждая страница инструмента показывает блок вроде этого: ```json theme={null} { "tool": "generate_image", "arguments": { "prompt": "a red fox in deep snow, golden hour, sharp focus", "steps": 30 } } ``` Это расшифровка того, что отправил агент, а не инструкция для вас. Вы сказали «сделай мне рыжую лису в снегу и добавь чуть больше детализации»; вот что вышло с другой стороны. Уметь такое читать стоит по двум причинам: когда хотите проверить, что агент вас понял, и когда что-то пошло не так и вы описываете это кому-то ещё. Заучивать это не стоит. ## Инструменты приходят из двух мест Есть две поверхности, и они существуют, потому что отвечают на разные вопросы. Живёт **внутри ComfyUI**, во вкладке Агент. Её инструменты (`panel_*`) действуют на граф, который вы смотрите прямо сейчас — настоящий холст, с вашими несохранёнными правками. Claude Desktop, Claude Code, редактор, телефон. Его инструменты действуют на **сервер**: файлы на диске, очередь заданий, модели, пакеты узлов, сам процесс ComfyUI. Разделение на самом деле про слово «это». Когда вы говорите «добавь LoRA к **этому**», панель знает, что такое «это», потому что видит ваш экран. Внешний клиент не может — ему нужно назвать имя файла. Поэтому панель берёт на себя такие вещи, как: * прочитать граф перед вами (`panel_graph_outline`) * запустить его ровно так, как если бы вы сами нажали Queue Prompt (`panel_run`) * подключить узел, изменить виджет, сказать, почему узел стал красным (`panel_add_node`, `panel_set_widget`, `panel_get_errors`) * загрузить целый воркфлоу на холст или сохранить то, что там есть (`panel_load_workflow`, `panel_save_workflow`) А внешний клиент берёт на себя генерацию изображения с нуля, управление моделями и пакетами узлов, работу с сохранёнными файлами и перезапуск ComfyUI. **Если вы новичок, используйте панель.** Это одна установка, она прямо рядом с графом и не требует отдельного приложения. См. [руководство по панели](/docs/docs/ru/panel), чтобы настроить. Внешний клиент добавите позже, когда агент понадобится для вещей, которые не холст. Они не соперники — панель говорит с тем же сервером внизу, и сессия может использовать оба. Кто-то правит граф на рабочем столе, пока телефон ведёт ту же сессию — это поддерживаемый сценарий, а не хак. ## Один инструмент, несколько задач Вы заметите, что некоторые инструменты принимают `action`: ```json theme={null} { "tool": "workspace", "arguments": { "action": "get" } } ``` Это выглядит загадочно — и не является. `workspace` — это тема: *о какой установке ComfyUI речь* — а `action` говорит, какой вопрос вы задаёте об этой теме: прочитать, сменить значение по умолчанию, перечислить доступное. Читается ровно как обычная речь, где глагол и объект — отдельные слова: | Вы говорите | Действие | | --------------------------------- | ------------- | | «Какой ComfyUI я использую?» | `get` | | «Всегда бери тот, что на диске D» | `set_default` | | «Какие установки ты видишь?» | `list` | ### Ничего не убрали Эта форма довольно новая, и её легко прочитать как урезание возможностей. Это не так, и путаницу стоит снять сразу, потому что она уже возникала. Раньше на каждый вопрос был свой инструмент — отдельное имя, чтобы прочитать workspace, другое — чтобы задать, третье — чтобы перечислить. Эти имена пропали, и если смотреть на число инструментов, оно падает, резко. На самом деле связанные инструменты **объединили**, а не удалили: | The old name | The same thing today | | ------------------------------- | ------------------------------------------- | | `get_workspace` | `workspace` with `action: "get"` | | `get_queue` | `queue` with `action: "list"` | | `apps_run_status` | `apps` with `action: "run_status"` | | `install_workflow_dependencies` | `list_packs` with `action: "install_deps"` | | `list_workflows` | `get_workflow` with `action: "list"` | | `analyze_workflow` | `get_workflow` with `action: "analyze"` | | `validate_workflow` | `create_workflow` with `action: "validate"` | Тот же код внизу, то же поведение, те же ответы. Сменилась только этикетка спереди. Причина в том, что меню стало достаточно длинным, чтобы вредить. Полное описание каждого инструмента нужно отдать модели, прежде чем она сможет выбрать, и после определённого размера само выбирание деградирует — особенно небольшие модели начинают брать правдоподобного соседа вместо нужного. Меньше, шире инструменты с ясным `action` это измеримо исправляет. Ещё это значит, что модель тратит внимание на ваш запрос, а не на чтение каталога. Вы ничего из этого не должны заметить. Старое имя вы тоже никогда не набирали; вы говорили «какой у меня ComfyUI?», и это по-прежнему работает. Если какой-то старый гайд или собственная память модели тянется к имени, которого больше нет, вы получаете конкретную ошибку с именем замены, а не пустой «unknown tool» — например: *removed in 0.49.0. Call workspace (action:"get") instead.* Агент обычно сам себя поправит и повторит попытку, ничего от вас не требуя. ## Попросить что-то другое Каждая страница инструмента перечисляет параметры — `max_chars`, `limit`, `depth`, `fields`. Справедливый вопрос: куда их набирать, и честный ответ: никуда. Нет окна настроек для `max_chars`, потому что это не настройка. Это аргумент, который **агент** заполняет заново при каждом вызове инструмента. Это не выводит вас из игры. Меняется то, как выглядит управление: Вы не задаёте параметр. Вы просите его — в той же фразе, которую и так собирались написать. ### Два способа попросить Оба работают. Ломаются они по-разному — только поэтому стоит знать оба. | | Звучит как | Беритесь, когда | | ----------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------ | | **Простой** | «Прочитай узел 42 подробно — только этот узел, не весь граф.» | Всегда начинайте отсюда. Именно так люди и пишут, и обычно это работает. | | **Явный** | «Используй `panel_query_graph` с `ids` \[42] и `max_chars` 20000.» | Модель уже ошиблась один раз, и вы не хотите оставлять ей пространства. | Назвать инструмент и аргумент — не *правильная* форма, а *жёсткая*. Оставьте её для повторной попытки. ### Когда ответ обрезают Длинные чтения ограничены, чтобы один огромный граф не проглотил весь разговор. Один и тот же разбор могут остановить два разных потолка — число перечисленных узлов (`limit`) и бюджет символов (`max_chars`) — и поднять тот, который не был проблемой, ничего не меняет, что читается ровно как провал повторной попытки. От вас не ждут, что вы разберётесь, какой. На сохранённом файле примечание **называет сработавший рычаг и исключает другой**, прямым текстом: > … truncated at 40 of 300 by `limit`=40 — raise `limit` up to 200, or narrow with `types`/`where`/`ids`/`depth`. `max_chars` is not the constraint here. А когда рычаг уже на потолке, оно так и говорит, вместо того чтобы снова просить его поднять, потому что поднимать больше нечего. На живом холсте (`panel_query_graph`) тот же разбор выполняет собственная копия этого движка в панели, которая ещё не догнала эту формулировку. Если примечание там называет аргумент, а его повышение ничего не меняет, попробуйте другой, прежде чем решить, что инструмент сломан. Агент должен прочитать своё собственное примечание и повторить попытку сам. Когда он этого не делает, запасной вариант — вы, и вот эта фраза: > Это обрезали — прочитай примечание и повтори тот же запрос, подняв предел, > который оно называет. ### Где стены Вот числа для двух инструментов, которые читают граф с бюджетом — `panel_query_graph` (живой холст) и `get_workflow` with `action: "query"` (сохранённый файл): | Аргумент | По умолчанию | Больше всего, что можно попросить | | ----------------------------- | ------------ | --------------------------------- | | `max_chars` | 12000 | 60000 | | `limit` (перечисленных узлов) | 40 | 200 | На этих двух инструментах запрос сверх потолка отклоняется как неверный аргумент, а не тихо округляется вниз, поэтому агент узнаёт сразу и может себя поправить. Числа и не универсальны: несколько других инструментов принимают `max_chars` и ставят свой потолок, указанный в описании того инструмента. ### Область важнее бюджета Поднять потолок — второе, что стоит пробовать, не первое. На воркфлоу из 600 узлов больший бюджет в основном покупает вам больше не тех узлов, а закопать ответ среди сотен посторонних портит ответ даже тогда, когда он технически умещается. Сначала сузьте, теми словами, которые естественны: | Вы говорите | К чему это сужает | | ----------------------------------- | ------------------------------ | | «Посмотри только узлы 42 и 43.» | только эти id | | «Что питает сэмплер?» | входящая сторона одного узла | | «…только на два шага назад.» | ограниченное расстояние оттуда | | «Сколько здесь узлов каждого типа?» | счётчики вместо списка | Потом, если всё ещё обрезано, расширяйте. ## Когда он говорит «нет» Отказ инструмента обычно не баг. Большинство отказов — сработавшая защита, потому что вызов сделал бы то, о чём вы не просили. ### «Он отказал, и я не понимаю почему» Вы увидите текст на обычном языке, а не трассировку стека — что-то, что называет, чего он не стал делать и что делать вместо этого. Читайте это как осторожность агента, а не как застревание. Честные частые отказы: * **Он не может понять, о каком воркфлоу речь.** Открыто больше одной вкладки, или у графа ещё нет сохранённой личности. Сохраните его или скажите, какой. * **Это перезаписало бы что-то.** Попросите новое имя файла — и он продолжит. * **Вещи действительно нет.** Файл модели, пакет узлов, работающий сервер. Если отказ читается как бессмыслица, а не как осторожность, это стоит сообщить — попросите агента завести issue, и он приложит детали вашей конфигурации за вас. ### «Эта панель слишком старая» Самый частый отказ с настоящим исправлением. Читается примерно так: > This ComfyUI-MCP panel is too old for *"…"* — update the ComfyUI-MCP panel, then reconnect. Боковая панель и этот сервер — отдельные части, которые выпускаются отдельно, поэтому одна может отставать от другой. Когда сервер просит то, что установленная панель не может сделать безопасно, он отказывается, а не угадывает — старая панель, которая не может подтвердить, *на какой* воркфлоу ляжет команда, могла бы применить правку не к той вкладке, поэтому её держат на чтении, пока не обновят. Исправление в три шага, и **третий — тот, который люди пропускают**: Попросите агента обновить её (`install_comfyui(action:'panel', panel_action:'update')`), или сделайте это из ComfyUI-Manager, где она числится как `comfyui-agent-panel`. Обновление само ничего не перезапускает. Попросите агента или перезапустите сами. **Ctrl+Shift+R** (**Cmd+Shift+R** на Mac). Браузер кэширует старый код панели, и одного перезапуска недостаточно, чтобы его сбросить. Пропустите этот шаг — и то же сообщение вернётся сразу, из-за чего кажется, будто обновление не сработало, хотя оно сработало. ### «Панель не подключена» Другая проблема, похожее сообщение. Это значит, что внешний агент не может найти вкладку браузера вашего ComfyUI. Почти всегда это одно из: * ComfyUI вообще не открыт в браузере — откройте его и посмотрите вкладку Агент на боковой панели. * ComfyUI только что перезапустили, или вы перезагрузили вкладку. Это рвёт соединение. **Перезагрузите вкладку ComfyUI** — и оно сразу вернётся. * Вкладка Агент открыта, но никогда не была подключена. Панель присоединяется, когда вы выбираете провайдера и нажимаете **«Подключить»**, никогда при загрузке, поэтому только что открытая вкладка, которая ничего не показывает, — обычное состояние, а не поломка. * Панель ещё не установлена. См. [руководство по панели](/docs/docs/ru/panel). Сообщение делит это на две группы за вас — отличает «подключалось раньше и отвалилось» от «ещё ничего не подключалось». Дальше оно не идёт и так и говорит, вместо того чтобы выбрать причину, которую не может наблюдать. Вкладка, которая подключалась раньше, доказывает, что панель установлена и работала, поэтому перезагрузка вкладки ComfyUI — первое, что стоит попробовать, и обычно единственное; если перезагрузка не вернула её, считайте это второй группой и идите по проверкам выше. ## Когда он ничего не говорит Более трудный сбой — тот, в котором вообще нет ошибки. Агент не вызывает инструмент, не отказывает, не жалуется. Он просто говорит: описывает, что, вероятно, содержит ваш воркфлоу, или предлагает написать вам скрипт. Звучит полезно — и он ничего не смотрел. Три совершенно разные ситуации дают одно и то же поведение, и с вашего места они неразличимы: Ваш клиент так и не получил инструменты. Их нет в списке, который он отдаёт модели, поэтому вызывать нечего. У клиента инструменты есть, и он не даёт модели их запускать. Вызов останавливается внутри вашего клиента. Всё работает. То, что вы хотели, существует под именем, которое ни разу не всплыло, поэтому никто за ним не потянулся. Средства указывают в три разные стороны, и два из них активно вредны, если угадать неверно: переустановить уже установленное или ослабить права, которые никогда не были проблемой. Поэтому первый шаг — не чинить что-то. А выяснить, в каком вы случае. ### Два вопроса, которые их различают Спросите агента простыми словами: > Какие инструменты у тебя есть от comfyui-mcp? Просто перечисли имена. Список из нескольких десятков имён — нормально и здорово: это прямая поверхность, которая с 0.50.0 стоит по умолчанию. **Три имени** — `list_tools`, `describe_tool`, `call_tool` — это *тоже* нормально и здорово. Это [компактный режим](#если-вы-используете-небольшую-локальную-модель), который вы получаете, передав `--compact`, и который небольшие локальные модели по-прежнему выбирают автоматически. Остальной каталог в одном вызове `list_tools`, так что попросите его выполнить — и увидите настоящий список. Ни один из этих ответов не значит, что что-то удерживают. **Вообще никаких имён** или «У меня нет инструментов для ComfyUI» исключает третий случай и больше ничего. Это **не** значит «нет». Политика прав может удержать инструменты из списка, который показывают модели, поэтому установленный, подключённый и работающий сервер даёт ровно этот ответ. «Нет» и «заблокировано» на этом шаге неразличимы, и именно эта ветка стоила пользователю нескольких дней — он был уверен, что дело в проводке. Одна проверка сужает круг, и это не то, что видит агент: **откройте собственный список MCP-серверов вашего клиента** — место, где он показывает, к каким серверам подключился; это другой список, не тот, который он отдаёт модели. * **comfyui-mcp там нет или показан как failed** → **нет**. Проблема проводки на стороне клиента, а не панели или сервера. Она снова делится надвое — никогда не подключали или хост, который вообще не может их держать — и список [ниже](#откуда-обычно-берётся-каждый-ответ) их различает. * **Он там и подключён, а модель по-прежнему ничего не перечисляет** → инструменты дошли до вашего клиента. Где они остановились дальше, ещё открыто: их может удерживать от модели правило прав, или модель просто не смогла или отказалась их перечислить — отсюда это выглядит одинаково. **Не** начинайте ослаблять права только из-за этого. Если тот список серверов ещё показывает, **какие инструменты он взял у comfyui-mcp**, это решает: инструменты перечислены там, но не моделью — значит, проблема в модели, а не в ваших правах; ничего там нет — значит, их фильтруют, прежде чем модель их увидит. Если ваш клиент этого не показывает — а многие не показывают — ничто из доступного вам здесь не различает эти два случая, и шаг 2 даёт лучший шанс, потому что отказ приходит словами. > Теперь вызови тот, который использовал бы для того, что не работает, > и вставь ровно то, что вернётся — включая любую ошибку. Не обходи. Две детали в этой фразе делают работу. **Тот инструмент, который использовал бы для того, что не работает**, именно. Правила прав обычно пишут по инструменту, поэтому успех другого инструмента ничего не доказывает про тот, который вам важен — именно так прячется блокировка. Если не читается холст, проверка должна быть чтением холста. **Не обходи.** Весь этот сбой — агент тихо обходит препятствие вместо того, чтобы его назвать, и предоставленный себе он сделает это снова. * **Настоящий результат** — этот инструмент работает. Вы в третьем случае. * **«Это отклонили» / «не разрешено» / «мне нужно разрешение»** — **заблокировано**, внутри вашего клиента. Этот случай окончательный: агент спросил и получил отказ. * **«У меня нет этого инструмента»** — всё ещё нет *или* заблокировано. Удержанный инструмент и отсутствующий выглядят одинаково с места модели, поэтому не действуйте только из-за этого: вернитесь к списку серверов шага 1, и если тот список тоже не показывает инструменты по серверам, тогда ничто, до чего вы можете дотянуться, их не разделяет, и честный следующий шаг — спросить в трекере issues, а не начинать менять настройки. * **Снова проза, по-прежнему нет вызова** — спросите прямо: *«Ты вызвал инструмент? Если нет, почему нет?»* Агент, который уклоняется дважды, обычно обходит что-то, о чём не сказал. ### Что мы видим отсюда, а чего нет Когда ваш клиент отказывает в вызове инструмента, этот вызов никогда не покидает ваш клиент. До этого сервера ничего не доходит, поэтому ничего не появляется в его логе и нигде, куда мы можем дотянуться, ошибка не возникает. Мы не можем обнаружить блокировку и не будем притворяться: любая страница или сообщение, которые претендуют сказать вам «ваш клиент это заблокировал», гадали бы. Тот же факт режет и в другую сторону, и именно эта часть вводит людей в заблуждение: тихий лог — не доказательство, что ничего не пытались. «Нет», «заблокировано» и «никогда не просили» отсюда все выглядят как тишина. Поэтому два вопроса выше — настоящая диагностика. Они работают, потому что спрашивают единственного участника, который *был* в комнате — вашего агента — сказать, что он пробовал, и отказывают ему в возможности обойти ответ. ### Откуда обычно берётся каждый ответ **Заблокировано — собственные правила прав вашего клиента.** В Claude Code это блок `permissions` в `settings.json` (`~/.claude/settings.json` или `.claude/settings.json` проекта); MCP-инструменты появляются там под именами с пространством имён, `mcp__comfyui__`. Строгий список `allow`, который их никогда не упоминает, останавливает каждый вызов, пока он не отправлен. Это тот случай, который стоил одному пользователю нескольких дней: инструменты выглядели рабочими именно потому, что ошибки, которые он искал, никогда не могли появиться. **Нет, и чинится — никогда не подключали.** Клиент говорит на MCP, но ему никогда не сказали про этот сервер, или сказали, и запись неверна. Это частый случай, и это правка конфига; см. [Быстрый старт](/docs/docs/ru/quickstart) про запись, которую ждёт ваш клиент. **Нет, и не чинится — хост вообще без MCP-клиента.** Некоторые агенты не говорят на MCP, и никакое количество настроек этого не меняет. `pi` — один из них: у него свои встроенные инструменты оболочки и редактора и нет MCP-клиента, поэтому наши ему нельзя отдать, что бы ещё ни было установлено. Панель говорит это прямо, когда вы его выбираете — *«у pi нет инструментов ComfyUI (нет MCP)»*. Эта строка и есть ответ, а не симптом для отладки; исправление — выбрать другой бэкенд. **Любой из двух — что-то посередине.** Шлюз, прокси или маршрутизатор, который несёт ваш MCP-трафик, может пропускать только часть поверхности. Если каталог и то, что реально выполняется, не согласны друг с другом, подозревайте середину. ### Если это третий случай Тогда ничего не было сломано и никто ничего не настроил неправильно: возможность существовала, и у вас не было способа это узнать. Это наш сбой, а не ваш, и об этом стоит сказать — попросите агента завести issue, и он приложит вашу конфигурацию за вас. Функция, которую никто не может найти, с вашего места — это функция, которую мы не поставили. ## Если вы используете небольшую локальную модель Отдать модели всё меню стоит большого чтения, прежде чем она скажет слово. На большой размещённой модели это нормально. На небольшой модели, которая работает на вашей машине, это часто разница между «работает» и «не работает». Поэтому по умолчанию агент получает **три** инструмента вместо полного набора: один, чтобы листать каталог, один, чтобы посмотреть один инструмент подробно, и один, чтобы его запустить. Он берёт то, что нужно, когда нужно, а не читает всё заранее. Вам ничего не нужно делать, чтобы это получить — так и есть по умолчанию. Элементы управления есть, если они вам нужны: ```bash theme={null} # force the small three-tool mode npx -y comfyui-mcp --compact # or hand the model everything at once npx -y comfyui-mcp --full ``` Любой из них также задаётся через `COMFYUI_MCP_TOOL_MODE=compact` или `COMFYUI_MCP_TOOL_MODE=full`. Обмен — пара лишних кругов до первого настоящего действия в обмен на модель, у которой осталось место думать. Большие модели обычно счастливее с `--full`. См. [локальные LLM](/docs/docs/ru/local-llms), какие модели с чем справляются. ## Куда дальше Установите и сгенерируйте первое изображение. Агент внутри ComfyUI и что он умеет делать с вашим холстом. Каждый инструмент с разобранными примерами того, как выглядит настоящий вызов. Когда это не отказ и что-то действительно сломано.