OpenCode Guide
Navigate: Menu

Intro (入门)

Usage (使用指南)

Configure (详细配置)

Develop (开发)

Console (控制台)

将已发布的包、指定版本的包、带 scope 的包，或本地插件目录添加到 opencode.json(c)。

配置

{
  "$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,
      },
    },
  ],
}
相对路径从包含该条目的配置文件所在目录解析。
配置的本地路径必须是目录。OpenCode 会加载该目录下的 server 或 index 模块，例如 index.ts。指向单个文件的路径会被跳过。
来自各适用配置文件的插件数组按从低到高的优先级依次应用，而不是相互替换。
~/.config/opencode/opencode.jsonc
./opencode.jsonc
./.opencode/opencode.jsonc

发现

OpenCode 还会从每个已发现的 .opencode/plugins/ 目录中加载直接放置的 .ts 和 .js 文件，以及紧邻的插件包目录。
.opencode/
└── plugins/
    ├── concise.ts
    ├── reviewer.js
    └── acme-package/
全局插件在 OpenCode 配置目录下使用相同的发现布局。
~/.config/opencode/plugins/
与项目根目录的 opencode.json(c) 同级的 plugins/ 目录不会被自动发现；请显式配置其插件目录，或将其移动到 .opencode/ 下。
{
  "plugins": ["./plugins/local"]
}

控制

插件条目按顺序处理。在 ID 或通配符前加 - 可禁用该项，使用 * 匹配所有插件，使用 .* 匹配 ID 前缀。靠后的 ID 可重新启用某个插件。
{
  "plugins": ["*", "-opencode.provider.*", "opencode.provider.openai", "-acme.reviewer"]
}
两个内置插件会忽略移除操作，以确保仓库无法关闭策略强制执行：opencode.config.policy 和 opencode.provider.opencode（后者是传递组织策略的 Console 连接）。

管理

使用 CLI 安装、列出、检查、更新或移除全局包插件。
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 会检查服务器端和仅 TUI 的包插件是否有更新。plugin update 会更新所有过时的包；传入已配置的包目标则仅检查或更新该包。本地插件和精确的包版本会被跳过。
包安装支持带版本、标签或范围的 npm 名称，以及 npm 兼容的 Git 包规格。Git 仓库可使用托管平台快捷方式、HTTPS 或 SSH，包括可通过现有 Git 凭据访问的私有仓库。
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: 仓库子目录选择器。本地路径请直接配置；plugin add 不接受 tarball 和 npm 别名目标。

重新加载

受监控配置目录下的更改会自动重新加载。服务器启动时会立即加载已缓存的包插件，在后台安装缺失的包，并检查未固定版本的 npm 和 Git 插件是否有更新，且不会更改已安装的包。精确的 npm 版本和完整的 Git commit 哈希保持固定。未受监控的本地依赖的更改可能仍需重启 OpenCode。
touch .opencode/plugins/concise/index.ts
opencode service restart

终端

仅 CLI 的插件单独配置，在连接到远程服务器时保持生效。
{
  "plugins": ["opencode-acme-cli"]
}

构建插件

创建可添加工具、钩子、集成、命令、智能体及其他行为的插件。