Omarchy 日常使用手册¶

本文按 Omarchy 3.8.5 @ 192.168.3.97（omarchy）实测写成，不是照抄官方手册。键位以这台机器上真正生效的 ~/.local/share/omarchy/default/hypr/bindings/tiling-v2.conf 和你自己改过的 ~/.config/hypr/bindings.conf 为准 —— 官方手册的若干条目和本机对不上，凡有出入都在"备注"列标了出来。

忘了快捷键就按 Super + K，那是系统内置的实时键位表（omarchy-menu-keybindings），永远和当前配置同步，比任何文档都可靠。

本机环境速记：

项目	实际值
Omarchy / Hyprland	3.8.5 / 0.56.2
终端	Ghostty 1.3.1（Alacritty 也装着，但不是默认）
浏览器	google-chrome-beta
编辑器	`nvim`（LazyVim）
联网	iwd + systemd-networkd（NetworkManager 已禁用）
顶栏 / 启动器 / 通知	waybar / walker / mako

1. 三个入口¶

Omarchy 的设计是"所有事都能从菜单走一遍"，快捷键只是加速。记住这四个就不会卡住：

快捷键	打开什么
`Super + Space`	应用启动器（walker）—— 启动程序、打开 web app
`Super + Alt + Space`	Omarchy 菜单 —— Apps / Learn / Trigger / Style / Setup / Install / Remove / Update / About / System
`Super + Escape`	系统菜单 —— 锁屏、注销、挂起、重启、关机
`Super + K`	键位速查表（实时读取当前配置）

装软件、换主题、配显示器、连 wifi、更新系统 —— 全部可以只走 Super + Alt + Space。

你的 ~/.config/hypr/bindings.conf 末尾有一段被注释掉的配置，可以把 Omarchy 菜单挪到 Super + Space（覆盖启动器）。想换的话取消那两行注释即可。

2. 常用快捷键¶

2.1 窗口与工作区¶

来源：tiling-v2.conf。

快捷键	作用	备注
`Super + W`	关闭窗口
`Ctrl + Alt + Delete`	关闭当前所有窗口
`Super + F`	全屏
`Super + Ctrl + F`	平铺内全屏（不遮顶栏）
`Super + Alt + F`	全宽
`Super + T`	浮动 / 平铺切换	旧版本是 `Super + Shift + V`
`Super + J`	切换分割方向（左右↔上下）
`Super + P`	伪平铺（保持窗口自然尺寸）
`Super + O`	把窗口"弹出"成浮动+置顶，跨工作区常驻
`Super + L`	切换工作区布局（dwindle ↔ scrolling）
`Super + ←/→/↑/↓`	移动焦点
`Super + Shift + ←/→/↑/↓`	与相邻窗口交换位置
`Super + 1..0`	跳到第 N 个工作区
`Super + Shift + 1..0`	把窗口丢到第 N 个工作区（跟随过去）
`Super + Shift + Alt + 1..0`	丢过去但不跟随
`Super + Tab` / `Super + Shift + Tab`	下一个 / 上一个工作区
`Super + Ctrl + Tab`	回到上一次待的工作区
`Super + 滚轮`	滚动切换工作区
`Super + 左键拖拽` / `Super + 右键拖拽`	移动 / 缩放窗口
`Super + -` / `Super + =`	横向调整窗口宽度
`Super + Shift + -` / `Super + Shift + =`	纵向调整窗口高度
`Alt + Tab` / `Alt + Shift + Tab`	在当前工作区内循环窗口
`Ctrl + Alt + Tab`	焦点切到下一个显示器
`Super + Shift + Alt + ←/→/↑/↓`	把整个工作区搬到指定方向的显示器

暂存区（scratchpad） —— 放临时窗口的隐藏工作区：

快捷键	作用
`Super + S`	呼出 / 收起暂存区
`Super + Alt + S`	把当前窗口丢进暂存区

窗口分组（tab 化） —— 多个窗口叠成一组，像标签页一样切：

快捷键	作用
`Super + G`	开启 / 关闭分组
`Super + Alt + G`	把当前窗口移出分组
`Super + Alt + Tab` / `Super + Alt + Shift + Tab`	组内切换窗口
`Super + Alt + 1..5`	直接跳到组内第 N 个窗口
`Super + Alt + ←/→/↑/↓`	把窗口并入该方向的分组
`Super + Ctrl + ←/→`	在分组内左右移动焦点

缩放：Super + / 循环放大缩放比例，Super + Alt + / 反向循环。

2.2 启动应用（本机定制）¶

⚠️ 这一节和官方手册差别最大。你把应用启动键统一改成了 Super + Shift + …，官方默认的 Super + B（浏览器）、Super + N（nvim）这类单键在本机不生效。

快捷键	启动什么	备注
`Super + Return`	终端（Ghostty），继承当前终端的工作目录	本机定制
`Super + Alt + Return`	终端并直接开一个 tmux 新会话	本机定制
`Super + Shift + Return`	浏览器（Chrome Beta）	官方默认亦同
`Super + Shift + Alt + B`	浏览器无痕窗口
`Super + Shift + F`	文件管理器（Nautilus）
`Super + Shift + Alt + F`	文件管理器，打开当前终端所在目录
`Super + Shift + N`	编辑器（nvim）
`Super + Shift + T`	活动监视器（btop）
`Super + Shift + D`	容器管理（lazydocker）
`Super + Shift + M`	Spotify
`Super + Shift + Alt + M`	cliamp（终端音乐播放器）
`Super + Shift + G`	Signal
`Super + Shift + O`	Obsidian
`Super + Shift + W`	Typora	本机新增
`Super + Shift + /`	1Password

Web app（本质是无边框 Chrome 窗口）：

快捷键	打开
`Super + Shift + A` / `Super + Shift + Alt + A`	ChatGPT / Grok
`Super + Shift + C` / `Super + Shift + E`	HEY 日历 / HEY 邮箱
`Super + Shift + Y`	YouTube
`Super + Shift + X` / `Super + Shift + Alt + X`	X / X 发帖
`Super + Shift + P`	Google Photos
`Super + Shift + Alt + G` / `Super + Shift + Ctrl + G`	WhatsApp / Google Messages

新增或删除 web app：菜单 Install > Web App / Remove > Web App。底层命令是 omarchy-webapp-install / omarchy-webapp-remove。 首次使用前先在普通浏览器里登录好账号，否则密码管理器会有兼容问题。

2.3 系统控制¶

快捷键	打开
`Super + Ctrl + W`	Wifi（impala）
`Super + Ctrl + B`	蓝牙（bluetui）
`Super + Ctrl + A`	音频（wiremix）
`Super + Ctrl + T`	活动监视器（btop）
`Super + Ctrl + S`	分享（LocalSend）
`Super + Ctrl + C`	截屏菜单
`Super + Ctrl + O`	开关切换菜单
`Super + Ctrl + H`	硬件菜单
`Super + Ctrl + E`	Emoji 选择器
`Super + Ctrl + L`	锁屏
`Super + Ctrl + .`	转码菜单

2.4 剪贴板与截屏¶

Omarchy 做了"通用剪贴板"，让 Super + C/V 在终端和 GUI 里行为一致：

快捷键	作用	备注
`Super + C`	复制	终端里也能用
`Super + V`	粘贴
`Super + X`	剪切	终端里无效
`Super + Ctrl + V`	剪贴板历史

快捷键	作用
`PrintScreen`	截图
`Alt + PrintScreen`	录屏
`Super + PrintScreen`	取色器
`Super + Ctrl + PrintScreen`	框选区域 OCR 取字到剪贴板
`Super + Ctrl + C`	截屏菜单（没有 PrintScreen 键时用）
`Alt + Shift + L`	复制当前 web app / Chrome 页面的 URL

截图默认路径是 $OMARCHY_SCREENSHOT_DIR → $XDG_PICTURES_DIR → ~/Pictures（依次回退）。想改位置：编辑 ~/.config/uwsm/default，取消 OMARCHY_SCREENSHOT_DIR / OMARCHY_SCREENRECORD_DIR 的注释（目录要先建好），重启生效。

2.5 通知、提醒、显示切换¶

快捷键	作用
`Super + ,` / `Super + Shift + ,`	关掉最新一条 / 全部通知
`Super + Ctrl + ,`	免打扰开关
`Super + Alt + ,`	点开最近一条通知
`Super + Ctrl + I`	禁止 / 允许自动休眠锁屏
`Super + Ctrl + N`	夜灯（色温）开关
`Super + Ctrl + Z` / `Super + Ctrl + Alt + Z`	屏幕放大（可连按）/ 复位
`Super + Ctrl + Delete`	开关笔记本内屏
`Super + Ctrl + Alt + Delete`	内屏镜像模式
`Super + Shift + Space`	显示 / 隐藏顶栏
`Super + Backspace`	窗口透明度开关
`Super + Shift + Backspace`	窗口间距（gaps）开关
`Super + Ctrl + Alt + T/B/W`	以通知形式显示时间 / 电量 / 天气
`Super + Ctrl + R`	设一个提醒；`+Alt` 查看全部，`+Shift` 清空

音量和亮度走多媒体键：Shift + 亮度键 直接到最大/最小，Alt + 亮度/音量键 是 1% 微调。

2.6 tmux（`Super + Alt + Return`）¶

前缀键是 Ctrl + Space（Ctrl + B 也保留可用）。

快捷键	作用
`前缀 + v` / `前缀 + h`	竖分屏 / 横分屏
`前缀 + x` / `前缀 + z`	关闭窗格 / 窗格全屏切换
`Ctrl + Alt + 方向键`	在窗格间移动
`Ctrl + Alt + Shift + 方向键`	调整窗格大小
`前缀 + c` / `前缀 + k` / `前缀 + r`	新建 / 关闭 / 重命名 window
`Alt + 1..9`，`Alt + ←/→`	切换 window
`前缀 + C/K/R/N/P`，`Alt + ↑/↓`	新建/关闭/重命名/下一个/上一个 session
`前缀 + s` / `前缀 + d`	列出 session / detach
`前缀 + [`，然后 `v` 选择、`y` 复制	复制模式（vi 风格）

三个开发布局函数（很好用）：

Bash
tdl <ai> [<second_ai>]    # 一屏三格：编辑器 + AI + 终端
tdlm <ai> [<second_ai>]   # 对每个子目录各开一套上面的布局
tsl <数量> <命令>          # 开 N 个窗格同时跑同一条命令

本机还有现成别名：ic = tdl c，ix = tdl cx，icx = tdl c cx。

2.7 Ghostty 终端¶

快捷键	作用
`Ctrl + Shift + E` / `Ctrl + Shift + O`	下方分屏 / 右侧分屏
`Ctrl + Alt + 方向键`	在分屏间移动
`Ctrl + Shift + T`	新标签页
`Ctrl + Shift + ←/→`	切换标签页；`Alt + 数字` 直接跳
`Shift + PgUp/PgDn`	翻滚动历史
`Ctrl + 左键`	打开链接

3. 常用设置¶

3.1 联网¶

⚠️ 本机用的是 iwd + systemd-networkd，NetworkManager 是禁用状态。 nmcli / nmtui 虽然装着，但对本机无效，别用。

方式	怎么做
图形/TUI	`Super + Ctrl + W` → impala。`Tab` 切换区域，`Space` 选网络，按提示输密码
顶栏	点 waybar 上的 wifi 图标，同样打开 impala
菜单	`Super + Alt + Space` → `Setup > Wifi`
纯命令行	`iwctl` → `station wlan0 scan` / `get-networks` / `connect <SSID>`

出问题时：

Bash
omarchy-restart-wifi        # 重启无线栈
omarchy-setup-dns           # 重配 DNS（systemd-resolved 在本机是 masked 的）
omarchy-wifi-powersave      # 省电模式开关，某些网卡断流是它引起的

代理：见 §3.6，那一节是本机最容易踩坑的地方。

3.2 壁纸 / 背景¶

操作	怎么做
换一张	`Super + Ctrl + Space`，在当前主题的背景里选
加自己的图	丢进 `~/.config/omarchy/backgrounds/<主题名>/`，立刻出现在选择器里
从菜单加	`Super + Alt + Space` → `Install > Style > Background`，会直接打开当前主题的背景目录

背景是按主题分目录的 —— 换主题就换了一批壁纸，这是设计如此，不是 bug。所以想要更多壁纸，最省事的办法是多装几个主题，见 §5。单独找图推荐 https://github.com/dharmx/walls。

3.3 显示器¶

配置文件：~/.config/hypr/monitors.conf（菜单 Setup > Monitors 会直接用编辑器打开它）。

Omarchy 默认按 2x 高分屏调优。屏幕不是视网膜级的话按下表改：

Text Only
# 27"/32" 4K
env = GDK_SCALE,1.75
monitor=,preferred,auto,1.666667

# 1080p / 1440p
env = GDK_SCALE,1
monitor=,preferred,auto,1

要点：

monitor= 管 Wayland 原生程序，GDK_SCALE 管 GTK/Electron 程序，两个要配套改。
GDK_SCALE 只影响改完之后新启动的程序，已开的窗口不会变。
临时试比例用 Super + /（循环 1x / 1.6x / 2x / 3x），不用改配置。
单块屏想关掉：monitor=DP-2,disable。屏幕名用 hyprctl monitors 查。
外接屏默认是扩展；要镜像按 Super + Ctrl + Alt + Delete。
合盖自动关内屏，开盖自动恢复。

3.4 键盘 / 鼠标 / 触控板¶

配置文件：~/.config/hypr/input.conf（菜单 Setup > Input）。

Text Only
input {
  kb_layout = us,fr                              # 多布局
  kb_options = compose:caps,grp:alts_toggle      # 左右 Alt 一起按切换布局
  repeat_rate = 40
  repeat_delay = 600
  sensitivity = 0.35

  touchpad {
    natural_scroll = true
    clickfinger_behavior = true                  # 两指点击 = 右键
    scroll_factor = 0.3
  }
}

CapsLock 被征用成了 compose 键（compose:caps），所以它不会切大小写 —— 这是特性不是故障。它的用途是快捷输入：

CapsLock M S → 😄，CapsLock M Y → 👍，CapsLock M H → ❤️ …（M = emoji 前缀）
CapsLock Space Space → —（长破折号），CapsLock Space N / E → 你的姓名 / 邮箱

想要回正常 CapsLock，把 compose:caps 改成 compose:ralt（改用右 Alt 当 compose）。把 Alt 和 Super 对调（Mac 键盘习惯）：kb_options = compose:caps,altwin:swap_alt_win。

3.5 配置文件是怎么组织的（重要）¶

~/.config/hypr/hyprland.conf 是总入口，顺序是先 source 官方默认，再 source 你的文件：

Text Only
~/.local/share/omarchy/default/hypr/...   ← 官方默认，每次 omarchy update 都会被覆盖
~/.config/hypr/monitors.conf              ← 你的，覆盖上面的设置
~/.config/hypr/input.conf
~/.config/hypr/bindings.conf
~/.config/hypr/envs.conf
~/.config/hypr/looknfeel.conf
~/.config/hypr/autostart.conf

规则：只改 ~/.config/hypr/ 下的文件，永远不要动 ~/.local/share/omarchy/default/。 后者是 git 仓库，更新时会被直接覆盖，改了等于白改。

要覆盖官方的某个键位，在自己的 bindings.conf 里先 unbind 再重新 bindd：

Text Only
unbind = SUPER, SPACE
bindd = SUPER, SPACE, Omarchy menu, exec, omarchy-menu

改完 Hyprland 配置会自动重载；不放心就 hyprctl reload。

3.6 代理（clash-verge）——只记一句话¶

永远用「规则」模式。永远不要用「全局」模式。

规则模式下，clash 配置里那 7000 多条规则才生效，国内域名（DOMAIN-SUFFIX,cn / GEOIP,CN）直连、国外走节点，各走各的。全局模式会把这些规则全部作废，把国内镜像也塞给机场节点 —— 而机场普遍把国内域名拉黑，于是下载全崩。2026-08-12 的更新失败就是这么来的，详见下面的"踩过的坑"。

本机现在的配置（已实测可用）¶

开关	状态	为什么
模式	规则	唯一重要的一项
TUN	关	用不着；开了也不解决问题，只是多一层
系统代理	关	同上
混合端口 7897	开（默认）	唯一真正在干活的东西

程序怎么用上代理：~/.config/hypr/hyprland.conf 末尾硬写了三行环境变量， 凡是从 Hyprland 启动的程序（终端、浏览器、编辑器…）都会继承：

Text Only
env = http_proxy, http://127.0.0.1:7897
env = https_proxy, http://127.0.0.1:7897
env = all_proxy, socks5h://127.0.0.1:7897

换端口改这里，改完重启 Hyprland 生效（只影响之后启动的程序）。

2026-08-13 修过第三行，原来写的是 sockets://127.0.0.1:7898 —— sockets:// 不是合法 scheme，7898 也根本没在监听。clash-verge 只开混合端口 7897（配置里那五个端口 7895/7896/7897/7898/7899 只有 7897 生效，ss -tlnp 一看便知）。

注意必须是 socks5h 而不是 socks5：socks5 让本机先解析域名、只把 IP 交给 mihomo，规则匹配不到域名就会走错节点（实测清华源直接失败）；socks5h 把域名交给 mihomo 解析，规则才生效。改完实测 google 204、清华源 200，两边都对。

这套组合的好处是分工干净：GUI 程序有 env → 国外能通、国内直连； sudo pacman 因为 sudo 会剥掉环境变量 → 纯直连，国内镜像满速。实测：

路径	google	清华镜像
走 7897	通	6.8 MB/s（规则判直连）
不走代理	超时	1.4 MB/s

出问题时的 30 秒自查¶

按这个顺序，第一条最常中：

Bash
# 1. 模式是不是被切成 global 了？（唯一答案应该是 rule）
curl -s --unix-socket /tmp/verge/verge-mihomo.sock http://localhost/configs \
  | grep -o '"mode":"[a-z]*"'

# 2. 核心在不在
systemctl is-active clash-verge-service
ss -ltn | grep 7897

# 3. 国内外各探一发
curl -m 8 -o /dev/null -w 'cn=%{http_code}\n' https://mirrors.tuna.tsinghua.edu.cn/archlinux/extra/os/x86_64/extra.db
https_proxy=http://127.0.0.1:7897 curl -m 8 -o /dev/null -w 'out=%{http_code}\n' https://www.google.com/generate_204

临时把模式掰回规则（不动配置文件，立刻生效）：

Bash
curl --unix-socket /tmp/verge/verge-mihomo.sock -X PATCH \
  -H 'Content-Type: application/json' -d '{"mode":"rule"}' http://localhost/configs

⚠️ 这只是运行时改动，重启就没了。要长期生效必须去 GUI / 托盘点一下「规则」 —— 模式持久化在 config.yaml，那个文件由 clash-verge 自己重写，手改会被覆盖。

踩过的坑（别再花一晚上重查）¶

① 报 TLS 错误，其实是 407。 全局模式下访问被拉黑的国内镜像，机场返回的是一段明文 HTTP/1.1 407 ... forbidden。打到 443 端口上，curl 把这段明文读成 TLS connect error: wrong version number，看着像证书/TLS 故障，根本不是。辨认方法：把同一个 URL 换成 http:// 再拉一次，407 就现原形了；响应头里 Date: Wed, 20 Jan 2021 这种硬编码日期是机场自己伪造响应的指纹。

② "关掉 TUN 就好了" 是错的。 TUN、系统代理、环境变量是三条并行的入口，关掉 TUN 只是把同样的流量挪到 7897，还是同一个节点、同一份黑名单。问题从来不在入口，在模式。

③ 别再搭 ip rule + /etc/hosts 那套绕过。 规则模式下国内镜像本来就直连，绕过纯属多余，而且 ip rule 只在内存里、重启即失效，镜像 IP 还会变。

④ GUI 报 "IPC path not ready" / TUN 打不开，是 /tmp/verge 的权限问题，和上面这些无关。systemctl restart clash-verge-service 通常就能恢复（服务里挂了个 ExecStartPost 重新打 ACL）。每次 clash-verge-rev-bin 升级后都可能复发。

4. 开发者相关¶

4.1 命令行工具（已预装，直接用）¶

工具	用法
fzf	`ff` 模糊找文件（带 bat 预览）；`Ctrl + R` 搜命令历史；`eff` 直接用编辑器打开选中的文件
zoxide	`cd` 已被替换成 zoxide —— `cd oma` 能跳到之前去过的任何含 "oma" 的目录
ripgrep	`rg <pattern> <path>` 搜文件内容
eza	`ls`（带图标详情）/ `lsa`（含隐藏）/ `lt`（树形两层）/ `lta`
fd	`fd <name>` 替代 `find`，语法友好得多
try	建一个带日期戳的实验目录，统一放在 `~/Work/tries`

本机现成别名：c=opencode，cx=claude code（bypass 权限），cy=codex， d=docker，g=git，t=tmux attach（没有就新建 Work 会话），n=nvim（无参数则开当前目录）， .. / ... / .... 逐级上跳，mup=mise up。

Shell 函数：

Bash
compress <文件或目录>      # 打成 tar.gz
decompress <file.tar.gz>  # 解开
iso2sd <image.iso>        # 交互式选盘，烧录启动盘
format-drive              # 把整块盘格成单个 exFAT 分区（Windows/macOS 也能读）

fip <端口...>              # 把远程主机的端口 SSH 转发到本地
dip <端口...>              # 断开转发
lip                       # 列出当前所有转发

fip 那组特别适合：在远程机器上跑 web 服务，转到 localhost 后就能拿到 secure-context 权限（websocket、剪贴板 API 等），不用折腾 SSL 证书。

4.2 TUI¶

工具	启动	常用键
lazygit	在 git 目录里敲 `lazygit`，或 nvim 里 `Space G G`	`Tab` 切面板，`Space` 暂存，`c` 提交，`?` 看全部
lazydocker	`Super + Shift + D`	`s` 停止容器，`r` 启动/重启，`?` 看全部
btop	`Super + Shift + T` 或 `Super + Ctrl + T`	CPU / 内存 / 磁盘 / 网络 / 进程
fastfetch	菜单 `About`	系统信息

4.3 语言与运行时¶

用 mise 管多版本：

Bash
mise use -g ruby        # 全局装并启用
mise i                  # 按项目目录下的 .ruby-version / .node-version 安装
mup                     # = mise up，升级

菜单 Install > Development 里可以一键配好 Rails、Node/bun/Deno、Laravel/Symfony、 .NET、OCaml、Zig、Elixir 等环境。

Docker 和 Docker Compose 已装好、用户权限也配好了。 Install > Development > Docker DB 可以起常用的开发数据库。

GitHub CLI：gh auth login 登录，之后 gh repo clone org/repo 能拉私有库。

4.4 Neovim（LazyVim）¶

快捷键	作用
`Space`	悬停显示所有可用命令（不记得就按它）
`Space Space`	模糊搜索打开文件
`Space S G`	全局搜索文件内容（ripgrep）
`Space E`	开关侧边栏
`Space G G`	打开 lazygit
`Ctrl + W W`	在侧栏和编辑区之间跳
`Shift + H` / `Shift + L`	左 / 右切换文件标签
`Space B D`	关闭当前标签

侧栏里：a 新建文件，A 新建目录，d 删除，m 移动，r 重命名，? 帮助。

想换编辑器：菜单 Install（VSCode / Cursor / Zed / Sublime / Helix），再到 Setup > Defaults > Editor 设成默认。VSCode、Cursor、VSCodium、Helix、Zed 支持主题联动。

4.5 AI 工具¶

命令	是什么
`c`	OpenCode（支持各家商业模型和开源权重模型）
`cx`	Claude Code，`--permission-mode bypassPermissions`
`cy`	Codex，`-s danger-full-access`
`codex` / `gemini` / `copilot` / `pi`	懒加载 stub，首次调用时用 npx 下载

加自己的 npm CLI：omarchy-npx-install <包名> [命令名]。

本地跑模型：菜单 Install > AI 里有 LM Studio（图形）和 Ollama（命令行）。

Omarchy 还带了一个实验性的 AI skill，让 agent 直接改系统配置（waybar、主题等），已经预配在 OpenCode 和支持 ~/.claude/skills 的 harness 里。 先跑 plan mode 看它要改什么，改坏了用 omarchy reinstall configs 还原。

5. 主题与外观¶

Super + Ctrl + Shift + Space 直接开主题选择器；或菜单 Style > Theme。

换主题会同时换掉：终端、Neovim、btop、mako 通知、waybar 顶栏、walker 启动器、 hyprlock 锁屏的配色。（Obsidian 例外，要在它自己的设置里选。）

选择器里的主题从哪来（两个目录的并集）¶

~/.config/omarchy/themes/ 只是其中一个。以 2026-08-13 为例：

Text Only
~/.config/omarchy/themes/        22   ← 你自己装的
~/.local/share/omarchy/themes/   19   ← Omarchy 自带的
合并去重                          41   ← 选择器里看到的

两边没有重名，也没有软链，所以就是 22 + 19 = 41。 omarchy-theme-list 的实现直接说明了这点：

Bash
{
  find ~/.config/omarchy/themes/ ...      # 用户装的
  find "$OMARCHY_PATH/themes/" ...        # 内置的，$OMARCHY_PATH = ~/.local/share/omarchy
} | sort -u

Super + Ctrl + Shift + Space 调的就是这个列表。

内置那 19 个：

Text Only
catppuccin  catppuccin-latte  ethereal   everforest  flexoki-light
gruvbox     hackerman         kanagawa   lumon       matte-black
miasma      nord              osaka-jade retro-82    ristretto
rose-pine   tokyo-night       vantablack white

它们随 omarchy update 更新，omarchy-theme-remove 删不掉（那个脚本只在 ~/.config/omarchy/themes/ 里找）；反过来 omarchy-theme-update 也只 pull 自装的那些。

开机解锁画面也能跟主题走：Style > Unlock。

装更多主题（顺着敲即可）¶

社区索引 https://omarchythemes.com/，233 个主题，比本机多得多。 每个主题自带壁纸，所以装主题就是拿壁纸，没有单独的壁纸源。

在站点上挑一个，进它的详情页，复制那个 GitHub 仓库链接
装上（会 clone 到 ~/.config/omarchy/themes/ 并立刻切过去）：

Bash
omarchy-theme-install https://github.com/jaredb1011/omarchy-adrift-theme

之后想让这些第三方主题跟上作者更新，自己跑：

Bash
omarchy-theme-update      # 对所有自装主题逐个 git pull

其余命令：

Bash
omarchy-theme-list          # 列出
omarchy-theme-set <名字>     # 切换
omarchy-theme-remove <名字>  # 删；不带参数会弹菜单让你选
omarchy-theme-bg-next       # 下一张背景（= Super + Ctrl + Space）

两个坑：

omarchy-theme-update 不在 omarchy update 里，不跑就永远停在装的那天。
它是 git pull，会覆盖主题目录里的 backgrounds/。自己加的壁纸要放 ~/.config/omarchy/backgrounds/<主题名>/（见 §3.2），那里才不会被动。

装完第三方主题后 Hyprland 报错¶

社区那 233 个主题里有不少是给老版 Hyprland 写的，装上一切换就会看到 invalid field blur: missing a value 这类提示。三件事要知道：

① 改 current/theme/ 没用，那是拷贝不是软链。 ~/.config/hypr/hyprland.conf source 的是 ~/.config/omarchy/current/theme/hyprland.conf，而 omarchy-theme-set 每次切主题都 rm -rf 再 cp -r 重建这个目录。 要改源头：~/.config/omarchy/themes/<主题名>/hyprland.conf。

② layerrule 的语法在 Hyprland 0.5x 变了，字段必须带值，选择器必须写 match:：

老写法	现在
`layerrule = blur, waybar`	`layerrule = blur on, match:namespace waybar`
`layerrule = ignorezero, walker`	`layerrule = ignore_alpha 0, match:namespace walker`
`layerrule = ignorealpha 0.1, mako`	`layerrule = ignore_alpha 0.1, match:namespace mako`

ignorezero / ignorealpha 这两个字段名已经不存在，统一成 ignore_alpha。另外 layerrule 必须写在顶层，嵌在 decoration { } 里不生效。

③ 颜色不接受逗号形式。 rgba(211, 211, 211, 0.8) 会报 failed to parse 0.8) as a color，要写成十六进制 rgba(d3d3d3cc)（alpha = 0.8 × 255 = 0xcc）。

排查与验证，在本机终端里：

Bash
hyprctl configerrors                                   # 空输出 = 干净
grep -rn 'layerrule' ~/.config/omarchy/themes/*/hyprland.conf   # 看哪些主题还是老写法

改完源文件后，当前主题的那份拷贝还是旧的，重切一次即可（或直接 cp 过去再 hyprctl reload）：

Bash
omarchy-theme-set <主题名>

不确定新字段叫什么，可以直接问 Hyprland ——它会当场告诉你认不认：

Bash
hyprctl keyword layerrule 'ignore_alpha 0.1, match:namespace waybar'   # ok / invalid field type ...

2026-08-13 已按上述规则修过 4 个主题：dreamwave（10 条 layerrule + 一处颜色，且规则原本嵌在 decoration {} 里）、farline（9 条）、rustleaf（1 条）、nyc（一处颜色）。改完 hyprctl configerrors 为空。改写脚本留在机器上 ~/fix_themes.py，幂等，以后再装到老主题直接 python3 ~/fix_themes.py。

改过主题后还能不能 `omarchy-theme-update`¶

能，放心跑。它的循环体只有一句 git -C "$dir" pull，没有 -f、没有 --rebase、也没有 set -e，所以只有三种结局：

情况	结果
上游没碰 `hyprland.conf`	正常更新，你的改动保留
上游改了 `hyprland.conf`	git 拒绝并中止：`Your local changes … would be overwritten by merge`
某个主题中止后	循环继续跑下一个，其余主题照常更新

第二种也不会丢东西 —— git 是拒绝，不是覆盖，屏幕上有明确报错，那个主题停在原地。真遇到了二选一：

Bash
# 要上游新版本，丢掉本地修补（之后重跑 fix_themes.py 即可）
git -C ~/.config/omarchy/themes/<名字> checkout -- hyprland.conf

# 或者把修补收起来，pull 完再放回去
git -C ~/.config/omarchy/themes/<名字> stash
git -C ~/.config/omarchy/themes/<名字> pull
git -C ~/.config/omarchy/themes/<名字> stash pop

多半走第一条：新版主题很可能自己就把语法修了。

想提前知道会不会撞上，逐个比一下本地和远端的 HEAD：

Bash
cd ~/.config/omarchy/themes && for d in */; do
  printf "%-14s %s\n" "${d%/}" \
    "$([ "$(git -C $d rev-parse HEAD)" = "$(git -C $d ls-remote origin HEAD | cut -f1)" ] \
       && echo 已是最新 || echo 上游有新提交)"
done

注意 backgrounds/ 不受这套保护。 上游换图属于正常提交、不是本地修改， git pull 会直接覆盖。自己的壁纸放 ~/.config/omarchy/backgrounds/<主题名>/。

常见外观微调¶

都在 ~/.config/hypr/looknfeel.conf（菜单 Setup > Config）：

Text Only
decoration {
    rounding = 8          # 圆角
}

general {
    gaps_in = 0           # 去掉窗口间距，小屏幕更省地方
    gaps_out = 0
    border_size = 0
}

顶栏托盘图标默认收在展开按钮后面，想全部常显：编辑 ~/.config/waybar/config.jsonc，把 "group/tray-expander" 改成 "tray"。

时钟改 12 小时制：同一个文件，把 {:%A %H:%M} 改成 {:%A %I:%M %p}。

6. 更新与快照¶

正确的更新姿势¶

Text Only
Super + Alt + Space  →  Update > Omarchy

或者终端里 omarchy update。有新版时顶栏时钟旁边会出现一个圆形箭头图标，点它也能更新。

⚠️ 不要直接 pacman -Syu 或 yay -Syu。 Omarchy 的更新不只是升级包，还会拉最新的 Omarchy 代码并跑配置迁移（migration）。绕过它 = 新版软件配着旧版配置，迟早出问题。

四个发布通道¶

通道	说明
stable（默认）	跟官方发布，滞后约一个月，问题基本被别人先踩完了
edge	Omarchy 代码跟正式版，但 Arch 包立刻更新。需要一定 Linux 经验
rc	大版本发布前的验证通道
dev	最前沿，会坏。只在你愿意折腾时用

切换：菜单 Update > Channel，或 omarchy-channel-set <名字>。

快照¶

每次更新自动建一个 Limine 快照。
手动建：omarchy-snapshot create
回滚：重启，在 Limine 启动菜单里按日期挑一个快照进去 → 会弹通知问要不要恢复，点它，或者进去之后跑 omarchy-snapshot restore。
快照只还原 /root，不动 /home，也不覆盖 ~/.config —— 个人文件安全，但如果新版配置格式和回滚后的旧版软件不兼容，得手动处理。
只在 Limine 引导下可用（Omarchy 2.0 起的默认）。GRUB / systemd-boot 没有这功能。

本机专属：更新报下载错误 / 特别慢的时候¶

先查代理模式，grep -o '"mode"' 那条命令见 §3.6。九成是 clash 被切到了全局模式：规则失效 → 国内镜像被机场拉黑 → 前三个镜像全报错。切回规则模式即可，实测清华从"TLS 报错"变成 7.4 MB/s。别再去搭ip rule` 绕过，那是误诊留下的产物。

排除模式问题后，还剩两件事是正常现象，不要瞎折腾：

pkgs.omarchy.org 尾段本来就慢（在 Cloudflare 上，几十 KB/s）。 /etc/pacman.conf 里已经配了 ParallelDownloads = 25 靠并发弥补。
pacman 从不断点续传。中途 kill 掉重来 = 之前下的全作废。看着不动不代表卡住，真想看进度用 pacman -Sup | grep -c '^file://'（已进缓存的包数），别看速率。

7. 故障排查¶

更新后系统坏了 1. 重启，在 Limine 启动菜单里选更新前的快照进去。 2. 还不行，跑 omarchy-debug 收集信息，去 Discord #omarchy-help 问。 3. 最后手段 omarchy-reinstall —— 恢复到最新 stable 并把配置重置为默认，你的定制会丢。

只是某个配置文件改崩了 菜单 Setup > Config 可以单个恢复（Omarchy 会自动备份），或 omarchy-reinstall-configs 全部重置。比 omarchy-reinstall 温和。

CapsLock 不工作 不是坏了 —— 它被设成了 compose 键，见 §3.4。

换主题后 Hyprland 弹配置错误（invalid field blur: missing a value 之类）第三方主题用了老版 Hyprland 语法。见 §5「装完第三方主题后 Hyprland 报错」—— 关键是改 ~/.config/omarchy/themes/<主题名>/，不是 current/theme/（那是拷贝）。

密码输错太多次被锁 Ctrl + Alt + F2 切到 TTY，用 root 登录，然后：

Bash
faillock --reset --user bxhu

界面/字太大或太小 见 §3.3，monitors.conf 里的 monitor= 和 GDK_SCALE 要一起调。 Spotify 单独用 Ctrl + - / Ctrl + + 缩放。

外接音箱没声音 点顶栏右上角喇叭图标打开 wiremix，选中你的外接设备，按 d 设为默认输出。

装的东西太多想删 菜单 Remove > Package 删软件，Remove > Web App 删预装的网页应用。

AUR 包编译失败，报 python3 is missing modules: xxx python 跳大版本（如 3.13 → 3.14）后，官方仓库的 python 包 Arch 会统一重建， AUR 的不会 —— 文件还留在 /usr/lib/python3.13/，pacman -Q 查得到但 import 不到。重建一下就好：

Bash
yay -S --rebuildtree <出错的包名>

用不上那个包就直接删，更省事（-s 会带走只有它在用的依赖）：

Bash
sudo pacman -Rns <包名>

想提前知道哪些包要重建：pacman -Qm 列出所有 AUR 包，逐个 pacman -Ql 看有没有旧版本 python 路径。纯二进制的 AUR 包（chrome、clash-verge 这类）不受影响。

想看系统到底怎么了

Bash
systemctl --failed              # 有没有服务挂了
journalctl -p 3 -b              # 本次启动的 error 级日志
omarchy-debug                   # 打包诊断信息
pacman -Qu                      # 有多少包待更新

8. 参考¶

官方手册总目录 — https://learn.omacom.io/2/the-omarchy-manual
快捷键 https://learn.omacom.io/2/the-omarchy-manual/53/hotkeys
显示器 https://learn.omacom.io/2/the-omarchy-manual/86/monitors
输入设备 https://learn.omacom.io/2/the-omarchy-manual/78/keyboard-mouse-trackpad
更新 https://learn.omacom.io/2/the-omarchy-manual/68/updates
快照 https://learn.omacom.io/2/the-omarchy-manual/101/system-snapshots
故障排查 https://learn.omacom.io/2/the-omarchy-manual/88/troubleshooting
常见微调 https://learn.omacom.io/2/the-omarchy-manual/102/common-tweaks
开发工具 https://learn.omacom.io/2/the-omarchy-manual/62/development-tools
Hyprland 配置 wiki — https://wiki.hyprland.org/Configuring/
壁纸合集 — https://github.com/dharmx/walls
Omarchy 源码（本机就有一份）— ~/.local/share/omarchy/，键位定义在 default/hypr/bindings/