中文
文档
插件

插件

编写你自己的插件来扩展 OpenCode。

插件让你能够通过挂钩各种事件并自定义行为来扩展 OpenCode。你可以创建插件来添加新功能、与外部服务集成，或修改 OpenCode 的默认行为。

想看示例，请查看社区创建的插件。

使用插件

有两种加载插件的方式。

从本地文件

将 JavaScript 或 TypeScript 文件放在插件目录中。

  • .opencode/plugins/ - 项目级插件
  • ~/.config/opencode/plugins/ - 全局插件

这些目录中的文件会在启动时自动加载。

从 npm

在你的配置文件中指定 npm 包。

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

常规和带 scope 的 npm 包都受支持。

在生态系统中浏览可用的插件。

插件如何安装

npm 插件会在启动时使用 Bun 自动安装。包及其依赖被缓存在 ~/.cache/opencode/node_modules/ 中。

本地插件直接从插件目录加载。要使用外部包，你必须在你的配置目录内创建一个 package.json（见"依赖"），或者将插件发布到 npm 并将其添加到你的配置。

加载顺序

插件从所有来源加载，且所有钩子按顺序运行。加载顺序为：

  1. 全局配置（~/.config/opencode/opencode.json）
  2. 项目配置（opencode.json）
  3. 全局插件目录（~/.config/opencode/plugins/）
  4. 项目插件目录（.opencode/plugins/）

同名且同版本的重复 npm 包只加载一次。然而，名称相似的一个本地插件和一个 npm 插件会被分别加载。

创建插件

一个插件是一个JavaScript/TypeScript 模块，它导出一个或多个插件函数。每个函数接收一个上下文对象，并返回一个 hooks 对象。

依赖

本地插件和自定义工具可以使用外部 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 worktree 路径。
  • client：用于与 AI 交互的 opencode SDK 客户端。
  • $：用于执行命令的 Bun shell API (opens in a new tab)。

TypeScript 支持

对于 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

待办事件

  • todo.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 在 macOS 上运行 AppleScript。这里我们用它来发送通知。

注意： 如果你使用 OpenCode 桌面应用，当响应就绪或会话出错时，它可以自动发送系统通知。

.env 保护

阻止 opencode 读取 .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 执行（AI 工具和用户终端）注入环境变量：

.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 schema 函数，并返回一个带以下内容的工具定义：

  • description：该工具的功能
  • args：该工具参数的 Zod schema
  • execute：工具被调用时运行的函数

你的自定义工具会与内置工具一同提供给 opencode。

注意： 如果一个插件工具使用了与内置工具相同的名称，则插件工具优先。

日志

使用 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 文档 (opens in a new tab)。

压缩钩子

自定义会话被压缩时所包含的上下文：

.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 数组会被忽略。

服务器生态系统