安装插件

理解 OpenCode 插件什么时候该用，以及如何安全扩展运行行为。

插件用于扩展 OpenCode 自身的运行行为。它可以监听事件、修改工具调用、注入环境变量、发送通知、写日志，甚至添加工具。

官方教程列出了本地插件、npm 插件、加载顺序、事件和示例。这里按新手视角讲：插件和自定义工具有什么区别，什么时候该写插件，以及怎么避免把 OpenCode 改得不可控。

先理解它解决什么问题

插件解决的是“OpenCode 运行过程中需要额外行为”的问题。例如：

会话完成时发系统通知。
每次 shell 执行前注入环境变量。
拦截危险工具调用。
把关键事件写入结构化日志。
在压缩上下文前补充项目状态。

如果你只是想让模型多一个可调用动作，优先看“自定义工具”。如果你想改变 OpenCode 的运行过程，再考虑插件。

插件、自定义工具、MCP 怎么区分

新手可以这样判断：

自定义工具：给模型一个可调用函数，例如“查询项目数据库”。
MCP：接入外部服务，例如文档搜索、Sentry、GitHub。
插件：改变 OpenCode 生命周期，例如“工具执行前检查参数”“会话结束发通知”。

不要用插件解决所有问题。插件越底层，越容易影响整个工作流。

插件放哪里

项目级：.opencode/plugins/
全局级：~/.config/opencode/plugins/

项目级适合当前仓库专属行为，例如保护某个目录、注入项目环境变量。全局级适合所有项目都需要的行为，例如通用日志或通知。

新手优先项目级。确认稳定后，再考虑全局。

npm 插件什么时候用

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

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

npm 插件会在 OpenCode 启动时通过 Bun 自动安装，并缓存在本机。使用前要先看插件源码、权限和维护状态。不要把不理解的插件直接放进全局配置。

最小插件长什么样

本地插件是一个 JavaScript 或 TypeScript 模块，导出插件函数。先从只记录事件的插件开始：

export const MyPlugin = async ({ client }) => {
  await client.app.log({
    body: {
      service: "my-plugin",
      level: "info",
      message: "Plugin loaded",
    },
  });

  return {};
};

这个插件不拦截工具、不改环境、不执行命令，只验证插件加载和日志链路。新手不要第一步就写会修改工具参数的插件。

常见事件怎么理解

你不需要背完整事件列表。先记住几类高频事件：

session.*：会话创建、更新、结束、压缩、出错。
tool.execute.before / tool.execute.after：工具执行前后。
permission.asked / permission.replied：权限询问和回复。
shell.env：Shell 环境变量准备阶段。
file.edited：文件被编辑。
tui.toast.show：显示 TUI 通知。

选事件时先问一句：我是要观察发生了什么，还是要改变它？观察型插件风险低；拦截和修改型插件风险高。

安全写法

插件可以影响 OpenCode 行为，所以默认要更谨慎：

不要在插件里硬编码 API Key。
不要把密钥写进日志。
拦截 bash 时，不要自己拼接未经校验的命令。
只在确实必要时修改工具参数。
插件出错时要返回清楚错误，不要静默吞掉。
全局插件越少越好。

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

依赖管理

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

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

依赖越多，启动和维护成本越高。插件依赖建议只放真正必要的包。

怎么判断插件写对了

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

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

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

新手常见坑

把插件当成提示词增强器。提示词规则应放 Rules、Agent 或 Command，插件不适合写大段行为说明。
在全局目录放项目专属插件，导致其他项目出现奇怪行为。
插件里直接执行危险 shell。
日志里打印完整环境变量。
本来只需要自定义工具，却写了一个会修改 OpenCode 生命周期的插件。

最近更新： 2026年5月1日

On this page