自顶向下、新手友好向的 Omarchy Linux 入坑指南¶

本文按 Omarchy 3.8.5 @ 192.168.3.97（omarchy）实测写成，不是照抄官方手册

键位以这台机器上真正生效的 ~/.local/share/omarchy/default/hypr/bindings/tiling-v2.conf 和笔者自己改过的 ~/.config/hypr/bindings.conf 为准

Warning

忘了快捷键就按 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`	应用启动器	启动程序、打开 web app	20%
`Super + Alt + Space`	Omarchy 菜单	Apps / Learn / Trigger / Style / Setup / Install / Remove / Update / About / System	100%
`Super + Escape`	系统菜单	锁屏、注销、挂起、重启、关机	20%
`Super + K`	键位速查表	PS: 支持实时读取当前配置	80%

Super + Alt + Space 这个控制菜单, 用的会比较多:

alt text

装软件: > Install
- 个人更喜欢命令行里直接 pacman
换主题: > Style
配显示器: > Setup > Monitors
- 相较于 Arch Linux 原版, 好用!
- 支持自动检测外接显示器
连 wifi: > Setup > Wifi
更新系统: > Update
- 相较于 Arch Linux 原版, 好用!
- 省的 AUR 到处滚

Danger

笔者的 ~/.config/hypr/bindings.conf 末尾有一段被注释掉的配置，可以把 Omarchy 菜单挪到 Super + Space（覆盖启动器）

想换的话取消那两行注释即可

2. 常用快捷键¶

只放笔者认为的重点和常用指令, 详细内容建议自己看 Omarchy 官方文档

2.1 窗口与工作区¶

来源：tiling-v2.conf

快捷键	作用
`Super + W`	关闭窗口
`Super + F`	全屏
`Super + J`	切换分割方向（左右↔上下）
`Super + ←/→/↑/↓`	移动焦点
`Super + 1..0`	跳到第 N 个工作区
`Super + Shift + 1..0`	把窗口丢到第 N 个工作区（跟随过去）
`Super + -` / `Super + =`	横向调整窗口宽度
`Super + Shift + -` / `Super + Shift + =`	纵向调整窗口高度
`Super + Shift + Alt + ←/→/↑/↓`	把整个工作区搬到指定方向的显示器

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

Danger

这个功能, 笔者不太常用...

快捷键	作用
`Super + G`	开启 / 关闭分组
`Super + Alt + G`	把当前窗口移出分组
`Super + Alt + Tab` / `Super + Alt + Shift + Tab`	组内切换窗口

2.2 启动应用¶

记忆

前缀: Super + Shift

⚠️ 这一节和官方手册差别最大

笔者把"应用启动键" (回顾 Chapter 1) 统一改成了 Super + Shift + …

官方默认的 Super + B（浏览器）、Super + N（nvim）这类单键在本机不生效

(1) 常用应用启动

快捷键	启动什么	备注
`Super + Return`	终端（Ghostty），继承当前终端的工作目录	本机定制
`Super + Shift + Return`	浏览器（Chrome Beta）	官方默认亦同
`Super + Shift + F`	文件管理器（Nautilus）
`Super + Shift + O`	Obsidian

(2) WebApp 启动

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

Danger

这个功能, 笔者不太常用...

快捷键	打开
`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

快捷键	打开
`Super + Ctrl + W`	Wifi（impala）
`Super + Ctrl + B`	蓝牙（bluetui）
`Super + Ctrl + S`	分享（LocalSend）
`Super + Ctrl + H`	硬件菜单 (显示器选择)
`Super + Ctrl + L`	锁屏

2.4 剪贴板与截屏¶

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

剪贴板:

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

截屏:

快捷键	作用
`PrintScreen (PrtSc)`	截图
`Alt + PrintScreen`	录屏
`Super + Ctrl + PrintScreen`	框选区域 OCR 取字到剪贴板 (这个是真NB!)
`Super + Ctrl + C`	截屏菜单（没有 PrintScreen 键时用）

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

笔者 prefer 的用法

Super + Ctrl + C 进入 "截屏菜单"

后面按要求自己选即可

alt text

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

快捷键	作用
`Super + Ctrl + ,`	免打扰开关
`Super + Ctrl + I`	禁止 / 允许自动休眠锁屏
`Super + Ctrl + N`	夜灯（色温）开关
`Super + Shift + Space`	显示 / 隐藏顶栏

上述功能会直观地在顶栏显示:

alt text

比如: Super + Ctrl + I 笔者常用, 完美代替 GNOME 中的 Caffine-ng, 保持笔记本始终亮屏

2.6 tmux¶

Danger

这个功能, 笔者不太常用...

前缀键是 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 终端¶

Danger

没啥必要...

快捷键	作用
`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 虽然装着，但对本机无效，别用

alt text

方式	怎么做
图形/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      # 省电模式开关，某些网卡断流是它引起的

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

3.2 壁纸 / 背景¶

操作	怎么做
换一张	`Super + Ctrl + Space`，在当前主题的背景里选

在 Omarchy 的设计架构中, Theme = Background + Opacity + ...

因此, 背景是按主题分目录的. 换主题就换了一批壁纸

所以想要更多壁纸，最省事的办法是多装几个主题，下见 §5 详细展开!

Danger

笔者超级不推荐自己折腾壁纸, 因为现在第三方主题非常丰富, 而且一键安装

看到 §5 就知道为什么了 :)

3.3 显示器¶

配置文件：~/.config/hypr/monitors.conf

菜单中, Setup > Monitors 会直接用编辑器打开它

(1) 设置分辨率

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 + Ctrl + Alt + Delete
合盖自动关内屏，开盖自动恢复

(2) 设置多屏相对位置

TODO

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，把 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 用户自己的文件:

Bash
~/.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 仓库，更新时会被直接覆盖，改了等于白改

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

3.6 代理 (clash-verge)¶

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

规则模式下，clash 配置里那 7000 多条规则才生效，国内域名（DOMAIN-SUFFIX,cn / GEOIP,CN）直连、国外走节点，各走各的

全局模式会把这些规则全部作废，把国内镜像也塞给机场节点。而机场普遍把国内域名拉黑，于是下载全崩。

2026-08-12 的更新失败就是这么来的，详见下面的"笔者踩过的大坑"

TLDR: 本机现在的配置已实测可用¶

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

(1) 普通程序怎么用上代理:

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

Bash
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 生效（只影响之后启动的程序）

(2) CLI 如何用上代理:

笔者最喜欢在 CLI 里手动新增 x_proxy_on/off 快捷键:

Bash
# In my fish shell
function x_proxy_on
    set -gx http_proxy http://127.0.0.1:7897
    set -gx https_proxy http://127.0.0.1:7897
    set -gx all_proxy socks5h://127.0.0.1:7897
    echo 终端代理已开启
end

function x_proxy_off
    set -e http_proxy
    set -e https_proxy
    set -e all_proxy
    echo 终端代理已关闭
end

这套组合的好处是分工干净:

GUI 程序有 env → 国外能通、国内直连
CLI 程序, 通过笔者最喜欢的 x_proxy_on/off 快捷键 → 国外能通、国内直连
- 在 shell config 中 Alias 一下, 以笔者的 fish shell 为例
sudo pacman 因为 sudo 会剥掉环境变量 → 纯直连，国内镜像满速

Warning

必须写 socks5h 而不是 socks5

socks5 让本机先解析域名、只把 IP 交给 mihomo, 规则匹配不到域名就会走错节点 (实测清华源直接失败)

socks5h 把域名交给 mihomo 解析, 规则才生效

Note

亲测, 这样配置下 omarchy-update 日常更新很顺利!!!

常见问题自查¶

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

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 / dashboard 点一下「规则」

模式持久化在 config.yaml，那个文件由 clash-verge 自己重写，手改会被覆盖

Clash 到底怎么工作¶

Tip

作为一名网络研究员, 会发现周边很多人都会栽在 clash 上

事实上, 笔者认为本小节会在日后时间充裕时, 单独开份笔记

先立个flag, 希望别咕咕咕🐦

一句话：「入口」和「模式」是两件独立的事，互不影响

Bash
程序 ──[入口]──> clash (127.0.0.1:7897) ──[模式]──> 节点 / 直连

(1) 入口: 流量怎么进到 clash

三条并行，任选，本机用的是第一条:

入口	怎么起作用	特点
环境变量	程序自己读 `http_proxy`，主动去连 7897	靠程序自觉，不读环境变量的程序不受影响
系统代理	clash-verge 替你把这套设置写进系统	还是同一招，只是不用手写；Linux 上覆盖面不稳
TUN	建虚拟网卡 + 改路由表，从网络层截走	程序跑不掉；但要 root，多一层封装

(2) 模式: clash 拿到流量后怎么发出去

模式	做什么
规则	逐条匹配那 7000 多条规则: 国内直连，国外走节点
全局	规则全部作废，一律走当前选中的节点
直连	一律不走节点

关键: "入口" 和 "模式" 二者完全正交

由此两条推论：

出问题九成在模式（被切成了全局），而人们总是去折腾入口
- 下面的 "坑 ②" 就是这么来的
本机关掉 TUN 还有个额外好处
- sudo 剥掉环境变量后，pacman 完全绕开 clash，国内镜像满速

踩过的坑¶

别再花一晚上重查 T_T

① 报 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 那套artificial bypass

规则模式下国内镜像本来就直连，绕过纯属多余

而且 ip rule 只在内存里、重启即失效，镜像 IP 还会变...

④ GUI 报 "IPC path not ready" / TUN 打不开

是 /tmp/verge 的权限问题，和上面这些无关

systemctl restart clash-verge-service 通常就能恢复（服务里挂了个 ExecStartPost 重新打 ACL）

每次 clash-verge-rev-bin 升级后都可能复发. 建议每次都得跟AI交互解决一下...

4. 开发者相关¶

Danger

这一部分是让claude code整理的, 笔者不常用

还是更习惯标准的linux指令 (主要是指令太多, 实在记不住...)

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`

本机现成alias:

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 本质就是 ssh -f -N -L 3000:localhost:3000 <主机>
dip 把那个后台 ssh 进程 pkill 掉
lip 用 pgrep 列出来

举例:

Bash
fip [email protected] 3000 5173    # 一次转两个口
lip                                # 确认转发还在
dip 3000 5173                      # 用完断开

alt text

提醒

上述快捷指令本质上都是一堆脚本指令合集的alias, 它们内置在 omarchy 的 bash 里!

如果用户自定义了 terminal, 比如笔者用的就是 fish shell, 那么这些指令就不能直接使用 😭

fish 里加载不到，敲 fip 会报 Unknown command

笔者本机已把 fip / dip / lip 等价移植进 ~/.config/fish/config.fish

不过: compress / iso2sd / format-drive 这几个还没移植，要用得先 bash -c

f/d/lip 非常实用

fip 那组特别适合: 在远程机器上跑 web 服务，转到 localhost 后就能拿到 secure-context 权限（websocket、剪贴板 API 等）

直接访问 http://<远程 IP>:3000 浏览器会当作不安全来源，http://localhost:3000 则不会。

不用折腾 SSL 证书! 爽!

4.2 TUI¶

Danger

纯鸡肋, 笔者不太常用...

工具	启动	常用键
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 Neovim (LazyVim)¶

Danger

真想玩的话, 建议看本站有关 lazynvim 的内容. 应该2024年写过几篇...

快捷键	作用
`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 设成默认
PS: VSCode、Cursor、VSCodium、Helix、Zed 支持主题联动

5. 主题与外观¶

回顾之前我们提到过, 对于 omarchy, theme = background + waybar + ...

如何选择主题和外观, 有两种方式:

Super + Ctrl + Shift + Space 直接开主题选择器
- 是的, 这个快捷键很费手...
菜单 Style > Theme

换主题会同时换掉: 终端、Neovim、btop、mako 通知、waybar 顶栏、walker 启动器、hyprlock 锁屏的 style

"选择器"里的主题从哪来¶

(1) 来源有两个:

~/.config/omarchy/themes: "DIY"
- 用户本地基于第三方 DIY, 不会随系统更新(omarchy-update)而更新
- 指令: omarchy-theme-update / omarchy-theme-remove / omarchy-theme-list / omarchy-theme-bg-next ...
~/.local/share/omarchy/themes/: "内置"
- omarchy 自带, 随系统更新(omarchy-update), 自更新
- 指令: omarchy-update

原理:

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

两边没有重名，也没有软链，所以就是 22 + 19 = 41

(2) "选择器"的实现原理:

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

用户 DIY 安装更多主题¶

笔者最喜欢的部分, 没有之一🤩

社区索引 https://omarchythemes.com/，233 个主题，比本机多得多。

alt text

每个主题自带壁纸，所以装主题就是拿壁纸，没有单独的壁纸源!!!

在站点上挑一个，进它的详情页，复制那个 GitHub 仓库链接
- 比如这里以右上角的 Adrift 为例

装上 (会 clone 到 ~/.config/omarchy/themes/ 并立刻切过去):

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

(过了一阵子, 假如你...) 想让这些第三方主题跟上作者更新:
Bash
1
omarchy-theme-update # 对所有自装主题逐个 git pull

其余命令:

Bash
omarchy-theme-list          # 列出 (仅限 "DIY" 主题, 不包含 "内置" 主题!!!)
omarchy-theme-set <名字>     # 切换
omarchy-theme-remove <名字>  # 删；不带参数会弹菜单让你选
omarchy-theme-bg-next       # 切换到本主题的"下一张"背景（= Super + Ctrl + Space）

尤其要注意两个update的区别

omarchy-theme-update 不在 omarchy update 里

不跑就永远停在装的那天, 二者完全不是一码事!!!

DIY 主题后 Hyprland 报错¶

社区那 233 个主题里有不少是给老版 Hyprland 写的，安装+切换就会看到 invalid field blur: missing a value 等提示

根本原因是: layerrule 的语法在 Hyprland 0.5x 变了，字段必须带值，选择器必须写 match:

我们按顺序解决:

① 改 current/theme/ 没用, 那是拷贝不是软链

~/.config/hypr/hyprland.conf source 的是 ~/.config/omarchy/current/theme/hyprland.conf

而 omarchy-theme-set 每次切主题都 rm -rf 再 cp -r 重建这个目录

因此直接按照报错信息改 ~/.config/omarchy/current/theme/hyprland.conf 是🐦用没有的!!!

我们要改源头: ~/.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(211,211,211,0.8)

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

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

改完源文件后，当前主题的那份拷贝还是旧的，重切一次即可:

Bash
omarchy-theme-set <主题名>

手动改过主题配置文件后, 依然能 `omarchy-theme-update`¶

笔者最开始会有这样的顾虑: 在笔者修复上述版本原因带来的错误后, 如果再 omarchy-theme-update:

本质上, 相当于在git仓库了改了东西, 但是没有 add/commit/..., 直接pull

这样会不会带来问题/冲突???

结论是"不会"! 放心跑!

原因是, 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
# [选择 1] 要的是: 上游新版本! 丢掉本地手动的补丁
git -C ~/.config/omarchy/themes/<名字> checkout -- hyprland.conf

# [选择 2] 把修补收起来, pull 完再放回去
git -C ~/.config/omarchy/themes/<名字> stash
git -C ~/.config/omarchy/themes/<名字> pull
git -C ~/.config/omarchy/themes/<名字> stash pop

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

6. 更新与快照¶

正确的更新姿势¶

在确保你的clash配置正确 (See §3.6) 的前提下, 按顺序两步走:

Super + Alt + Space 打开菜单
选择 Update > Omarchy

alt text

或者, 终端里 omarchy update 也可以. 个人倾向"两步走"

Tip

新版的顶栏时钟旁边, 会出现一个圆形箭头图标，点它也能更新

Warning

Omarchy 是基于 Arch 的, 根据发烧友多年玩 Arch 的经验

最好保持日常滚动更新, 不要拖很长时间才搞一次, 不然容易"滚炸"...

笔者的频率是每天 update 一次

⚠️ 不要直接 pacman -Syu 或 yay -Syu

Omarchy 的更新不只是升级包，还会拉最新的 Omarchy 代码并跑配置迁移（migration）

绕过它 -> 新版软件配着旧版配置, 迟早出问题!!!

必须: packet, code, config migration 同步更新

四个发布通道¶

更新系统前, 需要知道其有四个发布通道:

alt text

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

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

快照 omarchy-snapshot¶

(1) 快照是什么

系统快照: snapshot

Limine 引导菜单里可以进入的一份历史系统状态

它只覆盖根文件系统（系统软件与 /etc 等系统配置），不含 /home，所以恢复后:

系统软件回到快照那天的版本
你的个人文件和 ~/.config 原样保留，不会被覆盖，也不会被回滚 (好事!)

潜在副作用

~/.config 是新版格式，软件却退回了旧版，不兼容时要手动改。

前提是 Limine 引导（Omarchy 2.0 起的默认）

GRUB / systemd-boot 没有这功能

(2) 什么时候建、怎么建

omarchy update 每次更新前会自动建一个，日常不用管!!!

只有极个别场景需要!!!

比如, 在手动动系统时补一个: 换内核、装/删系统级包、改 /etc

建立快照的方式:

Bash
omarchy-snapshot create

(3) 怎么用快照恢复系统

重启. 在 Limine 启动菜单里按日期选中要回到的那个快照，进系统
进去后会弹通知问是否恢复
- 点它
- 没弹或点错了，终端里跑:
  Bash
  1
  omarchy-snapshot restore
再重启，系统即停留在该快照的状态

如果只想看看那天的系统、不想真恢复: 第 2 步不要确认，直接重启就回到当前状态

(4) 在正常运行的系统里, 查看已有快照

不用重启，终端直接跑:

Bash
sudo snapper list

列出全部快照：编号、创建时间、描述（自动建的那些描述是当时的 Omarchy 版本号）

alt text

本机只有 root 一个 snapper 配置，所以这一条就是全部

如果只想知道哪些快照能在 Limine 启动菜单里选到

Bash
sudo limine-snapper-list

alt text

Tip

limine snapper 数量受菜单条目上限限制，比 snapper list 少

删掉某个快照: sudo snapper delete <编号>
平时不用管，omarchy update 每次建完, 会自动 cleanup 旧的

7. 常见故障排查¶

下面是笔者多次遇到的问题. 争取保持常态更新~

(1) 更新后系统坏了

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

(2) 只是某个配置文件改崩了

菜单 Setup > Config 可以单个恢复（Omarchy 会自动备份）

或 omarchy-reinstall-configs 全部重置。比 omarchy-reinstall 温和

(3) 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 <包名>

(4) 想看系统到底怎么了

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/

自顶向下、新手友好向的 Omarchy Linux 入坑指南¶

1. 三个入口¶

2. 常用快捷键¶

2.1 窗口与工作区¶

2.2 启动应用¶

2.3 系统控制¶

2.4 剪贴板与截屏¶

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

2.6 tmux¶

2.7 Ghostty 终端¶

3. 常用设置¶

3.1 联网¶

3.2 壁纸 / 背景¶

3.3 显示器¶

3.4 键盘 / 鼠标 / 触控板¶

3.5 配置文件的组织/运行顺序 [非常重要!]¶

3.6 代理 (clash-verge)¶

TLDR: 本机现在的配置已实测可用¶

常见问题自查¶

Clash 到底怎么工作¶

踩过的坑¶

4. 开发者相关¶

4.1 命令行工具¶

4.2 TUI¶

4.3 Neovim (LazyVim)¶

5. 主题与外观¶

"选择器"里的主题从哪来¶

用户 DIY 安装更多主题¶

DIY 主题后 Hyprland 报错¶

手动改过主题配置文件后, 依然能 omarchy-theme-update¶

6. 更新与快照¶

正确的更新姿势¶

四个发布通道¶

快照 omarchy-snapshot¶

7. 常见故障排查¶

8. 参考¶

手动改过主题配置文件后, 依然能 `omarchy-theme-update`¶