Como integrar Claude com n8n no VPS

O que você está construindo

Três workflows de IA funcionais na instância n8n que você já executa: um webhook que resume qualquer conteúdo enviado, um leitor de feed agendado que transforma artigos em linhas estruturadas de uma planilha, e um AI Agent que chama uma API HTTP por conta própria para responder perguntas. Este é o equivalente no-code para chamar a API do Claude via Python no seu VPS — mesma API, mesmos tokens, mesma fatura, mas a orquestração ocorre em nós do n8n em vez de um script.

Assumo que o n8n já está rodando via HTTPS conforme o guia de n8n self-hosted no Docker. Se não estiver, faça isso primeiro — webhooks precisam de um endpoint TLS real, e o repositório de credenciais onde você inserirá uma chave de API precisa do backup da encryption-key mencionado nesse guia.

Os problemas interessantes aqui não são o drag-and-drop. São a seleção de modelo por nó, campos de prompt que interpolam silenciosamente undefined, e o fato de uma automação rodar sem supervisão — um workflow que custa meio centavo por execução é barato até que um loop de retry o execute quatro mil vezes durante a noite. A maior parte deste guia foca nisso.

Uma credencial, criptografada com a chave que você fez backup

Obtenha uma chave de API no Anthropic Console em platform.claude.com — Settings, depois API Keys, e crie uma chave com um nome como n8n-vps. Ela é exibida apenas uma vez. Adicione fundos à conta ou configure o faturamento; o uso da API é pay-per-token e totalmente separado de qualquer assinatura do Claude.ai.

No n8n: Credentials, Create credential, escolha Anthropic, cole a chave no campo API Key e salve. Cada nó do Claude em cada workflow referencia esta única credencial armazenada — você nunca cola a chave diretamente em um nó.

Duas notas operacionais. Primeiro, o n8n criptografa as credenciais armazenadas com N8N_ENCRYPTION_KEY. Se você definir essa env var explicitamente no seu compose file conforme o guia do n8n, sua credencial sobrevive à reconstrução do container; se você deixar o n8n gerar uma e depois perder o volume, cada credencial armazenada — incluindo esta chave — será um ciphertext irrecuperável. Faça o backup da chave agora se você pulou essa etapa. Segundo, trate o repositório de credenciais do n8n como o raio de explosão: qualquer pessoa que possa editar workflows na sua instância pode fazer requisições com sua chave Anthropic. Defina um limite de gastos (spend limit) no Console em Settings para que uma instância comprometida ou descontrolada tenha um teto.

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

O menu suspenso de modelos nos nós do Claude no n8n é carregado via API, portanto, mostra o que sua chave pode acessar. Em julho de 2026, a linha de produtos e o preço da API por milhão de tokens de input/output é: Claude Haiku 4.5 (claude-haiku-4-5) a $1/$5 com janela de contexto de 200K, Claude Sonnet 5 (claude-sonnet-5) a $3/$15 — 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, ambos com janelas de contexto de 1M de tokens. Existe também o Claude Fable 5 (claude-fable-5) a $10/$50 para tarefas de raciocínio complexas; nada neste guia precisa dele. Use exatamente esses IDs — uma variante com sufixo de data que você viu em um tutorial antigo resultará em 404, e os preços mudam, então verifique platform.claude.com antes de confiar em qualquer número, inclusive aqui.

O hábito a se criar: escolha o modelo por nó, não por plataforma. Classificação, extração, sumarização, roteamento — o básico da automação — funciona perfeitamente no Haiku por um terço do preço de tabela do Sonnet e um quinto do Opus. Reserve o Sonnet para agentes e raciocínio de múltiplos passos, e o Opus para o raro workflow onde uma resposta errada custa mais do que os tokens. Um workflow com cinco nós Claude pode e deve misturar modelos.

Os dois nós Claude, e qual usar em cada caso

O n8n entrega duas integrações distintas da Anthropic, e escolher a errada é o erro mais comum de iniciantes.

O nó Anthropic é um nó de app comum: uma requisição de entrada, uma resposta de saída. Seu recurso Text possui uma operação Message a Model, além de operações para analisar imagens e documentos. Use-o sempre que a lógica do workflow estiver no n8n — trigger, chamada ao Claude, próximo nó. Os workflows 1 e 2 abaixo utilizam este nó ou seu equivalente em cadeia.

O nó Anthropic Chat Model é um sub-nó — um anexo pequeno que fornece o modelo para um nó raiz como o AI Agent ou Basic LLM Chain. Ele não possui trigger nem saída própria; ele expõe o seletor de modelo e opções de amostragem como Maximum Number of Tokens e Sampling Temperature. Uma observação dos docs do n8n que vale memorizar: expressões dentro de sub-nós sempre resolvem contra o primeiro item de entrada, não contra cada item — coloque expressões por item nos campos de prompt do nó raiz, não no sub-nó.

Workflow 1: webhook de entrada, resumo de saída

O "hello-world" da automação de IA: qualquer coisa enviada via POST para uma URL é resumida e enviada para o Slack ou para seu e-mail.

1. Webhook node — HTTP Method POST, path summarize. O n8n fornece uma URL de teste e uma URL de produção; a de produção só responde quando o workflow está ativo.
2. Anthropic node — Message a Model, model claude-haiku-4-5, Max Tokens em torno de 300.
3. Slack node (ou Send Email) — envia o texto da resposta para um canal.

O prompt é onde as expressões do n8n encontram o Claude. O corpo do POST cai em $json.body, então o campo de mensagem do usuário deve ser:

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 role e formato no campo de system prompt do nó, não na mensagem do usuário — o system prompt permanece constante enquanto o payload varia, o que mantém o comportamento estável e torna o prompt legível seis meses depois. 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..."}'

Custo por execução no Haiku: 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 centavo. Mil execuções por mês custam menos de $3. O mesmo nó apontado para o Opus 4.8 custa cerca de cinco vezes isso. Essa proporção, multiplicada por cada workflow que você construir, é o motivo pelo qual o hábito de escolher o modelo por nó é importante.

Workflow 2: RSS agendado para linhas estruturadas

Agora algo baseado em tempo, com saída estruturada: ler um feed RSS de hora em hora, classificar cada item e adicionar linhas a uma planilha.

1. Schedule Trigger — a cada hora.
2. RSS Read — a URL do feed. Gera um item por artigo.
3. Basic LLM Chain — com um sub-nó Anthropic Chat Model configurado para claude-haiku-4-5, e um sub-nó Structured Output Parser contendo um schema JSON.
4. Google Sheets (ou Postgres) — adiciona uma linha por item.

O Structured Output Parser é o que transforma o "Claude, por favor retorne JSON" de um desejo em um contrato: ele valida a resposta do modelo contra o seu schema e falha o item de forma explícita em vez de escrever linhas com dados inúteis. Um schema como:

{
  "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 chain referencia o item do feed:

Classify this article for a VPS hosting audience.

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

A matemática de custo muda aqui: isso é por item, não por execução. Cinquenta artigos por hora, vinte e quatro horas por dia, são 36.000 chamadas do Claude por mês — no Haiku talvez custe entre $40–$90 dependendo do tamanho do artigo; no Opus, cerca de cinco vezes isso. Remova duplicatas antes do nó da LLM (um simples IF comparando links já vistos, ou o nó Remove Duplicates do n8n) e o número cai drasticamente, pois a maioria das consultas horárias não contém nada novo. O token mais barato é a chamada que você nunca faz.

Workflow 3: um AI Agent que utiliza ferramentas

Os dois primeiros workflows são pipelines — você decide os passos. Um nó AI Agent inverte isso: você dá ao Claude um objetivo e ferramentas, e ele decide quais ferramentas chamar e em qual ordem até terminar. O n8n exige um sub-nó de chat model e pelo menos um sub-nó de ferramenta anexado.

Uma implementação concreta — um assistente de operações que responde "o que está fora do ar e por quê" a partir do seu monitoramento:

1. Chat Trigger (ou webhook) — a pergunta chega.
2. AI Agent — com um sub-nó Anthropic Chat Model configurado para claude-sonnet-5. Agentes planejam e encadeiam chamadas de ferramentas; o Haiku pode gerenciar agentes simples de ferramenta única, mas o Sonnet é o patamar mínimo sensato conforme as ferramentas aumentam.
3. HTTP Request node anexado como uma ferramenta — apontado para sua API de status do Uptime Kuma ou endpoint do Zabbix. Uma segunda ferramenta HTTP pode acessar qualquer outra coisa com uma API REST.

Duas configurações realizam a maior parte do trabalho. A System Message do agente define a função: "Você é um assistente de operações. Use a ferramenta de status para verificar o estado atual do monitor antes de responder. Relate apenas monitores que estejam offline, com a duração." E a description de cada ferramenta não é documentação para humanos — é como o Claude decide quando chamá-la. "Returns current up/down state for all monitored services as JSON" será chamado nos momentos certos; "status API" será ignorado ou usado incorretamente. Ao anexar o nó HTTP Request como uma ferramenta, habilite a opção Optimize Response e selecione os campos JSON que importam — caso contrário, cada resposta verbosa de API será enviada para o contexto do modelo como tokens de input pelos quais você paga.

Defina o Max Iterations no agente (o padrão é 10) para o menor número que funcione — é a diferença entre "o agente desistiu após 4 chamadas de ferramenta" e um loop de uma dúzia de idas e voltas do modelo. E entenda o modelo de cobrança: cada iteração reenvia toda a conversa até então — system message, pergunta, cada resultado de ferramenta anterior — como tokens de input. Uma execução de agente de seis iterações pode facilmente totalizar 20.000 tokens de input cumulativos e 2.000 de output: no preço introdutório do Sonnet 5, cerca de $0.06, ou aproximadamente $0.09 no padrão de $3/$15 — o que equivale a vinte execuções de uma sumarização simples. Se você perceber que está anexando muitas ferramentas a um único agente, esse é o ponto onde rodar servidores MCP no seu VPS se torna a arquitetura mais limpa.

Guardrails de custo, porque ninguém está vigiando

Um workflow sem supervisão precisa dos controles que um humano ao teclado fornece implicitamente. Quatro camadas, da mais barata para a mais cara.

Max Tokens em cada nó Claude. É um limite rígido de saída. Um sumarizador precisa de 300, um classificador de 100. Isso limita o lado caro da fatura ($5–$25 por milhão de tokens de output versus $1–$5 para input) e serve como um freio de segurança — um bug no prompt que faz o Claude divagar custará 300 tokens, não 8.000.

Modelo por nó. Coberto acima; é um multiplicador de preço de cinco a dez vezes entre a linha atual e leva dez segundos para configurar.

Limite os loops. Max Iterations em agentes. Um timeout de workflow nas configurações do workflow para que uma execução travada morra em vez de girar infinitamente. E tenha cuidado com o Retry On Fail por nó: é a ferramenta certa para erros transitórios, mas retries multiplicam o custo — Max Tries de 3 com Wait Between Tries de 5000 ms significa que uma falha persistente cobrará você até três vezes por item antes de desistir. Nunca envolva um retry em um nó que já teve sucesso caro.

Um workflow de erro como salvaguarda. Crie um workflow começando com o nó Error Trigger que envie o nome do workflow que falhou e o erro para o Slack, e defina-o como o Error Workflow nas configurações de cada workflow de IA. O modo de falha que isso captura é o pior: um erro de workflow agendado que falha em cada execução, a cada hora, durante uma semana — cada execução queimando tokens antes de morrer. Combine isso com um limite de gastos mensal no Anthropic Console e verifique a página de uso do Console nos primeiros dias após ativar qualquer coisa agendada. Se quiser entender exatamente pelo que está sendo cobrado, o guia de uso de tokens detalha isso.

Modos de falha, com os erros que você verá

O nó falha instantaneamente com "Authorization failed - please check your credentials." A API retornou 401. O corpo real é:

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

Uma chave colada incorretamente — truncada, com espaços no final, ou o placeholder de um tutorial. Recrie a credencial no n8n e cole novamente; se funcionou ontem, verifique se a chave foi revogada no Console ou se um restore de volume reverteu para uma credencial criptografada com um N8N_ENCRYPTION_KEY diferente.

Execuções falham em rajadas com um erro 429 rate_limit_error, com uma mensagem do tipo "Number of request tokens has exceeded your per-minute rate limit." Os limites de taxa são por janelas de minuto, e o n8n facilita muito disparar cinquenta execuções de webhook ou RSS simultaneamente. Corrija isso estruturalmente: processe itens em sequência (Loop Over Items) em vez de paralelo, e configure o Retry On Fail com Max Tries 3 e Wait Between Tries no máximo de 5000 ms — o n8n limita esse campo em 5000 ms. Quando precisar de um backoff maior para que os retries caiam na próxima janela de minuto, coloque um nó Wait no caminho de erro ou processe os itens um por um. A resposta traz um header retry-after dizendo exatamente quanto tempo esperar — o wait fixo do n8n não consegue lê-lo, então construa a pausa longa você mesmo.

404 not_found_error ao nomear seu modelo. O corpo ecoa o erro de digitação:

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

Pontos em vez de hífens (4.5 para 4-5), um sufixo de data de um post de blog desatualizado ou um modelo descontinuado. Corrija o ID consultando a lista atual — isso atinge quem digita no campo do modelo como uma expressão em vez de selecionar no menu suspenso.

O Claude responde uma pergunta que você não fez. Nenhum erro em lugar nenhum — a execução fica verde. Uma expressão do n8n que referencia um campo inexistente, como {{ $json.body.text }} quando o payload usou message, interpola a string literal undefined no seu prompt, e o Claude responde prontamente a um prompt sobre nada. Se o nó referenciado não foi executado, você recebe "Referenced node is unavailable", mas um campo ausente é silencioso. Antes de ativar, sempre execute uma vez com dados reais e leia o prompt renderizado real no painel de input do nó — o editor de expressões mostra o valor resolvido, e undefined está bem ali se você procurar.

FAQ

Como eu conecto o Claude ao n8n?

Crie uma chave de API no Anthropic Console em platform.claude.com, depois no n8n adicione uma credencial do tipo Anthropic e cole-a no campo API Key. Cada nó Claude — o nó de app Anthropic e o sub-nó Anthropic Chat Model — referencia essa credencial armazenada. O n8n a criptografa com N8N_ENCRYPTION_KEY, então faça o backup dessa chave ou suas credenciais serão perdidas com o volume.

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

Estime os tokens por execução e multiplique pelos preços por milhão do modelo — em julho de 2026, Haiku 4.5 é $1/$5 por milhão de tokens de input/output e Sonnet 5 é $3/$15 ($2/$10 introdutório até agosto de 2026). Uma sumarização via webhook no Haiku custa cerca de um quarto de centavo; uma execução de agente no Sonnet com várias chamadas de ferramenta chega perto de $0.06–$0.10 porque cada iteração reenvia toda a conversa como input. Verifique a execução na página de uso do Console em vez de confiar em estimativas.

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

Haiku 4.5 para classificação, extração, sumarização e roteamento — trabalho de alto volume onde velocidade e preço dominam. Sonnet 5 para nós AI Agent e raciocínio de múltiplos passos. Opus 4.8 apenas onde uma resposta errada é cara o suficiente para justificar seu preço de tabela de $5/$25 — cinco vezes o Haiku, um pouco menos que o dobro do Sonnet. Defina o modelo por nó, não por workflow — um workflow pode misturar os três.

Como eu impeço que um workflow do n8n gaste demais na API do Claude?

Aplique camadas de proteção: um Max Tokens baixo em cada nó Claude, Max Iterations em agentes, um timeout de workflow e configurações conservadoras de Retry On Fail para que falhas não multipliquem o gasto de tokens. Em seguida, adicione um workflow de Error Trigger que te avise no Slack quando qualquer workflow de IA falhar, e defina um limite de gastos mensal no Anthropic Console como o teto rígido que nada no VPS pode ultrapassar.

Chamadas de ferramentas de AI Agent custam extra?

Não há uma taxa de ferramenta separada, mas ferramentas não são gratuitas: cada resultado de ferramenta é enviado de volta ao modelo como tokens de input, e cada iteração do agente reenvia toda a conversa até então. Uma resposta de API verbosa passada sem filtro pode dwarfar seu prompt real — habilite o Optimize Response em ferramentas HTTP Request e retorne apenas os campos que o agente precisa.