Requisitos do modelo
Seja franco consigo mesmo sobre o modelo que você está trazendo. A spec mínima para a experiência completa é um modelo com chamada de ferramentas + thinking + visão:
Modelos hospedados que cabem na spec completa mudam todo mês — confira o
card do modelo no seu provedor para as três capacidades em vez de
confiar numa lista. Em meados de 2026: Xiaomi MiMo-V2.5 (visão +
ferramentas + contexto longo) cabe na spec completa barato;
DeepSeek-V3.x / GLM / MiniMax têm chamada de ferramentas + thinking
fortes, mas variantes só-texto perdem o loop de visão; modelos locais
pequenos (abaixo) em geral mantêm a chamada de ferramentas e largam o
resto.
Modo compacto de ferramentas
A superfície completa são 37 ferramentas com schemas JSON ricos (~200 KB, cerca de 50k tokens, portools/list). A maioria dos harnesses que não
são Claude injeta cada schema registrado direto no contexto do modelo —
tranquilo para modelos de fronteira, fatal para um 4B local. O modo
compacto de ferramentas registra exatamente três meta-ferramentas e
mantém o catálogo de verdade atrás delas:
O loop do modelo é:
list_tools → escolher → describe_tool →
call_tool. Os schemas entram no contexto uma ferramenta por vez. As
meta-ferramentas são de propósito perdoadoras das manias de modelos
pequenos: args pode ser um objeto ou uma string JSON-encoded,
aliases comuns de campo (tool_name, arguments) são aceitos, e erros
de validação voltam com o schema esperado para o modelo se corrigir em
vez de morrer num erro opaco de protocolo.
O compacto é opt-in — a superfície direta é o padrão, então um
modelo pequeno precisa de um destes (a flag vence a variável de
ambiente):
--full ainda é aceito e agora é um no-op.
Auto-seleção: baseada no modelo, não no provedor
Nos backends de LLM local do painel (Ollama / LM Studio / llama.cpp / compatível com a OpenAI), quando você não escolheu um modo, o modelo escolhe um:- um modelo cujo id carrega uma contagem de parâmetros de 70B ou
mais (
llama3.3:70b,gpt-oss:120b,mixtral:8x22b) recebe a superfície completa; - qualquer coisa menor fica compacto;
- um id de modelo sem contagem de parâmetros legível
(
moonshotai/kimi-k2.5) é tratado como desconhecido, não como pequeno, e recebe o fallback compacto documentado.
COMFYUI_MCP_TOOL_MODE=full força a superfície completa num modelo 4B;
COMFYUI_MCP_TOOL_MODE=compact força o roteador num 405B. A
auto-seleção só preenche a lacuna em que nada foi escolhido.
O limiar de 70B é conservador de propósito: é o único número que alguém
de fato afirmou sobre este eixo, então nada é promovido no chute.
COMFYUI_MCP_FULL_SURFACE_MIN_PARAMS_B=30 abaixa se você quiser
descobrir onde o teto do seu hardware realmente está.
O system prompt segue o modo. O prompt compacto diz ao modelo que
ele tem seis ferramentas e roteia o ComfyUI por call_tool; quando a
superfície completa é selecionada isso simplesmente é mentira, então o
prompt do modo completo diz que as ferramentas do ComfyUI são anunciadas
direto e mantém a descrição do roteador só para panel_*. Auto-selecionar
completo enquanto nega que as ferramentas existem seria pior do que o
padrão que substituiu.
O modo ativo e o motivo dele são impressos na linha de pronto do
backend, por exemplo Tool mode: compact — chosen for this MODEL: "qwen3:4b" is ~4B parameters, below the 70B full-surface threshold…, então a alavanca
nunca fica invisível de novo.
Esta auto-seleção cobre a faixa de LLM local do painel. A faixa HTTP do
Codex / Gemini / Grok / Copilot fica pinada no compacto por outro motivo
— os próprios orçamentos de ferramenta deles expulsam as ferramentas
panel_* caso contrário — e o padrão do servidor MCP standalone não
muda.Entrada de áudio
No backendollama (/api/chat nativo), o áudio chega ao modelo só
onde o modelo de fato reporta que consegue ouvir. Antes de enviar, o
backend pergunta POST /api/show pelas capacidades daquele modelo:
audio, o anexo é
recusado em voz alta — com a lista de capacidades que o servidor
reportou e um comando de pull para um modelo que consegue ouvir — em vez
de ser dropado na requisição onde o modelo responderia só do seu texto.
O mesmo vale para um arquivo que não é um formato de áudio, ou que está
presente mas tem zero bytes.
Entregar os bytes não é bem o trabalho inteiro. Medido ao vivo contra
gemma4:e2b: com o WAV comprovadamente no contexto (555 tokens de
prompt, /api/show reportando audio), o modelo ainda respondeu “I do
not have the capability to transcribe audio — my functions are limited
to operating ComfyUI”. O system prompt do painel o trata como operador
de grafo e um modelo pequeno se racionaliza para fora de um sentido que
ele de fato tem. Então um turno cujo áudio foi checado por capacidade e
anexado também carrega uma nota curta dizendo ao modelo que o áudio está
lá e que ele deve responder a partir do que ouve. Com essa nota o mesmo
modelo transcreveu corretamente em quatro execuções de quatro.
Nos backends compatíveis com a OpenAI (LM Studio, llama.cpp,
OpenRouter, personalizado) não há um endpoint de capacidade para
perguntar. O áudio é enviado como uma parte de conteúdo input_audio e
o turno carrega uma linha explícita “I cannot confirm the model
actually receives them”. Recusar negaria áudio a todo endpoint que
simplesmente não tem uma API de capacidade; uma proteção que não
consegue rodar não é um veredito — mas também não é uma confirmação, e
o texto diz isso.
Veja Backends → Entrada de áudio
para o que cada outro provedor faz.
Configuração com um comando
comfyui-mcp setup <agent> grava a entrada do servidor no próprio
arquivo de configuração do harness (fundindo com o que já está lá —
servidores existentes, comentários em YAML, tudo preservado):
--compact / --full sobrescrevem o padrão por agente,
--comfyui-url <url> embute o seu alvo ComfyUI (URL local, LAN, ou
proxy RunPod), --dry-run imprime a config fundida em vez de gravá-la.
Hermes Agent
~/.hermes/config.yaml (adicione na mão se
preferir):
/reload-mcp (ou reinicie o Hermes). O Hermes prefixa as
ferramentas, então o modelo vê mcp_comfyui_list_tools,
mcp_comfyui_describe_tool e mcp_comfyui_call_tool — três definições
no contexto em vez de duzentas.
Num modelo de fronteira (via Nous Portal / OpenRouter) você pode rodar o
setup de novo com
--full e opcionalmente usar a allowlist
tools.include do próprio Hermes. Compacto é o padrão certo para
qualquer coisa menor.comfyui inclusa que conduz o ComfyUI
por REST cru a partir de scripts Python. Funciona, mas é anterior a este
servidor — a rota MCP te dá autoria/validação de workflows, gerenciamento
de modelos + nós personalizados, pacotes de instalador, controle de fila
e autodiagnóstico. Desative a skill se o agente continuar indo atrás
dela em vez das ferramentas MCP.
OpenClaw
~/.openclaw/openclaw.json:
Copilot CLI
~/.copilot/mcp-config.json:
--compact se estiver
roteando o Copilot para um modelo menor). Confira com /mcp show dentro
de copilot.
Nossos modelos locais com fine-tune (gratuitos, recomendados)
Se você quer rodar o agente localmente de graça, comece aqui. Fizemos fine-tune da família Gemma 4 especificamente para o comfyui-mcp: treinada em QLoRA em 1.055 trajetórias de uso de ferramenta verificadas no servidor sintetizadas contra um ComfyUI ao vivo — cobrindo a superfície completa de 178 ferramentas (113 MCP + 65 do painel) — então o modelo conhece este conjunto exato de ferramentas de forma nativa em vez de encontrá-lo frio.
Cada degrau agora vence a base de estoque. O retrain v2 do
:e2b
(treino em duas visões: chamadas diretas de ferramenta E o envelope do
roteador implantado) consertou a regressão de formato call_tool da v1
— zero envelopes malformados nas execuções de veredito. A orientação de
tamanho se mantém: :e4b é o ponto ideal (só ~1.5 GB a mais que o e2b e
+4 na arena); :e2b agora é uma escolha legítima para VRAM apertada;
:12b compra estabilidade em tarefas longas de vários passos, não
pontuação crua.
O backend Ollama do painel assume
:e4b por padrão — escolha
Ollama (local) no seletor de backend e funciona assim que o modelo
é puxado. Sem conta, sem chave de API, sem custo por token.
Janela de contexto: as tags saem com uma janela de 65.536 tokens
assada, e o orquestrador cede a ela (modelos de estoque recebem 16K). A
arquitetura suporta até 128K (:e2b/:e4b) e 256K (:12b) —
suba com COMFYUI_MCP_OLLAMA_NUM_CTX=131072 se você tem a VRAM (o cache
KV cresce com a janela). Se o agente começar a “esquecer” no meio da
conversa, olhe o log do orquestrador: ele avisa quando um turno enche
≥85% da janela. Pesos, adapters LoRA e o pipeline de treino são abertos:
artokun/gemma4-comfyui-mcp
(dataset: artokun/comfyui-mcp-trajectories).
LM Studio
O painel fala LM Studio nativamente: escolha LM Studio no seletor de backend e o orquestrador conduz o servidor local dele (http://127.0.0.1:1234/v1, sobrescreva com
COMFYUI_MCP_LMSTUDIO_HOST). O setup são dois cliques: instale em
lmstudio.ai, depois Developer → Start Server
com um modelo com chamada de ferramentas carregado. O seletor de
modelos espelha o que o servidor oferece; sem um padrão definido, o
primeiro modelo servido é adotado automaticamente. O orquestrador
gerencia o ciclo de vida completo sem as mãos: inicia o servidor
automaticamente quando precisa, faz JIT-load do seu modelo, libera a
VRAM dele enquanto uma renderização do ComfyUI roda (o chat fica em
espera e é respondido quando a renderização termina), descarrega o
modelo de saída numa troca de modelo, e libera tudo quando você troca
para outro provedor.
Os nossos GGUFs com fine-tune funcionam aqui também — busque
artokun/gemma4-comfyui-mcp no downloader de modelos do LM Studio e pegue
um model-q4_k_m.gguf. Espere a mesma pausa de cold-load JIT na primeira
mensagem que o Ollama tem (30s+ é normal).
llama.cpp (llama-server)
Rodandollama.cpp cru? Escolha llama.cpp no seletor de backend — o
orquestrador conduz o endpoint compatível com a OpenAI do llama-server
(http://127.0.0.1:8080/v1, sobrescreva com
COMFYUI_MCP_LLAMACPP_HOST):
-c) — o
agente avisa se o servidor roda abaixo de 16K (o payload de ferramentas
precisa disso). A chamada de ferramentas vem ligada por padrão nos
builds atuais; builds mais antigos precisam de --jinja (o painel
detecta um servidor incapaz de ferramentas no conectar e diz exatamente
isso). O único modelo carregado é adotado automaticamente — sem precisar
escolher.
Numa caixa de uma GPU só, um llama-server local (ou llama-swap na
frente) entra no mesmo handoff de VRAM que o Ollama e o LM Studio:
enquanto uma renderização do ComfyUI roda, o seu chat fica em espera e é
respondido no momento em que a renderização termina. Como o llama-server
não tem uma API de unload (e o llama-swap troca modelos no upstream sob
demanda), o handoff é só espera — nada é descarregado ou aquecido de
forma explícita. Um COMFYUI_MCP_LLAMACPP_HOST remoto é a GPU de
outra pessoa e nunca é bloqueado. O handoff vem ligado por padrão nos
três backends locais; saia com COMFYUI_MCP_PAUSE_LOCAL_ON_GEN=0 (o
legado COMFYUI_MCP_OLLAMA_PAUSE_ON_GEN=0 ainda é honrado).
Endpoint personalizado (qualquer servidor compatível com a OpenAI)
Qualquer coisa que fale/v1/chat/completions — vLLM, DeepSeek,
Together, Azure OpenAI, um llama-server em outra caixa, o gateway da sua
empresa — entra como o provedor Endpoint personalizado:
- Configurações do ComfyUI → Comfy MCP Agent → Endpoint personalizado
→ defina a URL base do endpoint (inclua o
/v1, por exemplohttp://192.168.1.20:8000/v1). - Se o servidor precisa de uma chave: Definir chave de API… — uma
entrada mascarada; a chave é guardada
0600pelo orquestrador em~/.comfyui-mcp, nunca nas configurações do ComfyUI ou no chat. - Escolha Endpoint personalizado no seletor de backend e Conectar.
/v1/models do servidor; servidores de um
modelo só são adotados automaticamente, ou defina um id de Modelo
padrão explicitamente para endpoints que não listam modelos. Válvulas
de escape de env: COMFYUI_MCP_CUSTOM_BASE_URL,
COMFYUI_MCP_CUSTOM_MODEL, COMFYUI_MCP_CUSTOM_API_KEY. O modelo precisa
suportar chamada de ferramentas.
Ollama e modelos locais — a Arena de LLMs
Qualquer harness MCP que fale com o Ollama (ou um endpoint compatível com a OpenAI) consegue conduzir o modo compacto com um modelo local. Dois harnesses repetíveis vêm no repositório:npm run test:local-llm
(checagem rápida de um modelo) e node scripts/llm-arena.mjs — a
Arena de LLMs do ComfyUI, que passa um campo de modelos por um
conjunto idêntico de tarefas contra um ComfyUI ao vivo e verifica cada
desfecho contra o servidor, nunca contra as afirmações do modelo.
Pontuações da faixa local na escada completa de 10 cenários (RTX 4090,
ComfyUI 0.27, temperature 0 — veja a página da Arena
para a escada de tarefas e o ranking de todas as faixas inclusive
fronteira e hospedados):
O que fica: a classe qwen3/gemma4 passa com folga as tarefas de uma
ferramenta (saúde, modelos instalados, busca no registro, fila) e pega
pontos nas faixas mais duras, mas a composição de grafo em vários
estágios (um grafo com duas saídas encadeadas, um pipeline img2img
estagiado em dois estágios) ainda é território de fronteira/B-tier. A
disciplina de formato de ferramenta do llama3.1:8b desaba neste catálogo
(ele alucina nomes de ferramenta e imprime JSON de chamada como texto).
O Gemma 4 saiu com function calling nativo na família toda (Ollama ≥
v0.20);
e4b ou maior é o ponto ideal.
Lembre da escada de capacidades acima: esses modelos pequenos mantêm a
chamada de ferramentas mas têm visão e thinking limitados/nenhum, então
conseguem gerar e gerenciar workflows mas não conseguem criticar
visualmente os resultados.
O painel lateral num modelo local
O agente do painel ganha um backend Ollama ao lado de Claude / ChatGPT / Gemini: escolha Ollama (local) no seletor de backend e o orquestrador conduz o seu grafo ao vivo com um modelo local — sem conta, sem chave de API, totalmente offline. O modelo vê o roteador de 6 ferramentas (as 3 meta-ferramentas compactas do comfyui maispanel_list_tools / panel_describe_tool / panel_call_tool para
o canvas ao vivo), então mesmo um modelo 4B não afoga em schemas. Modelo
padrão: artokun/gemma4-comfyui-mcp:e4b — o nosso fine-tune do
gemma4,
treinado neste conjunto exato de ferramentas (substitui o gemma4:e4b
de estoque, o melhor anterior da Arena); sobrescreva com
COMFYUI_MCP_OLLAMA_MODEL ou o seletor de modelos do painel, que lista
o que você puxou localmente. Espere trocas honestas em relação aos
backends de fronteira: turnos mais lentos (especialmente o primeiro,
enquanto o modelo carrega), sem visão, sem rollback de conversa.
O que você ganha (e o que não ganha)
Qualquer cliente MCP recebe a superfície completa de ferramentas — geração, autoria de workflows, modelos, nós personalizados, fila, diagnósticos — em qualquer modo de ferramenta. Os extras do plugin do Claude Code (skills, comandos de barra, hooks, pacotes de instalador, o agente do painel lateral) são recursos do plugin e não viajam para outros harnesses. O catálogolist_tools é desenhado para carregar
orientação suficiente para agentes sem aquela camada de conhecimento
ainda encontrarem o caminho.
Solução de problemas
- O modelo chama
call_toolcom umargsstringificado — suportado; o servidor parseia strings JSON-encoded automaticamente. - O modelo inventa nomes de ferramenta — nomes desconhecidos devolvem
sugestões de match próximo mais um ponteiro de volta para
list_tools. - Parâmetros errados/faltando — o erro inclui o JSON Schema da ferramenta; modelos capazes se corrigem na próxima tentativa.
- O modelo responde a partir do catálogo sem rodar nada — um modo de falha conhecido de modelo pequeno; empurre-o (“entradas do catálogo são nomes de ferramenta, não dados — rode a ferramenta com call_tool”).
- ComfyUI inalcançável — o modo compacto só muda o registro de ferramentas; a config de conexão é idêntica a qualquer outro setup (veja Configuração).