OpenClaw

OpenClaw è un agente open source. Puoi aggiungere HiAPI come provider di modelli con la procedura guidata integrata o con i comandi, poi chattare nella Dashboard (la console nel browser) o nella TUI (l’interfaccia di chat nel terminale). I passaggi seguenti usano claude-opus-5-5 come esempio; HiAPI usa il protocollo OpenAI Chat Completions. Questo tutorial è stato verificato su OpenClaw 2026.10.7.

1. Installare OpenClaw

Consigliamo lo script di installazione ufficiale; controlla e prepara l’ambiente Node.js necessario. Su Mac / Linux / WSL2 esegui:

curl -fsSL https://openclaw.ai/install.sh | bash

Su Windows usa PowerShell:

iwr -useb https://openclaw.ai/install.ps1 | iex

Dopo l’installazione riapri il terminale ed esegui openclaw --version; basta vedere il numero di versione.

2. Inizializzare e aprire OpenClaw

Prima prepara una chiave API HiAPI. Per usare un altro modello, trova il nome nell’elenco dei modelli testuali e inseriscilo.

Al primo utilizzo esegui questo in un terminale:

openclaw onboard --install-daemon

Completa la configurazione di base come indicato. La versione attuale apre la pagina delle impostazioni dei modelli nel browser; se compare la procedura guidata classica del terminale, scegli QuickStart, mantieni main come agente predefinito, scegli Skip for now per modello, canali, ricerca e Skills facoltative, poi collega HiAPI come descritto sotto. Se hai già inizializzato, apri direttamente la Dashboard:

openclaw dashboard

OpenClaw gira su un servizio Gateway in background. Se il Gateway non è ancora in esecuzione, esegui openclaw gateway run in un terminale e lascia la finestra aperta, poi esegui openclaw dashboard in un altro terminale. Se hai installato il servizio in background, puoi anche riavviarlo con openclaw gateway restart.

Gli screenshot seguenti provengono da un’istanza demo autonoma di OpenClaw 2026.10.7 del 28 ottobre 2026; la porta può essere diversa da quella del tuo computer, quindi usa l’indirizzo che apre openclaw dashboard.

3. Aggiungere HiAPI in OpenClaw

La prima volta che entri nella pagina Model settings, trova Custom OpenAI/Anthropic-compatible endpoint e fai clic su Set up endpoint. Se hai già inizializzato, vai su Settings → Models → Connect provider → On this Gateway per arrivare alla stessa voce.

3.1 Inserire l’indirizzo API

Imposta API Base URL su https://api.hiapi.ai/v1, senza aggiungere /chat/completions, e fai clic su Submit.

3.2 Inserire la chiave API

Nel passaggio How do you want to provide this API key? scegli Paste API key now, incolla la tua chiave API HiAPI e fai clic su Submit.

3.3 Scegliere il protocollo

Per Endpoint compatibility scegli OpenAI-compatible — Uses /chat/completions (cioè il protocollo OpenAI Chat Completions). Usa questo protocollo anche quando il modello è Claude.

3.4 Inserire modello e nome del provider

Imposta Model ID su claude-opus-5-5 e fai clic su Submit.

Imposta Endpoint ID su hiapi e fai clic su Submit. Il riferimento completo del modello in OpenClaw è quindi hiapi/claude-opus-5-5.

Model alias (optional) è un alias facoltativo; puoi lasciarlo vuoto e inviare. Al termine della verifica la configurazione iniziale mostra “Inference is ready” e “Verified model: hiapi/claude-opus-5-5”.

4. Impostare il modello predefinito e verificare una chat

Imposta il modello predefinito per le nuove sessioni, poi controlla la configurazione:

openclaw config set agents.defaults.model.primary hiapi/claude-opus-5-5
openclaw config validate
openclaw config get agents.defaults.model.primary

Il risultato deve includere Config valid e l’ultimo comando deve stampare hiapi/claude-opus-5-5, il che significa che la configurazione è stata scritta. Devi comunque verificare con un messaggio reale:

1. Se sei ancora nella pagina di configurazione iniziale, fai clic su Continue with the web app, poi su Back to app.
2. Avvia una nuova chat, fai clic sul nome del modello sotto la casella di input e scegli il modello appena configurato nel gruppo Hiapi. Le sessioni esistenti potrebbero usare ancora il modello scelto prima.
3. Invia “Ciao, presentati in una frase.” e aspetta la risposta.

Una risposta normale significa che il collegamento funziona. Le risposte possono variare ogni volta; orientati sul provider attualmente selezionato, sul fatto che la richiesta riesca e sui Registri delle richieste nella console HiAPI.

Per chattare nel terminale, esegui questo mentre il Gateway è in esecuzione:

openclaw tui

5. Scrivere la configurazione con i comandi (facoltativo)

Puoi anche fare tutto con i comandi: inizializzare → scrivere la configurazione → verificare. Salta questa sezione se l’hai già configurato nell’interfaccia web qui sopra. Prima sostituisci YOUR_HIAPI_API_KEY nei comandi con la tua chiave API HiAPI, poi esegui il comando per il tuo sistema.

openclaw config patch --stdin <<'JSON'
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "hiapi/claude-opus-5-5"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "hiapi": {
        "baseUrl": "https://api.hiapi.ai/v1",
        "apiKey": "YOUR_HIAPI_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-5-5",
            "name": "Claude Opus 5.5"
          }
        ]
      }
    }
  }
}
JSON

@'
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "hiapi/claude-opus-5-5"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "hiapi": {
        "baseUrl": "https://api.hiapi.ai/v1",
        "apiKey": "YOUR_HIAPI_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-5-5",
            "name": "Claude Opus 5.5"
          }
        ]
      }
    }
  }
}
'@ | openclaw config patch --stdin

Questa patch aggiunge il provider hiapi e imposta il modello predefinito; la configurazione degli altri provider viene mantenuta. Se esiste già un provider hiapi, la patch ne aggiorna la configurazione e sostituisce l’array dei modelli, quindi se ne aveva diversi scrivi prima tutti i modelli esistenti nell’array.

Su Windows CMD salva il JSON qui sopra come hiapi.patch.json, poi esegui:

openclaw config patch --file hiapi.patch.json

Dopo aver scritto, controlla la configurazione come al passaggio 4 e verifica con una nuova chat. Se dice che il Gateway deve essere riavviato: esegui openclaw gateway restart se hai installato il servizio in background; se gira in primo piano, premi Ctrl+C in quella finestra ed esegui di nuovo openclaw gateway run.

6. Risoluzione dei problemi

Qui sono elencati solo i problemi specifici di OpenClaw. Per gli errori comuni come 401, 404 e 429, vedi Errori comuni.