Usar Apexnova AI Hub con OpenCode

OpenCode es un agente de programación de terminal de código abierto que puede hablar con cualquier servicio compatible con OpenAI a través del AI SDK. Añade un proveedor personalizado en opencode.json y funcionará con los modelos de la plataforma.

Usa el endpoint estándar de chat completions (/v1/chat/completions), la misma ruta que los SDK y el Playground, con idéntica autenticación, límites, descuentos y facturación.

Antes de empezar

• Una API key creada en API Keys dentro de la consola. El valor sk- completo solo se muestra una vez, guárdalo en ese momento.
• Uno o varios modelos de chat elegidos en el catálogo de modelos: anota sus Public Model Names y prefiere modelos que admitan llamadas a herramientas.
• Saldo positivo en la cuenta. Sin saldo la API devuelve HTTP 402.

1. Instalar OpenCode

Elige la vía de instalación que prefieras:

# macOS / Linux
curl -fsSL https://opencode.ai/install | bash

# or, on any platform with Node.js
npm install -g opencode-ai

opencode --version

2. Configurar opencode.json

La configuración global está en ~/.config/opencode/opencode.json; para un solo proyecto, usa opencode.json en su raíz. Añade un proveedor personalizado y apunta el modelo por defecto a él:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apexnova": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Apexnova AI Hub",
      "options": {
        "baseURL": "https://api.apexnova-consulting.com/v1",
        "apiKey": "{env:APEXNOVA_API_KEY}"
      },
      "models": {
        "glm-4.6": {
          "name": "GLM-4.6",
          "limit": { "context": 200000, "output": 65536 }
        },
        "deepseek-v4-flash": {
          "name": "DeepSeek V4 Flash"
        }
      }
    }
  },
  "model": "apexnova/glm-4.6"
}

La clave bajo provider (apexnova en el ejemplo) es el prefijo de los ids de modelo. Puedes llamarla como quieras, mientras coincida con el prefijo del campo model.

3. Poner la clave y arrancar

Exporta la clave en la variable que interpola tu configuración y ejecuta opencode en un proyecto:

# macOS / Linux
export APEXNOVA_API_KEY=sk-xxxxxxxx
cd your-project && opencode

# Windows PowerShell
$env:APEXNOVA_API_KEY = "sk-xxxxxxxx"
opencode

Dentro de OpenCode, /models cambia de modelo: la lista es exactamente lo que pusiste en models.

4. Verificar

Como siempre, llama primero con curl al endpoint de chat completions para confirmar clave y base URL:

curl https://api.apexnova-consulting.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-4.6",
    "messages": [{"role": "user", "content": "ping"}]
  }'

Después pregunta algo en OpenCode y comprueba en «Uso» de la consola que aparece la llamada con ese modelo.

Diagnóstico

• Faltan modelos en el selector —— Un proveedor personalizado no descubre el catálogo de la plataforma: solo muestra lo que hayas listado en models. Añade una entrada cada vez que empieces a usar un modelo nuevo.
• 401 —— Casi siempre la interpolación {env:…} no resolvió nada: la variable no está definida, está mal escrita o no se exportó en la shell desde la que lanzaste opencode.
• 404 model_not_found —— Las claves bajo models tienen que ser Public Model Names tal cual aparecen en la plataforma, sin prefijo de proveedor. También puede quedar fuera de la lista blanca de tu espacio de trabajo, o ser un modelo privado sin autorizar.
• 429 —— Un tope de presupuesto del espacio de trabajo o de la clave, o un límite de RPM/TPM. Ajústalo en el espacio de trabajo.
• Responde, pero no edita archivos ni usa herramientas —— Editar y ejecutar comandos requiere llamadas a herramientas (function calling). Cambia a un modelo que las admita; la ficha del modelo lo indica.

Buenas prácticas

• Dale a OpenCode su propia clave dentro de su propio espacio de trabajo, con tope de presupuesto y límites de RPM/TPM.
• El opencode.json de la raíz del proyecto suele acabar commiteado, así que accede siempre a la clave con {env:…} en vez de escribirla en claro.
• Configura una cadena de conmutación por error en «Fallback de modelos» para que un fallo del proveedor no corte la sesión. La facturación sigue al modelo que realmente respondió.