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 da qual fez uma cópia de segurança

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 uma única vez. A Console também pede que escolha uma data de expiração ao criar a chave. Registe essa data, porque uma chave expirada interrompe um fluxo de trabalho não supervisionado com o mesmo erro 401 descrito abaixo, na secção sobre modos de falha. Financie a conta ou configure a faturação. A utilização da API é cobrada por token e paga com créditos pré-pagos. Uma subscrição Pro não cobre essa utilização, mas os planos Claude Max e Team incluem agora créditos mensais para a Claude API ($100 no Max 5x, $200 no Max 20x e até $500 partilhados no Team), que pode ativar associando uma organização da Console às definições de faturação do claude.ai. Esses créditos pagam chamadas à API, como as que o n8n faz, não cobrem o Claude Code e expiram no fim de cada ciclo de faturação. Se esperava criar estes três fluxos de trabalho sem pagar, a FAQ de preços da Anthropic informa que os novos utilizadores recebem uma pequena quantidade de créditos gratuitos para testar a API. Assim, uma nova conta da Console pode testar estes fluxos com esses créditos iniciais antes de adicionar a faturação. Quando os créditos terminarem, todas as chamadas ao Claude serão cobradas por token. Algumas operações também não têm custos além dos tokens, como o endpoint de contagem de tokens e até 1,550 horas gratuitas de execução de código por organização em cada mês. No entanto, nenhum destes três fluxos usa execução de código. O que os créditos gratuitos da API cobrem explica os detalhes.

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

Existem duas notas operacionais. Primeiro, o n8n encripta as credenciais armazenadas com N8N_ENCRYPTION_KEY. Se definir explicitamente essa variável de ambiente no ficheiro compose, conforme indicado no guia do n8n, a credencial sobrevive às recriações do contentor. Se deixar o n8n gerar uma chave e perder o volume, todas as credenciais armazenadas, incluindo esta chave, tornam-se texto cifrado irrecuperável. Faça agora uma cópia de segurança da chave, caso ainda não o tenha feito. Segundo, trate o armazenamento de credenciais do n8n como o limite de impacto: qualquer pessoa que possa utilizar a sua credencial Anthropic pode fazer pedidos com a sua chave. Na edição Community, essa pessoa é você e o proprietário da instância. A documentação do n8n indica que "Only the instance owner and the user who creates them can access workflows and credentials", pelo que as outras contas Member não podem aceder-lhe. A partilha de fluxos de trabalho e credenciais é uma funcionalidade paga no n8n self-hosted (Business ou Enterprise). Depois de partilhar um fluxo de trabalho, os respetivos editores podem utilizar todas as credenciais usadas por esse fluxo. Por isso, se outra pessoa iniciar sessão nesta instância, leia que controlos de acesso estão disponíveis através de uma licença n8n paga antes de criar contas. Defina um limite de gastos na Console, em Settings, para que uma instância comprometida ou fora de controlo tenha um teto de custos.

A escolha do modelo é feita por nó

O menu de modelos nos nós Claude do n8n é obtido diretamente da API, por isso mostra os modelos a que a sua key tem acesso. Os modelos usados neste guia, com os preços da API por milhão de tokens de entrada/saída em outubro de 2026, são: Claude Haiku 4.5 (claude-haiku-4-5) a $1/$5, com uma janela de contexto de 200K, Claude Sonnet 5 (claude-sonnet-5) a $2/$10 e Claude Opus 4.8 (claude-opus-4-8) a $5/$25, ambos com janelas de contexto de 1M de tokens. Existe também Claude Fable 5 (claude-fable-5) a $10/$50 para tarefas de raciocínio mais exigentes; nada neste guia precisa dele. Use esses IDs exatos. claude-haiku-4-5 é um alias do snapshot fixado claude-haiku-4-5-20251001, que também funciona, mas um ID com data copiado de um tutorial antigo pode referir-se a um modelo retirado e falhar. Os preços mudam, por isso consulte platform.claude.com antes de confiar em qualquer valor que leia, incluindo os valores apresentados aqui.

Desde a primeira publicação deste guia, a Anthropic lançou modelos mais recentes e a documentação agora classifica Haiku 4.5, Sonnet 5, Opus 4.8 e Fable 5 como legados. Eles continuam a funcionar. A página de descontinuações indica que a retirada do Haiku 4.5 não ocorreria antes de 15 de outubro de 2026; essa data já passou e, em 20 de outubro de 2026, a página ainda mostra o Haiku 4.5 como ativo, sem aviso de descontinuação. Sonnet 5, Opus 4.8 e Fable 5 não serão retirados antes de meados de 2027. A Anthropic avisa com pelo menos 60 dias de antecedência antes de retirar um modelo lançado publicamente, por isso monitorize a página de descontinuações se os seus workflows fixarem o Haiku 4.5. A linha atual inclui Claude Haiku 5.5 (claude-haiku-5-5, lançado em 7 de outubro de 2026), a partir de $0.10/$0.50 para prompts até 100,000 tokens e $0.50/$2.50 acima desse limite, Claude Sonnet 5.5 (claude-sonnet-5-5) a $2/$10, Claude Opus 5.5 (claude-opus-5-5) a $4/$20 e Claude Fable 5.1 (claude-fable-5-1) a $10/$50. O tokenizer do Haiku 5.5 conta o mesmo texto como aproximadamente 30% mais tokens do que o Haiku 4.5, por isso compare os custos reais por execução na página de utilização da Console, e não apenas os preços de tabela.

O hábito a criar é escolher o modelo por nó, e não por plataforma. Classificação, extração, sumarização e encaminhamento, que são a base da automação, funcionam muito bem no Haiku, a metade do preço de tabela do Sonnet e um quinto do preço do Opus. Reserve o Sonnet para agents e raciocínio em várias etapas. Use o Opus nos workflows pouco frequentes 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 utilizar cada um

O n8n disponibiliza duas integrações Anthropic distintas. Escolher a integração errada é o desvio mais comum entre principiantes.

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

O nó Anthropic Chat Model é um subnó, um pequeno componente ligado a um nó raiz como AI Agent ou Basic LLM Chain para fornecer o modelo. Não tem trigger nem saída própria. Disponibiliza o seletor de modelos e opções de amostragem como Maximum Number of Tokens e Sampling Temperature. Há uma limitação da documentação do n8n que convém memorizar: as expressões dentro dos subnós são sempre avaliadas 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ó. Há também uma limitação do lado da Anthropic: nos modelos Claude 4.7 e posteriores, que incluem todos os modelos deste guia exceto Haiku 4.5, definir temperature, top_p ou top_k com um valor diferente do padrão devolve um erro 400. Por isso, deixe Sampling Temperature, Top K e Top P sem definição nesses modelos.

Workflow 1: webhook recebido, resumo enviado

A automação básica de 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ó fica à escuta depois de o workflow ser publicado.
2. Nó Anthropic, Message a Model, modelo claude-haiku-4-5, Max Tokens aproximadamente 300.
3. Nó Slack (ou Send Email), para publicar o texto da resposta num canal.

É no prompt que as expressões do n8n são combinadas com o Claude. O corpo do POST fica 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 sobre o papel e o 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 mais fácil de compreender daqui a seis meses. Teste-o 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..."}'

O custo por execução no Haiku é baixo: um payload com 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ó apontado para o Opus 4.8 custa cerca de cinco vezes mais. Essa proporção, multiplicada por todos os workflows que criar, explica por que motivo é importante escolher o modelo por 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.

Fluxo de trabalho 3: um agente de IA que usa ferramentas

Os dois primeiros fluxos de trabalho são pipelines: você define as etapas. Um nó AI Agent inverte esse modelo: 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 porquê" 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 é a escolha mínima sensata 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 consultar qualquer outro serviço com uma API REST.

Duas definições fazem a maior parte do trabalho. A System Message do agente define a tarefa: "Você é um assistente de operações. Use a ferramenta de estado para verificar o estado atual dos monitores antes de responder. Relate 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 a chamar. "Retorna o estado atual, ativo ou indisponível, de todos os serviços monitorizados em JSON" é chamado nos momentos corretos. "API de estado" pode ser ignorado ou usado 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 (o valor predefinido é 10) para o menor número que funcione. Essa definição determina a diferença entre "o agente desistiu depois de 4 chamadas de ferramentas" e um ciclo de uma dúzia de interações de ida e volta com o modelo. Tenha também em conta o modelo de faturação: em cada iteração, o agente reenvia toda a conversa até esse ponto, incluindo a mensagem do sistema, a pergunta e todos os resultados anteriores das ferramentas, como tokens de entrada. Uma execução do agente com seis iterações pode facilmente totalizar 20,000 tokens de entrada acumulados e 2,000 tokens de saída. No Sonnet 5, a $2/$10, isso custa cerca de $0.06, ou seja, aproximadamente vinte vezes o custo de uma execução simples de resumo. Se 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 simples.

Controlo de custos, porque ninguém está a observar

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

Max Tokens em cada nó Claude. É um limite rígido para o output. Um summarizer precisa de 300, um classificador de 100. Isto limita o lado mais dispendioso da conta (entre os modelos deste guia, $5–$50 por milhão de output tokens contra $1–$10 por milhão de input tokens, com o output a custar cinco vezes mais do que o input em cada modelo) e funciona também como travão para execuções descontroladas: um erro no prompt que faça o Claude divagar custa 300 tokens, não 8,000.

Modelo por nó. Este ponto foi abordado acima. Entre Haiku 4.5 e Opus 4.8, o modelo representa uma diferença de cinco vezes no preço; até Fable 5, a diferença chega a dez vezes. Em toda a linha atual, de Haiku 5.5 a Fable 5.1, chega a cem vezes para prompts com até 100,000 tokens. A configuração demora dez segundos.

Limite os loops. Defina Max Iterations nos agents. 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 temporários, mas as tentativas repetidas multiplicam o custo. Max Tries de 3 com Wait Between Tries de 5000 ms pode cobrar até três vezes por item quando a falha é persistente, antes de desistir. Nunca envolva num retry um nó que já tenha terminado com sucesso depois de uma operação dispendiosa.

Um workflow de erro como último recurso. Crie um workflow que comece com o nó Error Trigger e 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 captura o pior cenário: um workflow acionado por um agendamento que falha em todas as execuções, de hora a hora, durante uma semana, consumindo tokens em cada execução antes de terminar. Combine-o com um limite mensal de despesa na Anthropic Console e consulte a página de utilização da Console nos primeiros dias depois de ativar qualquer agendamento. Se quiser perceber exatamente o que está a ser cobrado, o guia de utilização de tokens explica o assunto em detalhe.

Modos de falha e mensagens apresentadas

O node falha imediatamente com "Authorization failed - please check your credentials." A API devolveu 401. O corpo da resposta tem este formato (as respostas atuais também incluem um campo request_id):

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

A causa pode ser uma chave copiada incorretamente, truncada, com espaços no fim ou o placeholder de um tutorial. Recrie a credencial no n8n e cole a chave novamente. Se funcionava ontem, confirme na Console se a chave foi revogada ou atingiu a data de expiração. Verifique também se uma restauração de volume repôs 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 medidos por minuto e aplicados através de um token bucket continuamente reabastecido. O n8n torna muito fácil iniciar simultaneamente cinquenta execuções de webhook ou RSS. Corrija o problema na estrutura do workflow: processe os itens em sequência (Loop Over Items) em vez de em paralelo. Ative Retry On Fail, defina Max Tries como 3 e Wait Between Tries como 5000 ms, que é o valor máximo desse campo no n8n. Quando precisar de um backoff mais longo para permitir que o bucket seja reabastecido antes da nova tentativa, coloque um node Wait no caminho de erro ou processe os itens um de cada vez. Um 429 causado por limite de taxa normalmente inclui um cabeçalho retry-after que indica quantos segundos deve esperar (a documentação da Anthropic informa que nem todos os 429 o incluem). O tempo de espera fixo do n8n não consegue ler esse valor. Por isso, implemente essa pausa mais longa manualmente. Há uma exceção: um 429 sem o cabeçalho retry-after e com um error_code de enforced_spend_limit_reached significa que a organização atingiu o limite mensal de gastos do seu nível de utilização. Nenhuma nova tentativa terá sucesso até ao mês seguinte ou até aumentar o nível.

404 not_found_error ao indicar o modelo. A mensagem apresenta o ID do modelo enviado, com um formato semelhante a:

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

Pontos em vez de hífenes (4.5 para 4-5), um sufixo de data incorreto ou inventado, ou um modelo retirado de um artigo antigo. Corrija o ID consultando a lista atual. Este problema ocorre frequentemente quando o ID é 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 aparece qualquer erro e a execução termina com sucesso. Uma expressão do n8n que referencia um campo inexistente, como {{ $json.body.text }} quando o payload utilizou message, insere a cadeia literal undefined no prompt. O Claude responde então a um prompt que não contém a informação esperada. Se o node referenciado não tiver sido executado, o n8n interrompe a execução com um erro que indica que a expressão referencia um node que "hasn't been executed yet". A ausência de um campo é silenciosa. Antes de ativar o workflow, execute-o uma vez com dados reais e leia o prompt efetivamente renderizado no painel de entrada do node. O editor de expressões mostra uma pré-visualização do valor resolvido, e undefined aparece aí se verificar o resultado.

FAQ

Como ligo o Claude ao n8n?

Crie uma chave de API 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ó da 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 de segurança dessa chave, ou as suas credenciais serão perdidas juntamente com o volume.

Quanto custa uma execução de um fluxo de trabalho de IA?

Estime os tokens por execução e multiplique esse valor pelos preços do modelo por milhão. Em outubro de 2026, o Haiku 4.5 custa $1/$5 por milhão de tokens de entrada/saída e o Sonnet 5 custa $2/$10. Um resumo acionado por webhook no Haiku custa cerca de um quarto de cêntimo. Uma execução de agente no Sonnet com várias chamadas de ferramentas fica mais perto de $0.06–$0.10, porque cada iteração reenvia toda a conversa como entrada. Confirme a execução na página de utilização da Console em vez de confiar em estimativas.

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

Use o Haiku 4.5 para classificação, extração, resumo e encaminhamento, especialmente em tarefas de grande volume onde a velocidade e o preço são prioritários. Use o Sonnet 5 para nós AI Agent e raciocínio em várias etapas. Use o Opus 4.8 apenas quando o custo de uma resposta errada justificar o seu preço de tabela de $5/$25: cinco vezes o preço do Haiku e duas vezes e meia o do Sonnet. Os modelos Haiku 5.5, Sonnet 5.5 e Opus 5.5 mais recentes da Anthropic desempenham as mesmas funções com preços de tabela iguais ou inferiores. Defina o modelo por nó, não por fluxo de trabalho. Um fluxo de trabalho pode combinar os três modelos.

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

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

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

Não existe uma taxa separada para 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 acumulada. Uma resposta extensa da API, transmitida 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.