在 Olares 上使用技能与插件扩展 OpenCode AI 编码代理

原创2026-10-15 19:54:381,338 阅读
文章标签:云原生后端运维

在 Olares 上使用技能与插件扩展 OpenCode AI 编码代理

本文是 Olares(Terminus)个人云操作系统上 OpenCode AI 编码代理扩展机制的实战指南。OpenCode 通过**技能(Skills)与插件(Plugins)**两种方式获得扩展能力:技能以 Markdown 指令文件形式教会代理处理特定领域任务,插件以 npm 包或本地脚本形式注入运行时功能。读完本文,你将掌握 Olares 预装技能(system-admin、web-preview)的用法、技能与插件的全局/项目级配置方法,以及如何通过 npm 包和本地 .js/.ts 文件为 OpenCode 增加社区插件。

扩展机制总览:Skills 与 Plugins 的职责边界

OpenCode 支持两类扩展,二者在工作方式与生命周期上有明显区别:

  • Skills(技能):本质上是 Markdown 指令文件,用于教会 OpenCode 如何处理特定领域的任务(例如系统包管理、开发服务器预览)。OpenCode 会在对话过程中根据上下文自动加载相关技能,通常不需要用户手动管理。
  • Plugins(插件):本质上是 JavaScript 或 TypeScript 模块,用于添加运行时能力。它们在 OpenCode 启动时运行,可以接入 OpenCode 的执行管道(execution pipeline),例如拦截会话事件、注入工具或提供持久化记忆。

两种扩展均支持两种作用域:

  • 全局(Global):对所有项目生效;
  • 项目级(Project):仅对指定项目生效。

在 Olares 上,OpenCode 以容器化应用形式运行,其配置文件与扩展文件都保存在 Olares Files 中,可通过文件管理器直接查看与编辑。

技能(Skills):让 OpenCode 学会特定任务

OpenCode 在对话期间会自动加载相关技能,因此你很少需要手动管理技能。但了解技能的存储位置、加载命令与预装内容,仍是深度使用 OpenCode 的前提。

预安装技能

Olares 上的 OpenCode 附带两个预装技能:

技能 描述
system-admin 通过 pkg-install 进行系统包管理
web-preview 通过内置反向代理进行开发服务器预览

这两个技能文件位于全局配置目录 Application/Data/opencode/.config/opencode/skills/ 下。从仓库中的多代理编排文档(docs/use-cases/opencode-omo.md)可以看到 Olares 的预配置清单:skills/web-preview/ 与 skills/system-admin/ 两个技能目录属于 Olares 托管项,每次启动都会被强制更新到最新版本。这意味着你无需手工维护技能文件版本,重启应用即可获得最新指令集。

system-admin:AI 化的系统包管理

system-admin 技能的核心能力是让 OpenCode 通过 pkg-install 命令管理系统包。你只需在聊天中输入自然语言,例如:

Install ffmpeg

或:

Remove the curl package

OpenCode 便会识别意图并运行相应的 pkg-install 命令,无需你手动进入终端。如果技能未自动激活,可以在聊天中手动加载:

/skill load system-admin

关于 pkg-install 的完整命令参考,请参阅仓库中的 管理包指南(中文版见 docs/zh/use-cases/opencode-packages.md)。这里补充几个关键细节,帮助你理解 system-admin 技能的运行环境:

  • OpenCode 容器以非 root 用户运行,因此 sudo 与 apk 无法直接使用,所有系统包管理都必须经由 pkg-install 完成;
  • pkg-install 是 Alpine Linux 包管理器的封装,可用命令包括 pkg-install --list(列出已安装包)、pkg-install --search <keyword>(按关键词搜索)、pkg-install --info <package>(查看包详情)、pkg-install <package>(安装)、pkg-install <package>=<version>(安装指定版本)以及 pkg-install --remove <package>(卸载);
  • 包持久化:通过 pkg-install 安装的包在同一应用版本内跨容器重启保持;应用升级时,OpenCode 会记录已安装包并在新版初始化后自动重装。

通过 AI 聊天安装系统包

web-preview:容器内开发服务器的反向代理预览

web-preview 技能负责在 OpenCode 容器内启动开发服务器,并通过内置反向代理将其暴露到浏览器。在聊天中描述你的需求即可,例如:

Start the web project in this folder on port 5544

OpenCode 会启动服务器、确认运行状态,并返回一个预览 URL:

https://<your-OpenCode-domain>/__preview/<port>/

其中域名与你访问 OpenCode 时浏览器地址栏中显示的域名一致。如果技能未自动激活,可以手动加载:

/skill load web-preview

从 docs/use-cases/opencode-omo.md 的实现细节看,Olares 还维护了一个 olares-baseline-instructions.md 基线指令文件(位于 ~/.config/opencode/,每次启动刷新),其中包含 Web 预览、包管理与 Olares 域名约定——这正是 web-preview 技能在 Olares 环境下能稳定工作的底层支撑:技能负责行为指令,基线指令负责环境约定,二者配合完成"容器内起服务、反向代理对外暴露"的完整链路。

管理技能:列出与手动加载

在 OpenCode 聊天框中输入以下命令即可管理技能:

/skill list
/skill load <skill-name>

/skill list 列出当前可用的全部技能;/skill load <skill-name> 手动加载指定技能(例如 system-admin 或 web-preview)。

技能文件的存储位置

技能文件是存储在以下位置的 Markdown 文件:

范围 Olares Files 中的路径
全局(所有项目) Application/Data/opencode/.config/opencode/skills/
项目级别 Home/Code/<project>/.opencode/skills/

如果你想自定义技能,只需按照 OpenCode 的技能格式编写 Markdown 指令文件,并放入对应作用域的 skills/ 目录即可。需要注意的是,Olares 对全局目录下 web-preview 与 system-admin 两个技能目录采用每次启动强制更新策略,因此如果在这两个目录中做自定义修改,会被 Olares 的托管更新覆盖;自定义技能建议放在项目级目录或新建独立技能目录。

插件(Plugins):运行时能力的注入器

插件是 npm 包或本地脚本,可在运行时扩展 OpenCode。与技能不同,插件在启动时加载并接入执行管道,可以持续影响 OpenCode 的行为。

作为 npm 包安装

在 OpenCode 配置文件的 plugin 字段中声明插件包。配置文件按作用域区分:

范围 Files 中的配置文件
全局 Application/Data/opencode/.config/opencode/opencode.json
项目级别 项目根目录的 opencode.json

示例配置:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-helicone-session",
    "opencode-wakatime"
  ]
}

OpenCode 在启动时解析并安装声明的 npm 包,并将它们缓存在 ~/.cache/opencode/node_modules/ 目录中。因此:

  • 修改 plugin 字段后需要重启 OpenCode 才能生效;
  • 声明的是包名,OpenCode 会自行解析与安装,无需手动 npm install。

需要留意的是,在 Olares 上全局配置目录 ~/.config/opencode/ 下可能同时存在两个配置文件:

  • opencode.jsonc:首次通过 UI 添加自定义 provider 时由 OpenCode 自动创建;
  • opencode.json:由 Olares 构建为插件密集型场景添加。

OpenCode 在运行时合并这两个文件,因此二者并存是预期行为(详见 docs/use-cases/opencode-issues.md)。Olares 自身也通过全局 opencode.json 的 plugin 字段预注册了 oh-my-openagent 插件,用于多代理协作场景;Olares 托管的管理项只写入全局配置目录,不会写入工作区的 opencode.json,你在工作区配置中自行添加的内容会被保留(详见 docs/use-cases/opencode-omo.md)。

作为本地文件安装

你也可以将 .js 或 .ts 文件放入插件目录,OpenCode 会在启动时自动加载它们。无需额外注册:

范围 Olares Files 中的路径
全局插件 Application/Data/opencode/.config/opencode/plugins/
项目级别插件 Home/Code/<project>/.opencode/plugins/

本地插件非常适合团队内部分发的私有扩展:把脚本放入目录、重启 OpenCode 即可生效,不需要发布到 npm。

热门社区插件

以下社区插件可以显著扩展 OpenCode 的能力:

插件 描述
opencode-wakatime 跟踪 OpenCode 使用时间
opencode-firecrawl 网页爬取和搜索
oh-my-opencode 后台代理、LSP/AST 工具和预设代理
opencode-supermemory 跨会话持久记忆
opencode-pty 让 AI 在 PTY 中运行并与后台进程交互

其中 oh-my-opencode 与 Olares 集成度最高——它被预注册在全局 opencode.json 的 plugin 字段中,安装于容器内的 /usr/local/lib/node_modules/oh-my-opencode/,并随系统快照持久化;配合 ~/.config/opencode/oh-my-openagent.json(首次安装时写入的推荐模型与回退链配置)即可启用多代理协作。

实战注意事项

结合 docs/use-cases/opencode-issues.md 等仓库文档,在扩展 OpenCode 时需留意以下环境特性:

  1. Alpine/musl 环境限制:OpenCode 容器基于 Alpine Linux(musl libc),依赖 glibc 的包(如部分 Node.js 原生模块或含 C 扩展的 Python 包)可能无法安装或运行。系统级包应优先使用 pkg-install 安装。
  2. ARM64 设备上的终端限制:终端面板依赖 bun-pty(需要 glibc),在 ARM64 设备的 Alpine 容器中无法加载原生 PTY 库,可改用 Control Hub 中的容器终端。
  3. 前端资源来自 CDN:OpenCode 前端资源在运行时从 CDN 加载而非本地打包,CDN 故障时页面可能白屏(控制台报 TypeError: ot(...) is not a function),可先尝试强制刷新(Ctrl+Shift+R / Cmd+Shift+R)。
  4. 配置修改需重启生效:无论是声明插件还是编辑 provider 配置,保存后都要重启 OpenCode(从 Settings > Applications 中重启)才能应用。
  5. 作用域选择:全局配置放在 Application/Data/opencode/.config/opencode/,项目级配置放在项目根目录;同名文件(opencode.jsonc 与 opencode.json)会被运行时合并,编辑时注意避免重命名冲突(参见 issues 文档中的临时改名方案)。

了解更多

登录后查看全文
Terminus