Runbook: Configurar OpenAI Y OpenCode

Este runbook explica como dejar OPS listo para ejecutar tareas automaticas con OpenCode y modelos de OpenAI u otros proveedores compatibles.

Decision Rapida

Para automatismos de OPS, la opcion preferente es:

OpenAI Platform con billing activo.
API key de proyecto.
Credencial de workspace guardada en OPS para opencode/openai.
Worker anunciando opencode.

ChatGPT Plus/Pro sirve para usar OpenCode con autenticacion de usuario en el host, pero no sustituye por si solo una API key de OpenAI Platform para integraciones de servidor. Usarlo en un VPS compartido o futuro SaaS multitenant debe ser una decision explicita.

OpenCode Zen, OpenCode Go, OpenRouter, Minimax, Ollama, LM Studio u otros proveedores son opciones validas si se configuran como proveedor real. No deben ocultarse detras de aliases a OpenAI.

Fuentes Externas

OpenAI API: autenticacion por API key y facturacion por uso en Platform: https://platform.openai.com/docs/api-reference y https://platform.openai.com/docs/pricing
OpenCode Providers: /connect, API keys, ChatGPT Plus/Pro, OpenCode Zen/Go y proveedores custom: https://opencode.ai/docs/providers/
OpenCode Models: seleccion de modelos y variantes de razonamiento: https://opencode.ai/docs/models/

Antes de comprar o cambiar plan, revisar precios vigentes en la web del proveedor.

Paso 1: Elegir Que Comprar

OpenAI Platform API

Comprar o activar billing de OpenAI Platform si el objetivo es que OPS ejecute tareas automaticas de servidor.

Checklist:

acceder a OpenAI Platform;
crear o seleccionar proyecto;
activar billing/creditos;
crear una API key de proyecto;
guardar la clave una sola vez en OPS;
no pegar la clave en comentarios de tareas ni en prompts.

ChatGPT Plus/Pro Con OpenCode

Puede usarse cuando el worker es personal o interno y se acepta una sesion local de usuario.

Checklist:

ejecutar OpenCode en el host del worker;
usar /connect;
seleccionar OpenAI;
elegir ChatGPT Plus/Pro;
completar login en navegador;
ejecutar /models para verificar modelos disponibles.

Riesgo operativo: la sesion vive en el host y puede caducar. Si caduca, OPS debe mostrarlo como auth bloqueada, no caer a Hermes ni cambiar proveedor.

OpenCode Zen/Go U Otro Proveedor

Puede tener sentido si ofrece modelos, coste o fiabilidad mejores para coding.

Checklist:

crear API key en el proveedor;
conectarlo con /connect o configurar opencode.json;
registrar en OPS el provider_slug real;
usar metadata.env_var o env_bundle si el proveedor necesita una variable concreta;
probar con una tarea pequena antes de mover plantillas recurrentes.

Paso 2: Crear La Credencial En OPS

En OPS:

Abrir Credenciales.
Crear credencial:

- agente: opencode

- provider: openai

- etiqueta: OpenAI Platform - OPS

- tipo: api_key

- scope: workspace

- usage: agent

- secreto: API key de OpenAI Platform

Guardar.
Verificar que aparece activa y con preview/fingerprint, no con el secreto completo.

OPS inyectara esta clave como OPENAI_API_KEY solo durante la ejecucion de la tarea.

Para Minimax:

agente: opencode
provider: minimax
tipo: api_key
scope: workspace
usage: agent
metadata/env opcional: MINIMAX_API_KEY

OPS inyectara MINIMAX_API_KEY.

Para OpenCode Go:

agente: opencode
provider: opencode
tipo: api_key
scope: workspace
usage: agent
metadata/env opcional: OPENCODE_API_KEY

OPS inyectara OPENCODE_API_KEY.

Para un proveedor custom:

usar metadata.env_var si solo hace falta una variable;
usar env_bundle si hacen falta varias variables;
si el worker debe considerar esa variable como auth valida, anadir su nombre a OPENCODE_AUTH_ENV_KEYS.

Ejemplo de env_bundle:


MY_PROVIDER_API_KEY=...

MY_PROVIDER_BASE_URL=https://api.example.com/v1

Paso 3: Configurar OpenCode En El Worker

Para usar API key de workspace no hace falta guardar la clave en ~/.local/share/opencode/auth.json; OPS la inyecta al lanzar la tarea.

El binario opencode debe existir en el worker.

Si se usa proveedor custom, crear opencode.json con el proveedor y modelo reales. No usar un alias que cambie de proveedor sin dejar rastro.

Ejemplo MiniMax validado en OPS:


{

  "$schema": "https://opencode.ai/config.json",

  "provider": {

    "minimax": {

      "npm": "@ai-sdk/openai-compatible",

      "name": "MiniMax",

      "options": {

        "baseURL": "https://api.minimax.io/v1",

        "apiKey": "{env:MINIMAX_API_KEY}"

      },

      "models": {

        "MiniMax-M2.7": {

          "name": "MiniMax M2.7"

        }

      }

    }

  }

}

Nota: OpenCode conserva mayusculas en IDs de modelo. Usar minimax/MiniMax-M2.7, no minimax/minimax-m2.7.

Paso 4: Activar El Worker Para OpenCode

En el host del worker, ajustar el override del servicio:


Environment="SUPPORTED_AGENT_SLUGS=opencode,hermes"

Environment="ALLOW_TASK_SCOPED_CREDENTIAL_AUTH=true"

Si se usa una variable custom para considerar OpenCode autenticado:


Environment="OPENCODE_AUTH_ENV_KEYS=MY_PROVIDER_API_KEY"

Configuracion interna validada:


Environment=SUPPORTED_AGENT_SLUGS=opencode,hermes

Environment=ALLOW_TASK_SCOPED_CREDENTIAL_AUTH=true

Environment=OPENCODE_AUTH_ENV_KEYS=OPENCODE_API_KEY,MINIMAX_API_KEY,OPENAI_API_KEY,ANTHROPIC_API_KEY,OPENROUTER_API_KEY,GOOGLE_API_KEY,GEMINI_API_KEY,XAI_API_KEY

Reiniciar:


sudo systemctl daemon-reload

sudo systemctl restart ops-dispatch-launcher.service

Paso 5: Probar

Revisar health de dispatch.
Ejecutar doctor con el mismo entorno del servicio.
Crear una tarea pequena con:

- execution: interactive o auto

- agent: opencode

- model: openai/gpt-5.4-mini o el modelo real elegido

Usar Dispatch now.
Confirmar que la salida muestra:

- runtime=opencode

- credential_env=OPENAI_API_KEY o la variable esperada

- sin fallback silencioso a Hermes.

Smoke tests validados el 2026-05-06:

OpenCode Go: opencode/gpt-5-nano -> OPENCODE_GO_OK.
MiniMax token plan: minimax/MiniMax-M2.7 -> MINIMAX_OK.

No usar MiniMax a traves de OpenCode Go si existe un plan MiniMax separado; usa minimax/MiniMax-M2.7 con MINIMAX_API_KEY.

Criterio De Aceptacion

La configuracion queda lista cuando:

OpenCode aparece como worker compatible;
existe una credencial de workspace activa;
una tarea pequena pasa a review;
el contexto de la tarea registra runtime=opencode;
la salida del launcher registra runtime_version, runtime_model y runtime_provider;
dispatch/health muestra opencode como ready=true y mode=task_scoped cuando se usan credenciales OPS;
las plantillas recurrentes usan agente/modelo/proveedor explicitos.

Si Algo Falla

Si local_reason muestra oauth expired, revisar que mode=task_scoped, task_scoped_worker_ready=true y que existan credential_env_keys.
Si opencode aparece en blockers, falta una de estas piezas: worker fresco con opencode, ALLOW_TASK_SCOPED_CREDENTIAL_AUTH=true, credencial activa de workspace o auth local/global valida.
Si aparece model not found, revisar que el modelo existe para ese proveedor.
Si aparece ProviderModelNotFoundError y sugiere el mismo modelo con mayusculas, conservar el casing exacto en model.
Si no reclama tareas, revisar SUPPORTED_AGENT_SLUGS.
Si reclama pero falla auth, revisar credencial, provider_slug, metadata.env_var y OPENCODE_AUTH_ENV_KEYS.
Si se quiere usar Hermes, configurarlo explicitamente en tarea/plantilla/perfil. No usarlo como fallback silencioso.