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

# Solução de problemas

> Sintoma → causa → solução, além de perguntas frequentes

## Consulta rápida

| O app diz | Quase certamente | Solução |
| - | - | - |
| `401 Unauthorized`, `Invalid token` | Chave errada, caracteres faltando, expirada ou desativada | Cole a chave na [página de verificação](https://gpt.teamsoclo.site/check) |
| `404 Not Found` | Base URL sem `/v1` (ou duplicada para `/v1/v1`) | Corrija a Base URL |
| `No available channel for model ... under group ...` | Uma chave de um pacote chamando o modelo do outro pacote | Use o modelo do seu pacote, ver [Modelos](/pt/models) |
| `model not found`, erro imediato de nome de modelo | Erro de digitação no nome do modelo | Copie o nome da [tabela de modelos](/pt/models) |
| `429 Too Many Requests` | Acima do limite de requisições por minuto da chave | Aguarde o próximo minuto, diminua a velocidade |
| `insufficient quota` | A chave usou todos os seus tokens | Compre um novo código |
| Configuração editada mas nada muda | App não fechado completamente ou terminal não reaberto | Feche completamente e reabra |

## Chaves e limite

### Chave errada ou truncada

O problema mais comum não é uma chave quebrada, mas **alguns caracteres perdidos** ao selecionar texto com o mouse. Sempre use o botão **Copy** na página de resgate. Cole a chave na [página de verificação](https://gpt.teamsoclo.site/check): se disser válida, a chave está certa e o problema está na configuração do app.

### Chave expirada

Cada pacote tem um período de validade contado a partir do resgate (impresso no produto). Após a expiração, cada requisição retorna 401 mesmo que haja limite restante. A página de verificação mostra a data de expiração. Os tokens não utilizados não são transferidos para um novo código.

### Limite esgotado

Tudo funcionava, e de repente todas as requisições falham com *insufficient quota*. Veja o que resta na página de verificação. Um limite caindo incomumente rápido geralmente é um agente lendo o repositório inteiro, ou uma conversa muito longa sendo reenviada a cada turno.

### Chave perdida

Resgate o mesmo código CDK novamente em [redeem.teamsoclo.site](https://redeem.teamsoclo.site); a página mostrará a chave original. Os códigos não são reemitidos com uma nova chave.

### Quantas máquinas por chave

Não há limite de dispositivos, mas o **limite de requisições por minuto** é compartilhado por todas as máquinas que usam a chave. Compartilhar uma chave significa que os usuários competem pelo mesmo limite e chegam ao 429 mais cedo.

## Conexão

### Falta /v1

A Base URL correta é `https://gpt.teamsoclo.site/v1`. Sem `/v1`, as requisições chegam ao site em vez da API e o app reporta 404 ou "não foi possível conectar".

<Warning>
  O oposto também falha: alguns apps (Chatbox, algumas versões do Cline) adicionam `/v1` por conta própria. Se você inseriu e ainda recebe 404, tente sem `/v1`; o endereço real pode ter se tornado `/v1/v1`.
</Warning>

### Chamando o modelo do outro pacote

`No available channel for model gpt-astra under group default` significa que uma chave GPT está chamando o modelo Astra (ou o inverso). Cada chave só pode chamar o modelo do seu próprio pacote. Verifique com:

```bash theme={null}
curl https://gpt.teamsoclo.site/v1/models -H "Authorization: Bearer sk-xxx"
```

### 429 Too Many Requests

Cada chave tem um número máximo de requisições bem-sucedidas por minuto definido pelo seu pacote. Acima disso, você recebe 429 com uma mensagem de "limite de requisições atingido". Aguarde o próximo minuto. Para scripts em lote, adicione um atraso entre chamadas, ou compre outro código para distribuir a carga.

### Resposta cortada no meio

Para perguntas que exigem muito raciocínio, uma requisição sem streaming pode ser descartada antes do primeiro token. Ative `stream: true`. A maioria dos apps de chat já faz isso; adicione quando chamar a partir do código.

### `Unsupported parameter: reasoning_effort`

Apenas o Chat Completions aceita `reasoning_effort` no nível superior. Com a Responses API, use `"reasoning": {"effort": "high"}`. O Codex lida com isso por conta própria.

## Codex

### `codex: command not found` após instalar

O npm terminou, mas o terminal atual não recarregou o PATH. **Abra um novo terminal**. Se ainda falhar, verifique se a pasta bin do npm está no PATH:

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

Essa pasta mais `/bin` deve estar no `$PATH`.

### O Codex ainda pede login no OpenAI

A variável `TEAMSOCLO_API_KEY` não chegou ao processo do Codex:

* Terminal: abra uma nova aba, verifique `echo $TEAMSOCLO_API_KEY`.
* VS Code no macOS: feche com `Cmd + Q` e reabra. O comando de instalação configurou a variável para apps GUI via `launchctl`.
* VS Code no Linux: inicie o VS Code a partir de um terminal (`code .`), ou faça logout e login novamente.
* Windows: abra um **novo** PowerShell ou VS Code após o `setx`.

Verifique se `config.toml` tem `requires_openai_auth = false` e `env_key = "TEAMSOCLO_API_KEY"`.

### Editei o config.toml mas o Codex não muda

A configuração é lida apenas no início do processo. **Reload Window não é suficiente**; feche o VS Code completamente (macOS `Cmd + Q`, Windows feche todas as janelas e processos em segundo plano). Esta é a pergunta mais frequente sobre o Codex.

### `EACCES: permission denied` ao instalar com npm

O Node foi instalado com privilégios do sistema, comum no Linux. Mude o prefixo do npm:

```bash theme={null}
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"
```

Adicione a linha `export` ao `~/.bashrc` ou `~/.zshrc`. A longo prazo, instale o Node via nvm, ver [Primeiros passos](/pt/getting-started).

### Windows: `running scripts is disabled on this system`

O PowerShell bloqueia arquivos `.ps1`, e `codex` / `npm` digitados no PowerShell passam pelos shims `.ps1` do npm. Execute uma vez:

```powershell theme={null}
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

Depois abra um novo PowerShell. Ou digite `codex.cmd`, `npm.cmd` em vez disso.

### Windows: `EBUSY: resource busy or locked`

O Codex está em execução (CLI, extensão ou app), então o npm não consegue sobrescrever `codex.exe`. Feche tudo que esteja executando o Codex e execute o comando de instalação novamente. A configuração já foi escrita antes desta etapa; apenas a atualização da CLI foi ignorada.

### Windows: erro de codificação do arquivo de configuração

Editar com PowerShell 5.1 e `Set-Content -Encoding UTF8` adiciona um BOM que o Codex não consegue ler. Use o [comando de instalação](/pt/setup/codex) novamente (escreve UTF-8 sem BOM), ou salve o arquivo no VS Code como **UTF-8** (não UTF-8 com BOM).

### Restaurar a configuração anterior

Cada execução do comando de instalação faz backup da configuração antiga ao lado da nova:

```bash theme={null}
ls ~/.codex/*.bak.*
cp ~/.codex/config.toml.bak.20260925143000 ~/.codex/config.toml
```

Com a ferramenta, escolha **Redefinir** e ela restaura automaticamente.

## Perguntas frequentes

### Como altero as chaves

Execute novamente o [comando de instalação do Codex](/pt/setup/codex) com a nova chave, ou execute novamente a ferramenta. Para Cursor, Cline e Chatbox, edite o campo API Key nas Configurações.

### É seguro executar o comando de instalação várias vezes?

Sim. Foi projetado para ser executado novamente: a configuração antiga é salva como `.bak.<timestamp>`, a CLI é atualizada e a linha de chave antiga no seu rc do shell é substituída.

### O comando envia minha chave para algum lugar?

Não. Você cola a chave no comando no seu próprio computador; ele apenas escreve uma variável de ambiente e um arquivo de configuração local. O comando completo é mostrado na página, leia cada linha antes de executar.

### Remover tudo

Veja **Desinstalar** na página do [Codex](/pt/setup/codex). Para outros apps, basta excluir a chave nas Configurações do app.

## Ainda não funciona

<Steps>
  <Step title="A chave está ativa?">
    Cole-a na [página de verificação](https://gpt.teamsoclo.site/check). Um erro aqui significa que o problema é a chave (errada, expirada, sem limite), não o app.
  </Step>

  <Step title="Chame a API diretamente com 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 isso funcionar e o app não, o problema é a configuração do app.
  </Step>

  <Step title="Verifique três coisas no app">
    A Base URL termina com `/v1`, a chave está completa, o modelo corresponde ao seu pacote. Esses causam quase todos os problemas.
  </Step>

  <Step title="Contatar o suporte">
    Envie uma captura de tela do erro e os últimos 4 caracteres da sua chave para [t.me/teamsoclo](https://t.me/teamsoclo). Nunca envie a chave completa.
  </Step>
</Steps>


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