OpenCode

OpenCode è uno strumento di coding con AI open source che gira nel terminale. Puoi collegarlo a HiAPI con un’importazione da CC Switch oppure modificando manualmente il file di configurazione; scegli una delle due. I passaggi seguenti usano deepseek-v4.1-flash come esempio; HiAPI usa il protocollo OpenAI Chat Completions. Questo tutorial è stato verificato su Windows 11 con OpenCode 1.19.4. Prepara una chiave API HiAPI prima di iniziare; se importi con CC Switch, installa prima una versione che supporti OpenCode come descritto in Installazione di CC Switch e importazione con un clic.

1. Installare OpenCode

Su Mac / Linux esegui questo in un terminale:

curl -fsSL https://opencode.ai/install | bash

Se hai già Node.js (vedi Configurazione di Node.js), puoi installare anche con npm. Su Windows usa lo script di installazione qui sopra dentro WSL, oppure esegui questo in un terminale locale:

npm install -g opencode-ai

Dopo l’installazione riapri il terminale e controlla la versione:

opencode --version

Basta vedere il numero di versione.

2. Configurare HiAPI

Opzione 1: importazione con un clic tramite CC Switch

1. Apri la pagina di connessione OpenCode di HiAPI, scegli il modello e la chiave API HiAPI, e fai clic su Prepare import.

2. Nella finestra “Confirm provider import” di CC Switch controlla i punti seguenti, poi fai clic su Import:

Opzione 2: modificare manualmente il file di configurazione

Apri il file di configurazione globale ~/.config/opencode/opencode.json e aggiungi un provider HiAPI (protocollo OpenAI Chat Completions). Crea il file se non esiste; se hai già altre configurazioni, unisci solo i campi provider.hiapi e model qui sotto. Imposta il Base URL su https://api.hiapi.ai/v1, senza aggiungere /chat/completions.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "hiapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "HiAPI",
      "options": {
        "baseURL": "https://api.hiapi.ai/v1",
        "apiKey": "{env:HIAPI_API_KEY}"
      },
      "models": {
        "deepseek-v4.1-flash": {
          "name": "DeepSeek V4.1 Flash"
        },
        "claude-opus-5-5": {
          "name": "Claude Opus 5.5"
        }
      }
    }
  },
  "model": "hiapi/deepseek-v4.1-flash"
}

{env:HIAPI_API_KEY} è il modo in cui OpenCode legge una variabile d’ambiente; lascialo così. Poi imposta quella variabile nel terminale, sostituendo YOUR_HIAPI_API_KEY con la tua chiave API HiAPI e mantenendo le virgolette:

export HIAPI_API_KEY="YOUR_HIAPI_API_KEY"

$env:HIAPI_API_KEY = "YOUR_HIAPI_API_KEY"

La variabile d’ambiente vale solo per il terminale corrente, quindi avvia OpenCode nello stesso terminale dopo averla impostata; se riapri il terminale, impostala di nuovo, oppure aggiungila al file di avvio della shell (come ~/.zshrc) per renderla permanente.

L’esempio imposta hiapi/deepseek-v4.1-flash come modello predefinito. Per cambiare modello, modifica sia la definizione del modello in provider.hiapi.models sia il campo model.

3. Verificare

Vai nella directory del tuo progetto e avvia OpenCode nel terminale in cui hai impostato la variabile d’ambiente:

opencode

Digita /models e scegli un modello del provider HiAPI, per esempio deepseek-v4.1-flash. Invia “Ciao, presentati in una frase.” Una risposta normale significa che il collegamento funziona.

I due metodi di importazione possono mostrare nomi di provider diversi; controlla semplicemente il provider attualmente selezionato, il nome del modello e il Base URL. Puoi anche confermare nei Registri delle richieste nella console HiAPI che le richieste passino da HiAPI.

4. Risoluzione dei problemi

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