Claude e n8n su VPS: guida all'integrazione

Cosa stai costruendo

Tre workflow AI funzionanti sull'istanza n8n che già utilizzi: un webhook che riassume qualsiasi input, un feed-reader pianificato che trasforma gli articoli in righe strutturate su foglio di calcolo, e un AI Agent che chiama autonomamente un'API HTTP per rispondere a domande. Questo è il corrispettivo no-code di chiamare l'API di Claude da Python sul tuo VPS — stessa API, stessi token, stessa fatturazione, ma l'orchestrazione avviene tramite i nodi di n8n invece di uno script.

Assumo che n8n sia già attivo dietro HTTPS seguendo la guida per n8n self-hosted su Docker. In caso contrario, procedi prima con quello — i webhook richiedono un endpoint TLS reale, e il repository delle credenziali in cui inserirai una API key richiede il backup della encryption-key di cui parla quella guida.

I problemi interessanti qui non riguardano il drag-and-drop. Riguardano la selezione del modello per singolo nodo, i campi dei prompt che interpolano silenziosamente undefined, e il fatto che un'automazione giri senza supervisione — un workflow che costa mezzo centesimo per esecuzione è economico finché un loop di retry non lo esegue quattromila volte durante la notte. La maggior parte di questa guida riguarda questi aspetti.

Una credenziale, criptata con la chiave di cui hai fatto il backup

Ottieni una API key dalla Anthropic Console su platform.claude.com — Settings, poi API Keys, quindi crea una chiave con un nome simile a n8n-vps. Viene mostrata una sola volta. Carica l'account o imposta la fatturazione; l'uso delle API è pay-per-token ed è completamente separato da qualsiasi abbonamento Claude.ai.

In n8n: Credentials, Create credential, seleziona Anthropic, incolla la chiave nel campo API Key, salva. Ogni nodo Claude in ogni workflow fa riferimento a questa singola credenziale salvata — non incollare mai la chiave direttamente in un nodo.

Due note operative. Primo, n8n cripta le credenziali salvate con N8N_ENCRYPTION_KEY. Se imposti esplicitamente questa env var nel tuo file compose seguendo la guida di n8n, la tua credenziale sopravviverà alla ricostruzione del container; se lasci che n8n ne generi una e poi perdi il volume, ogni credenziale salvata — inclusa questa chiave — sarà un ciphertext irrecuperabile. Fai il backup della chiave ora se hai saltato questo passaggio. Secondo, considera il repository delle credenziali di n8n come il raggio d'azione: chiunque possa modificare i workflow sulla tua istanza può effettuare richieste con la tua chiave Anthropic. Imposta un limite di spesa nella Console sotto Settings, in modo che un'istanza compromessa o fuori controllo abbia un tetto massimo.

La scelta del modello è una decisione per singolo nodo

Il menu a discesa dei modelli nei nodi Claude di n8n viene recuperato in tempo reale dall'API, quindi mostra ciò a cui la tua chiave può accedere. A luglio 2026, la gamma e il prezzo dell'API per un milione di token di input/output è: Claude Haiku 4.5 (claude-haiku-4-5) a $1/$5 con una finestra di contesto da 200K, Claude Sonnet 5 (claude-sonnet-5) a $3/$15 — prezzo introduttivo di $2/$10 fino al 31 agosto 2026 — e Claude Opus 4.8 (claude-opus-4-8) a $5/$25, entrambi con finestre di contesto da 1M di token. È disponibile anche Claude Fable 5 (claude-fable-5) a $10/$50 per i compiti di ragionamento più complessi; nulla in questa guida ne ha bisogno. Usa questi ID esatti — una variante con suffisso di data che ricordi da un vecchio tutorial restituirà un 404, e i prezzi variano, quindi controlla platform.claude.com prima di fidarti di qualsiasi numero leggi ovunque, incluso qui.

L'abitudine da sviluppare: scegli il modello per nodo, non per piattaforma. Classificazione, estrazione, riassunto, routing — il pane quotidiano dell'automazione — funzionano perfettamente su Haiku a un terzo del prezzo di listino di Sonnet e a un quinto di Opus. Riserva Sonnet per gli agent e il ragionamento multi-step, Opus per il raro workflow in cui una risposta errata costa più dei token. Un workflow con cinque nodi Claude può e deve mixare i modelli.

I due nodi Claude, e quale usare dove

n8n fornisce due diverse integrazioni Anthropic, e scegliere quella sbagliata è l'errore più comune per i principianti.

Il nodo Anthropic è un normale nodo applicativo: una richiesta in entrata, una risposta in uscita. La sua risorsa Text ha un'operazione Message a Model, oltre a operazioni per analizzare immagini e documenti. Usalo ogni volta che la logica del workflow risiede in n8n — trigger, chiamata a Claude, nodo successivo. I workflow 1 e 2 qui sotto lo usano o usano il suo equivalente a catena.

Il nodo Anthropic Chat Model è un sub-nodo — un piccolo allegato che fornisce il modello a un nodo radice come AI Agent o Basic LLM Chain. Non ha un trigger né un output proprio; espone il selettore del modello e le opzioni di campionamento come Maximum Number of Tokens e Sampling Temperature. Un avvertimento dai documenti di n8n da memorizzare: le espressioni all'interno dei sub-nodi si risolvono sempre rispetto al primo elemento di input, non su ogni elemento — inserisci le espressioni per elemento nei campi prompt del nodo radice, non nel sub-nodo.

Workflow 1: webhook in entrata, riassunto in uscita

Il "hello-world" dell'automazione AI: qualsiasi cosa inviata tramite POST a un URL viene riassunta e inviata su Slack o nella tua inbox.

1. Nodo Webhook — HTTP Method POST, path summarize. n8n ti fornisce un URL di test e un URL di produzione; quello di produzione risponde solo quando il workflow è attivo.
2. Nodo Anthropic — Message a Model, model claude-haiku-4-5, Max Tokens circa 300.
3. Nodo Slack (o Send Email) — invia il testo della risposta a un canale.

Il prompt è dove le espressioni di n8n incontrano Claude. Un corpo POST finisce sotto $json.body, quindi il campo del messaggio utente apparirà così:

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

{{ $json.body.text }}

Inserisci le istruzioni di ruolo e di formato nel campo system prompt del nodo, non nel messaggio utente — il system prompt rimane costante mentre il payload varia, il che mantiene stabile il comportamento e rende il prompt leggibile tra sei mesi. Testalo direttamente dal 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..."}'

Costo per esecuzione su Haiku: un payload da 1.200 token più il prompt costa circa $0.0012 in entrata, 300 token in uscita costano $0.0015 — circa un quarto di centesimo. Mille esecuzioni al mese costano meno di $3. Lo stesso nodo puntato su Opus 4.8 costa circa cinque volte tanto. Questo rapporto, moltiplicato per ogni workflow che costruisci, è il motivo per cui l'abitudine di scegliere il modello per nodo è fondamentale.

Workflow 2: RSS pianificato in righe strutturate

Ora qualcosa basato su un timer, con output strutturato: leggi un feed RSS ogni ora, classifica ogni elemento, aggiungi righe a un foglio di calcolo.

1. Schedule Trigger — ogni ora.
2. RSS Read — l'URL del feed. Produce un elemento per ogni articolo.
3. Basic LLM Chain — con un sub-nodo Anthropic Chat Model impostato su claude-haiku-4-5, e un sub-nodo Structured Output Parser che contiene uno schema JSON.
4. Google Sheets (o Postgres) — aggiungi una riga per elemento.

Il Structured Output Parser è ciò che trasforma "Claude, per favore restituisci JSON" da una speranza in un contratto: valida la risposta del modello rispetto al tuo schema e interrompe l'elemento in caso di errore invece di scrivere righe di dati spazzatura. Uno schema come:

{
  "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 il prompt della catena fa riferimento all'elemento del feed:

Classify this article for a VPS hosting audience.

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

Il calcolo dei costi cambia forma qui: questo è per elemento, non per esecuzione. Cinquanta articoli all'ora, ventiquattro ore al giorno, sono 36.000 chiamate a Claude al mese — su Haiku circa $40–90 a seconda della lunghezza dell'articolo, su Opus circa cinque volte tanto. Rimuovi i duplicati prima del nodo LLM (un semplice IF contro i link già visti, o il nodo Remove Duplicates di n8n) e il numero crolla, perché la maggior parte dei poll orari non contiene nulla di nuovo. Il token più economico è la chiamata che non effettui mai.

Workflow 3: un AI Agent che utilizza strumenti (tools)

I primi due workflow sono pipeline — decidi tu i passaggi. Un nodo AI Agent inverte questo concetto: dai a Claude un obiettivo e degli strumenti, e lui decide quali strumenti chiamare, in quale ordine, finché non ha finito. n8n richiede un sub-nodo chat model e almeno un sub-nodo tool allegato.

Una configurazione concreta — un assistente operativo che risponde a "cosa è offline e perché" dai tuoi monitoraggi:

1. Chat Trigger (o webhook) — arriva la domanda.
2. AI Agent — con un sub-nodo Anthropic Chat Model impostato su claude-sonnet-5. Gli agent pianificano e concatenano le chiamate agli strumenti; Haiku può gestire agenti semplici con un solo strumento, ma Sonnet è il limite minimo ragionevole quando gli strumenti aumentano.
3. Nodo HTTP Request allegato come strumento — puntato alla tua Uptime Kuma status API o all'endpoint Zabbix. Un secondo strumento HTTP può colpire qualsiasi altra cosa con un'API REST.

Due impostazioni svolgono la maggior parte del lavoro. Il System Message dell'agent definisce il compito: "Sei un assistente operativo. Usa lo strumento status per controllare lo stato attuale del monitor prima di rispondere. Segnala solo i monitor offline, con la durata." E la descrizione di ogni strumento non è documentazione per umani — è il modo in cui Claude decide quando chiamarlo. "Restituisce lo stato up/down attuale per tutti i servizi monitorati come JSON" viene chiamato nei momenti corretti; "status API" viene ignorato o usato male. Quando alleghi il nodo HTTP Request come strumento, abilita l'opzione Optimize Response e seleziona i campi JSON che contano — altrimenti ogni verbosa risposta API viene caricata nel contesto del modello come token di input per i quali paghi.

Imposta Max Iterations sull'agent (il default è 10) al numero minimo che funziona — è la differenza tra "l'agent si è arreso dopo 4 chiamate agli strumenti" e un loop di una dozzina di round-trip del modello. E comprendi la struttura della fatturazione: ogni iterazione rispedisce l'intera conversazione fino a quel momento — system message, domanda, ogni precedente risultato dello strumento — come token di input. Un'esecuzione di un agent da sei iterazioni può facilmente totalizzare 20.000 token di input cumulativi e 2.000 di output: con il prezzo introduttivo di Sonnet 5 circa $0.06, circa $0.09 con il prezzo standard di $3/$15 — chiamiamolo venti volte un semplice workflow di riassunto. Se ti ritrovi ad aggiungere molti strumenti a un singolo agent, è il punto in cui eseguire MCP server sul tuo VPS diventa l'architettura più pulita.

Guardrail per i costi, perché nessuno sta guardando

Un workflow non supervisionato ha bisogno dei controlli che un essere umano fornisce implicitamente. Quattro livelli, dal più economico al più costoso.

Max Tokens su ogni nodo Claude. È un limite rigido di output. Un riassuntore ne ha bisogno di 300, un classificatore 100. Questo limita il lato costoso del bilancio ($5–$25 per un milione di token di output rispetto a $1–$5 per l'input) e funge da freno per le esecuzioni fuori controllo — un bug nel prompt che fa divagare Claude costa 300 token, non 8.000.

Modello per nodo. Coperto sopra; è una leva di prezzo di cinque-dieci volte sull'attuale gamma e richiede dieci secondi per essere impostata.

Limita i loop. Max Iterations sugli agent. Un timeout del workflow nelle impostazioni del workflow affinché un'esecuzione bloccata muoia invece di girare a vuoto. E fai attenzione al Retry On Fail per nodo: è lo strumento giusto per errori transitori, ma i retry moltiplicano i costi — Max Tries a 3 con Wait Between Tries a 5000 ms significa che un fallimento persistente ti fattura fino a tre volte per elemento prima di arrendersi. Non avvolgere mai un retry attorno a un nodo che ha già avuto successo in modo costoso.

Un workflow di errore come rete di salvataggio. Crea un workflow che inizi con il nodo Error Trigger che invii il nome del workflow fallito e l'errore su Slack, quindi impostalo come Error Workflow nelle impostazioni di ogni workflow AI. Il tipo di fallimento che questo intercetta è quello peggiore: un errore di un workflow pianificato che si ripete ad ogni esecuzione, ogni ora, per una settimana — ogni esecuzione brucia token prima di morire. Abbinalo a un limite di spesa mensile nella Anthropic Console e controlla la pagina di utilizzo della Console nei primi giorni dopo l'attivazione di qualsiasi automazione pianificata. Se vuoi capire esattamente per cosa stai pagando, la guida all'uso dei token lo analizza nel dettaglio.

Modalità di fallimento, con i segnali che vedrai

Il nodo fallisce istantaneamente con "Authorization failed - please check your credentials". L'API ha restituito 401. Il corpo sottostante è:

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

Una chiave incollata male — troncata, con spazi vuoti alla fine, o il segnaposto da un tutorial. Ricrea la credenziale n8n e incolla di nuovo; se funzionava ieri, controlla se la chiave è stata revocata nella Console o se un ripristino del volume è tornato a una credenziale criptata con un diverso N8N_ENCRYPTION_KEY.

Le esecuzioni falliscono a raffiche con un 429 rate_limit_error, con un messaggio simile a "Number of request tokens has exceeded your per-minute rate limit". I limiti di velocità sono per bucket al minuto, e n8n rende molto facile lanciare cinquanta esecuzioni di webhook o RSS simultaneamente. Risolvi strutturalmente: elabora gli elementi in sequenza (Loop Over Items) invece che in parallelo, e imposta Retry On Fail con Max Tries a 3 e Wait Between Tries al massimo di 5000 ms — n8n limita quel campo a 5000 ms. Quando hai bisogno di un backoff più lungo affinché i retry cadano nella finestra del minuto successivo, inserisci un nodo Wait nel percorso di errore o elabora gli elementi uno alla volta. La risposta contiene un header retry-after che ti dice esattamente quanto aspettare — il wait fisso di n8n non può leggerlo, quindi costruisci tu la pausa più lunga.

404 not_found_error indicando il nome del modello. Il corpo ripete l'errore di battitura:

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

Punti invece di trattini (4.5 per 4-5), un suffisso di data da un post di un blog datato, o un modello ritirato. Correggi l'ID rispetto alla lista attuale — questo colpisce chi scrive nel campo del modello come espressione invece di sceglierlo dal menu a discesa.

Claude risponde a una domanda che non hai fatto. Nessun errore ovunque — l'esecuzione è verde. Un'espressione n8n che fa riferimento a un campo mancante, come {{ $json.body.text }} quando il payload usava message, interpola la stringa letterale undefined nel tuo prompt, e Claude risponde con impegno a un prompt che non riguarda nulla. Se il nodo di riferimento non è stato eseguito affatto riceverai "Referenced node is unavailable", ma un campo mancante è silenzioso. Prima di attivare, esegui sempre una volta con dati reali e leggi il prompt effettivamente renderizzato nel pannello di input del nodo — l'editor delle espressioni mostra l'anteprima del valore risolto, e undefined è proprio lì se lo guardi.

FAQ

Come collego Claude a n8n?

Crea una API key nella Anthropic Console su platform.claude.com, poi in n8n aggiungi una credenziale di tipo Anthropic e incollala nel campo API Key. Ogni nodo Claude — il nodo applicativo Anthropic e il sub-nodo Anthropic Chat Model — fa riferimento a quella credenziale salvata. n8n la cripta con N8N_ENCRYPTION_KEY, quindi fai il backup di quella chiave o le tue credenziali andranno perse con il volume.

Quanto costa un workflow AI per esecuzione?

Stima i token per esecuzione, quindi moltiplica per i prezzi per milione del modello — a luglio 2026, Haiku 4.5 è $1/$5 per un milione di token di input/output e Sonnet 5 è $3/$15 ($2/$10 introduttivo fino ad agosto 2026). Un riassunto via webhook su Haiku costa circa un quarto di centesimo; un'esecuzione di un agent su Sonnet con diverse chiamate agli strumenti si avvicina a $0.06–$0.10 perché ogni iterazione rispedisce l'intera conversazione come input. Verifica l'esecuzione nella pagina di utilizzo della Console invece di fidarti delle stime.

Quale modello Claude dovrei usare per le automazioni n8n?

Haiku 4.5 per classificazione, estrazione, riassunto e routing — lavoro ad alto volume dove velocità e prezzo dominano. Sonnet 5 per i nodi AI Agent e il ragionamento multi-step. Opus 4.8 solo dove una risposta errata è abbastanza costosa da giustificare il suo prezzo di listino di $5/$25 — cinque volte Haiku, poco meno del doppio di Sonnet. Imposta il modello per nodo, non per workflow — un workflow può mixare tutti e tre.

Come posso impedire a un workflow n8n di spendere troppo con l'API di Claude?

Usa i guardrail a strati: un basso Max Tokens su ogni nodo Claude, Max Iterations sugli agent, un timeout del workflow e impostazioni conservative di Retry On Fail in modo che i fallimenti non moltiplichino la spesa dei token. Poi aggiungi un workflow Error Trigger che ti avvisi su Slack quando qualsiasi workflow AI fallisce, e imposta un limite di spesa mensile nella Anthropic Console come tetto massimo che nulla sul VPS può superare.

Le chiamate agli strumenti (tool calls) di un AI Agent costano extra?

Non c'è una tariffa separata per gli strumenti, ma gli strumenti non sono gratuiti: ogni risultato dello strumento viene rimandato al modello come token di input, e ogni iterazione dell'agent rispedisce l'intera conversazione fino a quel momento. Una risposta API prolissa passata senza filtri può superare di gran lunga il tuo prompt effettivo — abilita Optimize Response sui nodi HTTP Request e restituisci solo i campi di cui l'agent ha bisogno.