Puntos clave
- Verifica el endpoint con curl antes de tocar OpenCode, para saber si un fallo es de la configuración o de la API.
- Un proveedor personalizado necesita tres cosas: URL base, clave de API y un ID de modelo, que es uncensored aquí.
- Establece el límite de contexto en 100,000 tokens para que el agente planifique alrededor de la ventana real.
- El streaming y las llamadas a funciones son compatibles, lo que necesita un bucle de agente.
Lo que necesitas antes de comenzar
OpenCode es un agente de código de código abierto que se ejecuta en tu terminal. Puede hablar con muchos proveedores de modelos, y te permite agregar tu propio proveedor si el endpoint sigue el formato de chat de OpenAI. Esta API lo hace, por lo que la configuración es cuestión de completar algunos campos.
Reúne estos tres valores primero:
- URL base:
https://api.kimicode.top/v1 - ID de modelo:
uncensored - Clave de API: crea una en la página de clave de API. Las cuentas nuevas pueden reclamar un crédito de prueba de $0.50 con un clic, suficiente para las pruebas de abajo. La clave de prueba permite 2 peticiones simultáneas y 60 peticiones por minuto.
Mantén la clave en una variable de entorno en lugar de pegarla en archivos que subas:
export KIMICODE_API_KEY="your-key-here"Paso 1: prueba el endpoint con curl
Haz esto antes de configurar cualquier herramienta. Si curl funciona y OpenCode no, sabes que el problema está en la configuración. Si curl falla, corriges la clave o la URL una vez, no en dos lugares.
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "Say hello in five words."}],
"max_tokens": 40
}'Deberías obtener un objeto JSON con una matriz choices y un bloque usage. Un 401 significa que la clave es incorrecta o le falta el prefijo Bearer. Un 404 suele significar que la URL tiene un error de escritura o ya incluye /chat/completions.
Un agente de código transmite sus respuestas y llama a herramientas, así que verifica esos dos también:
curl -N https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"stream": true,
"messages": [{"role": "user", "content": "Count from one to five."}]
}'Deberías ver una serie de líneas data:, cada una con un pequeño delta JSON, finalizando con las cifras de uso y un marcador final. La bandera -N desactiva el buffering de curl para que los fragmentos aparezcan al llegar.
Paso 2: agrega un proveedor personalizado a OpenCode
OpenCode lee un archivo de configuración JSON, opencode.json, desde tu carpeta de proyecto o su directorio de configuración global. Los proveedores compatibles con OpenAI se declaran con el paquete compatible con OpenAI del SDK de IA, una URL base y una lista de modelos. La estructura de abajo sigue la documentación pública de OpenCode al momento de escribir. Los nombres de campos pueden cambiar entre versiones, así que compáralo con la sección de proveedores de la documentación actual de OpenCode si algo se rechaza.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"kimicode": {
"npm": "@ai-sdk/openai-compatible",
"name": "Kimicode API",
"options": {
"baseURL": "https://api.kimicode.top/v1",
"apiKey": "{env:KIMICODE_API_KEY}"
},
"models": {
"uncensored": {
"name": "Uncensored",
"limit": {
"context": 100000,
"output": 8192
}
}
}
}
},
"model": "kimicode/uncensored"
}La clave bajo models es el ID exacto del modelo enviado al servidor, así que debe leerse uncensored. La última línea selecciona el proveedor y el modelo como predeterminado, escrito como nombre del proveedor, una barra y luego el ID del modelo.
La forma {env:KIMICODE_API_KEY} le dice a OpenCode que lea la variable desde tu shell. Si tu versión maneja credenciales a través de su propio comando de inicio de sesión, usa esa ruta y deja la clave fuera del archivo. En cualquier caso, no subas una clave real.
Configuración del proyecto o configuración global
Puedes mantener el bloque del proveedor en dos lugares. Un archivo en la raíz del proyecto se aplica solo a ese repositorio, lo cual se adapta a un equipo que comparte una configuración. Un archivo en tu directorio de configuración de usuario se aplica en todas partes, lo cual se adapta a un predeterminado personal. Donde ambos existen, el archivo del proyecto se suma o anula el global.
Prefiere el archivo global para la definición del proveedor y la variable de entorno para la clave. Así, cada repositorio puede usar el endpoint, y nada secreto queda junto a tu código fuente. Si varias personas trabajan en un proyecto, sube solo el bloque del proveedor sin una clave, y haz que cada persona configure su propia variable. Esto también hace simple rotar una clave: cambia la variable, reinicia la terminal, y el archivo de configuración permanece intacto.
Paso 3: selecciona el modelo y ejecuta una tarea
Inicia OpenCode en una carpeta de proyecto y abre su selector de modelos. Tu proveedor personalizado debería aparecer en la lista con el nombre de visualización que configuraste. Selecciónalo, luego dale al agente una tarea pequeña y verificable como explicar una función o escribir una prueba unitaria para un archivo corto.
Empieza pequeño por dos razones. Primero, puedes ver si las llamadas a herramientas funcionan: cuando OpenCode le pide al modelo que lea o edite un archivo, lo hace a través de la interfaz de llamadas a herramientas. Segundo, un agente de código envía mucho texto por turno, incluyendo contenidos de archivos e historial, así que una sesión larga consume tokens rápidamente. La siguiente sección pone números a eso.
Si el modelo no aparece, verifica que el archivo sea JSON válido, que esté donde OpenCode busca la configuración y que el nombre del proveedor coincida con lo que escribiste en el campo model.
Prueba de llamadas a funciones y modo JSON directamente
OpenCode depende de las llamadas a herramientas para leer archivos, ejecutar comandos y editar código, así que vale la pena confirmar que el endpoint maneja una definición de herramienta antes de culpar al agente por un fallo. Esta petición ofrece una herramienta y hace una pregunta que la necesita.
curl https://api.kimicode.top/v1/chat/completions \
-H "Authorization: Bearer $KIMICODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
"tools": [{
"type": "function",
"function": {
"name": "read_file",
"description": "Read a text file by path",
"parameters": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"]
}
}
}],
"tool_choice": "auto"
}'Una buena respuesta contiene una entrada tool_calls que nombra read_file con una cadena de argumentos JSON. El agente ejecuta la herramienta y luego envía el resultado como un mensaje con role establecido en tool, y el modelo continúa desde allí. Si solo ves texto plano, intenta un prompt más directo, ya sea que el modelo decida llamar a una herramienta es parte de su comportamiento.
El modo JSON es un interruptor separado. Agregar "response_format": {"type": "json_object"} solicita salida JSON válida, y ayuda cuando otro script debe analizar lo que regresa. Menciona JSON en tu prompt también, para que el modelo sepa qué forma esperas.
Tamaño del contexto y costo de una sesión
La ventana de contexto es de 100,000 tokens, contando el prompt y la finalización juntos. Establecer limit.context en 100000 permite al agente conocer el límite real, para que pueda recortar o resumir el historial antes de que el servidor tenga que rechazar una petición. Una finalización puede usar cualquier espacio que quede, y max_tokens es opcional.
La facturación es $0.15 por cada 1M de tokens de entrada y $0.50 por cada 1M de tokens de salida. Los agentes son pesados en entrada, porque cada turno reenvía la conversación. Aquí hay un ejemplo trabajado para una sesión moderada:
- 40 turnos, cada uno enviando unos 30,000 tokens de entrada: 1,200,000 tokens de entrada, que es 1.2 x $0.15 = $0.18.
- Cada turno devuelve unos 800 tokens de salida: 32,000 tokens de salida, que es 0.032 x $0.50 = $0.016.
- Total: $0.196, así que unos veinte centavos por toda la sesión.
Tus números serán distintos. Lee los valores usage en las respuestas, o observa la cabecera X-Balance-USD, que informa tu saldo restante en cada respuesta. El crédito es prepago y nunca expira, y las peticiones fallidas o rechazadas no se cobran. Los detalles están en la página de precios.
Expectativas honestas para un agente de código
Este es un modelo de texto general ajustado para responder sin rechazos de contenido para uso adulto legal. No es un modelo construido específicamente para código, y esta página no hace afirmaciones de benchmark. Si edita tu repositorio de manera confiable es algo que debes probar en tus propias tareas, con control de versiones activado, antes de entregarle algo importante.
Maneja la infraestructura que necesita un agente: llamadas a herramientas con tool_calls en streaming, resultados de herramientas enviados como mensajes role: "tool", y modo JSON a través de response_format. Es solo texto, sin imágenes, así que las funciones que adjuntan capturas de pantalla no funcionarán.
Dos límites importan para agentes. Una clave completa permite 8 peticiones concurrentes y 300 peticiones por minuto. Los sub-agentes o ejecuciones paralelas de herramientas que disparan muchas llamadas a la vez pueden alcanzar el límite de concurrencia, y una petición en streaming mantiene su espacio hasta que termine el stream. Cuando eso ocurre, obtienes HTTP 429 con el código concurrency. El código rate_limited significa demasiadas peticiones por minuto. En sobrecarga temporal también puedes ver un 429 con Retry-After: 5. Reduce la paralelización o espera y reintenta.
Solución de problemas
| Síntoma | Causa probable | Solución |
|---|---|---|
| 401 No autorizado | Clave vacía o incorrecta; la variable de entorno no está configurada en el shell que lanzó OpenCode | Ejecuta echo $KIMICODE_API_KEY en la misma terminal, luego reinicia OpenCode |
| 404 No encontrado | La URL base incluye /chat/completions o carece de /v1 | Usa exactamente https://api.kimicode.top/v1 |
| Modelo no encontrado | La clave del modelo difiere de uncensored | Empareja la clave en models con el ID devuelto por GET /v1/models |
429 con concurrency | Demasiadas peticiones a la vez | Reduce las llamadas a herramientas en paralelo o espera a que finalicen los streams |
| Petición demasiado grande | Cuerpo superior a 8 MB o historial cerca del límite de la ventana de contexto | Inicia una sesión nueva o resume el historial |
Para cualquier tema no cubierto aquí, la página de documentación contiene la referencia completa de la petición, y la guía de integración aborda el mismo endpoint desde la perspectiva de otros clientes compatibles con OpenAI.
