Risoluzione dei problemi

Riferimento rapido

L’app dice	Quasi certamente	Soluzione
`401 Unauthorized`, `Invalid token`	Chiave errata, caratteri mancanti, scaduta o disabilitata	Incolla la chiave nella pagina di verifica
`404 Not Found`	Base URL senza `/v1` (o duplicata in `/v1/v1`)	Correggi la Base URL
`No available channel for model ... under group ...`	Una chiave di un pacchetto che chiama il modello dell’altro pacchetto	Usa il modello del tuo pacchetto, vedi Modelli
`model not found`, errore immediato del nome modello	Errore di battitura nel nome del modello	Copia il nome dalla tabella dei modelli
`429 Too Many Requests`	Superato il limite di richieste al minuto della chiave	Attendi il minuto successivo, rallenta
`insufficient quota`	La chiave ha esaurito tutti i suoi token	Acquista un nuovo codice
Configurazione modificata ma nulla cambia	App non chiusa completamente o terminale non riaperto	Chiudi completamente e riapri

Chiavi e credito

Chiave errata o troncata

Il problema più comune non è una chiave rotta ma alcuni caratteri persi durante la selezione del testo con il mouse. Usa sempre il pulsante Copy nella pagina di riscatto. Incolla la chiave nella pagina di verifica: se dice valida, la chiave è corretta e il problema è nella configurazione dell’app.

Chiave scaduta

Ogni pacchetto ha un periodo di validità contato dal riscatto (stampato sul prodotto). Dopo la scadenza ogni richiesta restituisce 401 anche se rimane del credito. La pagina di verifica mostra la data di scadenza. I token non utilizzati non vengono trasferiti a un nuovo codice.

Credito esaurito

Tutto funzionava, poi improvvisamente tutte le richieste falliscono con insufficient quota. Controlla quanto rimane nella pagina di verifica. Un credito che si esaurisce insolitamente in fretta è di solito un agente che legge l’intero repository, o una conversazione molto lunga che viene reinviata a ogni turno.

Chiave persa

Riscatta lo stesso codice CDK di nuovo su redeem.teamsoclo.site; la pagina mostrerà la chiave originale. I codici non vengono riemessi con una nuova chiave.

Quanti computer per chiave

Non c’è limite di dispositivi, ma il limite di richieste al minuto è condiviso da tutti i computer che usano la chiave. Condividere una chiave significa che gli utenti competono per lo stesso limite e raggiungono il 429 prima.

Connessione

Manca /v1

La Base URL corretta è https://gpt.teamsoclo.site/v1. Senza /v1 le richieste raggiungono il sito web invece dell’API e l’app riporta 404 o “impossibile connettersi”.

Il contrario fallisce anche: alcune app (Chatbox, alcune versioni di Cline) aggiungono /v1 da sole. Se l’hai inserita e ricevi ancora 404, prova senza /v1; l’indirizzo reale potrebbe essere diventato /v1/v1.

Chiamare il modello dell’altro pacchetto

No available channel for model gpt-astra under group default significa che una chiave GPT sta chiamando il modello Astra (o viceversa). Ogni chiave può chiamare solo il modello del proprio pacchetto. Verifica con:

curl https://gpt.teamsoclo.site/v1/models -H "Authorization: Bearer sk-xxx"

429 Too Many Requests

Ogni chiave ha un numero massimo di richieste riuscite al minuto impostato dal suo pacchetto. Superato quel limite ricevi 429 con un messaggio di “limite di richieste raggiunto”. Attendi il minuto successivo. Per gli script in batch aggiungi un ritardo tra le chiamate, o acquista un altro codice per distribuire il carico.

Risposta interrotta a metà

Per domande che richiedono molto ragionamento, una richiesta senza streaming può essere eliminata prima del primo token. Abilita stream: true. La maggior parte delle app di chat lo fa già; aggiungilo quando chiami dal codice.

`Unsupported parameter: reasoning_effort`

Solo Chat Completions accetta reasoning_effort al livello superiore. Con la Responses API usa "reasoning": {"effort": "high"}. Codex lo gestisce da solo.

Codex

`codex: command not found` dopo l’installazione

npm ha terminato ma il terminale attuale non ha ricaricato il PATH. Apri un nuovo terminale. Se continua a fallire, controlla che la cartella bin di npm sia nel PATH:

npm config get prefix

Quella cartella più /bin deve essere in $PATH. La variabile TEAMSOCLO_API_KEY non ha raggiunto il processo di Codex:

Terminale: apri una nuova scheda, controlla echo $TEAMSOCLO_API_KEY.
VS Code su macOS: chiudi con Cmd + Q e riapri. Il comando di installazione ha impostato la variabile per le app GUI tramite launchctl.
VS Code su Linux: avvia VS Code da un terminale (code .), oppure esci e rientra.
Windows: apri un nuovo PowerShell o VS Code dopo setx.

Controlla che config.toml abbia requires_openai_auth = false e env_key = "TEAMSOCLO_API_KEY".

Ho modificato config.toml ma Codex non cambia

La configurazione viene letta solo all’avvio del processo. Reload Window non è sufficiente; chiudi completamente VS Code (macOS Cmd + Q, Windows chiudi tutte le finestre e i processi in background). Questa è la domanda più frequente su Codex.

`EACCES: permission denied` durante l’installazione npm

Node è stato installato con privilegi di sistema, comune su Linux. Cambia il prefisso di npm:

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Aggiungi la riga export a ~/.bashrc o ~/.zshrc. A lungo termine, installa Node tramite nvm, vedi Guida introduttiva.

Windows: `running scripts is disabled on this system`

PowerShell blocca i file .ps1, e codex / npm digitati in PowerShell passano attraverso i shim .ps1 di npm. Esegui una volta:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Poi apri un nuovo PowerShell. Oppure digita codex.cmd, npm.cmd invece.

Windows: `EBUSY: resource busy or locked`

Codex è in esecuzione (CLI, estensione o app) quindi npm non riesce a sovrascrivere codex.exe. Chiudi tutto ciò che esegue Codex e riesegui il comando di installazione. La configurazione era già stata scritta prima di questo passaggio; è stata saltata solo l’aggiornamento della CLI.

Windows: errore di codifica del file di configurazione

La modifica con PowerShell 5.1 e Set-Content -Encoding UTF8 aggiunge un BOM che Codex non riesce a leggere. Usa di nuovo il comando di installazione (scrive UTF-8 senza BOM), oppure salva il file in VS Code come UTF-8 (non UTF-8 con BOM).

Ripristinare la configurazione precedente

Ogni esecuzione del comando di installazione esegue il backup della vecchia configurazione accanto alla nuova:

ls ~/.codex/*.bak.*
cp ~/.codex/config.toml.bak.20260925143000 ~/.codex/config.toml

Con lo strumento, scegli Ripristina e il ripristino avviene automaticamente.

Domande frequenti

Come cambio le chiavi

Riesegui il comando di installazione di Codex con la nuova chiave, oppure riesegui lo strumento. Per Cursor, Cline e Chatbox, modifica il campo API Key nelle Impostazioni.

È sicuro eseguire il comando di installazione più volte?

Sì. È progettato per essere rieseguito: la vecchia configurazione viene salvata come .bak.<timestamp>, la CLI viene aggiornata e la vecchia riga della chiave nel tuo rc della shell viene sostituita.

Il comando invia la mia chiave da qualche parte?

No. Incolli la chiave nel comando sul tuo computer; scrive solo una variabile di ambiente e un file di configurazione locale. L’intero comando viene mostrato sulla pagina, leggi ogni riga prima di eseguire.

Rimuovere tutto

Vedi Disinstallare nella pagina di Codex. Per altre app, elimina semplicemente la chiave nelle Impostazioni dell’app.

Non funziona ancora

La chiave è attiva?

Incollala nella pagina di verifica. Un errore qui significa che il problema è la chiave (errata, scaduta, senza credito), non l’app.

Chiama l'API direttamente con cURL

curl https://gpt.teamsoclo.site/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"hi"}]}'

Se questo funziona e l’app no, il problema è la configurazione dell’app.

Ricontrolla tre cose nell'app

La Base URL termina con /v1, la chiave è completa, il modello corrisponde al tuo pacchetto. Questi causano quasi tutti i problemi.

Contattare il supporto

Invia uno screenshot dell’errore e gli ultimi 4 caratteri della tua chiave a t.me/teamsoclo. Non inviare mai la chiave completa.

​Riferimento rapido

​Chiavi e credito

​Chiave errata o troncata

​Chiave scaduta

​Credito esaurito

​Chiave persa

​Quanti computer per chiave

​Connessione

​Manca /v1

​Chiamare il modello dell’altro pacchetto

​429 Too Many Requests

​Risposta interrotta a metà

​Unsupported parameter: reasoning_effort

​Codex

​codex: command not found dopo l’installazione

​Codex chiede ancora il login su OpenAI

​Ho modificato config.toml ma Codex non cambia

​EACCES: permission denied durante l’installazione npm

​Windows: running scripts is disabled on this system

​Windows: EBUSY: resource busy or locked

​Windows: errore di codifica del file di configurazione

​Ripristinare la configurazione precedente

​Domande frequenti

​Come cambio le chiavi

​È sicuro eseguire il comando di installazione più volte?

​Il comando invia la mia chiave da qualche parte?

​Rimuovere tutto

​Non funziona ancora

Riferimento rapido

Chiavi e credito

Chiave errata o troncata

Chiave scaduta

Credito esaurito

Chiave persa

Quanti computer per chiave

Connessione

Manca /v1

Chiamare il modello dell’altro pacchetto

429 Too Many Requests

Risposta interrotta a metà

`Unsupported parameter: reasoning_effort`

Codex

`codex: command not found` dopo l’installazione

Codex chiede ancora il login su OpenAI

Ho modificato config.toml ma Codex non cambia

`EACCES: permission denied` durante l’installazione npm

Windows: `running scripts is disabled on this system`

Windows: `EBUSY: resource busy or locked`

Windows: errore di codifica del file di configurazione

Ripristinare la configurazione precedente

Domande frequenti

Come cambio le chiavi

È sicuro eseguire il comando di installazione più volte?

Il comando invia la mia chiave da qualche parte?

Rimuovere tutto

Non funziona ancora