Something went wrong. Try again.
opencode v2 mirror
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386---title: Complementosdescription: Escriba sus propios complementos para extender OpenCode.---
Los complementos le permiten extender OpenCode al conectarse a varios eventos y personalizar el comportamiento. Puede crear complementos para agregar nuevas funciones, integrarlos con servicios externos o modificar el comportamiento predeterminado de OpenCode.
Para ver ejemplos, consulte los [complementos](/docs/ecosystem#plugins) creados por la comunidad.
---
## Usar un complemento
Hay dos formas de cargar complementos.
---
### Desde archivos locales
Coloque los archivos JavaScript o TypeScript en el directorio del complemento.
- `.opencode/plugins/` - Complementos a nivel de proyecto- `~/.config/opencode/plugins/` - Complementos globales
Los archivos en estos directorios se cargan automáticamente al inicio.
---
### Desde npm
Especifique paquetes npm en su archivo de configuración.
```json title="opencode.json"{ "$schema": "https://opencode.ai/config.json", "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]}```
Se admiten paquetes npm regulares y de alcance.
Explore los complementos disponibles en el [ecosistema](/docs/ecosystem#plugins).
---
### Cómo se instalan los complementos
Los **complementos npm** se instalan automáticamente usando Bun al inicio. Los paquetes y sus dependencias se almacenan en caché en `~/.cache/opencode/node_modules/`.
**Los complementos locales** se cargan directamente desde el directorio de complementos. Para usar paquetes externos, debe crear un `package.json` dentro de su directorio de configuración (consulte [Dependencias](#dependencies)), o publicar el complemento en npm y [agregarlo a su configuración](/docs/config#plugins).
---
### Orden de carga
Los complementos se cargan desde todas las fuentes y todos los enlaces se ejecutan en secuencia. El orden de carga es:
1. Configuración global (`~/.config/opencode/opencode.json`)2. Configuración del proyecto (`opencode.json`)3. Directorio global de complementos (`~/.config/opencode/plugins/`)4. Directorio de complementos del proyecto (`.opencode/plugins/`)
Los paquetes npm duplicados con el mismo nombre y versión se cargan una vez. Sin embargo, un complemento local y un complemento npm con nombres similares se cargan por separado.
---
## Crear un complemento
Un complemento es un módulo **JavaScript/TypeScript** que exporta uno o más complementos.funciones. Cada función recibe un objeto de contexto y devuelve un objeto de enlace.
---
### Dependencias
Los complementos locales y las herramientas personalizadas pueden utilizar paquetes npm externos. Agregue un `package.json` a su directorio de configuración con las dependencias que necesita.
```json title=".opencode/package.json"{ "dependencies": { "shescape": "^2.1.0" }}```
OpenCode ejecuta `bun install` al inicio para instalarlos. Luego, sus complementos y herramientas pueden importarlos.
```ts title=".opencode/plugins/my-plugin.ts"import { escape } from "shescape"
export const MyPlugin = async (ctx) => { return { "tool.execute.before": async (input, output) => { if (input.tool === "bash") { output.args.command = escape(output.args.command) } }, }}```
---
### Estructura básica
```js title=".opencode/plugins/example.js"export const MyPlugin = async ({ project, client, $, directory, worktree }) => { console.log("Plugin initialized!")
return { // Hook implementations go here }}```
La función del complemento recibe:
- `project`: La información actual del proyecto.- `directory`: El directorio de trabajo actual.- `worktree`: La ruta del árbol de trabajo de git.- `client`: Un cliente SDK opencode para interactuar con la IA.- `$`: [shell API](https://bun.com/docs/runtime/shell) de Bun para ejecutar comandos.
---
### Soporte TypeScript
Para los complementos TypeScript, puede importar tipos desde el paquete de complementos:
```ts title="my-plugin.ts" {1}import type { Plugin } from "@opencode-ai/plugin"
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => { return { // Type-safe hook implementations }}```
---
### Eventos
Los complementos pueden suscribirse a eventos como se ve a continuación en la sección Ejemplos. Aquí hay una lista de los diferentes eventos disponibles.
#### Eventos de comando
- `command.executed`
#### Eventos de archivo
- `file.edited`- `file.watcher.updated`
#### Eventos de instalación
- `installation.updated`
#### Eventos LSP
- `lsp.client.diagnostics`- `lsp.updated`
#### Eventos de mensajes
- `message.part.removed`- `message.part.updated`- `message.removed`- `message.updated`
#### Eventos de permiso
- `permission.asked`- `permission.replied`
#### Eventos del servidor
- `server.connected`
#### Eventos de sesión
- `session.created`- `session.compacted`- `session.deleted`- `session.diff`- `session.error`- `session.idle`- `session.status`- `session.updated`
#### Eventos de Shell
- `shell.env`
#### Eventos de herramientas
- `tool.execute.after`- `tool.execute.before`
#### Eventos TUI
- `tui.prompt.append`- `tui.command.execute`- `tui.toast.show`
---
## Ejemplos
A continuación se muestran algunos ejemplos de complementos que puede utilizar para ampliar opencode.
---
### Enviar notificaciones
Enviar notificaciones cuando ocurran ciertos eventos:
```js title=".opencode/plugins/notification.js"export const NotificationPlugin = async ({ project, client, $, directory, worktree }) => { return { event: async ({ event }) => { // Send notification on session completion if (event.type === "session.idle") { await $`osascript -e 'display notification "Session completed!" with title "opencode"'` } }, }}```
Estamos usando `osascript` para ejecutar AppleScript en macOS. Aquí lo estamos usando para enviar notificaciones.
:::noteSi está utilizando la aplicación de escritorio OpenCode, puede enviar notificaciones del sistema automáticamente cuando una respuesta esté lista o cuando se produzca un error en una sesión.:::
---
### Protección .env
Evite que opencode lea archivos `.env`:
```javascript title=".opencode/plugins/env-protection.js"export const EnvProtection = async ({ project, client, $, directory, worktree }) => { return { "tool.execute.before": async (input, output) => { if (input.tool === "read" && output.args.filePath.includes(".env")) { throw new Error("Do not read .env files") } }, }}```
---
### Inyectar variables de entorno
Inyecte variables de entorno en toda la ejecución del shell (herramientas de inteligencia artificial y terminales de usuario):
```javascript title=".opencode/plugins/inject-env.js"export const InjectEnvPlugin = async () => { return { "shell.env": async (input, output) => { output.env.MY_API_KEY = "secret" output.env.PROJECT_ROOT = input.cwd }, }}```
---
### Herramientas personalizadas
Los complementos también pueden agregar herramientas personalizadas a opencode:
```ts title=".opencode/plugins/custom-tools.ts"import { type Plugin, tool } from "@opencode-ai/plugin"
export const CustomToolsPlugin: Plugin = async (ctx) => { return { tool: { mytool: tool({ description: "This is a custom tool", args: { foo: tool.schema.string(), }, async execute(args, context) { const { directory, worktree } = context return `Hello ${args.foo} from ${directory} (worktree: ${worktree})` }, }), }, }}```
El ayudante `tool` crea una herramienta personalizada a la que opencode puede llamar. Toma una función de esquema Zod y devuelve una definición de herramienta con:
- `description`: Qué hace la herramienta- `args`: Esquema Zod para los argumentos de la herramienta.- `execute`: Función que se ejecuta cuando se llama a la herramienta
Sus herramientas personalizadas estarán disponibles para opencode junto con las herramientas integradas.
:::noteSi una herramienta de complemento utiliza el mismo nombre que una herramienta integrada, la herramienta de complemento tiene prioridad.:::
---
### Registro
Utilice `client.app.log()` en lugar de `console.log` para el registro estructurado:
```ts title=".opencode/plugins/my-plugin.ts"export const MyPlugin = async ({ client }) => { await client.app.log({ body: { service: "my-plugin", level: "info", message: "Plugin initialized", extra: { foo: "bar" }, }, })}```
Niveles: `debug`, `info`, `warn`, `error`. Consulte la [documentación del SDK](https://opencode.ai/docs/sdk) para obtener más detalles.
---
### Hooks de compactación
Personalice el contexto incluido cuando se compacta una sesión:
```ts title=".opencode/plugins/compaction.ts"import type { Plugin } from "@opencode-ai/plugin"
export const CompactionPlugin: Plugin = async (ctx) => { return { "experimental.session.compacting": async (input, output) => { // Inject additional context into the compaction prompt output.context.push(`## Custom Context
Include any state that should persist across compaction:- Current task status- Important decisions made- Files being actively worked on`) }, }}```
El hook `experimental.session.compacting` se activa antes de que LLM genere un resumen de continuación. Úselo para inyectar contexto específico del dominio que el mensaje de compactación predeterminado omitiría.
También puede reemplazar completamente el mensaje de compactación configurando `output.prompt`:
```ts title=".opencode/plugins/custom-compaction.ts"import type { Plugin } from "@opencode-ai/plugin"
export const CustomCompactionPlugin: Plugin = async (ctx) => { return { "experimental.session.compacting": async (input, output) => { // Replace the entire compaction prompt output.prompt = `You are generating a continuation prompt for a multi-agent swarm session.
Summarize:1. The current task and its status2. Which files are being modified and by whom3. Any blockers or dependencies between agents4. The next steps to complete the work
Format as a structured prompt that a new agent can use to resume work.` }, }}```
Cuando se configura `output.prompt`, reemplaza completamente el mensaje de compactación predeterminado. En este caso, se ignora la matriz `output.context`.