> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teamsoclo.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Risoluzione dei problemi

> Sintomo → causa → soluzione, più domande frequenti

## 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](https://gpt.teamsoclo.site/check) |
| `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](/it/models) |
| `model not found`, errore immediato del nome modello | Errore di battitura nel nome del modello | Copia il nome dalla [tabella dei modelli](/it/models) |
| `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](https://gpt.teamsoclo.site/check): 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](https://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".

<Warning>
  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`.
</Warning>

### 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:

```bash theme={null}
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:

```bash theme={null}
npm config get prefix
```

Quella cartella più `/bin` deve essere in `$PATH`.

### Codex chiede ancora il login su OpenAI

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:

```bash theme={null}
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](/it/getting-started).

### 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:

```powershell theme={null}
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](/it/setup/codex) (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:

```bash theme={null}
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](/it/setup/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](/it/setup/codex). Per altre app, elimina semplicemente la chiave nelle Impostazioni dell'app.

## Non funziona ancora

<Steps>
  <Step title="La chiave è attiva?">
    Incollala nella [pagina di verifica](https://gpt.teamsoclo.site/check). Un errore qui significa che il problema è la chiave (errata, scaduta, senza credito), non l'app.
  </Step>

  <Step title="Chiama l'API direttamente con cURL">
    ```bash theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Contattare il supporto">
    Invia uno screenshot dell'errore e gli ultimi 4 caratteri della tua chiave a [t.me/teamsoclo](https://t.me/teamsoclo). Non inviare mai la chiave completa.
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.