Menu
Formazione AI Hermes Agent WSL2

Come aggiungere provider custom al picker di Hermes Agent su WSL2

4 min di lettura Manuel

Il picker di Hermes Agent (hermes model o /model in sessione) è il cuore della flessibilità di questo agente. Puoi aggiungere OpenRouter, endpoint custom (Ollama, vLLM, LM Studio) e provider OAuth, averli sempre a disposizione e cambiare modello con un comando.

Due comandi, due funzioni

hermes model (dal terminale, fuori da una sessione) — È il wizard completo: aggiunge provider, configura API key, esegue flussi OAuth, imposta modelli. È l'unico modo per aggiungere un provider.

/model (dentro una sessione attiva) — Può solo cambiare tra provider e modelli già configurati. Non aggiunge provider, non chiede API key, non fa OAuth.

Se non vedi un provider nel picker, probabilmente non l' Hai configurato. Esci dalla sessione (Ctrl+C o /quit), esegui hermes model, e aggiungilo.

Configurare OpenRouter

Metodo interattivo

hermes model
  1. Seleziona OpenRouter dalla lista provider
  2. Inserisci la tua API key (inizia con sk-or-...)
  3. Scegli il modello dal catalogo curato (400+ modelli, inclusi quelli stealth)

La scrittura va in ~/.hermes/config.yaml:

model:
  provider: openrouter
  default: ~anthropic/claude-sonnet-latest

Metodo rapido (non interattivo)

hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx
hermes chat --provider openrouter --model '~anthropic/claude-sonnet-latest'

Oppure modifica direttamente ~/.hermes/.env:

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxx

Provider routing con OpenRouter

OpenRouter routes attraverso centinaia di provider. Puoi controllare come:

provider_routing:
  sort: "throughput"          # "price" (default), "throughput", o "latency"
  # only: ["anthropic"]       # Solo questi provider
  # ignore: ["deepinfra"]     # Salta questi provider
  order: ["anthropic", "google"]  # Prova in quest'ordine
  data_collection: "deny"     # Escludi provider che conservano i dati

Shortcut: Aggiungi :nitro a qualsiasi modello per ordinare per throughput (es. ~anthropic/claude-sonnet-latest:nitro), o :floor per prezzo minimo.

Configurare custom endpoint (Ollama, vLLM, LM Studio)

Metodo interattivo

hermes model
# Seleziona: "Custom endpoint (self-hosted / VLLM / etc.)"
# API base URL: http://localhost:11434/v1
# API key: ollama (o vuoto per server locali)
# Model name: qwen2.5-coder:32b
# Context length: 65536 ← minimo Hermes: 64K

Metodo config.yaml

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://localhost:11434/v1

provider: custom è un provider di prima classe, non un alias. Funziona con qualsiasi API compatibile con OpenAI.

WSL2: il problema del localhost

Su WSL2, localhost non punta a Windows. Se il tuo server Ollama/vLLM gira su Windows, devi usare l'IP dell'host Windows:

# Trova l'IP di Windows da dentro WSL2
ip route show | grep -i default | awk '{print $3}'

Poi usa quell'IP:

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://172.29.192.1:11434/v1  # IP Windows, non localhost

Se invece il server gira dentro WSL2, localhost funziona normalmente.

Fallback providers

Configura una catena di provider che Hermes prova in sequenza quando il primo fallisce:

fallback_providers:
  - provider: openrouter
    model: ~anthropic/claude-sonnet-latest
  - provider: openrouter
    model: ~google/gemini-flash-latest
  - provider: custom
    model: qwen2.5-coder:32b
    base_url: http://localhost:11434/v1

Utile per sessioni lunghe: se un provider va down, Hermes switcha automaticamente al successivo senza interrompere la sessione.

Custom model aliases

Crea alias per modelli che usi spesso, così puoi richiamarli con /model alias:

custom_providers:
  local-qwen:
    base_url: http://localhost:11434/v1
    api_key: ollama

model_aliases:
  fav: openrouter/~anthropic/claude-sonnet-latest
  grok: openrouter/~x-ai/grok-4
  local: custom:local-qwen:qwen2.5-coder:32b

Uso in sessione:

/model fav
/model grok
/model local

Filtrare i provider nel picker

Se hai tanti provider e vuoi ridurre il rumore, usa picker_providers:

model:
  default: ~anthropic/claude-sonnet-latest
  provider: openrouter
  picker_providers:
    - openrouter
    - custom
ValoreEffetto
Non setttatoMostra tutti i provider (default)
["custom"]Mostra solo custom providers
["openrouter", "custom"]Mostra OpenRouter + custom
[]Non mostrato (edge case)

Configurazione completa di esempio

Ecco un config.yaml con OpenRouter, Ollama locale e fallback:

model:
  provider: openrouter
  default: ~anthropic/claude-sonnet-latest
  picker_providers:
    - openrouter
    - custom

provider_routing:
  sort: "throughput"
  data_collection: "deny"

fallback_providers:
  - provider: openrouter
    model: ~google/gemini-flash-latest
  - provider: custom
    model: qwen2.5-coder:32b
    base_url: http://localhost:11434/v1

custom_providers:
  local-qwen:
    base_url: http://localhost:11434/v1
    api_key: ollama

model_aliases:
  fav: openrouter/~anthropic/claude-sonnet-latest
  local: custom:local-qwen:qwen2.5-coder:32b

Risoluzione dei problemi

Provider non visibile nel picker: Non è configurato. Esci dalla sessione e usa hermes model per aggiungerlo.

/model non mostra un modello specifico: Potrebbe non essere nel catalogo curato. Usa /model provider:modello per forzarlo, o controlla che il modello abbia tool-calling supportato.

WSL2: connessione rifiutata al custom endpoint: Probabilmente stai usando localhost invece dell'IP di Windows. Trova l'IP con ip route show | grep -i default | awk '{print $3}' e usalo in base_url.

API key non riconosciuta: Controlla ~/.hermes/.env per variabili d'ambiente, o ripeti hermes model per reinserirla.

Modello con contesto troppo piccolo: Hermes richiede minimo 64K token. Se il tuo modello locale ha meno, imposta context_length manualmente nel config.

Riferimenti