Claude no n8n: crie fluxos de IA no seu VPS

O que está a construir

Três fluxos de trabalho de IA funcionais na instância do n8n que já executa: um webhook que resume qualquer conteúdo que lhe envie, um leitor de feeds agendado que transforma artigos em linhas estruturadas numa folha de cálculo e um AI Agent que chama uma API HTTP por iniciativa própria para responder a perguntas. Este é o equivalente sem código de chamar a API do Claude a partir de Python no seu VPS, com a mesma API, os mesmos tokens e a mesma faturação, mas com a orquestração nos nós do n8n em vez de estar num script.

Parto do princípio de que o n8n já está disponível atrás de HTTPS, conforme o guia para alojar o n8n no Docker. Se ainda não estiver, faça isso primeiro. Os webhooks precisam de um endpoint TLS real e o armazenamento de credenciais onde vai colocar uma chave de API precisa da cópia de segurança da chave de encriptação mencionada nesse guia.

Os problemas relevantes aqui não estão no arrastar e largar. Estão na seleção do modelo para cada nó, nos campos de prompt que interpolam undefined silenciosamente e no facto de uma automação ser executada sem supervisão. Um fluxo de trabalho que custa meio cêntimo por execução é barato até um ciclo de novas tentativas o executar quatro mil vezes durante a noite. A maior parte deste guia trata desses problemas.

Uma credencial, encriptada com a chave que guardou

Obtenha uma chave de API na Anthropic Console, em platform.claude.com, Settings, depois API Keys, e crie uma chave com um nome como n8n-vps. A chave é apresentada apenas uma vez. Adicione fundos à conta ou configure a faturação; o uso da API é cobrado por token e é totalmente independente de qualquer subscrição do Claude.ai. Se esperava criar estes três fluxos de trabalho sem pagar nada, não existe um nível gratuito, apenas um pequeno crédito de registo e alguns endpoints que não têm qualquer custo.

No n8n: Credentials, Create credential, selecione Anthropic, cole a chave no campo API Key e guarde. Todos os nós Claude em todos os fluxos de trabalho usam esta credencial armazenada. Nunca cole a chave num nó.

Duas notas operacionais. Primeiro, o n8n encripta as credenciais armazenadas com N8N_ENCRYPTION_KEY. Se definir explicitamente essa variável de ambiente no seu ficheiro compose, conforme o guia do n8n, as suas credenciais permanecem disponíveis depois de recriar os contentores. Se permitir que o n8n gere uma chave e perder o volume, todas as credenciais armazenadas, incluindo essa chave, tornam-se texto cifrado irrecuperável. Faça agora uma cópia de segurança da chave se não o fez.

Segundo, trate o armazenamento de credenciais do n8n como o limite do impacto: qualquer pessoa que possa editar fluxos de trabalho na sua instância pode fazer pedidos com a sua chave da Anthropic. A edição Community não tem permissões por utilizador para credenciais. Por isso, se outra pessoa iniciar sessão nesta instância, leia quais controlos de acesso estão disponíveis numa licença paga do n8n antes de criar contas. Defina um limite de gastos na Console, em Settings, para que uma instância comprometida ou com execução descontrolada tenha um limite máximo.

A escolha do modelo é uma decisão por nó

A lista de modelos nos nós Claude do n8n é obtida diretamente da API, por isso mostra os modelos a que a sua chave tem acesso. Em julho de 2026, a lista e os preços da API por milhão de tokens de entrada/saída são: Claude Haiku 4.5 (claude-haiku-4-5) a $1/$5, com uma janela de contexto de 200K tokens; Claude Sonnet 5 (claude-sonnet-5) a $3/$15, com preço introdutório de $2/$10 até 31 de agosto de 2026; e Claude Opus 4.8 (claude-opus-4-8) a $5/$25. Os dois últimos têm janelas de contexto de 1M de tokens. Também existe o Claude Fable 5 (claude-fable-5) a $10/$50 para tarefas de raciocínio mais exigentes, mas nada neste guia precisa dele. Use esses IDs exatos. Uma variante com a data no nome, que possa ter visto num tutorial antigo, devolverá 404. Os preços mudam, por isso consulte platform.claude.com antes de confiar em qualquer valor, incluindo os apresentados aqui.

Crie este hábito: escolha o modelo por nó, não por plataforma. Classificação, extração, sumarização e encaminhamento, que são a base das automações, funcionam muito bem com o Haiku, por um terço do preço de tabela do Sonnet e um quinto do preço do Opus. Reserve o Sonnet para agentes e raciocínio em várias etapas. Use o Opus nos poucos workflows em que uma resposta errada custa mais do que os tokens. Um workflow com cinco nós Claude pode e deve combinar modelos.

Os dois nós Claude e quando usar cada um

O n8n inclui duas integrações Anthropic distintas. Escolher a integração errada é o desvio mais comum para iniciantes.

O nó Anthropic é um nó de aplicação normal: recebe uma solicitação e devolve uma resposta. O recurso Text inclui a operação Message a Model, além de operações para analisar imagens e documentos. Use-o quando a lógica do workflow estiver no n8n: trigger, chamada ao Claude, próximo nó. Os Workflows 1 e 2 abaixo usam este nó ou o equivalente baseado em cadeia.

O nó Anthropic Chat Model é um subnó, um pequeno componente que fornece o modelo a um nó raiz, como AI Agent ou Basic LLM Chain. Não tem trigger nem saída própria. Expõe o seletor de modelo e opções de amostragem, como Maximum Number of Tokens e Sampling Temperature. Há uma limitação da documentação do n8n que vale a pena memorizar: as expressões dentro dos subnós são sempre resolvidas em relação ao primeiro item de entrada, e não a cada item. Coloque as expressões por item nos campos de prompt do nó raiz, não no subnó.

Workflow 1: webhook recebido, resumo enviado

O exemplo mais básico de automação com IA: tudo o que for enviado por POST para um URL é resumido e chega ao Slack ou à sua caixa de entrada.

1. Nó Webhook, método HTTP POST, caminho summarize. O n8n fornece um URL de teste e um URL de produção; o URL de produção só recebe pedidos quando o workflow está ativo.
2. Nó Anthropic, Message a Model, modelo claude-haiku-4-5, Max Tokens próximo de 300.
3. Nó Slack (ou Send Email), que publica o texto da resposta num canal.

É no prompt que as expressões do n8n se ligam ao Claude. O corpo do POST fica disponível em $json.body, por isso o campo da mensagem do utilizador fica assim:

Summarize the following feedback in three bullets, then one line:
verdict: praise | complaint | churn-risk. No preamble.

{{ $json.body.text }}

Coloque as instruções de função e formato no campo de prompt do sistema do nó, não na mensagem do utilizador. O prompt do sistema permanece constante enquanto o payload varia. Isto mantém o comportamento estável e torna o prompt legível daqui a seis meses. Teste a partir do próprio VPS:

curl -X POST https://n8n.example.com/webhook/summarize \
  -H 'Content-Type: application/json' \
  -d '{"text": "Third support ticket this month about slow disk IO..."}'

Por execução, o custo com Haiku é o seguinte: um payload de 1,200 tokens mais o prompt custa cerca de $0.0012 de entrada, e 300 tokens de saída custam $0.0015, aproximadamente um quarto de cêntimo. Mil execuções por mês ficam abaixo de $3. O mesmo nó configurado para usar Opus 4.8 custa cerca de cinco vezes mais. Essa proporção, multiplicada por todos os workflows que criar, explica por que razão é importante escolher o modelo em cada nó.

Fluxo 2: RSS agendado para linhas estruturadas

Agora um fluxo executado segundo um horário, com saída estruturada: lê um feed RSS a cada hora, classifica cada item e acrescenta linhas a uma folha.

1. Schedule Trigger, a cada hora.
2. RSS Read, com o URL do feed. Produz um item por artigo.
3. Basic LLM Chain, com um subnó Anthropic Chat Model definido como claude-haiku-4-5 e um subnó Structured Output Parser que contém um esquema JSON.
4. Google Sheets (ou Postgres), para acrescentar uma linha por item.

O Structured Output Parser transforma "Claude, devolva JSON" de uma expectativa num contrato: valida a resposta do modelo de acordo com o esquema e faz o item falhar explicitamente, em vez de gravar linhas inválidas. Um esquema pode ser:

{
  "type": "object",
  "properties": {
    "category": { "type": "string", "enum": ["release", "security", "tutorial", "other"] },
    "relevance": { "type": "number" },
    "one_line_summary": { "type": "string" }
  },
  "required": ["category", "relevance", "one_line_summary"]
}

E o prompt da cadeia referencia o item do feed:

Classify this article for a VPS hosting audience.

Title: {{ $json.title }}
Content: {{ $json.contentSnippet }}

O cálculo do custo muda neste caso: é feito por item, não por execução. Cinquenta artigos por hora, 24 horas por dia, correspondem a 36,000 chamadas Claude por mês. Com Haiku, o custo pode ser de cerca de $40–90, dependendo do tamanho dos artigos. Com Opus, é aproximadamente cinco vezes superior. Elimine duplicados antes do nó LLM (com um IF simples que compare os links já processados ou com o nó Remove Duplicates do n8n). Assim, o número de chamadas diminui bastante, porque a maioria das consultas horárias não encontra nada novo. O token mais barato é o da chamada que nunca é feita.

Workflow 3: um agente de IA que utiliza ferramentas

Os dois primeiros workflows são pipelines: você define as etapas. Um nó AI Agent inverte essa lógica: você fornece ao Claude um objetivo e ferramentas, e ele decide quais ferramentas chamar e em que ordem, até concluir a tarefa. O n8n exige um subnó de modelo de chat e pelo menos um subnó de ferramenta associado.

Um exemplo concreto é um assistente de operações que responde a "o que está indisponível e por quê" com base no seu sistema de monitorização:

1. Chat Trigger (ou webhook): a pergunta é recebida.
2. AI Agent, com um subnó Anthropic Chat Model configurado para claude-sonnet-5. Os agentes planeiam e encadeiam chamadas de ferramentas. O Haiku pode executar agentes simples com uma única ferramenta, mas o Sonnet é o mínimo razoável quando o número de ferramentas aumenta.
3. Nó HTTP Request associado como ferramenta, apontado para a sua API de estado do Uptime Kuma ou para um endpoint do Zabbix. Uma segunda ferramenta HTTP pode chamar qualquer outro serviço com uma API REST.

Duas configurações fazem a maior parte do trabalho. A System Message do agente define a função: "Você é um assistente de operações. Utilize a ferramenta de estado para verificar o estado atual dos monitores antes de responder. Informe apenas os monitores que estão indisponíveis, com a duração." A descrição de cada ferramenta não é documentação para humanos. É o que permite ao Claude decidir quando deve chamá-la. "Retorna o estado atual, disponível/indisponível, de todos os serviços monitorizados em JSON" será usado nos momentos certos. "API de estado" pode ser ignorado ou utilizado incorretamente. Ao associar o nó HTTP Request como ferramenta, ative a opção Optimize Response e selecione os campos JSON relevantes. Caso contrário, cada resposta detalhada da API é inserida no contexto do modelo como tokens de entrada pelos quais você paga.

Defina Max Iterations no agente, cujo valor predefinido é 10, como o menor número que funcionar. Essa configuração determina se "o agente desistiu depois de 4 chamadas de ferramentas" ou se executou um ciclo com uma dúzia de interações de ida e volta com o modelo. Entenda também o modelo de cobrança: em cada iteração, a conversa completa até esse ponto é enviada novamente, incluindo a mensagem do sistema, a pergunta e todos os resultados anteriores das ferramentas, como tokens de entrada. Uma execução com seis iterações pode facilmente totalizar 20,000 tokens de entrada acumulados e 2,000 tokens de saída: com o preço introdutório do Sonnet 5, cerca de $0.06; com o preço normal de $3/$15, aproximadamente $0.09. Considere esse custo vinte vezes superior ao de uma execução simples de resumo. Se você começar a adicionar muitas ferramentas a um único agente, esse é o ponto em que executar servidores MCP no seu VPS se torna uma arquitetura mais limpa.

Controles de custo, porque ninguém está a monitorizar

Um workflow não supervisionado precisa dos controlos que uma pessoa ao teclado aplica implicitamente. Existem quatro camadas, começando pela mais barata.

Max Tokens em todos os nós Claude. É um limite rígido para a saída. Um sumarizador precisa de 300, um classificador de 100. Isto limita o lado mais caro da conta ($5–$25 por milhão de tokens de saída, contra $1–$5 para a entrada) e também funciona como travão para execuções descontroladas: um erro no prompt que faça o Claude produzir texto excessivo custa 300 tokens, não 8,000.

Modelo por nó. Isto foi abordado acima. É uma alavanca de preço de cinco a dez vezes entre os modelos atualmente disponíveis e demora dez segundos a configurar.

Limite os loops. Defina Max Iterations nos agentes. Configure um timeout do workflow nas definições do workflow, para que uma execução bloqueada termine em vez de continuar indefinidamente. Tenha também cuidado com Retry On Fail por nó: é a ferramenta certa para erros transitórios, mas as tentativas repetidas multiplicam o custo. Max Tries definido como 3 e Wait Between Tries definido como 5000 ms significa que uma falha persistente pode ser faturada até três vezes por item antes de o workflow desistir. Nunca envolva num retry um nó que já tenha concluído uma operação dispendiosa.

Um workflow de erro como último recurso. Crie um workflow iniciado pelo nó Error Trigger que publique no Slack o nome e o erro do workflow que falhou. Depois, defina-o como Error Workflow nas definições de cada workflow de IA. Este mecanismo deteta o modo de falha mais problemático: um workflow acionado por agenda que falha em todas as execuções, de hora a hora, durante uma semana, consumindo tokens antes de terminar. Combine-o com um limite de gastos mensal na Anthropic Console e consulte a página de utilização da Console nos primeiros dias depois de ativar qualquer workflow agendado. Para perceber exatamente o que está a ser faturado, o guia de utilização de tokens explica esses custos em detalhe.

Modos de falha e as mensagens apresentadas

O nó falha imediatamente com "Authorization failed - please check your credentials." A API devolveu 401. O corpo subjacente é:

{"type": "error", "error": {"type": "authentication_error", "message": "invalid x-api-key"}}

A causa pode ser uma chave colada incorretamente, truncada, com espaços em branco no fim ou o marcador de posição de um tutorial. Recrie a credencial do n8n e cole a chave novamente. Se funcionava ontem, confirme se a chave foi revogada na Console ou se uma restauração de volume reverteu para uma credencial encriptada com um N8N_ENCRYPTION_KEY diferente.

As execuções falham em rajadas com um 429 rate_limit_error, com uma mensagem semelhante a "Number of request tokens has exceeded your per-minute rate limit." Os limites de taxa são aplicados em intervalos de um minuto, e o n8n facilita muito o disparo simultâneo de cinquenta execuções de webhook ou RSS. Corrija o problema estruturalmente: processe os itens em sequência (Loop Over Items), em vez de em paralelo, e ative Retry On Fail com Max Tries 3 e Wait Between Tries no valor máximo de 5000 ms. O n8n limita esse campo a 5000 ms. Quando precisar de um intervalo maior para que as novas tentativas ocorram no intervalo do minuto seguinte, coloque um nó Wait no caminho de erro ou processe os itens um de cada vez. A resposta inclui um cabeçalho retry-after que indica exatamente quanto tempo deve esperar. A espera fixa do n8n não consegue ler esse valor, por isso deve criar a pausa maior manualmente.

404 not_found_error ao indicar o modelo. O corpo repete o erro de escrita:

{"type": "error", "error": {"type": "not_found_error", "message": "model: claude-haiku-4.5"}}

Podem ser pontos em vez de hífenes (4.5 para 4-5), um sufixo de data de uma publicação desatualizada ou um modelo retirado. Corrija o ID consultando a lista atual. Este problema ocorre frequentemente quando o valor é introduzido no campo do modelo como uma expressão, em vez de ser selecionado na lista pendente.

O Claude responde a uma pergunta que não fez. Não há erros e a execução termina com sucesso. Uma expressão do n8n que referencia um campo inexistente, como {{ $json.body.text }} quando o payload usou message, insere a cadeia literal undefined no prompt. O Claude responde então a um prompt sem conteúdo relevante. Se o nó referenciado nem sequer foi executado, verá "Referenced node is unavailable", mas a ausência de um campo não gera erro. Antes de ativar o fluxo, execute-o uma vez com dados reais e leia o prompt efetivamente renderizado no painel de entrada do nó. O editor de expressões apresenta uma pré-visualização do valor resolvido, e undefined está visível se o consultar.

FAQ

Como ligo o Claude ao n8n?

Crie uma API key na Anthropic Console, em platform.claude.com. Depois, no n8n, adicione uma credencial do tipo Anthropic e cole a chave no campo API Key. Todos os nós Claude, o nó de aplicação Anthropic e o subnó Anthropic Chat Model usam essa credencial armazenada. O n8n cifra-a com N8N_ENCRYPTION_KEY. Faça uma cópia dessa chave, caso contrário perderá as credenciais juntamente com o volume.

Quanto custa uma execução de um workflow de IA?

Estime os tokens por execução e multiplique pelo preço do modelo por milhão de tokens. Em julho de 2026, o Haiku 4.5 custa $1/$5 por milhão de tokens de entrada/saída, e o Sonnet 5 custa $3/$15 ($2/$10 em preço introdutório até agosto de 2026). Uma sumarização acionada por webhook com Haiku custa cerca de um quarto de cêntimo. Uma execução de agente com Sonnet e várias chamadas de ferramentas fica mais perto de $0.06–$0.10, porque cada iteração reenvia toda a conversação como entrada. Confirme a execução na página de utilização da Console, em vez de confiar nas estimativas.

Qual modelo Claude devo usar para automações n8n?

Use Haiku 4.5 para classificação, extração, sumarização e encaminhamento, sobretudo em tarefas de grande volume onde a velocidade e o preço são prioritários. Use Sonnet 5 para nós AI Agent e raciocínio em várias etapas. Use Opus 4.8 apenas quando o custo de uma resposta errada justificar o preço de tabela de $5/$25: cinco vezes o preço do Haiku e um pouco menos do dobro do Sonnet. Defina o modelo por nó, não por workflow. Um workflow pode combinar os três modelos.

Como impeço um workflow n8n de gastar demasiado na Claude API?

Aplique várias salvaguardas: defina um valor baixo para Max Tokens em todos os nós Claude, limite Max Iterations nos agentes, configure um timeout para o workflow e use definições conservadoras de Retry On Fail para evitar que as falhas multipliquem o consumo de tokens. Depois, adicione um workflow Error Trigger que envie um alerta para o Slack quando qualquer workflow de IA falhar. Defina também um limite mensal de gastos na Anthropic Console. Esse limite funciona como teto absoluto e nada no VPS o pode ultrapassar.

As chamadas de ferramentas dos AI Agent têm custos adicionais?

Não existe uma taxa separada pelas ferramentas, mas elas não são gratuitas. Cada resultado de uma ferramenta é devolvido ao modelo como tokens de entrada, e cada iteração do agente reenvia toda a conversação acumulada. Uma resposta prolixa da API, passada sem filtragem, pode ser muito maior do que o prompt original. Ative Optimize Response nas ferramentas HTTP Request e devolva apenas os campos de que o agente precisa.