第12章 插件
Plugins
在 opencode.json(c) 中添加已发布的包、带版本号的包、作用域包或本地插件目录。
opencode.jsonc { "$schema": "https://opencode.ai/config.json", "plugins": [ "opencode-acme-plugin", "opencode-acme-plugin@1.2.0", "@acme/opencode-plugin", "./plugins/local", "../shared/plugin", "/absolute/path/plugin", "file:///home/me/plugins/local", { "package": "@acme/opencode-plugin", "options": { "agent": "reviewer", "strict": true, }, }, ], }
相对路径基于包含该条目的配置文件解析。 配置中的本地路径必须是目录;指向单个文件的路径会被跳过。参见 Load 了解 OpenCode 如何在目录中查找各个部分。 来自适用配置文件的插件数组按从低到高的优先级应用,而不是相互替换。 ~/.config/opencode/opencode.jsonc ./opencode.jsonc ./.opencode/opencode.jsonc
OpenCode 还会从每个发现的 .opencode/plugins/ 目录中加载直接的 .ts 和 .js 文件以及紧邻的插件包目录。 Files .opencode/ └── plugins/ ├── concise.ts ├── reviewer.js └── acme-package/
全局插件使用 OpenCode 配置目录下的相同发现布局。 ~/.config/opencode/plugins/
项目根目录旁 opencode.json(c) 旁边的 plugins/ 目录不会被自动发现;请显式配置其插件目录或将其移动到 .opencode/ 下。 opencode.jsonc { "plugins": ["./plugins/local"] }
按顺序处理插件条目。在 ID 或通配符前加 - 可禁用它,使用 * 匹配所有插件,使用 .* 匹配 ID 前缀。后文的 ID 会重新启用插件。 opencode.jsonc { "plugins": ["*", "-opencode.provider.*", "opencode.provider.openai", "-acme.reviewer"] }
两个内置插件忽略移除操作,以防止仓库关闭策略执行:opencode.config.policy 和 opencode.provider.opencode(即通过 Console 连接传递组织策略)。
使用 CLI 安装、列出、检查、更新或移除全局包插件。 Terminal opencode plugin add opencode-acme-plugin@1.2.0 opencode plugin list opencode plugin list --builtin opencode plugin check opencode plugin update opencode plugin update opencode-acme-plugin opencode plugin remove opencode-acme-plugin@1.2.0
plugin check 检查服务器、仅 GUI 和仅 TUI 的包插件是否有更新。plugin update 更新所有过时的包;传入配置的包目标则仅检查或更新该包。本地插件和精确的包修订版会被跳过。 包安装接受带版本、标签或范围的 npm 名称,以及兼容 npm 的 Git 包规范。 Git 仓库可以使用托管快捷方式、HTTPS 或 SSH,包括通过现有 Git 凭据访问的私有仓库。 Terminal opencode plugin add @acme/opencode-plugin@latest opencode plugin add github:acme/opencode-plugin opencode plugin add git+ssh://git@github.com/acme/opencode-plugin.git#main opencode plugin add 'github:acme/plugins#main::path:packages/opencode-plugin'
支持分支、标签、完整 commit 哈希以及 npm 的 ::path: 仓库子目录选择器。本地路径可直接配置;tarball 和 npm 别名目标不被 plugin add 接受。
监视配置目录下的变更会自动重新加载。服务器启动时立即加载缓存的包插件,在后台安装缺失的包,并检查未固定的 npm 和 Git 插件是否有更新,但不改变已安装的包。精确的 npm 版本和完整的 Git commit 哈希保持固定。对未监视本地依赖的更改仍可能需要重启 OpenCode。 Terminal touch .opencode/plugins/concise/index.ts opencode service restart
导出 ./gui-experimental 的插件还会向 OpenCode Desktop 添加面板、命令或设置。应用程序从运行的服务器加载插件,因此请在您的全局 opencode.json(c) 中配置该插件,以便在每个窗口中使用。 ~/.config/opencode/opencode.jsonc { "plugins": ["opencode-acme-plugin"], }
当选择应用程序自身的服务器时,Settings > Extensions > Plugins 会列出这些插件。插件的开关仅关闭其桌面 UI,失败后 Reload 会重新加载它。若要关闭整个插件,请在 plugins 中添加 - 及其 ID,例如 "-acme"。
仅 TUI 的插件单独配置,并在连接到远程服务器时保持激活。 cli.json { "plugins": ["opencode-acme-cli"] }
构建插件 创建添加工具、钩子、集成、命令、代理及其他行为的插件。