安装插件

Plugin 是 OpenCode 的运行时扩展。它不是提示词，也不是 Agent 角色，而是在 OpenCode 运行过程中监听事件、注入环境、修改工具调用、发送通知、写日志，或者添加自定义工具。

先给结论：大多数新手暂时不需要插件

Plugin 站得很底层。它能改变 OpenCode 的运行过程，所以不要把它当成“高级提示词”使用。

先按这个顺序判断：

Plugin 在扩展层里的位置

OpenCode 的扩展不是一层东西。把层级分清，后面才不会越配越乱。

flowchart TB
  Rules[Rules / AGENTS.md<br/>项目长期约束]
  Agent[Agents<br/>角色和权限边界]
  Skill[Skills<br/>可复用流程说明]
  Tool[Custom tools / MCP<br/>模型可调用能力]
  Plugin[Plugins<br/>运行时事件和行为扩展]

  Rules --> Agent
  Agent --> Skill
  Agent --> Tool
  Plugin -.监听和改变.-> Tool
  Plugin -.注入或记录.-> Agent

一句话判断：如果你只是想让模型“知道怎么做”，不要写插件；如果你要在 OpenCode 运行时“发生某事时自动做某事”，才考虑插件。

插件放在哪里

OpenCode 支持本地插件和 npm 插件。

项目级插件只影响当前仓库，更适合试错。全局插件会影响所有 OpenCode 会话，除非它已经很稳定，否则不要默认放全局。

npm 插件什么时候用

如果社区已有成熟插件，可以在配置里引用 npm 包：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-wakatime"]
}

OpenCode 会在启动时用 Bun（一个比 Node.js 快得多的 JavaScript 运行时和包管理器，OpenCode 内部用它跑插件代码）自动安装 npm 插件，并把依赖缓存到本机。使用前至少检查三件事：

• 插件源码做了什么，有没有读写文件、执行 shell、上传数据。
• 插件是否仍在维护，是否和当前 OpenCode 版本匹配。
• 是否真的需要全局启用，还是只在某个项目启用。

加载顺序怎么理解

OpenCode 会从多个来源加载插件，并按顺序运行 hooks。官方加载顺序是：

如果同名同版本的 npm 包重复出现，只会加载一次；本地插件和 npm 插件即使名字相近，也会分别加载。

先写一个只记录日志的最小插件

第一个插件不要拦截工具，也不要改 shell 环境。先验证它能被加载，并能写结构化日志。

文件：.opencode/plugins/audit-events.ts

export const AuditEventsPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "audit-events",
      level: "info",
      message: "Plugin loaded",
    },
  })

  return {}
}

这类插件失败时影响面小，适合作为“插件链路是否正常”的第一步。

事件怎么选

你不需要背完整事件表。先按风险选择：

选事件前先问一句：我是观察发生了什么，还是要改变它？观察型插件风险低；拦截和修改型插件要有测试仓库和禁用方案。

依赖怎么管理

本地插件需要第三方 npm 包时，在配置目录放 package.json。OpenCode 启动时会运行 bun install。

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

依赖越多，启动、缓存和排障成本越高。插件依赖只放真正必要的包；如果只是几行字符串处理，不要引入新依赖。

插件和 Custom Tool 的关系

Plugin 也可以添加 custom tool。这个能力很强，但也更容易误用。

适合：

• 工具需要和插件上下文绑定。
• 工具要配合事件监听、日志或权限逻辑。
• 团队希望用插件包统一分发工具。

不适合：

• 只是封装一个简单项目命令。
• 只是让模型多一个 API 调用入口。
• 没有测试参数 schema 和错误输出。

安全写法

插件可以影响 OpenCode 行为，所以默认按高风险扩展处理：

• 不在插件里硬编码 API Key。
• 不把完整环境变量写进日志。
• 拦截 bash 时，不拼接未经校验的命令。
• 只在确实必要时修改工具参数。
• 插件出错时返回清楚错误，不静默吞掉。
• 给每个插件保留禁用路径，例如移出目录或清空配置里的 plugin 数组。

如果你的目标只是阻止模型读 .env，优先用权限或内置敏感文件保护；只有需要更细粒度逻辑时才写插件。

怎么判断插件写对了

验证插件不要直接上真实任务。按这个顺序验收：

1. 插件能被加载，没有启动错误。
2. 只读日志或通知能正常触发。
3. 如果拦截工具调用，先在测试仓库验证。
4. 插件失败时，错误信息能定位到原因。
5. 禁用插件后，OpenCode 能恢复默认行为。

一个好插件应该可关闭、可解释、可定位问题。否则它会让排障变得更难。

新手常见坑

• 把插件当成提示词增强器。提示词规则应放 Rules、Agent、Command 或 Skill。
• 在全局目录放项目专属插件，导致其他项目出现异常。
• 插件里直接执行危险 shell。
• 日志里打印完整环境变量。
• 本来只需要 custom tool，却写了一个会修改 OpenCode 生命周期的插件。
• 没有禁用方案，一出问题只能猜是不是插件导致。

接下来去哪

官方资料

• OpenCode plugins
• OpenCode configuration
• OpenCode custom tools