Como reparar um workflow quebrado do ComfyUI com Claude

Não comece pedindo ao Claude para reescrever o workflow inteiro. Preserve o JSON original no formato normal de salvamento e os erros exatos, prove que um workflow padrão atual funciona com os custom nodes desativados e só então deixe o Claude classificar as evidências fornecidas. Altere uma dependência por vez, reconstrua o menor grafo viável, execute uma imagem e confirme pessoalmente que o resultado aparece em Save Image, pode ser salvo e abre novamente.

Esse método transforma “o ComfyUI mudou muito” em camadas testáveis: núcleo do ComfyUI, extensões de frontend, custom nodes, arquivos de modelo ou o próprio grafo antigo. O guia oficial de troubleshooting do ComfyUI também recomenda testar o workflow padrão, desativar custom nodes e ler o erro exato do terminal antes de aplicar uma correção.

Sequência de reparo em sete passos

1. Mantenha o workflow original no formato normal de salvamento e nunca o sobrescreva.
2. Registre o erro completo, o log de inicialização, o tipo de instalação, versões e mudanças recentes.
3. Desative todos os custom nodes e execute o workflow padrão atual de imagem.
4. Entregue ao Claude um pacote limitado de evidências; análise antes de edição ou instalação.
5. Classifique a falha como core, frontend, custom node, model ou unknown.
6. Atualize ou substitua um nó incompatível, ou reconstrua um grafo mínimo atual.
7. Execute uma imagem pequena e verifique o arquivo salvo de verdade.

1. Congele o workflow e as evidências antes de mudar qualquer coisa

Salve o workflow antigo como JSON normal e crie uma cópia de trabalho separada. Uma pasta pequena deixa a investigação reproduzível:

comfyui-repair-case/
  workflow-original.json
  workflow-working.json
  error-report.txt
  startup-log.txt
  environment.md

Trate workflow-original.json como somente leitura. Coloque em error-report.txt todo o texto de Show report, e não um resumo como “o nó quebrou”. Guarde em startup-log.txt falhas de importação, conflitos de dependência e tracebacks do terminal de inicialização. Em environment.md, registre se a instalação é Desktop, Portable ou manual, a versão do ComfyUI, sistema operacional, GPU e o que foi atualizado recentemente: core, frontend, custom nodes ou modelos.

Preserve também a diferença entre Save format e API format. A página oficial Workflow API Format explica que o salvamento normal retém posições, cores, grupos e outros metadados de edição, enquanto o formato de API é uma representação mais enxuta para envio programático. Mantenha o original em formato normal para o reparo. Exporte uma cópia de API separada apenas quando a tarefa realmente envolver uma API.

2. Prove primeiro que uma base limpa do ComfyUI funciona

O grafo antigo não deve ser o primeiro teste. Desative temporariamente os nós de terceiros. No Desktop, use a opção nas configurações; uma instalação manual normalmente pode ser iniciada assim:

python main.py --disable-all-custom-nodes

Carregue o template padrão atual Image Generation, escolha um checkpoint compatível que já apareça no seletor e gere uma imagem. O guia oficial de custom nodes fornece uma separação útil: se o problema desaparece com todos os custom nodes desativados, um deles está envolvido; se persiste, investigue core, frontend, modelos ou ambiente.

Use o resultado para escolher a próxima ramificação:

Resultado da base	Camada mais provável	Próxima prova
O workflow padrão não abre ou não executa	Instalação core, frontend, modelo ou hardware	Corrija a base antes de editar o grafo antigo
O padrão funciona, mas o antigo mostra missing nodes	Custom nodes ausentes, renomeados ou não carregados	Mapeie os tipos do JSON para seus pacotes
O grafo antigo carrega e falha em um nó	Arquitetura do modelo, conexões, dependências ou memória	Guarde o primeiro nó com falha e o relatório completo
A interface volta ao desativar extensões de frontend	Extensão de terceiros incompatível	Reative metade por vez até isolar uma

Se o grafo padrão falha, reescrever o JSON antigo não comprova um reparo.

3. Dê ao Claude um pacote de evidências com limites claros

A Anthropic descreve Claude Code como capaz de ler uma base de código, editar arquivos e executar comandos. Isso é útil, mas também exige que a primeira passagem seja somente analítica. Inicie o Claude dentro da pasta do caso, ou anexe os mesmos arquivos no chat, com uma instrução como esta:

Você está diagnosticando um workflow do ComfyUI que parou após uma atualização.

Leia apenas:
- workflow-original.json
- workflow-working.json
- error-report.txt
- startup-log.txt
- environment.md

Ainda não instale, atualize, exclua, renomeie nem edite nada.
Primeiro:
1. Liste os tipos de nós e os arquivos de modelo referenciados.
2. Classifique cada problema como ComfyUI core, frontend extension,
   custom node, model file ou unknown.
3. Cite o campo JSON ou a linha de erro exata de cada conclusão.
4. Proponha a menor mudança reversível.
5. Aguarde aprovação antes de editar workflow-working.json.

Não declare sucesso até eu executar uma imagem e confirmar um arquivo salvo.

Uma resposta útil deve ser uma tabela de mapeamento: tipo antigo, extensão proprietária, contrato de entradas e saídas, possível substituto, migração de parâmetros, evidência e risco. Se o pacote ou o substituto não puder ser comprovado, o Claude deve marcar unknown em vez de adivinhar por semelhança de nome.

4. Classifique a falha em vez de atualizar tudo

Nó ausente: identifique o proprietário antes de substituir

Inspecione o type, o título e as ligações do nó ausente no JSON normal. Nomes parecidos não garantem sockets ou valores de widgets compatíveis; trocar uma string no JSON não é uma migração segura. Descubra se o nó pertence ao core ou a um repositório específico de custom node e compare entradas, saídas e parâmetros antigos e novos.

Se a extensão ainda é mantida, atualize apenas ela e teste novamente. Se foi abandonada, escolha uma alternativa mantida ou reconstrua essa pequena função com nós core. O guia oficial apresenta as mesmas saídas: atualizar, substituir, reportar ao autor ou remover/desativar o nó.

Conflito de frontend: desative e faça busca binária

Alguns custom nodes também injetam extensões de frontend. Tela em branco, conexões quebradas, previews ausentes ou falha de comunicação entre frontend e backend podem vir dessa camada. Primeiro desative extensões de terceiros. Se o sintoma sumir, ative metade de cada vez e repita. Essa busca binária preserva a causalidade e é mais segura do que reinstalar tudo.

Modelo ausente: confira pastas e caminhos de busca

Um grafo antigo pode referenciar um checkpoint, VAE, LoRA ou ControlNet que foi removido, renomeado ou movido. O ComfyUI encontra modelos nas pastas categorizadas de ComfyUI/models/ e nos caminhos de extra_model_paths.yaml. Se um seletor está vazio ou mostra null, verifique o local real e depois atualize ou reinicie o ComfyUI. Não renomeie um modelo incompatível apenas para satisfazer um nome antigo.

Arquitetura incompatível: verifique a família, não só o arquivo

O guia oficial de problemas de modelos recomenda manter os modelos do workflow na mesma família de arquitetura. Misturar checkpoint, VAE, text encoder ou ControlNet de famílias diferentes pode gerar erros de dimensões durante amostragem ou VAE decode. O Claude pode relacionar o stack trace ao grafo, mas um template oficial da família pretendida é uma referência de compatibilidade melhor.

5. Atualize ou substitua um único nó na cópia de trabalho

Antes de aprovar uma edição, peça ao Claude este plano:

Item	Pergunta obrigatória
Nó antigo	Qual é o type exato no JSON?
Proprietário	É core, custom node ou frontend extension?
Substituto	Os tipos de entrada e saída correspondem?
Migração de parâmetros	Quais widget values ficam e quais precisam ser refeitos?
Reversão	Como restaurar o workflow-working.json anterior?

Autorize mudanças somente em workflow-working.json, uma falha por vez. Recarregue depois de cada edição e confirme que o nó existe, as conexões continuam válidas e os parâmetros não mudaram de posição. Um “update all custom nodes” pode criar um segundo conflito e elimina a evidência de qual alteração realmente resolveu.

Páginas da comunidade podem ajudar a reconhecer sintomas, mas não são diagnósticos universais. Por exemplo, frontend issue #6328 e ComfyUI discussion #14344 são relatos individuais. Use-os apenas quando versão, erro e contexto do nó coincidirem com o seu caso.

6. Reconstrua um eixo mínimo e atual de imagem

Se o grafo antigo tem muitas ramificações obsoletas de LoRA, ControlNet, upscale, preview e utilitários, reparar todas de uma vez é mais arriscado do que recuperar o núcleo. Reconstrua-o a partir do exemplo mínimo oficial no formato Save do ComfyUI. Não é uma cadeia em série: várias saídas convergem no KSampler, e o VAEDecode recebe separadamente o VAE do checkpoint.

Porta de saída	Porta de entrada
CheckpointLoaderSimple.MODEL	KSampler.model
CheckpointLoaderSimple.CLIP	CLIPTextEncode.clip do prompt positivo
CheckpointLoaderSimple.CLIP	CLIPTextEncode.clip do prompt negativo
CLIPTextEncode.CONDITIONING do prompt positivo	KSampler.positive
CLIPTextEncode.CONDITIONING do prompt negativo	KSampler.negative
EmptyLatentImage.LATENT	KSampler.latent_image
KSampler.LATENT	VAEDecode.samples
CheckpointLoaderSimple.VAE	VAEDecode.vae
VAEDecode.IMAGE	SaveImage.images

EmptyLatentImage não recebe conditioning. O KSampler precisa de quatro entradas independentes —model, positive, negative e latent_image—, enquanto o VAEDecode precisa tanto de samples quanto do vae fornecido pelo checkpoint. Só depois de ligar essas portas como na tabela o grafo mínimo pode entrar na fila e salvar uma imagem.

Use esse cabeamento apenas quando a arquitetura do checkpoint escolhido corresponder ao exemplo oficial. Um modelo novo pode exigir outro loader, text encoder, nó latent ou caminho de VAE; nesse caso, siga o workflow oficial desse modelo em vez de forçar este grafo. Para a base, escolha um checkpoint compatível que já apareça em Load Checkpoint, use batch size 1 e resolução moderada, e mantenha desconectadas as ramificações opcionais antigas. Depois que o eixo passar, adicione um LoRA, ControlNet, upscaler ou pós-processamento customizado e execute novamente após cada adição.

O objetivo não é deixar o grafo novo visualmente igual ao antigo. É criar um eixo atual comprovadamente funcional e migrar apenas as capacidades realmente necessárias. O Claude pode comparar os dois JSONs e preparar o mapa de migração, mas a execução continua sendo o teste de aceitação.

7. Execute uma imagem pequena e verifique o resultado salvo

Um workflow que apenas abre ainda não está reparado. Complete o ciclo usando o guia oficial da primeira geração:

1. Depois de instalar ou mover modelos, pressione R para atualizar as listas, ou reinicie se necessário.
2. Confirme que Load Checkpoint mostra um modelo visível e compatível.
3. Clique em Run ou pressione Ctrl + Enter.
4. Aguarde a fila terminar sem missing node, validation error ou nó vermelho com falha.
5. Confirme que a imagem aparece em Save Image.
6. Clique com o botão direito para salvar localmente, anote o nome e reabra em um visualizador.
7. Opcionalmente, arraste o PNG gerado de volta para a interface e confirme que os metadados do workflow são lidos.
8. Salve o grafo normal reparado como workflow-repaired.json e mantenha workflow-original.json intacto.

O registro de aceitação deve incluir o nome do workflow reparado, o arquivo de imagem, o modelo usado, os custom nodes ativos, as substituições e as limitações conhecidas. Só então “corrigido” é um status baseado em evidência.

O que fazer se uma ramificação ainda falhar

• O workflow padrão falha com custom nodes desativados: pare de editar o grafo antigo e corrija instalação, modelo, driver ou frontend.
• O padrão funciona, mas o antigo ainda tem missing nodes: continue mapeando proprietários e substitutos; não adivinhe renomeando tipos JSON.
• O grafo carrega, mas a geração falha: comece pelo primeiro nó com erro em Show report; verifique família do modelo e ligações antes de culpar memória.
• A falha volta quando um grupo de extensões é ativado: continue dividindo até restar um custom node ou frontend extension.
• O nó original não é mais mantido: substitua ou reconstrua a função e documente qualquer diferença de comportamento.
• O Claude não cita o erro ou um campo JSON: trate a sugestão como hipótese e ainda não a execute.

Conclusão

Nesse cenário, Claude é mais confiável como organizador de evidências e planejador de mudanças do que como botão de reparo automático sem verificação. O ciclo robusto é backup → base limpa → classificação → menor mudança → uma imagem → verificação do arquivo salvo. Preserve o grafo original, mude uma variável por vez e deixe o resultado real do ComfyUI, não uma explicação confiante, decidir se o reparo terminou.