Shell 插件体系 (Plugins)

Omarchy 桌面作为名为 omarchy-shell 的单一长生命周期 Quickshell 进程运行，你在屏幕上看到的几乎一切都是其内部的插件 (Plugin)。状态栏是插件，从状态栏下拉的控制面板是插件，Emoji 选择器和剪贴板管理器等全屏覆盖层是插件，Omarchy 菜单本身、锁屏界面、Polkit 提权认证弹窗，乃至监听电池电量和夜间护眼色温的无界面后台服务也全部都是插件。

这绝不仅仅是一个底层实现细节。它意味着你可以自由关闭桌面的某些部分、替换它们，或者无需修改 Omarchy 任何一行源码即可编写属于你自己的桌面组件。

官方第一方插件随 Omarchy 一同分发并存放在 $OMARCHY_PATH/shell/plugins/ 中。你自己添加的任何内容 —— 你自己的实验项目，或从 GitHub 上找到的社区插件 —— 均存放在 ~/.config/omarchy/plugins/ 目录下。两者在启动时以完全相同的方式被自动扫描发现，唯一的区别只是磁盘存放路径不同。

查看已安装的插件

omarchy plugin list

该命令会列出所有扫描到的插件及其 ID、是否启用、属于第一方还是第三方、插件类型以及显示名称。若需与其他脚本集成，可加上 --json 参数。

插件 ID 采用命名空间隔离。内置的第一方插件均以 omarchy. 开头（如 omarchy.clock、omarchy.network、omarchy.notifications），该命名空间受到系统保留保护，第三方插件无法占用。

启用与禁用插件

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

或者通过图形菜单操作：进入 Setup > Plugins，其中提供了 Enable（启用）、Disable（禁用）、Add（添加）、Clone（克隆）和 Remove（移除）选项，每个选项都会弹出经过智能过滤的选择器。

插件的启用状态保存在 ~/.config/omarchy/shell.json 中。第三方插件只要其 ID 出现在该文件中的任意位置（例如状态栏布局配置、plugins[] 列表或 bar.id）即视为启用。而对于非状态栏微件的第一方插件则恰好相反：它们默认全部处于启用状态，只有显式列入 disabledPlugins[] 中才会被关闭。

完整状态栏插件没有“关闭”状态 —— 系统始终需要恰好一个状态栏，因此你是通过启用另一个状态栏来替换它。关于状态栏微件的布局排列请参见顶部状态栏。

从 Git 安装第三方插件

第三方插件本质上就是一个根目录下包含 manifest.json 的 Git 仓库。

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

在执行任何操作之前，命令行会明确告知你：插件将作为未经沙箱隔离的任意代码在常驻 Shell 进程中运行，并展示仓库 URL 要求你确认。请务必认真对待：插件不是静态配置文件，而是伴随你整个登录会话持续运行的可执行代码，拥有你当前用户账户所能触及的一切系统权限。请仅添加你信任的仓库，并在启用前仔细审阅源码。

确认后，系统会将仓库克隆到临时暂存目录，验证其清单文件，若该 ID 已被其他插件占用则会拒绝安装，最后移动到 ~/.config/omarchy/plugins/<id>/。若未附加 --enable 参数，它会询问你是否现在启用，你可以选择否并先审阅代码。整个过程不会运行插件内部的任何代码，不执行安装钩子，也绝不需要 sudo 提权 —— 它仅负责克隆文件、校验清单并通过 IPC 发送启用信号。

更新插件只需对该仓库执行 fast-forward pull：

omarchy plugin update acme.weather
omarchy plugin update

若不带 ID 参数，则会更新你安装的所有由 Git 管理的插件。它会在应用前展示 diff 代码差异，若存在未提交的本地冲突修改则会拒绝更新，并在新版本清单校验失败时自动回滚。

omarchy plugin remove acme.weather

移除插件会先将其禁用，若为 Git 检出目录则会将其删除（上游仓库依然完好），若为软链接则会取消链接。对于无 Git 仓库的手动创建插件目录，系统会将其移至带有时间戳的备份文件夹中，防止误删。

克隆内置插件进行二次修改

这是我最喜欢的设计。如果你想修改某个官方微件的行为，切勿直接编辑 $OMARCHY_PATH 下的文件 —— 那些属于软件包，下一次更新就会被覆盖。正确的做法是克隆它：

omarchy plugin clone omarchy.clock

这会将整个插件完整复制到 ~/.config/omarchy/plugins/<your-username>.clock 中，重命名为“My Clock”，自动将其启用，并将 Shell 状态栏从官方内置版本无缝切换到你的副本 —— 同时完整保留原状态栏微件的位置与设置。附加 --edit 参数可立即在 $EDITOR 中打开新目录，菜单中的 Setup > Plugins > Clone Plugin 正是为你执行此操作。

使用用户名作为前缀可以确保你的克隆副本 ID 独一无二，分享给他人时绝不会冲突。对原官方内置 ID 的调用会自动路由至你的克隆副本，因此任何引用 omarchy.clock 的地方都无需修改。如果不小心改坏了，只需运行 omarchy plugin remove <your-username>.clock 即可立即恢复使用官方内置版本。

在 ~/.config/omarchy/plugins/ 下保存任何文件都会自动触发插件代码热重载，因此你可以保持编辑器打开并实时预览改动效果。

开发属于你自己的插件

一个插件就是一个包含 manifest.json 和若干 QML 文件的目录。清单文件声明 schemaVersion: 1、id、name、version、一种或多种 kinds（插件类型），以及指向对应类型入口 QML 文件的 entryPoints 对象：

一个插件可以同时声明多种类型 —— 例如媒体播放插件既是 service 又是 bar-widget。状态栏微件还拥有一个额外的 barWidget 配置块，包含显示名称、分类、可选的 defaultSection（默认分区），以及 allowMultiple（是否允许在状态栏放置多个实例）。大多数微件设为 false，而间隙占位符和指示器则设为 true。

在发布插件前，可进行全面验证：

omarchy plugin validate ./my-plugin

这会运行与 Shell 在加载时完全相同的校验逻辑：Schema 版本、必填字段、非保留 ID、合法且实际存在的相对入口路径、所有声明类型均具备入口，以及目录内不存在任何软链接。

如需查阅完整规范，源码即是最佳文档：Omarchy 仓库中的 shell/README.md 详述了清单 Schema、Shell 的 IPC 契约以及 shell.json 的完整结构；shell/plugins/README.md 则列出了所有官方第一方插件的 ID、类型与入口点。

与全世界分享你的作品

一旦你制作出了满意的插件，只需将其推送到公开的 Git 仓库即可。这就是全部的分发机制 —— 任何人只需针对你的 URL 运行 omarchy plugin add 即可在数秒内安装并运行。

为了让更多人发现你的作品，可以将其提交到 omarchyplugins.com。这是 Omarchy Shell 插件的社区目录，也是寻找他人是否已经实现了你所需微件的最佳起点。动手开发前不妨先去逛逛！