Omarchy 中的 Quickshell：桌面 Shell、插件、QML 与诊断

Quickshell 是用 QML 构建桌面界面的工具包与运行时，Omarchy Shell 是 Omarchy 基于它构建的界面。两者相关但不等同：只安装 Quickshell，不会重建 Omarchy 菜单、插件配置与服务。本页解释固定的 Omarchy Shell 集成，较早 Waybar 安装应使用对应文档。

上游入门教 QML 窗口与响应式组件，Omarchy Shell 说明解释宿主与 IPC。完整分类列表见桌面交互层。

一次点击如何到达系统能力

用户点击顶栏组件
  → Omarchy Shell 打开面板/插件
  → 插件读取或请求后台能力
  → 后台改变或报告状态
  → 响应式界面显示新状态

Hyprland 呈现这些界面；
Quickshell 承载它们，不自行管理所有后台服务。

桌面控件	后台边界	界面可见不代表什么
网络面板	NetworkManager	网卡已连上或可用
音频面板	PipeWire/WirePlumber 集成	正确扬声器或麦克风路由已选中
电池组件	电源/设备信息	休眠或电池健康已经解决
工作区组件	Hyprland 状态与动作	每个工作区都分配到预期屏幕
通知界面	通知服务和应用请求	应用确实发出通知

网络面板能开却连不上，应同时检查网络后台；窗口与键盘正常而所有控件消失，则先检查 Shell。Hyprland专题解释合成器职责。

一个宿主，多种插件

固定实现由一个长时间运行的 Quickshell 实例承载顶栏、组件、面板、覆盖界面、菜单与服务。bar widget 属于顶栏，完整 bar 插件替换顶栏，service 可以没有可见界面。同一时间只启用一个完整顶栏；选择的替代项不能加载时，文档描述会回退到内置顶栏。

所以“重启顶栏”可能不只是重启一条像素：多个控件与服务共用宿主。部分保持加载的服务在代码重载时保留原实例，修改代码需要主动重启 Shell。不要在依赖活动锁屏操作时重启它。

选择正确定制层

固定布局的层	用途	常见误区
~/.config/omarchy/shell.json	布局、选定插件与个人设置	用几行示例替换整个文件
~/.config/omarchy/shell.toml	个人外观覆盖	期待切主题清除本地固定尺寸
当前主题 shell.toml	主题外观 token	把生成文件当永久源
~/.config/omarchy/plugins/<id>/	个人/安装插件源	混淆个人克隆与内置原件
系统 shell/ 目录	宿主与内置实现	为小组件偏好直接改系统代码

调整顺序与时钟格式，优先用顶栏指南和支持的控件。设置无法表达行为时才进入 QML，不必先学源码才能移动时钟。

查看状态，不启动重复桌面

在该用户的活动桌面中运行：

omarchy-shell shell ping
omarchy plugin list
pgrep -af quickshell

第一条是固定宿主的 IPC 健康查询；成功只证明宿主回应，不证明每个插件与后台都正常。清单用于区分安装/活动插件。进程名称可能包含多个实例或命令行，不是完整诊断。

Shell 未运行时 wrapper 会失败，静默 -q 是尽力执行模式，不适合需要看到错误的调查。直接 qs/quickshell 可能选中另一配置，不要作为健康检查启动第二份。日志与 CLI 功能先查已安装的 qs --help，再匹配上游版本，不猜通用日志路径。

观察	下一步
IPC 无应答，窗口正常	宿主启动、进程、配置与会话环境
IPC 有应答，一个组件缺失	位置、启用状态与插件加载错误
面板能开但操作失败	后台与目标设备/动作
切主题后外观错误	个人 TOML 覆盖与主题应用
两个顶栏重叠	多个宿主/配置或另一个顶栏被启动
改代码没有效果	是否改选中的克隆、保持加载服务、重载生命周期

定位并恢复损坏个人设置/插件后，此版本可有意识地使用 omarchy-restart-shell。先保留报错，不必为一个面板重启 Hyprland 或重置全部设置。

在独立小窗口学习 QML

上游教程常从会保留桌面空间的面板开始，第一次实验用独立浮动窗口更容易分清边界。查 qs --help 是否支持 --path/-p，并将运行时与 v0.3.0 FloatingWindow 参考匹配。

确认 ~/quickshell-guide 不含已有工作，再创建新的练习目录，将以下原创例子存为 shell.qml，不要替换 Omarchy 的 Shell 文件：

import Quickshell
import QtQuick

FloatingWindow {
    visible: true
    implicitWidth: 360
    implicitHeight: 140
    color: "#1f1f28"

    Text {
        anchors.centerIn: parent
        text: "My separate QML window"
        color: "#dcd7ba"
        font.pixelSize: 20
    }
}

在普通终端明确启动这个文件：

qs -p "$HOME/quickshell-guide/shell.qml"

预期只有一个独立学习窗口，Omarchy 顶栏不被替换。只改 text、保存，观察上游的实时重载。类型或属性未知时保留准确错误并核对对应版本，不改生产宿主去强行适配例子。在这个启动终端按 Ctrl + C 停止练习进程，或关闭它的窗口。不要结束所有 Quickshell 进程，那会连 Omarchy Shell 一起停止。

例子做了源码核对，没有在你的会话实测。目的是先连接 QML 对象、属性、子项目与文件选择，再学习插件和后台动作。

有意识地从练习进入插件

Omarchy 支持把内置插件克隆为个人 ID，并保留文档规定的集成身份。通过其克隆流程研究实际源码，保留原副本，先测试一项纯 UI 修改，再添加进程或服务动作。不需要改源码时，顶栏指南提供更小的配置任务。

插件以用户权限运行在共享宿主中，不是沙箱。固定版本的第三方添加流程先禁用供审阅，更新会展示改动。API facade 限制支持的集成接口，但不能保证未知 QML 无法访问文件或进程。启用前审查代码与依赖，不为缩短安装而跳过正常提示。

恢复时还原个人文件或禁用具体错误插件，再查状态。文档描述移除活动内置克隆会回到内置源，操作前保留自己的修改。有效报告包含 Omarchy/Quickshell 版本、插件 ID、最后改动、IPC 结果与准确加载错误，才能区分工具包、宿主集成和后台故障，不把缺一个图标都叫 Quickshell bug。