← Volver al listado de tecnologías ← Índice de OpenCode

Capitulo 15: Plugins

Por: Artiko
opencodeaipluginsextensionesecosistema

Capitulo 15: Plugins

< Volver al Indice del Tutorial

Que son los Plugins

Los plugins son extensiones que agregan funcionalidad a OpenCode mas alla de lo que permiten MCP servers, skills o comandos custom. Mientras que MCP conecta con servicios externos y los skills definen instrucciones, los plugins pueden modificar el comportamiento interno de OpenCode: agregar nuevos proveedores de modelos, definir herramientas nativas, registrar hooks y mas.

Son el mecanismo de extension mas profundo disponible.

Tipos de Plugins

Plugins npm

Paquetes publicados en el registro npm que puedes instalar y configurar:

{
  "plugins": {
    "mi-plugin": {
      "type": "npm",
      "package": "opencode-plugin-mi-extension"
    }
  }
}

OpenCode instala y carga el paquete automaticamente. El plugin debe seguir la API de plugins de OpenCode para ser reconocido.

Plugins Locales

Directorios locales con el codigo del plugin. Ideales para desarrollo y testing:

{
  "plugins": {
    "dev-plugin": {
      "type": "local",
      "path": "./mi-plugin"
    }
  }
}

El path es relativo al directorio del proyecto. OpenCode carga el plugin directamente desde el sistema de archivos sin necesidad de publicarlo en npm.

Configuracion en opencode.json

Los plugins se definen bajo la clave "plugins":

{
  "plugins": {
    "analytics": {
      "type": "npm",
      "package": "opencode-plugin-analytics"
    },
    "custom-tool": {
      "type": "local",
      "path": "./plugins/custom-tool"
    }
  }
}

Puedes combinar plugins npm y locales en la misma configuracion. Cada plugin tiene un nombre unico que lo identifica.

API de Plugins

Los plugins pueden extender OpenCode en varias dimensiones:

Agregar Tools

Un plugin puede registrar herramientas nuevas que el agente puede usar:

export default {
  name: "mi-plugin",
  tools: [
    {
      name: "analizar_dependencias",
      description: "Analiza las dependencias del proyecto y reporta vulnerabilidades",
      parameters: {
        type: "object",
        properties: {
          path: { type: "string", description: "Ruta al package.json" }
        }
      },
      execute: async ({ path }) => {
        // Logica de la herramienta
        return { resultado: "..." };
      }
    }
  ]
};

Las herramientas registradas por plugins aparecen junto a las herramientas nativas y MCP.

Agregar Providers

Los plugins pueden registrar nuevos proveedores de modelos LLM:

export default {
  name: "mi-provider",
  providers: [
    {
      id: "mi-llm",
      name: "Mi Proveedor Custom",
      models: ["modelo-v1", "modelo-v2"],
      chat: async (messages, options) => {
        // Implementacion del proveedor
      }
    }
  ]
};

Esto permite conectar OpenCode a modelos que no estan soportados nativamente.

Registrar Hooks

Los hooks permiten ejecutar logica en momentos especificos del ciclo de vida:

export default {
  name: "mi-hook-plugin",
  hooks: {
    onSessionStart: async (session) => {
      // Se ejecuta al iniciar una sesion
    },
    onMessage: async (message) => {
      // Se ejecuta con cada mensaje
    },
    onToolCall: async (tool, params) => {
      // Se ejecuta antes de cada llamada a herramienta
    }
  }
};

Los hooks son utiles para logging, analytics, validaciones y side effects.

Desarrollo de Plugins Locales

Para crear un plugin local:

Paso 1: Crear la estructura

mkdir -p plugins/mi-plugin

Paso 2: Crear el archivo principal

plugins/mi-plugin/index.ts:

export default {
  name: "mi-plugin",
  tools: [
    {
      name: "contar_lineas",
      description: "Cuenta las lineas de codigo en un directorio",
      parameters: {
        type: "object",
        properties: {
          directorio: { type: "string" }
        }
      },
      execute: async ({ directorio }) => {
        // Implementacion
        return { lineas: 0 };
      }
    }
  ]
};

Paso 3: Registrar en opencode.json

{
  "plugins": {
    "mi-plugin": {
      "type": "local",
      "path": "./plugins/mi-plugin"
    }
  }
}

Paso 4: Probar

Reinicia OpenCode y verifica que la herramienta aparece disponible. Puedes pedirle al agente que use contar_lineas para confirmar que funciona.

Ecosistema de Plugins

La comunidad de OpenCode desarrolla plugins para diversas necesidades. Al ser un proyecto open source con mas de 114K estrellas, el ecosistema crece rapidamente.

Algunas categorias comunes:

Consulta el repositorio de OpenCode en GitHub para ver plugins populares y contribuir con los tuyos.

Cuando Usar Cada Mecanismo de Extension

OpenCode ofrece multiples formas de extender su funcionalidad. Elegir la correcta depende de tu necesidad:

Plugins

MCP Servers

Custom Tools

Resumen

NecesidadMecanismo
Conectar con Sentry/Slack/GitHubMCP Server
Agregar un proveedor LLM customPlugin
Ejecutar un script y devolver resultadoCustom Tool
Logging de todas las interaccionesPlugin (hook)
Acceder a docs actualizadasMCP Server
Herramienta simple de proyectoCustom Tool

La mayoria de usuarios solo necesitaran MCP servers y custom tools. Los plugins son para casos avanzados donde se requiere modificar el comportamiento core de OpenCode.

Buenas Practicas

Siguiente: Capitulo 16: GitHub Actions y CI/CD —>

← Volver al listado de tecnologías ← Índice de OpenCode