Omarchy Plugins：安装、更新与安全指南

学会在 Omarchy Quattro 中查找、安装、启用、更新和移除 Shell 插件，并理解第三方 QML 插件的权限与安全风险。

Omarchy Quattro 把顶栏组件、面板、菜单、浮层和后台服务统一为 Shell Plugins。插件可以扩展桌面，但第三方插件不是浏览器扩展或静态主题：它会以当前用户权限在长驻 Shell 进程中执行 QML 与代码。

安装插件等于运行第三方代码

Omarchy 官方明确说明第三方插件不受沙箱保护，能够访问当前账号可访问的文件和资源。安装前应检查作者、仓库、许可证、代码和最近提交；工作设备不要安装来源不明的插件。

查看和启用插件

先列出当前可用插件：

omarchy plugin list

启用或关闭已经安装的插件：

omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather

第一方插件位于 $OMARCHY_PATH/shell/plugins/，用户安装的插件位于 ~/.config/omarchy/plugins/；启用状态记录在 ~/.config/omarchy/shell.json。修改前先复制自己的配置文件，不要直接改第一方插件目录。

从 Git 仓库安装社区插件

官方 CLI 可以克隆并校验插件清单：

omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

--enable 会在安装后启用插件。安装器会克隆仓库并验证 manifest，但这不等于代码经过安全审计。官方说明安装过程不会运行安装钩子或使用 sudo，插件启用后仍会在 Shell 中执行。

社区目录 Omarchy Plugins 可以用于发现插件，但目录收录不应被理解为安全背书。下载前至少检查：

仓库 URL 是否与作者公开链接一致；
是否有可读许可证、README 和变更记录；
QML/脚本是否读取密钥、浏览器资料、SSH 配置或执行外部命令；
最近更新是否突然更换维护者或加入混淆代码；
是否能在测试账号或非生产设备先验证。

更新、查看差异与回退

更新单个插件或全部插件：

omarchy plugin update acme.weather
omarchy plugin update

官方更新流程会显示差异，只接受 fast-forward 更新，并在新版本验证失败时回退。这些保护能减少意外损坏，却不能判断新增代码是否值得信任。更新前阅读 diff；若插件行为异常，先禁用再排查：

omarchy plugin disable acme.weather

确认不再需要后移除：

omarchy plugin remove acme.weather

如果 Shell 无法正常启动，应从 TTY 或恢复环境备份 ~/.config/omarchy/shell.json，再移走可疑的用户插件目录。不要在没有备份时一次删除整套配置。

开发或修改自己的插件

可以克隆第一方插件作为起点，再验证本地目录：

omarchy plugin clone omarchy.clock
omarchy plugin validate ./my-plugin

插件 manifest 当前使用 schemaVersion: 1 和 QML 入口。官方支持的类型包括 bar-widget、panel、overlay、menu、service 和 bar。版本升级可能改变接口，发布前应重新对照当前Shell Plugins 官方手册。

安装插件后检查什么

顶栏、通知、锁屏和快捷菜单是否仍能打开；
Shell 的 CPU、内存与日志是否出现异常；
插件断网或服务不可用时是否会阻塞桌面；
更新后是否新增权限、网络请求或外部命令；
禁用插件后问题是否消失。

想了解插件体系来自哪个版本，阅读 Omarchy Quattro 4.0 升级指南；需要恢复桌面时，按故障排查顺序保存日志并逐项隔离。

来源：Omarchy Shell Plugins 官方手册与 Omarchy v4.0.0 发布说明。