Shell 插件

Omarchy 桌面作为一个名为 omarchy-shell 的长期运行 Quickshell 进程工作；屏幕上几乎所有内容都是其中的插件。顶部栏是插件，从中展开的面板、表情选择器和剪贴板管理器等全屏覆盖层、Omarchy 菜单本身、锁屏、polkit 对话框，以及监测电池并在夜间调暖屏幕的无界面服务，也都是插件。

这不只是实现细节。它意味着你无需改动 Omarchy 的任何一行源码，就可以关闭、替换桌面的某些部分，或编写自己的插件。

第一方插件随 Omarchy 提供，位于 $OMARCHY_PATH/shell/plugins/。你自行添加的内容——自己的实验或从 GitHub 找到的插件——位于 ~/.config/omarchy/plugins/。启动时两者以相同方式被发现，但内置插件可获得受信任的 Shell 接口，第三方插件只能获得限定在自身服务和生命周期内的有限接口。内置插件的克隆仅保留实现原有行为所需的源特定配置与 UI 调用。

查看已安装插件

omarchy plugin list

该命令会输出每个已发现插件的 ID、是否启用、是第一方还是第三方、插件类型和显示名称。如需供其他程序处理，请添加 --json。

插件 ID 使用命名空间。所有内置插件均以 omarchy. 开头，例如 omarchy.clock、omarchy.network、omarchy.notifications；该命名空间被保留，第三方插件不能使用它。

启用与停用

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

也可使用菜单：设置 > 插件 提供启用、停用、添加、克隆和移除操作；每项操作的选择器只显示适用的插件。

启用状态保存在 ~/.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 后要求确认。请认真对待这一提示。第三方插件接口不会直接暴露认证服务，替代顶部栏只能获得为已配置的非认证 UI 提供的有限能力。可视化插件仍会共享 Shell 的 QML 场景并能遍历普通父对象；同时，所有插件代码都能访问用户账户可访问的一切内容。认证状态通过将相关服务置于不可到达的宿主对象图之外而单独保护。只添加你愿意运行的仓库，并在启用前阅读其代码。

替代顶部栏可渲染已安装的小组件，但由服务支持的第三方小组件在其中可能功能受限，因为顶部栏不能请求其他插件的实时服务对象。如果这类小组件需要其配套服务，请切回内置的 omarchy.bar。

随后，系统会将仓库克隆至暂存目录、验证清单；若已有其他插件声明同一 ID，则拒绝安装；验证通过后将其移动至 ~/.config/omarchy/plugins/<id>/。未指定 --enable 时，系统会询问是否立即启用，你可以选择否并先阅读代码。它不会运行插件中的任何内容、不会执行安装钩子、也不会请求 sudo——只会克隆文件、检查清单，并通过 IPC 切换一个状态位。

更新会对同一检出执行快进拉取：

omarchy plugin update acme.weather
omarchy plugin update

未指定 ID 时，它会更新所有由 Git 管理的插件。应用前会显示差异；如果本地修改导致无法快进，则拒绝更新；如果新版本未通过验证，则会回滚。

omarchy plugin remove acme.weather

移除时会先停用插件：若它是 Git 检出则删除（仓库仍在上游），若是符号链接则解除链接。没有 Git 仓库的手工插件目录不会被直接删除，而是移至插件目录中的带时间戳备份。

克隆内置插件以修改

这是其中最实用的部分。如果想改变内置小组件的行为，不要编辑 $OMARCHY_PATH 下的文件——它们属于软件包，下次更新会将其覆盖。请改用克隆：

omarchy plugin clone omarchy.clock

该命令会将整个插件复制到 ~/.config/omarchy/plugins/dhh.clock（使用你的用户名，而不是示例中的用户名），将其改名为“我的时钟”、启用它，并将 Shell 从内置版本切换至你的副本——同时保留现有顶部栏小组件的位置和设置。添加 --edit 可立即在 $EDITOR 中打开新目录，这也是菜单 设置 > 插件 > 克隆插件 的操作方式。

用户名此前缀可保证克隆的 ID 专属于你，分享时不会与他人冲突。针对原始内置 ID 的调用会被路由到你的克隆，因此引用 omarchy.clock 的内容无需更新。如果改坏了，运行 omarchy plugin remove dhh.clock 就能恢复内置版本。

在 ~/.config/omarchy/plugins/ 下任意位置保存文件，都会自动重新加载插件代码，因此可保持编辑器打开并即时观察修改生效。

编写自己的插件

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

类型	说明
bar-widget	活动顶部栏可放入某个区域的组件
panel	常驻或可呼出的浮动窗口
overlay	全屏覆盖层
menu	可呼出的菜单界面
service	没有 UI 的无界面单例服务
bar	替换内置顶部栏的完整顶部栏

一个插件可以同时声明多种类型——媒体插件既是 service，也是 bar-widget。顶部栏小组件会额外获得 barWidget 区块，其中包含显示名称、分类、可选的 defaultSection，以及表示是否适合在顶部栏中放置多个实例的 allowMultiple。大多数小组件将其设为 false；间隔器和指示器则设为 true。

发布前，请进行检查：

omarchy plugin validate ./my-plugin

该命令运行与 Shell 加载时相同的检查：模式版本、必填字段、未被保留的 ID、安全且真实存在的相对路径入口、每个声明类型对应的入口，以及目录内不存在任何符号链接。

开发插件时，请参阅 Shell 参考文档和第一方插件目录。

与世界分享你的插件

完成自己喜欢的插件后，请将它放入公开 Git 仓库。这就是完整的分发机制——任何人随后都可针对你的 URL 运行 omarchy plugin add，在数秒内让它运行起来。

为方便他人找到它，请将其列在 omarchyplugins.com。这是 Omarchy Shell 插件的社区目录；当你想知道是否已有人构建了计划编写的小组件时，这里是首要查找地点。开始前不妨先浏览一下！