Docs

OpenCode

OpenCode es un agente de terminal open source. Declaras Helmcode como un proveedor más y a partir de ahí puedes cambiar de modelo desde dentro del propio agente.

Configuración

Escribe esto en ~/.config/opencode/opencode.json para tenerlo en todos los proyectos, o en un opencode.json en la raíz del proyecto si solo lo quieres ahí:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "helmcode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Helmcode",
      "options": {
        "baseURL": "https://api.helmcode.com/v1",
        "apiKey": "sk-your-key-here"
      },
      "models": {
        "deepseek-v4-flash": {
          "name": "DeepSeek V4 Flash",
          "limit": { "context": 1048576, "output": 32768 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "glm5.3": {
          "name": "GLM 5.3",
          "limit": { "context": 1048576, "output": 32768 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "glm5.3-flash": {
          "name": "GLM 5.3 Flash",
          "limit": { "context": 1048576, "output": 32768 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "qwen3.6": {
          "name": "Qwen 3.6",
          "limit": { "context": 262144, "output": 32768 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "gemma4": {
          "name": "Gemma 4",
          "limit": { "context": 262144, "output": 32768 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        }
      }
    }
  },
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 50000
  }
}

Estos son los modelos de lenguaje que merece la pena declarar: deepseek-v4-flash, glm5.3, glm5.3-flash, qwen3.6 y gemma4. Los cinco aceptan imágenes y los cinco hacen tool calling. Los modelos de embeddings, reranking y voz no los usa el agente, así que no van aquí.

@ai-sdk/openai-compatible es el adaptador genérico, el que habla con cualquier API con forma de OpenAI. No uses @ai-sdk/openai a secas: ese espera la API real de OpenAI.

De todo lo que va dentro de cada modelo, lo único obligatorio es su clave, que es el id. name, limit y modalities son opcionales: sin ellos OpenCode funciona igual, solo que ves el id pelado en el selector y la compactación automática corre con sus propios valores por defecto.

Dónde poner la key

En el ejemplo de arriba la key está escrita dentro del fichero, que es lo más directo pero no lo más cómodo si ese fichero acaba en un repositorio.

La alternativa es dejar apiKey fuera del opencode.json y guardarla con el comando /connect de OpenCode, que la escribe en su propio almacén de credenciales:

/connect

Te pedirá un Provider id. Escribe exactamente:

helmcode

Aviso: el Provider id tiene que coincidir con la clave del JSON. OpenCode empareja la credencial con el proveedor por ese identificador. Si tu proveedor se llama helmcode en opencode.json y escribes Helmcode o cualquier otra cosa en /connect, OpenCode guarda la credencial pero no la asocia a ningún proveedor, y las peticiones salen sin key. Es el fallo más común al conectar OpenCode, y nada en el error lo explica.

Después pega tu API key y pulsa Enter.

Los límites de contexto

"limit": { "context": 1048576, "output": 32768 }

limit.context y limit.output son los campos que lee OpenCode — no contextWindow, que no forma parte del esquema de OpenCode: una clave desconocida no levanta nada que nadie vea, OpenCode se cae a su propia suposición sobre la ventana, y el síntoma es una sesión que compacta demasiado pronto en los modelos de contexto largo.

limit.context es la ventana publicada en Modelos: 1M para deepseek-v4-flash, glm5.3 y glm5.3-flash, 256K para qwen3.6 y gemma4. limit.output es un presupuesto del cliente, no un tope del servidor, así que súbelo si necesitas respuestas más largas.

El bloque de compactación

"compaction": { "auto": true, "prune": true, "reserved": 50000 }

OpenCode resume la conversación por su cuenta cuando se acerca al límite de contexto, y reserved es el margen de tokens que se guarda para hacerlo. Con ventanas de un millón de tokens no vas a tocar el límite en una sesión normal, pero dejarlo activo evita que una sesión muy larga se corte de golpe.

Comprueba que funciona

opencode

Dentro del agente, elige el modelo con /models y pídele algo corto. Si responde, ya está saliendo por Helmcode.

Modelo recomendado

glm5.3-flash para código y para todo lo agéntico — ventana de 1M, dentro de la cuota de todos los planes. deepseek-v4-flash es el otro modelo de ese tamaño. qwen3.6 cuando la tarea está acotada y quieres la respuesta ya.

Problemas conocidos

  • La key queda escrita en el fichero. Si mantienes el opencode.json dentro del repositorio, la key se va con él. Tenlo en el fichero de tu directorio home, usa /connect, o añade el fichero al .gitignore.
  • No subas las ventanas a mano. Son las que acepta la API; por encima de ellas, OpenCode llena la conversación hasta un punto en el que las peticiones empiezan a ser rechazadas.