Documentación

opencode

opencode crea sus proveedores sobre Vercel AI SDK, así que para apuntarlo a un endpoint nuevo basta con un bloque que indique un paquete npm y un baseURL. El paquete que se indique determina cuál de los dos formatos de protocolo usará.

Un bloque de proveedor en opencode.json — @ai-sdk/openai-compatible para completaciones de chat, @ai-sdk/openai cuando quieras la superficie /v1/responses.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kunavo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kunavo",
      "options": {
        "baseURL": "https://api.kunavo.com/v1",
        "apiKey": "{env:KUNAVO_API_KEY}"
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "limit": { "context": 200000, "output": 64000 }
        },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5" }
      }
    }
  }
}

El campo npm determina el formato de protocolo. @ai-sdk/openai-compatible usa /v1/chat/completions; @ai-sdk/openai usa /v1/responses. Kunavo ofrece ambos, así que cualquiera sirve. Use el paquete de Responses si quiere que los elementos de razonamiento se conserven al procesar la familia GPT, y el paquete de chat completions para todo lo demás.

"apiKey": "{env:KUNAVO_API_KEY}" lee la clave del entorno al cargar la configuración. opencode.json es un archivo que acaba en repositorios; una clave literal en él no permanece secreta.

Defina limit.context y limit.output para cada modelo. opencode contabiliza el contexto restante con esos valores, así que, si no los especifica para un modelo, lo calcula según un valor predeterminado que no corresponde a ese modelo.

¿Aún no tienes una clave? Crea una cuenta de Kunavo, genera una clave (empieza por sk-kn-) y añade crédito desde $10; las llamadas se pagan con ese saldo y las llamadas fallidas no se facturan. El panel se abre entonces en la configuración de opencode.

Paso a paso

Cree una clave en /app/keys y cópiela: se muestra una sola vez.
Expórtela: export KUNAVO_API_KEY=sk-kn-...
Añada el bloque de proveedor a opencode.json: al archivo global en ~/.config/opencode/opencode.json para todos los proyectos, o al archivo de la raíz del proyecto para aplicarlo solo a este repositorio.
Inicie opencode y elija el modelo de la lista; el proveedor aparecerá bajo el name que haya indicado.
Para añadir otro modelo más adelante, agregue otra clave en models: el identificador es lo que se envía por el protocolo; name es solo una etiqueta.

Comprobado con documentación de proveedores de opencode el 6 de septiembre de 2026. La configuración de terceros puede cambiar; si el nombre de un campo ya no coincide con lo que ves, esa página es la autoridad, no esta.

Verifica antes de depurar el cliente

Una solicitud determina si el fallo está en el endpoint, la clave o el archivo de configuración. Si devuelve JSON, la misma URL base y la misma clave funcionan en opencode.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Qué ID de modelo introducir en el campo

Todos los modelos de texto están disponibles mediante un ID de modelo; la lista activa está en GET /v1/models, y el catálogo con precios está en la página de modelos. Las tarifas son USD por 1M de tokens, entrada / salida.

ID de modelo	Entrada / salida de Kunavo	Dónde encaja en opencode
`claude-sonnet-5`	$1.40 / $7.00	el modelo de compilación predeterminado
`claude-opus-5`	$3.50 / $17.50	modo de planificación, donde todo lo que viene después depende del plan
`claude-haiku-4-5`	$0.70 / $3.50	trabajo de subagentes y búsquedas, donde la cantidad de solicitudes es elevada
`gpt-5-6-sol`	$2.00 / $12.00	úselo con @ai-sdk/openai para que los elementos de razonamiento se conserven durante el intercambio

La facturación es por token desde un saldo prepago, sin cuota mensual; consulta facturación. Con contexto repetido —que constituye la mayor parte de lo que envía un editor o cliente de chat—, la caché de indicaciones cambia más la factura que la elección del modelo.

Preguntas frecuentes

¿Cómo añado un proveedor personalizado a opencode?

Añada un bloque en «provider» en opencode.json e indique un paquete npm, un nombre para mostrar, options.baseURL, options.apiKey y un mapa models. Use @ai-sdk/openai-compatible para un endpoint que ofrezca /v1/chat/completions y @ai-sdk/openai para uno que ofrezca /v1/responses. El proveedor aparecerá en la lista de modelos de opencode con el nombre que le haya asignado.

¿Cómo puedo evitar que la clave API aparezca en opencode.json?

Use la sintaxis de interpolación {env:VAR_NAME} en options.apiKey; por ejemplo, "apiKey": "{env:KUNAVO_API_KEY}", y exporte la variable en el shell. opencode la resuelve al cargar la configuración, por lo que el archivo se puede guardar en el repositorio junto con el proyecto que configura sin exponer la clave.

¿Cuál es la diferencia entre @ai-sdk/openai y @ai-sdk/openai-compatible en opencode?

Seleccionan endpoints distintos en la misma URL base. @ai-sdk/openai-compatible llama a /chat/completions, que implementan casi todas las pasarelas; @ai-sdk/openai llama a /responses, la interfaz más reciente de OpenAI. Elija el paquete que ofrece su endpoint: si usa el paquete equivocado, la URL base será correcta, pero obtendrá un error 404.

¿Por qué opencode se queda sin contexto antes de lo esperado?

Porque la entrada del modelo no tiene un bloque limit, así que opencode calcula el presupuesto según un valor predeterminado en vez de usar la ventana real del modelo. Añada "limit": { "context": <window>, "output": <max output> } al modelo correspondiente en opencode.json, usando las cifras del catálogo del proveedor, y los indicadores de contexto y los puntos de compactación reflejarán los valores reales.