OpenCode 插件教程5 分钟接入第一个自定义工具【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencodeOpenCode 是一个开源 AI 编码代理。你在终端里跟它对话它帮你读代码、改文件、跑命令。它的 OpenCode 插件系统让你不改源码就能扩展它丢一个 JS/TS 文件进指定目录AI 就会多出新能力比如发通知、加工具、拦危险操作。本文用 3 个真实场景带你 5 分钟写出第一个插件。 快速上手3 步跑通 OpenCode先装 CLI任选一种方式npm i -g opencode-ailatest # 或 brew install anomalyco/tap/opencode opencode # 在项目目录里直接运行白话解释装一个全局命令行工具进任意项目目录敲opencode就进入交互界面。启动后按Tab切换两个内置代理build有完整权限plan只读不改文件选一个模型后就可以直接下达任务想改默认行为、加工具就是本文的插件要解决的问题 核心机制OpenCode 插件是怎么工作的打个比方。OpenCode 像一列火车钩子hooks就是沿途车站。火车每到一站某个关键节点就按顺序经过所有插件。插件在这站有任务就出手改一下没有就放行。插件就是一个 JS/TS 文件导出一个异步函数返回值是钩子对象常用钩子点event订阅事件如session.idle、file.editedtool.execute.before/tool.execute.after在工具调用前后拦截shell.env注入环境变量tool注册自定义工具OpenCode 会向插件传入上下文项目信息、工作目录directory、git worktree 路径worktree、SDK 客户端client、命令执行器$插件文件放两处自动生效项目级.opencode/plugins/全局~/.config/opencode/plugins/钩子不并行全部按加载顺序依次执行改动的结果会传给下一个钩子 场景实战3 个真实例子动手写给 OpenCode 写一个自定义工具工具是最常用的插件形态。保存为.opencode/plugins/custom-tools.tsimport { type Plugin, tool } from opencode-ai/plugin export const MyTools: Plugin async () ({ tool: { hello: tool({ description: 返回一句问候, args: { name: tool.schema.string() }, async execute(args) { return Hello ${args.name}! }, }), }, })白话解释tool帮你用 Zod 声明参数重启 OpenCode 后 AI 就能主动调用hello工具。注意插件工具与内置工具同名时插件优先生效。禁止 AI 读取 .env 文件密钥文件不该被读走。用tool.execute.before在调用前拦截// .opencode/plugins/env-protection.js export const EnvProtection async () ({ tool.execute.before: async (input, output) { if (input.tool read output.args.filePath.includes(.env)) { throw new Error(禁止读取 .env 文件) } }, })白话解释每次读文件前先查一眼路径命中.env直接抛错终止。一行判断就是一道闸门。会话结束发桌面通知长任务跑完时提醒一声不用盯着屏幕// .opencode/plugins/notification.js export const NotificationPlugin async ({ $ }) ({ event: async ({ event }) { if (event.type session.idle) { await $osascript -e display notification 会话完成 with title opencode } }, })白话解释session.idle表示会话空闲此时执行一条系统命令弹通知osascript仅限 macOS。如果你用 OpenCode 桌面版它本身就能在响应完成或出错时自动弹系统通知不用写这个插件。⚙️ OpenCode 插件加载顺序与调优加载顺序固定 4 步全局配置 → 项目配置 → 全局插件目录 → 项目插件目录npm 插件写在opencode.json的plugin数组里启动时自动用 Bun 安装依赖缓存在~/.cache/opencode/node_modules/同名同版本的 npm 包只加载一次本地插件与 npm 插件即使名字相近也各自独立加载本地插件要用外部包时在配置目录放一个package.json启动时会自动bun install日志别用console.log改用client.app.log()支持debug/info/warn/error四级会话过长会自动压缩compaction可用experimental.session.compacting钩子往里注入自定义上下文❓ OpenCode 插件常见报错解决插件不生效先查这 3 处文件是否在.opencode/plugins/或~/.config/opencode/plugins/下改完后是否重启了 OpenCode启动时才自动加载用了外部包却没在配置目录放package.json。本地插件和 npm 插件怎么选单文件小逻辑用本地插件放项目目录方便随仓库走。要分享给团队或多项目复用就发布成 npm 包写进opencode.json的plugin字段装 OpenCode 时自动带上。多个钩子会冲突吗不会并行冲突。所有钩子按加载顺序串行执行上一个钩子改完的output会传给下一个。想调行为顺序就调整插件文件所在的加载层级。自定义工具能覆盖内置工具吗能。插件工具与内置工具同名时插件优先生效。这正是改写某个内置工具行为的正规做法但建议换个名字避免以后升级时踩坑。写在最后OpenCode 插件系统把扩展门槛降到了一个文件。从 3 个场景抄起再改成你的工作流就够了。仓库内资源官方插件文档见packages/web/src/content/docs/plugins.mdx类型与tool助手源码见packages/plugin/src/示例插件见packages/plugin/src/example.ts。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenCode 插件教程：5 分钟接入第一个自定义工具
OpenCode 插件教程5 分钟接入第一个自定义工具【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencodeOpenCode 是一个开源 AI 编码代理。你在终端里跟它对话它帮你读代码、改文件、跑命令。它的 OpenCode 插件系统让你不改源码就能扩展它丢一个 JS/TS 文件进指定目录AI 就会多出新能力比如发通知、加工具、拦危险操作。本文用 3 个真实场景带你 5 分钟写出第一个插件。 快速上手3 步跑通 OpenCode先装 CLI任选一种方式npm i -g opencode-ailatest # 或 brew install anomalyco/tap/opencode opencode # 在项目目录里直接运行白话解释装一个全局命令行工具进任意项目目录敲opencode就进入交互界面。启动后按Tab切换两个内置代理build有完整权限plan只读不改文件选一个模型后就可以直接下达任务想改默认行为、加工具就是本文的插件要解决的问题 核心机制OpenCode 插件是怎么工作的打个比方。OpenCode 像一列火车钩子hooks就是沿途车站。火车每到一站某个关键节点就按顺序经过所有插件。插件在这站有任务就出手改一下没有就放行。插件就是一个 JS/TS 文件导出一个异步函数返回值是钩子对象常用钩子点event订阅事件如session.idle、file.editedtool.execute.before/tool.execute.after在工具调用前后拦截shell.env注入环境变量tool注册自定义工具OpenCode 会向插件传入上下文项目信息、工作目录directory、git worktree 路径worktree、SDK 客户端client、命令执行器$插件文件放两处自动生效项目级.opencode/plugins/全局~/.config/opencode/plugins/钩子不并行全部按加载顺序依次执行改动的结果会传给下一个钩子 场景实战3 个真实例子动手写给 OpenCode 写一个自定义工具工具是最常用的插件形态。保存为.opencode/plugins/custom-tools.tsimport { type Plugin, tool } from opencode-ai/plugin export const MyTools: Plugin async () ({ tool: { hello: tool({ description: 返回一句问候, args: { name: tool.schema.string() }, async execute(args) { return Hello ${args.name}! }, }), }, })白话解释tool帮你用 Zod 声明参数重启 OpenCode 后 AI 就能主动调用hello工具。注意插件工具与内置工具同名时插件优先生效。禁止 AI 读取 .env 文件密钥文件不该被读走。用tool.execute.before在调用前拦截// .opencode/plugins/env-protection.js export const EnvProtection async () ({ tool.execute.before: async (input, output) { if (input.tool read output.args.filePath.includes(.env)) { throw new Error(禁止读取 .env 文件) } }, })白话解释每次读文件前先查一眼路径命中.env直接抛错终止。一行判断就是一道闸门。会话结束发桌面通知长任务跑完时提醒一声不用盯着屏幕// .opencode/plugins/notification.js export const NotificationPlugin async ({ $ }) ({ event: async ({ event }) { if (event.type session.idle) { await $osascript -e display notification 会话完成 with title opencode } }, })白话解释session.idle表示会话空闲此时执行一条系统命令弹通知osascript仅限 macOS。如果你用 OpenCode 桌面版它本身就能在响应完成或出错时自动弹系统通知不用写这个插件。⚙️ OpenCode 插件加载顺序与调优加载顺序固定 4 步全局配置 → 项目配置 → 全局插件目录 → 项目插件目录npm 插件写在opencode.json的plugin数组里启动时自动用 Bun 安装依赖缓存在~/.cache/opencode/node_modules/同名同版本的 npm 包只加载一次本地插件与 npm 插件即使名字相近也各自独立加载本地插件要用外部包时在配置目录放一个package.json启动时会自动bun install日志别用console.log改用client.app.log()支持debug/info/warn/error四级会话过长会自动压缩compaction可用experimental.session.compacting钩子往里注入自定义上下文❓ OpenCode 插件常见报错解决插件不生效先查这 3 处文件是否在.opencode/plugins/或~/.config/opencode/plugins/下改完后是否重启了 OpenCode启动时才自动加载用了外部包却没在配置目录放package.json。本地插件和 npm 插件怎么选单文件小逻辑用本地插件放项目目录方便随仓库走。要分享给团队或多项目复用就发布成 npm 包写进opencode.json的plugin字段装 OpenCode 时自动带上。多个钩子会冲突吗不会并行冲突。所有钩子按加载顺序串行执行上一个钩子改完的output会传给下一个。想调行为顺序就调整插件文件所在的加载层级。自定义工具能覆盖内置工具吗能。插件工具与内置工具同名时插件优先生效。这正是改写某个内置工具行为的正规做法但建议换个名字避免以后升级时踩坑。写在最后OpenCode 插件系统把扩展门槛降到了一个文件。从 3 个场景抄起再改成你的工作流就够了。仓库内资源官方插件文档见packages/web/src/content/docs/plugins.mdx类型与tool助手源码见packages/plugin/src/示例插件见packages/plugin/src/example.ts。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考