Плагины

Плагины позволяют расширять opencode, подключаясь к различным событиям и настраивая поведение. Вы можете создавать плагины для добавления новых функций, интеграции с внешними сервисами или изменения поведения opencode по умолчанию.

Для примера ознакомьтесь с plugins, созданными сообществом.

Есть два способа загрузки плагинов.

Поместите файлы JavaScript или TypeScript в каталог плагина.

.opencode/plugins/ – плагины уровня проекта.
~/.config/opencode/plugins/ — глобальные плагины

Файлы в этих каталогах автоматически загружаются при запуске.

Укажите пакеты npm в файле конфигурации.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "opencode-wakatime", "@my-org/custom-plugin"]
}

Поддерживаются как обычные, так и ограниченные пакеты npm.

Просмотрите доступные плагины в папке ecosystem.

Плагины npm устанавливаются автоматически с помощью Bun при запуске. Пакеты и их зависимости кэшируются в ~/.cache/opencode/node_modules/.

Локальные плагины загружаются непосредственно из каталога плагинов. Чтобы использовать внешние пакеты, вы должны создать package.json в своем каталоге конфигурации (см. Зависимости) или опубликовать плагин в npm и добавить его в свой config.

Плагины загружаются из всех источников, и все хуки запускаются последовательно. Порядок загрузки следующий:

Глобальная конфигурация (~/.config/opencode/opencode.json)
Конфигурация проекта (opencode.json)
Глобальный каталог плагинов (~/.config/opencode/plugins/)
Каталог плагинов проекта (.opencode/plugins/)

Дубликаты пакетов npm с тем же именем и версией загружаются один раз. Однако локальный плагин и плагин npm со схожими именами загружаются отдельно.

Плагин — это модуль JavaScript/TypeScript, который экспортирует один или несколько плагинов. функции. Каждая функция получает объект контекста и возвращает объект перехватчика.

Локальные плагины и специальные инструменты могут использовать внешние пакеты npm. Добавьте package.json в каталог конфигурации с необходимыми вам зависимостями.

.opencode/package.json

{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

opencode запускает bun install при запуске для их установки. Затем ваши плагины и инструменты смогут импортировать их.

.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)
      }
    },
  }
}

.opencode/plugins/example.js

export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")

  return {
    // Hook implementations go here
  }
}

Функция плагина получает:

project: Текущая информация о проекте.
directory: текущий рабочий каталог.
worktree: путь к рабочему дереву git.
client: клиент SDK с открытым кодом для взаимодействия с ИИ.
$: Bun shell API для выполнения команд.

Для плагинов TypeScript вы можете импортировать типы из пакета плагина:

my-plugin.ts

import type { Plugin } from "@opencode-ai/plugin"

export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

Плагины могут подписываться на события, как показано ниже в разделе «Примеры». Вот список различных доступных событий.

Командные события

command.executed

События файла

file.edited
file.watcher.updated

События установки

installation.updated

События LSP

lsp.client.diagnostics
lsp.updated

События сообщений

message.part.removed
message.part.updated
message.removed
message.updated

События разрешения

permission.asked
permission.replied

События сервера

server.connected

События сессии

session.created
session.compacted
session.deleted
session.diff
session.error
session.idle
session.status
session.updated

События shell

shell.env

События инструмента

tool.execute.after
tool.execute.before

Мероприятия TUI

tui.prompt.append
tui.command.execute
tui.toast.show

Вот несколько примеров плагинов, которые вы можете использовать для расширения opencode.

Отправляйте уведомления при возникновении определенных событий:

.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"'`
      }
    },
  }
}

Мы используем osascript для запуска AppleScript на macOS. Здесь мы используем его для отправки уведомлений.

Запретите открытому коду читать файлы .env:

.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")
      }
    },
  }
}

Внедряйте переменные среды во все shell-процессы выполнения (инструменты искусственного интеллекта и пользовательские terminal):

.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
    },
  }
}

Плагины также могут добавлять в opencode собственные инструменты:

.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})`
        },
      }),
    },
  }
}

Помощник tool создает собственный инструмент, который может вызывать opencode. Он принимает функцию схемы Zod и возвращает определение инструмента:

description: Что делает инструмент
args: схема Zod для аргументов инструмента.
execute: функция, которая запускается при вызове инструмента.

Ваши пользовательские инструменты будут доступны для открытия кода наряду со встроенными инструментами.

Используйте client.app.log() вместо console.log для структурированного ведения журнала:

.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" },
    },
  })
}

Уровни: debug, info, warn, error. Подробности см. в документации SDK](/docs/sdk).

Настройте контекст, включаемый при сжатии сеанса:

.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
`)
    },
  }
}

Хук experimental.session.compacting срабатывает до того, как LLM сгенерирует сводку для продолжения. Используйте его для внедрения контекста, специфичного для домена, который будет пропущен при запросе на сжатие по умолчанию.

Вы также можете полностью заменить запрос на уплотнение, установив output.prompt:

.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 status
2. Which files are being modified and by whom
3. Any blockers or dependencies between agents
4. The next steps to complete the work

Format as a structured prompt that a new agent can use to resume work.
`
    },
  }
}

Если установлен output.prompt, он полностью заменяет приглашение на сжатие по умолчанию. Массив output.context в этом случае игнорируется.

Плагины

Используйте плагин

Из локальных файлов

Из npm

Как устанавливаются плагины

Порядок загрузки

Создать плагин

Зависимости

Базовая структура

Поддержка TypeScript

События

Командные события

События файла

События установки

События LSP

События сообщений

События разрешения

События сервера

События сессии

События shell

События инструмента

Мероприятия TUI

Примеры

Отправлять уведомления

Защита .env

Внедрение переменных среды

Пользовательские инструменты

Ведение журнала

Хуки сжатия