Punti chiave
- Verifica l'endpoint con curl prima di toccare OpenCode, così sai se un errore è nella configurazione o nell'API.
- Un provider personalizzato richiede tre cose: URL base, chiave API e un ID modello, che qui è uncensored.
- Imposta il limite del contesto a 100.000 token in modo che l'agent pianifichi in base alla finestra reale.
- Lo streaming e la chiamata di funzioni sono supportati, il che è ciò di cui ha bisogno un loop di agent.
Cosa ti serve prima di iniziare
OpenCode è un agente di programmazione open-source che gira nel tuo terminale. Può parlare con molti provider di modelli e ti permette di aggiungere il tuo provider se l'endpoint segue il formato chat di OpenAI. Questa API lo fa, quindi la configurazione consiste nel compilare alcuni campi.
Raccogli prima questi tre valori:
- URL base:
https://api.kimicode.top/v1 - ID modello:
uncensored - Chiave API: creane una nella pagina delle chiavi API. I nuovi account possono richiedere un credito di prova da $0,50 con un clic, che è più che sufficiente per i test seguenti. La chiave di prova consente 2 richieste parallele e 60 richieste al minuto.
Tieni la chiave in una variabile d'ambiente invece di incollarla nei file che commetti:
export KIMICODE_API_KEY="your-key-here"Fase 1: testa l'endpoint con curl
Fallo prima di configurare qualsiasi strumento. Se curl funziona e OpenCode no, sai che il problema è nella configurazione. Se curl fallisce, correggi la chiave o l'URL una volta sola, non in due punti.
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Say hello in five words."}],
"max_tokens": 40
}'Dovresti ricevere un oggetto JSON con un array choices e un blocco usage. Un 401 significa che la chiave è sbagliata o manca il prefisso Bearer. Un 404 di solito significa che l'URL è stato digitato male o include già /chat/completions.
Un agente di programmazione trasmette le sue risposte e chiama strumenti, quindi controlla anche questi due aspetti:
curl -N https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"stream": true,
"messages": [{"role": "user", "content": "Count from one to five."}]
}'Dovresti vedere una serie di righe data:, ognuna con un piccolo delta JSON, che termina con le figure di utilizzo e un marcatore finale. L'opzione -N disattiva il buffering di curl in modo che i chunk appaiano man mano che arrivano.
Fase 2: aggiungi un provider personalizzato a OpenCode
OpenCode legge un file di configurazione JSON, opencode.json, dalla cartella del progetto o dalla sua directory di configurazione globale. I provider personalizzati in stile OpenAI sono dichiarati con il pacchetto compatibile OpenAI dell'AI SDK, un URL base e un elenco di modelli. La struttura qui segue la documentazione pubblica di OpenCode al momento della stesura. I nomi dei campi possono cambiare tra le versioni, quindi confrontalo con la sezione provider della documentazione attuale di OpenCode se qualcosa viene rifiutato.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"kimicode": {
"npm": "@ai-sdk/openai-compatible",
"name": "Kimicode API",
"options": {
"baseURL": "https://api.kimicode.top/v1",
"apiKey": "{env:KIMICODE_API_KEY}"
},
"models": {
"uncensored": {
"name": "Uncensored",
"limit": {
"context": 100000,
"output": 8192
}
}
}
}
},
"model": "kimicode/uncensored"
}La chiave sotto models è l'ID modello esatto inviato al server, quindi deve leggere uncensored. L'ultima riga seleziona il provider e il modello come predefiniti, scritti come nome del provider, una barra e poi l'ID del modello.
La forma {env:KIMICODE_API_KEY} dice a OpenCode di leggere la variabile dal tuo shell. Se la tua versione gestisce le credenziali tramite il suo comando di accesso, usa quella via e lascia la chiave fuori dal file. In ogni caso, non inserire una chiave reale.
Configurazione del progetto o configurazione globale
Puoi tenere il blocco provider in due posti. Un file nella radice del progetto si applica solo a quel repository, il che si adatta a un team che condivide una sola configurazione. Un file nella directory di configurazione del tuo utente si applica ovunque, il che si adatta a un'impostazione predefinita personale. Dove esistono entrambi, il file del progetto si aggiunge o sovrascrive quello globale.
Preferisci il file globale per la definizione del provider e la variabile d'ambiente per la chiave. In questo modo ogni repository può usare l'endpoint e nessun dato segreto si trova accanto al tuo codice sorgente. Se più persone lavorano a un progetto, inserisci solo il blocco del provider senza chiave e fai in modo che ogni persona imposti la propria variabile. Questo rende anche semplice ruotare una chiave: cambia la variabile, riavvia il terminale e il file di configurazione resta invariato.
Fase 3: scegli il modello ed esegui un'attività
Avvia OpenCode in una cartella di progetto e apri il suo selettore di modelli. Il tuo provider personalizzato dovrebbe apparire nell'elenco con il nome visualizzato che hai impostato. Selezionalo, quindi dai all'agent un compito piccolo e verificabile come spiegare una funzione o scrivere un test unitario per un file breve.
Inizia in piccolo per due motivi. Primo, puoi vedere se le chiamate di strumenti funzionano: quando OpenCode chiede al modello di leggere o modificare un file, lo fa tramite l'interfaccia di chiamata di strumenti. Secondo, un agente di programmazione invia molto testo per turno, inclusi contenuti di file e cronologia, quindi una sessione lunga consuma token rapidamente. La sezione successiva mette i numeri su questo.
Se il modello non appare, controlla che il file sia un JSON valido, che si trovi dove OpenCode cerca la configurazione e che il nome del provider corrisponda a ciò che hai digitato nel campo model.
Test della chiamata di funzioni e della modalità JSON direttamente
OpenCode si affida alla chiamata di strumenti per leggere file, eseguire comandi ed editare codice, quindi vale la pena confermare che l'endpoint gestisca una definizione di strumento prima di dare la colpa all'agente per un errore. Questa richiesta offre uno strumento e pone una domanda che lo richiede.
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
"tools": [{
"type": "function",
"function": {
"name": "read_file",
"description": "Read a text file by path",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"]
}
}
}],
"tool_choice": "auto"
}'Una buona risposta contiene una voce tool_calls che nomina read_file con una stringa di argomento JSON. L'agent esegue lo strumento, quindi invia il risultato indietro come messaggio con role impostato su tool, e il modello continua da lì. Se vedi solo testo normale, prova un prompt più diretto, poiché se il modello decide di chiamare uno strumento fa parte del suo comportamento.
La modalità JSON è un interruttore separato. Aggiungere "response_format": {"type": "json_object"} chiede un output JSON valido e aiuta quando un altro script deve analizzare ciò che torna. Menziona JSON anche nel tuo prompt, in modo che il modello sappia che forma ti aspetti.
Dimensioni del contesto e costo di una sessione
La finestra di contesto è di 100.000 token, contando il prompt e il completamento insieme. Impostare limit.context a 100000 fa sapere all'agente il limite reale, così può tagliare o riassumere la cronologia prima che il server debba rifiutare una richiesta. Un completamento può usare tutto lo spazio rimasto e max_tokens è facoltativo.
La fatturazione è di $0,15 per 1M di token di input e $0,50 per 1M di token di output. Gli agenti sono pesanti in input, perché ogni turno ritrasmette la conversazione. Ecco un esempio pratico per una sessione moderata:
- 40 turni, ognuno dei quali invia circa 30.000 token di input: 1.200.000 token di input, che equivalgono a 1,2 x $0,15 = $0,18.
- Ogni turno restituisce circa 800 token di output: 32.000 token di output, che equivalgono a 0,032 x $0,50 = $0,016.
- Totale: $0,196, quindi circa venti centesimi per l'intera sessione.
I tuoi valori saranno diversi. Leggi i valori usage nelle risposte, oppure osserva l'intestazione X-Balance-USD, che riporta il tuo saldo residuo in ogni risposta. Il credito è prepagato e non scade mai, e le richieste fallite o rifiutate non vengono addebitate. I dettagli sono nella pagina dei prezzi.
Aspettative oneste per un agente di programmazione
Questo è un modello di testo generale ottimizzato per rispondere senza rifiuti di contenuti per l'uso adulto legale. Non è un modello costruito specificamente per il codice e questa pagina non fa affermazioni sui benchmark. Se modificherà il tuo repository in modo affidabile è qualcosa che dovresti testare sui tuoi compiti, con il controllo versione attivo, prima di affidargli qualcosa di importante.
Gestisce la parte infrastrutturale di cui ha bisogno un agente: chiamata di funzioni con tool_calls in streaming, risultati degli strumenti inviati come messaggi role: "tool" e modalità JSON tramite response_format. È solo testo, senza immagini, quindi le funzionalità che allegano screenshot non funzioneranno.
Due limiti sono importanti per gli agenti. Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto. I sotto-agenti o le esecuzioni parallele di strumenti che attivano molte chiamate contemporaneamente possono raggiungere il limite di concorrenza, e una richiesta in streaming mantiene il suo slot fino alla fine dello stream. Quando ciò accade ricevi HTTP 429 con il codice concurrency. Il codice rate_limited significa troppe richieste al minuto. In caso di sovraccarico temporaneo potresti anche vedere un 429 con Retry-After: 5. Riduci il parallelismo o attendi e riprova.
Risoluzione dei Problemi
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| 401 Non autorizzato | Chiave vuota o errata; la variabile d'ambiente non è impostata nello shell che ha avviato OpenCode | Esegui echo $KIMICODE_API_KEY nello stesso terminale, quindi riavvia OpenCode |
| 404 Non trovato | L'URL base include /chat/completions o manca /v1 | Usa esattamente https://api.kimicode.top/v1 |
| Modello non trovato | La chiave del modello differisce da uncensored | Fai corrispondere la chiave in models con l'ID restituito da GET /v1/models |
429 con concurrency | Troppe richieste contemporaneamente | Riduci le chiamate di funzioni parallele o attendi che gli streaming terminino |
| Richiesta troppo grande | Corpo superiore a 8 MB o cronologia vicina al limite della finestra di contesto | Avvia una nuova sessione o riassumi la cronologia |
Per qualsiasi argomento non trattato qui, la pagina documentazione contiene il riferimento completo alle richieste, mentre la guida di integrazione copre lo stesso endpoint dall'angolo di vista di altri client compatibili con OpenAI.
