OpenCode 插件使用教程开篇OpenCode 插件是扩展平台能力的核心解决方案。开发者可以借助插件监听系统事件、拦截工具执行、注入自定义逻辑、集成外部服务或是修改 OpenCode 默认行为。插件支持本地文件和NPM 包两种部署形式同时拥有庞大的社区生态提供大量开箱即用的第三方插件。本文结合官方文档全面讲解 OpenCode 插件的加载规则、部署方式、依赖管理、开发规范、事件钩子、实战案例同时整理官方生态插件与第三方项目清单并梳理使用与开发过程中的注意事项帮助普通用户快速使用插件也助力开发者自主编写定制化插件。一、插件核心基础1.1 插件定位OpenCode 插件基于事件钩子Hook机制运行能够在命令执行、文件编辑、工具调用、会话变更等全生命周期中介入逻辑。它区别于自定义工具、MCP 服务自定义工具偏向单次功能调用MCP 偏向外部服务对接而插件更擅长全局行为拦截、事件监听与流程改造。插件支持 JavaScript、TypeScript 两种主流编写语言。1.2 插件加载顺序OpenCode 会按照固定优先级依次加载插件与配置加载顺序决定了钩子执行顺序具体规则如下全局配置文件~/.config/opencode/opencode.json中声明的 NPM 插件项目配置文件当前项目opencode.json中声明的 NPM 插件全局插件目录~/.config/opencode/plugins/下的本地插件项目插件目录.opencode/plugins/下的本地插件重复加载规则同名同版本的 NPM 包仅会加载一次避免重复执行本地插件与名称相似的 NPM 插件相互独立会分别加载、依次执行。二、插件加载方式OpenCode 提供两种主流插件加载方案本地文件加载适合自定义私有插件、NPM 包加载适合社区开源插件可根据使用场景灵活选择。2.1 本地文件加载将 JS/TS 插件文件放入指定目录OpenCode 启动时会自动扫描并加载无需额外配置。分为项目级插件和全局插件项目级插件仅对当前项目生效目录.opencode/plugins/适用场景项目专属定制逻辑、团队内部私有插件。全局插件对本机所有 OpenCode 会话生效目录~/.config/opencode/plugins/适用场景个人通用配置、全设备共享插件。示例在项目中创建本地插件文件目录结构你的项目/ └── .opencode/ └── plugins/ └── my-plugin.js # 本地插件文件2.2 NPM 包加载社区开源插件可直接通过 NPM 包形式引入只需在项目 / 全局opencode.json中声明包名即可。2.2.1 配置语法在opencode.json的plugin数组中填写 NPM 包名支持普通包与作用域包{$schema:https://opencode.ai/config.json,plugin:[opencode-wakatime,opencode-helicone-session,my-org/custom-plugin]}2.2.2 安装与缓存规则OpenCode 启动时会自动使用 Bun 下载并安装声明的 NPM 插件插件及依赖会统一缓存到~/.cache/opencode/node_modules/目录下次启动直接复用缓存提升加载速度。三、插件依赖管理本地插件如果需要引用第三方 NPM 包如工具库、SDK不能直接导入需要在对应目录创建package.json管理依赖。3.1 配置步骤在插件所在目录项目级.opencode/、全局~/.config/opencode/新建package.json在dependencies字段声明所需依赖OpenCode 启动时自动执行bun install安装依赖。3.2 示例配置以引入shescape命令转义库为例依赖配置文件.opencode/package.json{dependencies:{shescape:^2.1.0}}插件中导入依赖并使用.opencode/plugins/shell-escape.tsimport{escape}fromshescapeexportconstShellEscapePluginasync(ctx){return{tool.execute.before:async(input,output){// 转义 bash 命令防止注入风险if(input.toolbash){output.args.commandescape(output.args.command)}},}}四、插件开发详解4.1 基础代码结构插件本质是一个异步 JS/TS 模块导出异步插件函数函数接收上下文对象最终返回钩子集合。4.1.1 JavaScript 基础模板// .opencode/plugins/example.jsexportconstMyPluginasync({project,client,$,directory,worktree}){console.log(插件初始化完成);// 在此处编写各类事件钩子return{};};4.1.2 上下文参数说明插件函数的上下文内置多个核心对象覆盖项目、终端、SDK 等能力参数作用project当前项目基础信息directoryOpen 运行的工作目录worktreeGit 工作树根路径clientOpenCode SDK 客户端用于日志、AI 交互$Bun Shell API可直接执行终端命令4.2 TypeScript 类型支持官方提供专用类型包opencode-ai/plugin可实现完整类型校验与代码提示// .opencode/plugins/example.tsimporttype{Plugin}fromopencode-ai/pluginexportconstMyPlugin:Pluginasync({project,client,$,directory,worktree}){// 类型安全的钩子逻辑return{};};4.3 全量事件钩子列表插件可订阅 OpenCode 全生命周期事件按功能分类整理如下所有钩子均可在插件中监听使用命令事件command.executed终端 / TUI 命令执行后触发文件事件file.edited文件被编辑时触发file.watcher.updated文件监听器检测到文件变更时触发安装事件installation.updated插件 / 依赖安装更新时触发LSP 事件lsp.client.diagnosticsLSP 诊断信息更新lsp.updatedLSP 服务状态变更消息事件message.part.removed/message.part.updated消息片段删除 / 更新message.removed/message.updated整条消息删除 / 更新权限事件permission.asked触发权限审批弹窗permission.replied用户完成权限选择服务器事件server.connected服务连接成功会话事件session.created/session.deleted会话创建 / 删除session.compacted会话上下文压缩session.diff会话内容差异变更session.error/session.idle会话报错 / 空闲session.status/session.updated会话状态 / 内容更新待办事件todo.updated待办列表变更Shell 事件shell.envShell 环境变量加载时触发工具事件tool.execute.before工具执行前置钩子拦截修改参数tool.execute.after工具执行后置钩子处理返回结果TUI 事件tui.prompt.append输入框追加内容tui.command.executeTUI 斜杠命令执行tui.toast.showTUI 弹出提示消息实验性事件experimental.session.compacting会话压缩自定义钩子五、实战插件案例本节提供官方原生插件案例覆盖通知、安全防护、环境注入、自定义工具、会话压缩等高频场景所有代码均可直接部署使用。案例 1系统桌面通知插件macOS监听会话空闲事件通过系统弹窗发送通知// .opencode/plugins/notification.jsexportconstNotificationPluginasync({$}){return{event:async({event}){// 会话进入空闲状态时触发通知if(event.typesession.idle){await$osascript -e display notification 会话执行完成 with title OpenCode;}},};};案例 2.env 隐私文件防护插件拦截read工具读取.env配置文件保护密钥、账号等敏感信息// .opencode/plugins/env-protection.jsexportconstEnvProtectionasync(){return{tool.execute.before:async(input,output){// 拦截读取 .env 相关文件的请求if(input.toolreadoutput.args.filePath.includes(.env)){thrownewError(禁止读取 .env 隐私配置文件);}},};};案例 3全局 Shell 环境变量注入在所有 Shell 执行前注入自定义环境变量// .opencode/plugins/inject-env.jsexportconstInjectEnvPluginasync(){return{shell.env:async(input,output){// 注入自定义密钥与项目根路径output.env.MY_API_KEYxxxxxx;output.env.PROJECT_ROOTinput.cwd;},};};案例 4插件内注册自定义工具在插件中直接创建 OpenCode 自定义工具无需单独编写工具文件// .opencode/plugins/custom-tools.tsimport{typePlugin,tool}fromopencode-ai/pluginexportconstCustomToolsPlugin:Pluginasync(){return{tool:{// 定义自定义工具mytool:tool({description:示例自定义工具,args:{foo:tool.schema.string().describe(自定义入参),},asyncexecute(args,context){return当前目录${context.directory}入参${args.foo};},}),},};};案例 5自定义会话压缩规则修改会话压缩逻辑追加自定义上下文也可完全替换压缩提示词方式 1追加自定义上下文// .opencode/plugins/compaction.tsimporttype{Plugin}fromopencode-ai/pluginexportconstCompactionPlugin:Pluginasync(){return{experimental.session.compacting:async(input,output){// 向压缩上下文追加自定义内容output.context.push(## 项目专属上下文 - 当前任务代码重构 - 活跃文件src/main.ts);},};};方式 2完全替换压缩提示词// .opencode/plugins/custom-compaction.tsimporttype{Plugin}fromopencode-ai/pluginexportconstCustomCompaction:Pluginasync(){return{experimental.session.compacting:async(input,output){// 完全重写压缩规则output.prompt请精简会话内容保留1. 当前任务 2. 已修改文件 3. 待办步骤 输出结构化摘要支持会话续接。;},};};案例 6结构化日志插件使用官方 SDK 日志接口替代原生console.log支持分级日志// .opencode/plugins/log-plugin.tsimporttype{Plugin}fromopencode-ai/pluginexportconstLogPlugin:Pluginasync({client}){// 初始化日志awaitclient.app.log({body:{service:custom-plugin,level:info,message:插件加载成功,extra:{version:1.0.0},},});return{};};日志级别支持debug、info、warn、error。六、OpenCode 生态资源汇总OpenCode 拥有丰富的社区生态包含开源插件、第三方集成项目、专用代理以下为官方整理的生态清单可直接选用。6.1 社区插件列表插件名称功能描述opencode-daytona在 Daytona 隔离沙箱运行会话支持 Git 同步与实时预览opencode-helicone-session自动注入 Helicone 会话头用于请求分组opencode-type-inject自动注入 TS/Svelte 类型到文件读取逻辑opencode-openai-codex-auth复用 ChatGPT Plus/Pro 订阅替代独立 API 额度opencode-gemini-auth复用 Gemini 套餐降低计费成本opencode-vibeguard替换机密信息为占位符保护隐私opencode-websearch-cited增强网页搜索采用 Google 检索风格opencode-pty支持 AI 运行后台交互式进程opencode-shell-strategy优化 Shell 命令防止 TTY 挂起opencode-wakatime接入 Wakatime 统计使用时长opencode-md-table-formatter自动格式化 LLM 生成的 Markdown 表格opencode-notificator会话事件桌面通知与声音提醒opencode-supermemory实现跨会话持久记忆opencode-scheduler基于 cron 语法定时执行任务6.2 第三方集成项目项目名称功能描述kimaki基于 SDK 开发的 Discord 会话管理机器人opencode.nvimNeovim 编辑器插件提供感知式提示词portal移动端优先 Web UI支持 Tailscale/VPN 访问OpenChamberOpenCode 桌面 / Web/VS Code 一体化扩展OpenWorkClaude Cowork 开源替代方案ocx扩展管理器支持隔离式可移植配置6.3 开源代理代理名称功能描述Agentic结构化开发专用模块化代理与命令opencode-agents增强工作流的配置、提示词与代理合集七、进阶使用技巧日志规范开发插件时优先使用client.app.log接口而非原生console.log日志可分级、结构化便于问题排查。钩子执行顺序加载顺序靠前的插件其钩子会优先执行可利用该特性实现 “前置拦截 后置处理” 的组合逻辑。插件隔离团队项目优先使用项目级插件个人习惯类插件使用全局插件避免配置互相干扰。错误处理tool.execute.before钩子中抛出异常可直接拦截工具执行常用于安全校验。八、重要注意事项加载顺序风险依赖全局插件逻辑的项目插件需保证全局插件优先加载同名 NPM 包仅加载一次升级插件后建议手动清理缓存。命名冲突插件内自定义工具、钩子名称若与内置能力重名插件逻辑会优先覆盖内置逻辑需谨慎命名避免功能异常。依赖问题本地插件的package.json必须放置在.opencode/或全局根目录而非plugins子目录否则依赖无法正常安装。隐私安全编写 Shell、文件相关插件时禁止硬编码密钥、密码等敏感信息使用.env防护类插件是生产环境必备操作。实验性事件experimental开头的事件属于内测功能官方可能随时调整正式项目谨慎使用。跨环境迁移Windows、macOS、Linux 路径存在差异编写路径相关插件时建议使用worktree、directory内置变量避免硬编码绝对路径。NPM 插件网络部分海外社区插件下载较慢可手动下载包放入缓存目录或切换国内镜像源。终端命令限制使用$执行系统命令时遵循系统权限规则禁止编写高危删除、格式化类命令。总结OpenCode 插件体系依托灵活的事件钩子、双加载模式和丰富社区生态既满足普通用户开箱即用的需求也支持开发者深度定制。对于普通使用者优先选用社区成熟 NPM 插件快速实现通知、统计、隐私防护等能力对于团队与开发者可基于本地插件编写项目专属逻辑结合依赖管理实现复杂功能。在实际使用中个人场景推荐全局插件统一习惯团队项目推荐项目级插件保证协作一致性开发插件时严格遵循加载规则、类型规范与安全要求合理使用事件钩子区分正式功能与实验性功能。借助插件能力可大幅拓展 OpenCode 的边界打造适配自身工作流的一体化 AI 编码环境。