Gerenciamento de Workflows n8n

O que Gerenciamento de Workflows n8n faz?

Gerenciamento abrangente de automação de workflows para a plataforma n8n com criação, teste, monitoramento de execução e capacidades de otimização de desempenho.

⚠️ CRÍTICO: Regras de Criação de Workflows

Ao criar workflows n8n, SEMPRE:

1. ✅ Gere workflows COMPLETOS com todos os nós funcionais
2. ✅ Inclua nós reais de HTTP Request para chamadas de API (ImageFX, Gemini, Veo, Suno, etc.)
3. ✅ Adicione nós Code para transformação de dados e lógica
4. ✅ Crie conexões adequadas entre todos os nós
5. ✅ Use tipos de nós reais (n8n-nodes-base.httpRequest, n8n-nodes-base.code, n8n-nodes-base.set)

NUNCA:

• ❌ Crie nós de "Instruções de Configuração" como placeholders
• ❌ Gere workflows com apenas comentários TODO
• ❌ Faça workflows incompletos que exijam adição manual de nós
• ❌ Use nós somente de texto como substitutos para funcionalidades reais

Exemplo de workflow BOM:

Manual Trigger → Set Config → HTTP Request (chamada API) → Code (analisar) → Response

Exemplo de workflow RUIM:

Manual Trigger → Code ("Adicione nós HTTP aqui, configure APIs...")

Sempre construa o workflow completo e funcional com todos os nós necessários configurados e conectados.

Configuração

Variáveis de ambiente necessárias:

• N8N_API_KEY — Sua chave de API do n8n (Configurações → API na interface n8n)
• N8N_BASE_URL — URL da sua instância n8n

Configure as credenciais via configurações do OpenClaw:

Adicione em ~/.config/openclaw/settings.json:

{
  "skills": {
    "n8n": {
      "env": {
        "N8N_API_KEY": "sua-chave-api-aqui",
        "N8N_BASE_URL": "sua-url-n8n-aqui"
      }
    }
  }
}

Ou defina por sessão (não persista segredos em arquivos rc do shell):

export N8N_API_KEY="sua-chave-api-aqui"
export N8N_BASE_URL="sua-url-n8n-aqui"

Verifique a conexão:

python3 scripts/n8n_api.py list-workflows --pretty

Nota de segurança: Nunca armazene chaves de API em arquivos de configuração de shell em texto simples (~/.bashrc, ~/.zshrc). Use o arquivo de configurações do OpenClaw ou um gerenciador de segredos seguro.

Referência Rápida

Gerenciamento de Workflows

Listar Workflows

python3 scripts/n8n_api.py list-workflows --pretty
python3 scripts/n8n_api.py list-workflows --active true --pretty

Obter Detalhes do Workflow

python3 scripts/n8n_api.py get-workflow --id <id-do-workflow> --pretty

Criar Workflows

# A partir de arquivo JSON
python3 scripts/n8n_api.py create --from-file workflow.json

Ativar/Desativar

python3 scripts/n8n_api.py activate --id <id-do-workflow>
python3 scripts/n8n_api.py deactivate --id <id-do-workflow>

Teste e Validação

Validar Estrutura do Workflow

# Validar workflow existente
python3 scripts/n8n_tester.py validate --id <id-do-workflow>

# Validar a partir de arquivo
python3 scripts/n8n_tester.py validate --file workflow.json --pretty

# Gerar relatório de validação
python3 scripts/n8n_tester.py report --id <id-do-workflow>

Teste Dry-Run

# Testar com dados
python3 scripts/n8n_tester.py dry-run --id <id-do-workflow> --data '{"email": "[email protected]"}'

# Testar com arquivo de dados
python3 scripts/n8n_tester.py dry-run --id <id-do-workflow> --data-file test-data.json

# Relatório de teste completo (validação + dry-run)
python3 scripts/n8n_tester.py dry-run --id <id-do-workflow> --data-file test.json --report

Suíte de Testes

# Executar múltiplos casos de teste
python3 scripts/n8n_tester.py test-suite --id <id-do-workflow> --test-suite test-cases.json

Monitoramento de Execução

Listar Execuções

# Execuções recentes (todos os workflows)
python3 scripts/n8n_api.py list-executions --limit 10 --pretty

# Execuções de workflow específico
python3 scripts/n8n_api.py list-executions --id <id-do-workflow> --limit 20 --pretty

Obter Detalhes da Execução

python3 scripts/n8n_api.py get-execution --id <id-da-execucao> --pretty

Execução Manual

# Acionar workflow
python3 scripts/n8n_api.py execute --id <id-do-workflow>

# Executar com dados
python3 scripts/n8n_api.py execute --id <id-do-workflow> --data '{"chave": "valor"}'

Otimização de Desempenho

Analisar Desempenho

# Análise completa de desempenho
python3 scripts/n8n_optimizer.py analyze --id <id-do-workflow> --pretty

# Analisar período específico
python3 scripts/n8n_optimizer.py analyze --id <id-do-workflow> --days 30 --pretty

Obter Sugestões de Otimização

# Sugestões ordenadas por prioridade
python3 scripts/n8n_optimizer.py suggest --id <id-do-workflow> --pretty

Gerar Relatório de Otimização

# Relatório legível por humanos com métricas, gargalos e sugestões
python3 scripts/n8n_optimizer.py report --id <id-do-workflow>

Obter Estatísticas do Workflow

# Estatísticas de execução
python3 scripts/n8n_api.py stats --id <id-do-workflow> --days 7 --pretty

API Python

Uso Básico

from scripts.n8n_api import N8nClient

client = N8nClient()

# Listar workflows
workflows = client.list_workflows(active=True)

# Obter workflow
workflow = client.get_workflow('id-do-workflow')

# Criar workflow
novo_workflow = client.create_workflow({
    'name': 'Meu Workflow',
    'nodes': [...],
    'connections': {...}
})

# Ativar/desativar
client.activate_workflow('id-do-workflow')
client.deactivate_workflow('id-do-workflow')

# Execuções
execucoes = client.list_executions(workflow_id='id-do-workflow', limit=10)
execucao = client.get_execution('id-da-execucao')

# Executar workflow
resultado = client.execute_workflow('id-do-workflow', data={'chave': 'valor'})

Validação e Teste

from scripts.n8n_api import N8nClient
from scripts.n8n_tester import WorkflowTester

client = N8nClient()
tester = WorkflowTester(client)

# Validar workflow
validacao = tester.validate_workflow(workflow_id='123')
print(f"Válido: {validacao['valid']}")
print(f"Erros: {validacao['errors']}")
print(f"Avisos: {validacao['warnings']}")

# Dry run
resultado = tester.dry_run(
    workflow_id='123',
    test_data={'email': '[email protected]'}
)
print(f"Status: {resultado['status']}")

# Suíte de testes
casos_teste = [
    {'name': 'Teste 1', 'input': {...}, 'expected': {...}},
    {'name': 'Teste 2', 'input': {...}, 'expected': {...}}
]
resultados = tester.test_suite('123', casos_teste)
print(f"Aprovados: {resultados['passed']}/{resultados['total_tests']}")

# Gerar relatório
relatorio = tester.generate_test_report(validacao, resultado)
print(relatorio)

Otimização de Desempenho

from scripts.n8n_optimizer import WorkflowOptimizer

optimizer = WorkflowOptimizer()

# Analisar desempenho
analise = optimizer.analyze_performance('id-do-workflow', days=7)
print(f"Pontuação de Desempenho: {analise['performance_score']}/100")
print(f"Saúde: {analise['execution_metrics']['health']}")

# Obter sugestões
sugestoes = optimizer.suggest_optimizations('id-do-workflow')
print(f"Ações Prioritárias: {len(sugestoes['priority_actions'])}")
print(f"Vitórias Rápidas: {len(sugestoes['quick_wins'])}")

# Gerar relatório
relatorio = optimizer.generate_optimization_report(analise)
print(relatorio)

Workflows Comuns

1. Validar e Testar Workflow

# Validar estrutura do workflow
python3 scripts/n8n_tester.py validate --id <id-do-workflow> --pretty

# Testar com dados de exemplo
python3 scripts/n8n_tester.py dry-run --id <id-do-workflow> \
  --data '{"email": "[email protected]", "name": "Usuário Teste"}'

# Se os testes passarem, ativar
python3 scripts/n8n_api.py activate --id <id-do-workflow>

2. Depurar Workflow com Falha

# Verificar execuções recentes
python3 scripts/n8n_api.py list-executions --id <id-do-workflow> --limit 10 --pretty

# Obter detalhes de execução específica
python3 scripts/n8n_api.py get-execution --id <id-da-execucao> --pretty

# Validar estrutura do workflow
python3 scripts/n8n_tester.py validate --id <id-do-workflow>

# Gerar relatório de teste
python3 scripts/n8n_tester.py report --id <id-do-workflow>

# Verificar problemas de otimização
python3 scripts/n8n_optimizer.py report --id <id-do-workflow>

3. Otimizar Desempenho do Workflow

# Analisar desempenho atual
python3 scripts/n8n_optimizer.py analyze --id <id-do-workflow> --days 30 --pretty

# Obter sugestões acionáveis
python3 scripts/n8n_optimizer.py suggest --id <id-do-workflow> --pretty

# Gerar relatório abrangente
python3 scripts/n8n_optimizer.py report --id <id-do-workflow>

# Revisar estatísticas de execução
python3 scripts/n8n_api.py stats --id <id-do-workflow> --days 30 --pretty

# Testar otimizações com dry-run
python3 scripts/n8n_tester.py dry-run --id <id-do-workflow> --data-file test-data.json

4. Monitorar Saúde do Workflow

# Verificar workflows ativos
python3 scripts/n8n_api.py list-workflows --active true --pretty

# Revisar status de execução recente
python3 scripts/n8n_api.py list-executions --limit 20 --pretty

# Obter estatísticas para cada workflow crítico
python3 scripts/n8n_api.py stats --id <id-do-workflow> --pretty

# Gerar relatórios de saúde
python3 scripts/n8n_optimizer.py report --id <id-do-workflow>

Verificações de Validação

O módulo de teste realiza validação abrangente:

Validação de Estrutura

• ✓ Campos obrigatórios presentes (nodes, connections)
• ✓ Todos os nós têm nomes e tipos
• ✓ Destinos de conexão existem
• ✓ Nenhum nó desconectado (aviso)

Validação de Configuração

• ✓ Nós que exigem credenciais estão configurados
• ✓ Parâmetros obrigatórios estão definidos
• ✓ Nós HTTP têm URLs
• ✓ Nós Webhook têm caminhos
• ✓ Nós de Email têm conteúdo

Validação de Fluxo

• ✓ Workflow tem nós de gatilho
• ✓ Fluxo de execução adequado
• ✓ Nenhuma dependência circular
• ✓ Nós finais identificados

Análise de Otimização

O otimizador analisa múltiplas dimensões:

Métricas de Execução

• Total de execuções
• Taxas de sucesso/falha
• Status de saúde (excelente/bom/razoável/ruim)
• Padrões de erro

Métricas de Desempenho

• Contagem e complexidade de nós
• Padrões de conexão
• Operações caras (chamadas de API, consultas a banco de dados)
• Oportunidades de execução paralela

Detecção de Gargalos

• Operações caras sequenciais
• Altas taxas de falha
• Tratamento de erro ausente
• Problemas de limite de taxa

Oportunidades de Otimização

• Execução Paralela: Identificar nós que podem ser executados concorrentemente
• Cache: Sugerir cache para chamadas de API repetidas
• Processamento em Lote: Recomendar lotes para grandes conjuntos de dados
• Tratamento de Erro: Adicionar mecanismos de recuperação de erros
• Redução de Complexidade: Dividir workflows complexos
• Configurações de Timeout: Definir limites de execução

Pontuação de Desempenho

Os workflows recebem uma pontuação de desempenho (0-100) com base em:

• Taxa de Sucesso: Quanto maior, melhor (50% de peso)
• Complexidade: Quanto menor, melhor (30% de peso)
• Gargalos: Quanto menos, melhor (crítico: -20, alto: -10, médio: -5)
• Otimizações: Melhores práticas implementadas (+5 cada)

Interpretação da pontuação:

• 90-100: Excelente - Bem otimizado
• 70-89: Bom - Melhorias menores possíveis
• 50-69: Razoável - Otimização recomendada
• 0-49: Ruim - Problemas significativos

Melhores Práticas

Desenvolvimento

1. Planejar Estrutura: Projetar nós e conexões do workflow antes de construir
2. Validar Primeiro: Sempre validar antes da implantação
3. Testar Completamente: Usar dry-run com múltiplos casos de teste
4. Tratamento de Erro: Adicionar nós de erro para confiabilidade
5. Documentação: Comentar lógica complexa em nós Code

Teste

1. Dados de Exemplo: Criar arquivos de dados de teste realistas
2. Casos Limite: Testar condições de contorno e erros
3. Incremental: Testar cada adição de nó
4. Regressão: Retestar após alterações
5. Semelhante à Produção: Usar ambiente de staging que espelhe a produção

Implantação

1. Inativo Primeiro: Implantar workflows em estado inativo
2. Lançamento Gradual: Testar com tráfego limitado inicialmente
3. Monitorar de Perto: Observar as primeiras execuções cuidadosamente
4. Reversão Rápida: Estar pronto para desativar se surgirem problemas
5. Documentar Mudanças: Manter changelog de modificações

Otimização

1. Métricas de Base: Capturar desempenho antes das mudanças
2. Uma Mudança de Cada Vez: Isolar impactos da otimização
3. Medir Resultados: Comparar métricas antes/depois
4. Revisões Regulares: Agendar revisões mensais de otimização
5. Consciência de Custo: Monitorar uso de API e custos de execução

Manutenção

1. Verificações de Saúde: Revisão semanal de estatísticas de execução
2. Análise de Erro: Investigar padrões de falha
3. Monitoramento de Desempenho: Rastrear tempos de execução
4. Rotação de Credenciais: Atualizar credenciais regularmente
5. Limpeza: Arquivar ou excluir workflows não utilizados

Solução de Problemas

Erro de Autenticação

Error: N8N_API_KEY não encontrada no ambiente

Solução: Defina a variável de ambiente:

export N8N_API_KEY="sua-chave-api"

Erro de Conexão

Error: HTTP 401: Não Autorizado

Solução:

1. Verifique se a chave de API está correta
2. Verifique se N8N_BASE_URL está definida corretamente
3. Confirme se o acesso à API está habilitado no n8n

Erros de Validação

Validação falhou: Nó sem campo 'name'

Solução: Verifique a estrutura JSON do workflow, garanta que todos os campos obrigatórios estejam presentes

Timeout de Execução

Status: timeout - Execução não foi concluída

Solução:

1. Verifique se há loops infinitos no workflow
2. Reduza o tamanho do conjunto de dados para teste
3. Otimize operações caras
4. Defina timeout de execução nas configurações do workflow

Limitação de Taxa

Error: HTTP 429: Muitas Requisições

Solução:

1. Adicione nós Wait entre chamadas de API
2. Implemente backoff exponencial
3. Use processamento em lote
4. Verifique os limites de taxa da API

Credenciais Ausentes

Aviso: Nó 'HTTP_Request' pode exigir credenciais

Solução:

1. Configure credenciais na interface n8n
2. Atribua credenciais ao nó
3. Teste a conexão antes de ativar

Estrutura de Arquivos

~/clawd/skills/n8n/
├── SKILL.md                    # Este arquivo
├── scripts/
│   ├── n8n_api.py             # Cliente API principal (estendido)
│   ├── n8n_tester.py          # Teste e validação
│   └── n8n_optimizer.py       # Otimização de desempenho
└── references/
    └── api.md                 # Referência da API n8n

Referência da API

Para documentação detalhada da API REST do n8n, veja references/api.md ou visite: https://docs.n8n.io/api/

Suporte e Contribuição

Para relatar problemas ou sugerir melhorias, abra uma issue no repositório. Contribuições são bem-vindas! Certifique-se de seguir as regras de criação de workflows ao contribuir com novos recursos.

Licença

Este projeto é distribuído sob a licença MIT. Consulte o arquivo LICENSE para obter detalhes.

---

Nota: Sempre use a API do n8n com responsabilidade. Evite criar workflows desnecessários ou fazer chamadas excessivas à API para manter a estabilidade e eficiência do sistema.