Deutsch
Dokumentation
Plugins

Plugins

Schreiben Sie Ihre eigenen Plugins, um OpenCode zu erweitern.

Mit Plugins können Sie OpenCode erweitern, indem Sie sich in verschiedene Ereignisse einklinken und das Verhalten anpassen. Sie können Plugins erstellen, um neue Funktionen hinzuzufügen, externe Dienste zu integrieren oder das Standardverhalten von OpenCode zu ändern.

Beispiele finden Sie bei den von der Community erstellten Plugins.

Ein Plugin verwenden

Es gibt zwei Möglichkeiten, Plugins zu laden.

Aus lokalen Dateien

Legen Sie JavaScript- oder TypeScript-Dateien im Plugin-Verzeichnis ab.

  • .opencode/plugins/ - Plugins auf Projektebene
  • ~/.config/opencode/plugins/ - Globale Plugins

Dateien in diesen Verzeichnissen werden beim Start automatisch geladen.

Aus npm

Geben Sie npm-Pakete in Ihrer Konfigurationsdatei an.

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

Sowohl reguläre als auch Scoped-npm-Pakete werden unterstützt.

Durchsuchen Sie verfügbare Plugins im Ökosystem.

Wie Plugins installiert werden

npm-Plugins werden beim Start automatisch mit Bun installiert. Pakete und ihre Abhängigkeiten werden in ~/.cache/opencode/node_modules/ zwischengespeichert.

Lokale Plugins werden direkt aus dem Plugin-Verzeichnis geladen. Um externe Pakete zu verwenden, müssen Sie eine package.json in Ihrem Konfigurationsverzeichnis erstellen (siehe Abhängigkeiten) oder das Plugin auf npm veröffentlichen und es zu Ihrer Konfiguration hinzufügen.

Ladereihenfolge

Plugins werden aus allen Quellen geladen und alle Hooks werden nacheinander ausgeführt. Die Ladereihenfolge ist:

  1. Globale Konfiguration ( ~/.config/opencode/opencode.json )
  2. Projektkonfiguration ( opencode.json )
  3. Globales Plugin-Verzeichnis ( ~/.config/opencode/plugins/ )
  4. Projekt-Plugin-Verzeichnis ( .opencode/plugins/ )

Doppelte npm-Pakete mit demselben Namen und derselben Version werden einmal geladen. Ein lokales Plugin und ein npm-Plugin mit ähnlichen Namen werden jedoch beide separat geladen.

Ein Plugin erstellen

Ein Plugin ist ein JavaScript-/TypeScript-Modul, das eine oder mehrere Plugin-Funktionen exportiert. Jede Funktion erhält ein Kontextobjekt und gibt ein Hooks-Objekt zurück.

Abhängigkeiten

Lokale Plugins und benutzerdefinierte Tools können externe npm-Pakete verwenden. Fügen Sie eine package.json mit den benötigten Abhängigkeiten zu Ihrem Konfigurationsverzeichnis hinzu.

.opencode/package.json
{
  "dependencies": {
    "shescape": "^2.1.0"
  }
}

OpenCode führt beim Start bun install aus, um diese zu installieren. Ihre Plugins und Tools können sie dann importieren.

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

Grundstruktur

.opencode/plugins/example.js
export const MyPlugin = async ({ project, client, $, directory, worktree }) => {
  console.log("Plugin initialized!")
 
  return {
    // Hook implementations go here
  }
}

Die Plugin-Funktion erhält:

  • project : Die Informationen zum aktuellen Projekt.
  • directory : Das aktuelle Arbeitsverzeichnis.
  • worktree : Der Pfad zum Git-Worktree.
  • client : Ein opencode-SDK-Client für die Interaktion mit der KI.
  • $ : Bun's Shell-API (opens in a new tab) zur Ausführung von Befehlen.

TypeScript-Unterstützung

Für TypeScript-Plugins können Sie Typen aus dem Plugin-Paket importieren:

my-plugin.ts
import type { Plugin } from "@opencode-ai/plugin"
 
export const MyPlugin: Plugin = async ({ project, client, $, directory, worktree }) => {
  return {
    // Type-safe hook implementations
  }
}

Ereignisse

Plugins können Ereignisse abonnieren, wie unten im Abschnitt Beispiele zu sehen ist. Hier ist eine Liste der verschiedenen verfügbaren Ereignisse.

Befehlsereignisse

  • command.executed

Dateiereignisse

  • file.edited
  • file.watcher.updated

Installationsereignisse

  • installation.updated

LSP-Ereignisse

  • lsp.client.diagnostics
  • lsp.updated

Nachrichtenereignisse

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

Berechtigungsereignisse

  • permission.asked
  • permission.replied

Serverereignisse

  • server.connected

Sitzungsereignisse

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

Todo-Ereignisse

  • todo.updated

Shell-Ereignisse

  • shell.env

Tool-Ereignisse

  • tool.execute.after
  • tool.execute.before

TUI-Ereignisse

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

Beispiele

Hier sind einige Beispiele für Plugins, die Sie verwenden können, um opencode zu erweitern.

Benachrichtigungen senden

Senden Sie Benachrichtigungen, wenn bestimmte Ereignisse eintreten:

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

Wir verwenden osascript, um AppleScript unter macOS auszuführen. Hier verwenden wir es zum Senden von Benachrichtigungen.

Hinweis: Wenn Sie die OpenCode-Desktop-App verwenden, kann sie automatisch Systembenachrichtigungen senden, wenn eine Antwort bereit ist oder eine Sitzung einen Fehler aufweist.

.env-Schutz

Verhindern Sie, dass opencode .env-Dateien liest:

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

Umgebungsvariablen injizieren

Injizieren Sie Umgebungsvariablen in alle Shell-Ausführungen (KI-Tools und Benutzerterminals):

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

Benutzerdefinierte Tools

Plugins können opencode auch benutzerdefinierte Tools hinzufügen:

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

Der tool-Helfer erstellt ein benutzerdefiniertes Tool, das opencode aufrufen kann. Er nimmt eine Zod-Schema-Funktion entgegen und gibt eine Tool-Definition zurück mit:

  • description : Was das Tool tut
  • args : Zod-Schema für die Argumente des Tools
  • execute : Funktion, die ausgeführt wird, wenn das Tool aufgerufen wird

Ihre benutzerdefinierten Tools stehen opencode neben den integrierten Tools zur Verfügung.

Hinweis: Wenn ein Plugin-Tool denselben Namen wie ein integriertes Tool verwendet, hat das Plugin-Tool Vorrang.

Logging

Verwenden Sie client.app.log() anstelle von console.log für strukturiertes Logging:

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

Stufen: debug, info, warn, error. Siehe SDK-Dokumentation (opens in a new tab) für Details.

Compaction-Hooks

Passen Sie den Kontext an, der einbezogen wird, wenn eine Sitzung komprimiert wird:

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

Der Hook experimental.session.compacting wird ausgelöst, bevor das LLM eine Fortsetzungszusammenfassung generiert. Verwenden Sie ihn, um domänenspezifischen Kontext zu injizieren, den der Standard-Compaction-Prompt übersehen würde.

Sie können den Compaction-Prompt auch vollständig ersetzen, indem Sie output.prompt setzen:

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

Wenn output.prompt gesetzt ist, ersetzt es den Standard-Compaction-Prompt vollständig. Das Array output.context wird in diesem Fall ignoriert.

ServerÖkosystem