> Para agentes de IA: guía paso a paso de configuración — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), índice de documentación — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Para agentes de IA

Cómo delegar la integración a un agente de IA: prompt listo para cualquier herramienta. A continuación: direcciones legibles por máquina de la documentación y una skill que el agente instala con un solo comando.

## Prompt para el agente

Envía este prompt a tu agente de IA. Configurará la herramienta según las instrucciones de abajo y te pedirá la clave.

```text
Conecta tu herramienta a JoinGonka Gateway —la API compatible con OpenAI y Anthropic de la red Gonka— siguiendo las instrucciones de https://gate.joingonka.ai/docs/agents.md. La clave te la daré yo: no la guardes en archivos del repositorio ni modifiques variables de entorno globales. Al final, comprueba la conexión con una solicitud corta e informa del resultado.
```

Abajo están las instrucciones. El agente las recibe en Markdown en [/docs/agents.md](https://gate.joingonka.ai/docs/agents.md).

## Reglas

- La clave API la crea una persona en el panel de usuario en [gate.joingonka.ai](https://gate.joingonka.ai/keys). No registres una cuenta ni crees claves por tu cuenta: pídele la clave al usuario.
- Mantén la clave en la variable de entorno `JOINGONKA_API_KEY` de tu sesión de terminal. No la escribas en archivos bajo git, no la incluyas en commits ni la muestres en el informe.
- No modifiques las variables globales `OPENAI_*` ni `ANTHROPIC_*`, ni en el perfil del shell ni en el sistema: otros herramientas del usuario las leen. La clave y la dirección se escriben en la configuración de la propia herramienta, eso hace el instalador.

## Datos

- URL base para clientes de OpenAI API: `https://gate.joingonka.ai/v1`
- URL base para clientes de Anthropic API, sin `/v1`: `https://gate.joingonka.ai`
- La clave se envía en el encabezado `Authorization: Bearer jg-…` o `x-api-key: jg-…`
- La clave para consultar los modelos empieza por `jg-`; la clave de gestión `gm-` no da acceso a los modelos.
- Modelo recomendado: `MiniMaxAI/MiniMax-M2.7`
- Lista de modelos disponibles: `GET https://gate.joingonka.ai/v1/models`
- Por clave, hasta 120 solicitudes por minuto; por encima del límite, respuesta 429 con la cabecera `Retry-After`. Los límites y tiempos de espera están en la respuesta `GET /v1/capabilities`, campo `limits`.

## Configuración

Busca la herramienta del usuario en la tabla al final de la sección. Si existe el valor `--tool`, configura con el instalador; si no, hazlo manualmente siguiendo la guía.

### Con el instalador

Un solo comando sin preguntas: la clave sale de la variable de entorno y el modelo se pasa con un flag. El instalador escribirá la configuración de la herramienta, guardará una copia de la anterior y comprobará la conexión con una solicitud a la pasarela.

```bash
JOINGONKA_API_KEY=<key> npx -y @joingonka/setup --tool <id> --model MiniMaxAI/MiniMax-M2.7 --non-interactive
```

| Flag | Qué hace |
| --- | --- |
| `--tool <id>` | Qué herramienta configurar: valor de la tabla de herramientas. |
| `--model <id>` | Identificador del modelo: el recomendado es `MiniMaxAI/MiniMax-M2.7`; todos los disponibles, `GET /v1/models`. |
| `--non-interactive` | Sin preguntas: la clave se toma de `JOINGONKA_API_KEY`. |
| `--scope local` | Configuración en el proyecto actual, no en el directorio home. Solo para Claude Code; el archivo de configuración se añade a `.gitignore`. |
| `--no-verify` | No comprobar la conexión después de escribir la configuración. |

| Código de salida | Qué significa |
| --- | --- |
| `0` | Listo: configuración escrita y solicitud de verificación superada. Si no se pudo verificar por red o saldo, el instalador imprime una advertencia pero también sale con código 0: avísale al usuario. |
| `1` | La configuración falló; el motivo está en la salida: por ejemplo, un valor desconocido de `--tool`, `JOINGONKA_API_KEY` sin definir o una clave que no empieza por `jg-`. |
| `2` | La configuración se escribió, pero la solicitud de verificación falló: revisa la clave y el identificador del modelo. |

Si la herramienta estaba en ejecución, reiníciala: la configuración se lee al arrancar.

### Manualmente

Para una herramienta sin instalador, abre su guía (enlace en la tabla de abajo) y define tres valores:

- dirección base — `https://gate.joingonka.ai/v1` para clientes de OpenAI API o `https://gate.joingonka.ai` para clientes de Anthropic API;
- clave — en el campo de clave API en los ajustes de la herramienta;
- modelo — `MiniMaxAI/MiniMax-M2.7` u otro de `GET /v1/models`.

### Herramientas y guías

| Herramienta | `--tool` |
| --- | --- |
| [Cursor](https://joingonka.ai/es/knowledge/cursor/) | `cursor` |
| [Claude Code](https://joingonka.ai/es/knowledge/claude-code/) | `claude-code` |
| [OpenClaw](https://joingonka.ai/es/knowledge/openclaw/) | `openclaw` |
| [OpenCode](https://joingonka.ai/es/knowledge/opencode/) | `opencode` |
| [Continue](https://joingonka.ai/es/knowledge/continue-dev/) | `continue` |
| [Cline](https://joingonka.ai/es/knowledge/cline/) | `cline` |
| [Aider](https://joingonka.ai/es/knowledge/aider/) | `aider` |
| [LangChain](https://joingonka.ai/es/knowledge/langchain/) | — |
| [n8n](https://joingonka.ai/es/knowledge/n8n/) | — |
| [Open WebUI](https://joingonka.ai/es/knowledge/open-webui/) | — |
| [LibreChat](https://joingonka.ai/es/knowledge/librechat/) | — |
| [Hermes](https://joingonka.ai/es/knowledge/hermes/) | `hermes` |
| [Kilo Code](https://joingonka.ai/es/knowledge/kilo-code/) | `kilo` |
| [Roo Code](https://joingonka.ai/es/knowledge/roo-code/) | `roo` |
| [LlamaIndex](https://joingonka.ai/es/knowledge/llamaindex/) | — |
| [PydanticAI](https://joingonka.ai/es/knowledge/pydantic-ai/) | — |
| [Vercel AI SDK](https://joingonka.ai/es/knowledge/vercel-ai-sdk/) | — |
| [TanStack AI](https://joingonka.ai/es/knowledge/tanstack-ai/) | — |
| [ZCode](https://joingonka.ai/es/knowledge/zcode/) | `zcode` |
| [JetBrains](https://joingonka.ai/es/knowledge/jetbrains/) | `jetbrains` |
| [Copilot BYOK](https://joingonka.ai/es/knowledge/copilot-byok/) | `copilot-byok` |
| [Zed](https://joingonka.ai/es/knowledge/zed/) | `zed` |
| [Pi](https://joingonka.ai/es/knowledge/pi/) | `pi` |
| [Codex CLI](https://joingonka.ai/es/knowledge/codex/) | `codex` |
| [DeepSeek Harness](https://joingonka.ai/es/knowledge/deepseek-harness/) | — |
| [MiniMax Code](https://joingonka.ai/es/knowledge/minimax-code/) | `minimax-code` |
| [Warp](https://joingonka.ai/es/knowledge/warp/) | — |
| [Trae](https://joingonka.ai/es/knowledge/trae/) | — |
| [Cherry Studio](https://joingonka.ai/es/knowledge/cherry-studio/) | — |
| [omp (Oh My Pi)](https://joingonka.ai/es/knowledge/omp/) | `omp` |
| [OpenHands](https://joingonka.ai/es/knowledge/openhands/) | — |
| [Qwen Code](https://joingonka.ai/es/knowledge/qwen-code/) | `qwen-code` |
| [Goose](https://joingonka.ai/es/knowledge/goose/) | `goose` |
| [Crush](https://joingonka.ai/es/knowledge/crush/) | `crush` |
| [Zoo Code](https://joingonka.ai/es/knowledge/zoo-code/) | `zoo` |
| [Kimi Code](https://joingonka.ai/es/knowledge/kimi-code/) | `kimi-code` |
| [Factory Droid](https://joingonka.ai/es/knowledge/factory-droid/) | `droid` |
| [MiMo Code](https://joingonka.ai/es/knowledge/mimo-code/) | `mimo-code` |

## Verificación

Verificación de la clave: consulta de saldo. No gasta tokens y la clave se toma de `JOINGONKA_API_KEY`:

```bash
curl -s https://gate.joingonka.ai/api/balance \
  -H "Authorization: Bearer $JOINGONKA_API_KEY"
```

Verificación de la dirección, la clave y el modelo: una solicitud corta al modelo:

```bash
curl -s https://gate.joingonka.ai/v1/chat/completions \
  -H "Authorization: Bearer $JOINGONKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MiniMaxAI/MiniMax-M2.7", "messages": [{"role": "user", "content": "Say OK"}], "max_tokens": 32}'
```

Una respuesta `200` con texto del modelo significa que la conexión funciona. El instalador hace esta comprobación por sí solo: después basta con un código de salida 0.

## Si algo va mal

El error llega en el campo `error` del cuerpo de la respuesta, con el tipo y el texto del motivo.

| Respuesta | Qué hacer |
| --- | --- |
| `401 authentication_error` | Clave no aceptada. Comprueba que se copió completa y se envió en `Authorization: Bearer` o `x-api-key`; el usuario es quien crea una clave nueva. |
| `402 insufficient_funds` | No hay fondos en el saldo. Avísale al usuario: el saldo se recarga en el panel de usuario. |
| `402 child_key_limit_exceeded` | Se agotó el límite de la clave secundaria. Hace falta otra clave o un límite mayor: eso lo decide el propietario de la clave. |
| `403 forbidden` | Esta es la clave de gestión `gm-`: no da acceso a los modelos. Se necesita una clave `jg-`. |
| `400 invalid_request_error` | Error en la solicitud. Si no se encuentra el modelo, el texto del error incluye la lista de identificadores disponibles: tómala de ahí o de `GET /v1/models`. |
| `404 model_not_found` | Ese modelo no está disponible ahora: elige otro de `GET /v1/models`. |
| `429` | Demasiadas solicitudes o red ocupada. Espera los segundos indicados en la cabecera `Retry-After` y reintenta. |
| `503 model_unavailable` | La red no está sirviendo el modelo ahora mismo. Cambia al modelo del texto del error o a otro de `GET /v1/models`. |
| `504 upstream_timeout` | La red no empezó a responder a tiempo. Reintenta la solicitud; para respuestas largas, activa `stream: true`. |
| `502` | Fallo del lado de la pasarela o de la red: la clave no tiene nada que ver. Reintenta más tarde; el estado de la red está en la página [Estado de la red](https://gate.joingonka.ai/es/status). |

Todos los códigos de respuesta y límites están en la sección [Errores y límites](https://gate.joingonka.ai/es/docs/errors).

## Informe

Al final, indícale al usuario:

- qué herramienta quedó configurada y qué archivo de configuración se escribió (el instalador imprime la ruta y deja una copia de la anterior al lado);
- la URL base y el identificador del modelo;
- el resultado de la comprobación: el código de respuesta y la respuesta del modelo, o por qué no se pudo comprobar;
- lo que aún debe hacer el usuario por su cuenta: por ejemplo, reiniciar la herramienta o recargar el saldo.

No incluyas la clave en el informe.

## Direcciones para máquinas

| Dirección | Qué contiene |
| --- | --- |
| [/llms.txt](https://gate.joingonka.ai/llms.txt) | Índice de documentación para modelos de lenguaje. |
| [/llms-full.txt](https://gate.joingonka.ai/llms-full.txt) | Toda la documentación en un solo archivo. |
| `/docs/<page>.md` | Versión Markdown de una página de documentación: la misma dirección con `.md` al final ([/docs/models.md](https://gate.joingonka.ai/docs/models.md)) o una petición de la página con la cabecera `Accept: text/markdown`. |
| `GET /v1/capabilities` | Capacidades y límites del gateway: el campo `limits`. |
| `GET /v1/models` | Modelos disponibles ahora mismo. |
| `GET /api/pricing` | Precios por modelo por 1M de tokens y comisiones. |
| `GET /v1/network-status` | Estado de los modelos e incidencias. |

## Habilidad para el agente

Las instrucciones se pueden instalar como habilidad (skill) para el agente: así las tendrá siempre a mano y sin necesidad de prompt:

```bash
npx skills add https://gate.joingonka.ai
```