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

# Solución de problemas

> Síntoma → causa → solución, además de preguntas frecuentes

## Búsqueda rápida

| La app dice | Casi seguramente | Solución |
| - | - | - |
| `401 Unauthorized`, `Invalid token` | Clave incorrecta, caracteres faltantes, expirada o desactivada | Pega la clave en la [página de verificación](https://gpt.teamsoclo.site/check) |
| `404 Not Found` | A la Base URL le falta `/v1` (o se duplicó a `/v1/v1`) | Corrige la Base URL |
| `No available channel for model ... under group ...` | Una clave de un paquete llamando al modelo del otro paquete | Usa el modelo de tu paquete, ver [Modelos](/es/models) |
| `model not found`, error inmediato de nombre de modelo | Error tipográfico en el nombre del modelo | Copia el nombre de la [tabla de modelos](/es/models) |
| `429 Too Many Requests` | Por encima del límite de solicitudes por minuto de la clave | Espera al siguiente minuto, reduce la velocidad |
| `insufficient quota` | La clave ha usado todos sus tokens | Compra un nuevo código |
| Configuración editada pero nada cambia | App no cerrada completamente o terminal no reabierta | Cierra completamente y vuelve a abrir |

## Claves y cupo

### Clave incorrecta o truncada

El problema más común no es una clave rota sino **unos pocos caracteres perdidos** al seleccionar texto con el ratón. Usa siempre el botón **Copy** en la página de canje. Pega la clave en la [página de verificación](https://gpt.teamsoclo.site/check): si dice válida, la clave está bien y el problema está en la configuración de la app.

### Clave expirada

Cada paquete tiene un período de validez contado desde el canje (impreso en el producto). Después de la expiración, cada solicitud devuelve 401 incluso si queda cupo. La página de verificación muestra la fecha de expiración. Los tokens no utilizados no se transfieren a un nuevo código.

### Cupo agotado

Todo funcionaba, y de repente todas las solicitudes fallan con *insufficient quota*. Comprueba lo que queda en la página de verificación. Un cupo que cae inusualmente rápido suele deberse a un agente que lee todo el repositorio o a una conversación muy larga que se reenvía en cada turno.

### Clave perdida

Canjea el mismo código CDK de nuevo en [redeem.teamsoclo.site](https://redeem.teamsoclo.site); la página mostrará la clave original. Los códigos no se vuelven a emitir con una clave nueva.

### Cuántas máquinas por clave

No hay límite de dispositivos, pero el **límite de solicitudes por minuto** es compartido por todas las máquinas que usan la clave. Compartir una clave significa que los usuarios compiten por el mismo límite y llegan al 429 antes.

## Conexión

### Falta /v1

La Base URL correcta es `https://gpt.teamsoclo.site/v1`. Sin `/v1` las solicitudes llegan al sitio web en lugar de a la API y la app reporta 404 o "no se pudo conectar".

<Warning>
  Lo contrario también falla: algunas apps (Chatbox, algunas versiones de Cline) añaden `/v1` ellas mismas. Si lo ingresaste y sigues obteniendo 404, prueba sin `/v1`; la dirección real puede haberse convertido en `/v1/v1`.
</Warning>

### Llamar al modelo del otro paquete

`No available channel for model gpt-astra under group default` significa que una clave GPT está llamando al modelo Astra (o al revés). Cada clave solo puede llamar al modelo de su propio paquete. Verifica con:

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

### 429 Too Many Requests

Cada clave tiene un número máximo de solicitudes exitosas por minuto fijado por su paquete. Por encima de ese límite recibes 429 con un mensaje de "límite de solicitudes alcanzado". Espera al siguiente minuto. Para scripts por lotes añade un retraso entre llamadas, o compra otro código para distribuir la carga.

### Respuestá cortada a mitad

Para preguntas que requieren mucho razonamiento, una solicitud sin streaming puede descartarse antes del primer token. Activa `stream: true`. La mayoría de las apps de chat ya lo hacen; añádelo cuando llames desde código.

### `Unsupported parameter: reasoning_effort`

Solo Chat Completions acepta `reasoning_effort` en el nivel superior. Con la Responses API usa `"reasoning": {"effort": "high"}`. Codex lo maneja por sí solo.

## Codex

### `codex: command not found` después de instalar

npm terminó pero la terminal actual no ha recargado PATH. **Abre una nueva terminal**. Si sigue fallando, comprueba que la carpeta bin de npm esté en PATH:

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

Esa carpeta más `/bin` debe estar en `$PATH`.

### Codex sigue pidiendo inicio de sesión en OpenAI

La variable `TEAMSOCLO_API_KEY` no ha llegado al proceso de Codex:

* Terminal: abre una nueva pestaña, comprueba `echo $TEAMSOCLO_API_KEY`.
* VS Code en macOS: cierra con `Cmd + Q` y vuelve a abrir. El comando de instalación configuró la variable para apps GUI mediante `launchctl`.
* VS Code en Linux: inicia VS Code desde una terminal (`code .`), o cierra sesión y vuelve a iniciarla.
* Windows: abre una **nueva** PowerShell o VS Code después de `setx`.

Comprueba que `config.toml` tenga `requires_openai_auth = false` y `env_key = "TEAMSOCLO_API_KEY"`.

### Edité config.toml pero Codex no cambia

La configuración se lee solo al inicio del proceso. **Reload Window no es suficiente**; cierra VS Code completamente (macOS `Cmd + Q`, Windows cierra todas las ventanas y procesos en segúndo plano). Está es la pregunta más frecuente sobre Codex.

### `EACCES: permission denied` al instalar con npm

Node se instaló con privilegios del sistema, común en Linux. Cambia el prefijo de npm:

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

Añade la línea `export` a `~/.bashrc` o `~/.zshrc`. A largo plazo, instala Node mediante nvm, ver [Primeros pasos](/es/getting-started).

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

PowerShell bloquea los archivos `.ps1`, y `codex` / `npm` escritos en PowerShell pasan por los shims `.ps1` de npm. Ejecuta una vez:

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

Luego abre una nueva PowerShell. O escribe `codex.cmd`, `npm.cmd` en su lugar.

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

Codex está ejecutándose (CLI, extensión o app) por lo que npm no puede sobreescribir `codex.exe`. Cierra todo lo que esté ejecutando Codex y vuelve a ejecutar el comando de instalación. La configuración ya se escribió antes de este paso; solo se omitió la actualización de la CLI.

### Windows: error de codificación del archivo de configuración

Editar con PowerShell 5.1 y `Set-Content -Encoding UTF8` añade un BOM que Codex no puede leer. Usa el [comando de instalación](/es/setup/codex) de nuevo (escribe UTF-8 sin BOM), o guarda el archivo en VS Code como **UTF-8** (no UTF-8 con BOM).

### Restaurar la configuración anterior

Cada ejecución del comando de instalación respalda la configuración antigua junto a la nueva:

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

Con la herramienta, elige **Restablecer** y se restaura automáticamente.

## Preguntas frecuentes

### Cómo cambio las claves

Vuelve a ejecutar el [comando de instalación de Codex](/es/setup/codex) con la nueva clave, o vuelve a ejecutar la herramienta. Para Cursor, Cline y Chatbox, edita el campo API Key en Configuración.

### ¿Es seguro ejecutar el comando de instalación varias veces?

Sí. Está diseñado para ejecutarse de nuevo: la configuración antigua se guarda como `.bak.<timestamp>`, se actualiza la CLI y la línea de clave antigua en tu rc de shell se reemplaza.

### ¿El comando envía mi clave a algún lugar?

No. Pegas la clave en el comando en tu propia máquina; solo escribe una variable de entorno y un archivo de configuración local. El comando completo se muestra en la página, lee cada línea antes de ejecutar.

### Eliminar todo

Ver **Desinstalar** en la página de [Codex](/es/setup/codex). Para otras apps, simplemente elimina la clave en la Configuración de la app.

## Sigue sin funcionar

<Steps>
  <Step title="¿La clave está activa?">
    Pégala en la [página de verificación](https://gpt.teamsoclo.site/check). Un error aquí significa que el problema es la clave (incorrecta, expirada, sin cupo), no la app.
  </Step>

  <Step title="Llama a la API directamente 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"}]}'
    ```

    Si esto funciona y la app no, el problema es la configuración de la app.
  </Step>

  <Step title="Revisa tres cosas en la app">
    La Base URL termina con `/v1`, la clave está completa, el modelo coincide con tu paquete. Estos causan casi todos los problemas.
  </Step>

  <Step title="Contactar soporte">
    Envía una captura de pantalla del error y los últimos 4 caracteres de tu clave a [t.me/teamsoclo](https://t.me/teamsoclo). Nunca envíes la clave completa.
  </Step>
</Steps>


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