Usare OpenCode con CometAPI

Usa questa guida per eseguire OpenCode con CometAPI. La configurazione espone quattro formati API tramite provider personalizzati separati. Questa configurazione è stata testata con OpenCode 1.18.16. Riferimenti ufficiali:

Sostituisci ogni valore your-model-id con un ID modello dalla pagina Modelli di CometAPI. Scegli un modello che accetti il formato API della voce del provider circostante.

Prerequisiti

Node.js e npm, oppure un altro metodo di installazione dalla guida di OpenCode
Un account CometAPI con una chiave API attiva dalla dashboard
Uno o più ID modello dalla pagina Modelli di CometAPI

Comprendere i formati API

Ogni ID provider seleziona un adattatore SDK e un formato API.

ID provider	Adattatore OpenCode	URL di base	Formato API
`cometapi-chat`	`@ai-sdk/openai-compatible`	`https://api.cometapi.com/v1`	Chat Completions
`cometapi-responses`	`@ai-sdk/openai`	`https://api.cometapi.com/v1`	Responses
`cometapi-messages`	`@ai-sdk/anthropic`	`https://api.cometapi.com/v1`	Anthropic Messages
`cometapi-gemini`	`@ai-sdk/google`	`https://api.cometapi.com/v1beta`	Gemini generateContent

Questa guida verifica l’operazione di Streaming Gemini usata durante un normale turno dell’agente OpenCode. L’adattatore Google aggiunge :streamGenerateContent?alt=sse al percorso del modello. Non aggiungere /chat/completions, /responses, /messages, né un percorso di modello Gemini a baseURL. Ogni adattatore aggiunge il percorso dell’operazione richiesto.

Comprendere le autorizzazioni di runtime

OpenCode viene eseguito con le autorizzazioni del processo che lo avvia. Avvia OpenCode nella directory del progetto desiderata e conserva un percorso di rollback, ad esempio git. Usa un container o una sandbox quando ti servono limiti più rigidi per filesystem, processi, rete o chiavi API.

Configura OpenCode

Installa OpenCode

Installa OpenCode con il pacchetto npm ufficiale:

npm install -g opencode-ai

Conferma che la CLI sia disponibile:

opencode --version

Consulta la guida all’installazione di OpenCode per Homebrew, Windows, Docker e altri metodi di installazione.

Imposta la chiave API di CometAPI

Memorizza la chiave API di CometAPI nella variabile d’ambiente COMETAPI_KEY.

macOS / Linux / WSL
Windows PowerShell

Leggi la chiave API senza visualizzarla nel terminale:

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY

Leggi la chiave API nella sessione PowerShell corrente:

$secureKey = Read-Host "CometAPI API key" -AsSecureString
$env:COMETAPI_KEY = [System.Net.NetworkCredential]::new(
  "",
  $secureKey
).Password

Imposta la variabile in ogni sessione shell che avvia OpenCode. Non eseguire il commit delle chiavi API nel controllo versione.

Scegli una posizione per la configurazione

Usa una delle seguenti posizioni supportate:

Configurazione globale: ~/.config/opencode/opencode.json
Configurazione del progetto: opencode.json nella radice del progetto

OpenCode unisce i file di configurazione. Una configurazione di progetto sostituisce i valori in conflitto della configurazione globale.Usa il file globale quando vuoi che i provider siano disponibili in ogni progetto. Usa il file di progetto quando un repository necessita di proprie voci di modello.

Aggiungi i provider di CometAPI

Crea il file di configurazione selezionato. Se il file contiene già un provider oggetto, unisci queste quattro voci a quell’oggetto:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cometapi-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CometAPI Chat Completions",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Chat model"
        }
      }
    },
    "cometapi-responses": {
      "npm": "@ai-sdk/openai",
      "name": "CometAPI Responses",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Responses model"
        }
      }
    },
    "cometapi-messages": {
      "npm": "@ai-sdk/anthropic",
      "name": "CometAPI Anthropic Messages",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Messages model"
        }
      }
    },
    "cometapi-gemini": {
      "npm": "@ai-sdk/google",
      "name": "CometAPI Gemini",
      "options": {
        "baseURL": "https://api.cometapi.com/v1beta",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Gemini model"
        }
      }
    }
  }
}

Sostituisci ogni chiave your-model-id indipendentemente. Le quattro voci possono usare ID modello diversi.La configurazione non imposta un model di primo livello. Questo ti consente di scegliere il formato API e il modello richiesti tramite /models.

Non usare /connect per questa configurazione. I campi apiKey leggono COMETAPI_KEY dall’ambiente. Una variabile non impostata viene risolta in un valore vuoto anziché in una chiave API /connect memorizzata.

Seleziona e verifica ogni provider

Avvia OpenCode nel progetto a cui vuoi consentire l’accesso:

opencode

Esegui /models, quindi seleziona una voce provider/model. Nelle quattro verifiche eseguite per questa guida, ogni turno del modello ha utilizzato il formato API corrispondente alla voce selezionata. Non è stato osservato alcun fan-out delle richieste tra formati né alcuna negoziazione automatica del formato API osservata.Per verificare Chat Completions dalla riga di comando, esegui:

opencode run \
  --model cometapi-chat/your-model-id \
  "Reply exactly with: COMETAPI_CHAT_OK"

Per verificare Responses dalla riga di comando, esegui:

opencode run \
  --model cometapi-responses/your-model-id \
  "Reply exactly with: COMETAPI_RESPONSES_OK"

Per verificare Anthropic Messages dalla riga di comando, esegui:

opencode run \
  --model cometapi-messages/your-model-id \
  "Reply exactly with: COMETAPI_MESSAGES_OK"

Per verificare Gemini generateContent dalla riga di comando, esegui:

opencode run \
  --model cometapi-gemini/your-model-id \
  "Reply exactly with: COMETAPI_GEMINI_OK"

Risoluzione dei problemi

OpenCode non mostra un modello CometAPI

Verifica che la configurazione sia JSON valido. Ogni voce personalizzata deve trovarsi all’interno dell’oggetto provider di primo livello, e ogni ID modello deve trovarsi all’interno dell’oggetto models corrispondente. Riavvia OpenCode, quindi apri nuovamente /models.

OpenCode segnala un errore relativo alla chiave API o all'autenticazione

Verifica che COMETAPI_KEY sia impostato nella shell che avvia OpenCode. Un riferimento {env:COMETAPI_KEY} non impostato diventa un valore vuoto. Apri una nuova shell dopo aver modificato un profilo della shell.

Un ID modello non è disponibile

Consulta la pagina Modelli di CometAPI, quindi sostituisci l’ID del modello all’interno della voce del provider selezionato. Verifica che il modello accetti il formato API del provider.

Le richieste usano un percorso errato

Mantieni baseURL impostato su /v1 per Chat Completions, Responses e Messages. Usa /v1beta per Gemini. Non includere un percorso dell’operazione in baseURL.

Un provider funziona, ma un altro non riesce

Usa un ID modello che accetti il formato API del provider selezionato. Non presumere che un unico ID modello accetti tutti e quattro i formati.

La configurazione del progetto modifica un provider globale

OpenCode unisce la configurazione globale e quella di progetto. Rinomina l’ID del provider di progetto oppure rimuovi i valori in conflitto quando vuoi che la voce del provider globale rimanga invariata.

OpenCode dispone di più accesso del previsto

OpenCode usa le autorizzazioni del processo che lo ha avviato. Esegui OpenCode in un container o in una sandbox quando hai bisogno di limiti di accesso più rigorosi.

Panoramica

Agenti AI per la programmazione

Agenti AI

Client di chat AI

Traduzione e linguaggio

Piattaforme di automazione

Osservabilità e valutazione

Framework AI

Prerequisiti

Comprendere i formati API

Comprendere le autorizzazioni di runtime

Configura OpenCode

Risoluzione dei problemi

Risorse correlate

​Prerequisiti

​Comprendere i formati API

​Comprendere le autorizzazioni di runtime

​Configura OpenCode

​Risoluzione dei problemi

​Risorse correlate

Prerequisiti

Comprendere i formati API

Comprendere le autorizzazioni di runtime

Configura OpenCode

Risoluzione dei problemi

Risorse correlate