Fai girare Chatwoot Captain su un endpoint OpenAI-compatible personalizzato.

Risposta rapida: tre config Captain in Super Admin.

Sull'attuale Chatwoot self-hosted, le impostazioni LLM di Captain sono config di installazione, non variabili .env; il .env.example distribuito lo dice esplicitamente e ti indirizza a Super Admin, App Configs, Captain. Tre valori contano: CAPTAIN_OPEN_AI_API_KEY prende la chiave gateway, CAPTAIN_OPEN_AI_MODEL prende l'id del modello, e CAPTAIN_OPEN_AI_ENDPOINT prende l'host dell'endpoint. Il valore dell'endpoint ha uno spigolo tagliente: dallo senza il suffisso /v1. L'inizializzatore di Chatwoot costruisce da solo la base API rimuovendo uno slash finale e aggiungendo /v1, e la descrizione stessa della config mostra il default come https://api.openai.com/ esattamente in quella forma. Per APIsRouter, inserisci https://api.apisrouter.com e lascia che Chatwoot derivi https://api.apisrouter.com/v1. Queste config vengono lette all'avvio dell'app, quindi riavvia Chatwoot dopo averle cambiate.

CAPTAIN_OPEN_AI_API_KEY:  sk-YOUR-APISROUTER-KEY
CAPTAIN_OPEN_AI_MODEL:    claude-haiku-4-5-20251001
CAPTAIN_OPEN_AI_ENDPOINT: https://api.apisrouter.com
                          (no /v1 -- Chatwoot appends it)

then restart the Chatwoot processes

Cosa fa Captain con il modello configurato.

Chatwoot (circa 34K stelle su GitHub) è la piattaforma di customer support open source leader, e Captain è il suo strato AI: un agente AI che risponde alle conversazioni dei clienti a partire dagli articoli del tuo help center e dalle FAQ, un copilot che redige risposte e riassume thread per gli agenti umani, e funzionalità di conoscenza basate su documenti dietro entrambi. Sulle installazioni self-hosted dove Captain è disponibile, tutto questo gira attraverso il modello configurato sopra. Sotto il cofano, Chatwoot configura una volta il suo agents SDK all'avvio: la chiave, la base API derivata, e il modello predefinito. Ogni funzionalità Captain parla quindi chat completions standard a quell'URL base, e l'id del modello viaggia come stringa semplice. Chatwoot mantiene comunque una mappa di prefissi di nomi di modello (claude-, gemini-, deepseek-) ma la usa per l'etichettatura della telemetria, non per il routing, quindi un id Claude o DeepSeek impostato come CAPTAIN_OPEN_AI_MODEL va comunque al tuo endpoint configurato come qualsiasi altra stringa. Il traffico di supporto ha un profilo di costo distintivo: molte conversazioni, turni brevi, e risposte fondate assemblate da articoli recuperati. Questo rende il costo per conversazione il numero che conta, ed è dominato dai token di input della fonte recuperata. Un id veloce gestisce bene il livello assistente, con l'escalation a un id più forte come una modifica di una config quando vuoi che il copilot scriva bozze migliori.

Configurazione completa e il dettaglio a tempo di avvio.

Apri la console Super Admin sulla tua installazione, vai su App Configs e seleziona Captain, poi riempi i tre valori. Se il tuo Chatwoot precede la config dell'endpoint (è arrivata nell'era v4.4 a metà 2025), aggiorna prima; sulle versioni più vecchie esistevano solo la chiave e il modello e l'endpoint era hardcoded. Poiché l'inizializzatore legge queste config durante l'avvio dell'applicazione, i cambiamenti hanno effetto dopo un riavvio dei processi web e worker. Questo significa anche che un valore sbagliato non fallisce al momento del salvataggio; fallisce alla prima richiesta Captain dopo il riavvio, il che vale la pena sapere prima di fare debug nel posto sbagliato. Captain ha anche un lato embedding: CAPTAIN_EMBEDDING_MODEL (default text-embedding-3-small) alimenta la ricerca documenti sul contenuto del tuo help center, e si risolve contro lo stesso endpoint configurato. Se reindirizzi l'endpoint verso un gateway, conferma che l'id di embedding che configuri lì sia uno che l'endpoint serve davvero; altrimenti lascia le funzionalità documenti sulla loro configurazione esistente e validale separatamente dopo il cambio.

# Chatwoot will call <endpoint>/v1/chat/completions
curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001",
       "messages":[{"role":"user","content":"ping"}]}'

Scegliere un modello per l'automazione di supporto.

Il ciclo di valutazione che funziona: esegui una settimana su un id veloce, esporta i numeri di utilizzo, poi esegui i team con molto copilot su un id più forte e confronta l'accettazione delle bozze piuttosto che le sensazioni. Entrambi i candidati fatturano attraverso la stessa chiave, quindi il confronto arriva già prezzato.

• Il livello agente AI è lavoro di volume: risposte fondate su articoli recuperati, migliaia di conversazioni al mese. claude-haiku-4-5-20251001, gpt-5.4-mini, e gemini-3.5-flash mantengono piatto il costo per conversazione senza perdere disciplina di fondamento.
• Il livello copilot legge interi thread e redige risposte per gli umani, dove tono e giudizio si vedono. claude-sonnet-4-6 è il passo avanti naturale quando la qualità delle bozze guida la produttività dell'agente.
• Le postazioni di supporto multilingue dovrebbero testare deepseek-v4-pro e gemini-3.5-flash sul loro mix linguistico reale; la qualità della risposta fondata varia tra le lingue più di quanto suggeriscano i benchmark in inglese.
• Il costo per conversazione è misurabile, non teorico: token per conversazione moltiplicati per conversazioni al mese, direttamente dal log di utilizzo.
• Un modello serve tutte le funzionalità Captain per installazione, quindi scegli per il tuo carico dominante e rivedi dopo aver letto una settimana di utilizzo reale.

Pagamento a consumo · sotto i prezzi ufficiali

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Modalità di errore specifiche di Chatwoot Captain.

Il doppio suffisso /v1 è il classico. Poiché Chatwoot aggiunge /v1 a qualunque cosa tu inserisca, incollare https://api.apisrouter.com/v1 produce richieste contro /v1/v1/chat/completions, che danno 404 al gateway. Inserisci l'host senza /v1. I cambi di config che sembrano ignorati sono la regola del riavvio. L'agents SDK viene configurato una volta all'avvio dalle config di installazione; modificarle in Super Admin senza riavviare lascia i vecchi valori attivi in ogni processo in esecuzione. Le vecchie guide puntano alla superficie sbagliata. I tutorial di versioni Chatwoot precedenti configurano OPENAI_API_KEY tramite variabili d'ambiente o l'integrazione OpenAI legacy; sulle versioni attuali le config Captain in Super Admin sono la superficie, e il .env.example lo dice in tante parole. Model-not-found sulla prima risposta di Captain dopo un cambio è un errore di battitura nell'id in CAPTAIN_OPEN_AI_MODEL; l'elenco /v1/models del gateway è la grafia autorevole. Gli errori di autenticazione significano che chiave ed endpoint nelle config non appartengono insieme. E se la ricerca articoli o il fondamento documenti degrada mentre le risposte chat vanno bene, guarda la config di embedding, che è un modello separato che si risolve contro lo stesso endpoint.

Chi instrada Chatwoot Captain tramite un gateway.

• Team di supporto self-hosted che vogliono una redazione di qualità Claude nel copilot senza un account fornitore separato e una relazione di fatturazione.
• Postazioni ad alto volume dove l'agente AI risponde alla maggior parte delle conversazioni, e il costo per conversazione decide se l'automazione ripaga; gli id veloci del catalogo mantengono onesto quel numero.
• Team che eseguono un Chatwoot per brand o regione, misurando ogni installazione con la propria chiave così il costo AI di supporto si riporta da solo per brand.
• Operatori che confrontano modelli di supporto su traffico reale: ogni candidato è un valore di config e un riavvio, non una migrazione.
• Sviluppatori senza accesso alla fatturazione di un dato fornitore. L'accesso basato su ricarica senza obbligo di carta rimuove la dipendenza dalla registrazione per provider.

Verifica l'endpoint e fai debug della prima conversazione.

Verifica prima fuori da Chatwoot: elenca i modelli con la tua chiave ed esegui una chat completion contro l'id esatto che hai impostato in CAPTAIN_OPEN_AI_MODEL. Se questi passano, la metà gateway è dimostrata e tutto il resto è lato Chatwoot. Poi riavvia e osserva la prima interazione Captain. I fallimenti di autenticazione puntano alla config della chiave; model-not-found punta alla config del modello; errori a forma di 404 puntano a un /v1 incollato nella config dell'endpoint. Se le funzionalità Captain semplicemente non appaiono, quella è disponibilità e licenza sul tuo livello di installazione, non config dell'endpoint. Una volta che le conversazioni fluiscono, la console di APIsRouter mostra il modello per richiesta, i conteggi dei token e la spesa. L'AI di supporto è una voce di budget che si accumula mensilmente, e una chiave per installazione trasforma il log di utilizzo nel report di costo per postazione che il tuo team finanziario continua a chiedere.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50

Domande frequenti