Hermes Agent con Claude tramite un gateway: configurazione di un provider personalizzato, controllo dei costi e soluzioni ai problemi
Hermes Agent conserva i segreti in ~/.hermes/.env e tutto il resto in ~/.hermes/config.yaml. Il modo affidabile per eseguirlo con Claude tramite un gateway è usare un provider personalizzato con nome che utilizzi il formato Anthropic Messages. La scorciatoia, provider: anthropic con un URL di base diverso, sembra corretta ma invia le richieste ad Anthropic per qualsiasi host che non riconosce.
Installazione
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bashiex (irm https://hermes-agent.nousresearch.com/install.ps1)hermes setup esegue l'intera procedura guidata; hermes model gestisce solo provider e modello; hermes doctor verifica un'installazione esistente.
Aggiungi il gateway come provider personalizzato
AIPRIME_API_KEY=your_gateway_keyproviders:
aiprime:
api: https://aiprimetech.io/v1
key_env: AIPRIME_API_KEY
transport: anthropic_messages
catalog_provider: anthropic
model:
provider: custom:aiprime
default: claude-sonnet-5| Chiave | Motivo |
|---|---|
transport: anthropic_messages | Usa il formato Messages di Anthropic. Senza questa impostazione, Hermes ripiega sul formato Chat Completions di OpenAI |
key_env | Il nome della variabile in .env che contiene la chiave |
catalog_provider: anthropic | I modelli Claude del gateway ereditano i metadati di Anthropic relativi al contesto e alla visione |
provider: custom:aiprime | Seleziona il provider con il nome indicato; /model custom:aiprime:<model> consente di cambiarlo all'interno di una chat |
La procedura guidata fa lo stesso: hermes model, poi **Endpoint personalizzato**, quindi la modalità API **Anthropic Messages**. Se invece scegli Chat Completions, mantieni /v1 nell'URL.
Perché provider: anthropic con un URL di base non funziona
provider: anthropic e base_url: https://aiprimetech.io sembra corretto ma non ha effetto: nel codice sorgente attuale di Hermes, la sostituzione dell'URL di base del provider Anthropic integrato viene accettata solo per host Anthropic, Claude e Azure, quindi le richieste continuano a essere inviate ad Anthropic. Usa il provider personalizzato con nome indicato sopra.ANTHROPIC_BASE_URL è documentato come un'impostazione che sostituisce l'URL di base di Anthropic, ma un bug di Hermes ancora aperto fa sì che il selettore dei modelli lo ignori. Il provider personalizzato evita entrambi i problemi.
Cosa determina il consumo di token e quali impostazioni lo limitano
Hermes esegue attività oltre alla conversazione che vedi, e tutte vengono addebitate alla stessa chiave, a meno che tu non le instradi altrove.
| Origine del consumo | Impostare |
|---|---|
| Subagents (delegation) | delegation.max_concurrent_children (valore predefinito 10), delegation.max_iterations (valore predefinito 250), delegation.max_spawn_depth (valore predefinito 1); un delegation.model |
| Revisione in background della memoria e delle competenze dopo ogni turno | auxiliary.background_review.enabled: false, oppure un valore inferiore di max_input_tokens |
| Attività ausiliarie (compressione, titoli, visione) | auxiliary.<task>.provider e .model per inviarle a un modello più economico |
| Attività pianificate | cron.model per tutte le attività; hermes cron pause <id> o hermes pause |
| Gateway di messaggistica (Telegram, Discord e altri) | Elenchi di elementi consentiti come TELEGRAM_ALLOWED_USERS; evita GATEWAY_ALLOW_ALL_USERS=true |
delegation:
max_concurrent_children: 3
model: claude-haiku-4-5
auxiliary:
background_review:
enabled: false
cron:
model: claude-haiku-4-5hermes prompt-size mostra il costo fisso di ogni chiamata; /usage e /compress sono utili durante una sessione lunga.
Accesso con Claude Pro o Max al posto di una chiave
Hermes può accedere a un account Claude, ma la sua documentazione indica che questa modalità funziona solo con un piano Max e crediti acquistati per l'utilizzo extra, e che gli abbonati Pro non possono usarla. Con una chiave API di un gateway non c'è alcuna finestra di utilizzo legata all'abbonamento; l'utilizzo viene addebitato per token sul tuo saldo.
Modelli
| ID del modello | Usalo per |
|---|---|
claude-sonnet-5 | Scelta predefinita per programmazione e attività degli agenti: veloce, potente, di fascia media. |
claude-opus-5-5 | Ragionamenti più complessi, refactoring estesi, esecuzioni prolungate degli agenti. |
claude-fable-5-1 | Il più capace e il più costoso; riservalo alle attività più difficili. |
claude-haiku-4-5 | Economico e rapido: titoli, riepiloghi, classificazione, piccoli passaggi. |
Hermes richiede una finestra di contesto di almeno 64K token; ogni modello della tabella soddisfa questo requisito.
Risoluzione dei problemi
| Che cosa vedi | Causa | Soluzione |
|---|---|---|
| HTTP 400 alla prima esecuzione | Il nome del modello non corrisponde a un ID di modello del gateway | Usa un ID della tabella qui sopra |
| Le richieste vengono inviate ad Anthropic oppure falliscono con un errore di autenticazione di Anthropic | provider: anthropic con un URL di base di terze parti | Usa il provider personalizzato con nome |
| Risposte incomprensibili o vuote | Trasporto errato per l'URL | transport: anthropic_messages per Claude |
| Lunghezza del contesto superata | Sessione più grande della finestra configurata | Imposta model.context_length; /compress |
403 Your request was blocked | Un firewall davanti all'endpoint rifiuta il client | Aggiungi extra_headers con uno User-Agent simile a quello di un browser |
| Impostazioni mancanti dopo un aggiornamento | Lo schema di configurazione è cambiato | hermes config check, quindi hermes config migrate |
| Il bot non risponde su Telegram o Discord | Il gateway non è in esecuzione o il mittente non è autorizzato | hermes gateway status; controlla ~/.hermes/logs/gateway.log |
Stai confrontando i framework per agenti? Consulta la guida alla configurazione di OpenClaw.
Domande frequenti
Come posso usare Hermes Agent con un endpoint Claude personalizzato?
Perché Hermes ignora il mio base_url di Anthropic?
Come posso ridurre il consumo di token di Hermes Agent?
Hermes Agent può usare un abbonamento Claude Pro?
Ottieni una chiave API: non servono un account Anthropic né una lista d'attesa.
Ottieni la tua chiave APIAI Prime Tech è un gateway API indipendente. Non è affiliato ad Anthropic, non è approvato da Anthropic e non è un suo rivenditore. Claude e i nomi dei modelli correlati sono marchi dei rispettivi proprietari.