插件加载与编写
从本地目录或 npm 加载插件，管理依赖、顺序和上下文对象。
插件是导出一个或多个函数的 JavaScript/TypeScript 模块。函数接收 OpenCode 上下文并返回 hooks 对象，可以监听事件、调整行为或注册工具。
加载位置
本地插件放在项目 .opencode/plugins/ 或全局 ~/.config/opencode/plugins/，启动时自动加载。npm 插件在运行时配置的 plugin 数组中指定，支持普通与 scoped 包。
npm 包和依赖在启动时通过 Bun 自动安装，缓存位于 ~/.cache/opencode/node_modules/。本地插件直接加载；需要外部依赖时，在配置目录的 package.json 声明，OpenCode 启动时会运行 bun install。
因此，添加配置并不只是保存文本，还可能在下次启动时加载代码和获取依赖。使用前检查来源与依赖，不把本地文件扩展名当成隔离边界。
多来源顺序
插件从全部来源加载，hooks 按顺序运行：
- 全局
opencode.json中的插件。 - 项目
opencode.json中的插件。 - 全局插件目录。
- 项目插件目录。
同名同版本 npm 包只加载一次；本地插件和名称相似的 npm 包仍分别加载。不要按普通配置覆盖规则理解为项目插件会自动替换全局插件。
插件上下文
| 字段 | 用途 |
|---|---|
project | 当前项目信息 |
directory | 当前工作目录 |
worktree | Git worktree 路径 |
client | OpenCode SDK client |
$ | Bun shell API |
TypeScript 可以从 @opencode-ai/plugin 导入 Plugin 类型。不同 hook 的 input/output 各不相同，不能假定所有事件都接受文件路径或命令字段。
结构化日志
官方建议使用 client.app.log() 替代 console.log，请求的 body 可包含 service、level、message 和 extra。支持的 level 为 debug、info、warn、error。
初始化成功、hook 触发和外部操作成功应分别记录，避免只有一条“插件启动”就把整个功能视为已验证。
注册工具与下一步
插件返回对象中的 tool 可注册由 tool() 定义的工具。与内置工具同名时插件工具优先，应使用明确且不冲突的名称；仅需禁用内置工具时用权限，不必用同名插件替换。