Omarchy：专为 AI Agent 打造的 Linux，装完就能跑 Codex、OpenCode 和 Claude Code

admin@yesmiracle.net (万戈) — Sat, 24 Oct 2026 00:00:00 +0000

把 Codex、OpenCode、Claude Code 装到一台新机器上，要做的第一个决定是选系统。

这件事以前只关乎你顺手不顺手，现在它同时框住了 agent 的能力边界：沙箱依赖哪些 Linux 原语、Node 版本会不会落后、包管理器能不能跟上上游的迭代速度。选错了，后面是长期打补丁。

我的答案是 Omarchy。理由在于它做了别的桌面没做的事：把 coding agent 当作系统的一部分接进来，而不是事后往旁边挂一个。

一、为什么是 Omarchy

底座是 Arch，好处照单全收

Omarchy 建在 Arch Linux 和 Hyprland 之上。这意味着前面那些关于 Arch 的收益全部成立：滚动发布、AUR 覆盖、当前版本的 Node。

几个可查的当前版本：nodejs 26.12.1-1 和 nodejs-lts-jod 22.23.4-1 都在 extra 里，两条 Node 线任选；opencode 2.1.3-1 在官方仓库里（OpenCode 的官方文档为 Arch 单独写了一节安装说明）；Claude Code 的 Linux 沙箱依赖 bubblewrap 0.13.1-1 和 socat 1.8.1.3-1，也都在 extra。

顺带说清一件事，因为这是关于 Omarchy 最常见的那个质疑：它以前确实像一个「装在风衣里的 dotfiles 仓库」，一个 git checkout 加上一堆有主张的配置。4.0 之后这句话不再成立。系统现在以 Arch 包的形式安装，文件落在 /etc 和 /usr/share/omarchy，更新走 pacman。桌面本身也是一份真代码：v4.0.0 标签下有 104 个 QML 文件、约 1.2 MB，占仓库体积的三分之一左右。

九个 agent CLI 预接，而且是懒加载

这是我把这篇单独写出来的主要原因。Omarchy 4 预接九个 coding agent 的 CLI，做法是 ~/.local/bin/ 里放一批 mise 管理的极小的 stub，你第一次运行某个命令之前，什么都不会下载：

命令	Agent
`claude`	Claude Code
`codex`	OpenAI Codex
`opencode`	OpenCode
`gemini`	Google Gemini CLI
`copilot`	GitHub Copilot CLI
`crush`	Crush
`grok`	Grok CLI
`pi`	Pi
`omp`	Oh My Pi

它不替你选偏好。默认 agent 用 omarchy default agent <名字> 设定，或者走 Setup > Defaults > Agent，Super + Shift + Ctrl + A 会在一个专门的窗口里启动它。终端里还有几个别名：a 内联跑默认 agent，c、cx、cy 分别是 OpenCode、Claude Code、Codex。

两个细节能看出设计者真跑过这些东西。第一，这样启动的 agent 会进入自动批准模式，手册自己给的原话提醒是「准备好它们真的会动手」。第二，因为 agent 通常不肯为整个家目录持久化信任，从 $HOME 启动会被落到 ~/Work。

agent 是系统公民，这是可以验证的说法

「agent 是系统公民」这种话很容易变成宣传。Omarchy 这边有三条具体的证据。

崩溃诊断交给 agent。 系统盯着 systemd-coredump，进程崩了就弹通知，点一下，core dump 连同随系统分发的 diagnose-crash skill 一起交给你默认的 agent，由它去把事实理清楚、判断值不值得往上游报。手工触发也行：omarchy agent crash <pid>。这个默认开着，在 Trigger > Toggle > Crash Capture 里可以关。

顶栏有 agent 用量面板。 第一次在这台机器上发现 AI coding 用量之后，顶栏会长出一个 agents 图标。点开是按订阅分组的用量：套餐、5 小时窗口和每周额度各烧了多少百分比、各自何时重置、最近一周按天的 token、按模型的 token（悬停能看到输入/输出/缓存的拆分）。预付制的 agent 显示的是余额账本。Claude Code、Codex 和 Fireworks 开箱就在覆盖范围内。数据是 ~/.local/state/omarchy/agents/usage/ 下的普通 JSON，每 15 分钟由 omarchy agent usage-update 重新生成一次；面板只读这个目录，不管是谁写的，所以把几台机器指向同一个同步目录，就能看到合并后的消耗。

随系统分发一个 agent skill。 这个 skill 的用途是改机器本身：Hyprland 配置、bar 布局、从零做一个主题。它被软链到 ~/.claude/skills、~/.codex/skills、~/.pi/agent/skills 以及通用的 ~/.agents/skills，所以多数 harness 都能自动发现它。

写这个 skill 的方式值得单独说，因为它是给 agent 划爆炸半径的一个范本。它把 /usr/share/omarchy/（随便读、绝不要改，包拥有它，omarchy update 会覆盖你的修改）和 ~/.config/（你的）之间划了一条硬线。不过手册自己的说法要照抄而不是转述：把它当作实验性的，先在 plan 模式里跑，准备好回滚，或者准备好用 omarchy reinstall configs 收拾残局。我认真对待这条警告，因为一个对你的窗口管理器配置有写权限的 agent，是一个能把你锁在自己桌面外的 agent。

桌面是代码，不是一堆配置

4.0 把整个桌面壳重写成 Quickshell 上的单个常驻进程。代价是删掉了八个程序：Waybar、Walker、Mako、SwayOSD、hyprlock、hypridle、swaybg、polkit-gnome。它们各自有配置格式、各自的主题方案，而且互不知道对方存在。现在它们是一个 QML 进程里的插件。官方给的运行时内存数字是不到 300 MB。

实际差别在细节上：状态更新从轮询改成事件驱动；通知弹窗能扛过 shell 重启；主题色从 8 个变成 24 个，这就是为什么自动生成的 Neovim、VS Code 和 btop 主题不再看起来像凑合的。Hyprland 的配置也从 .conf 换成了 Lua，于是配置里有了循环、条件和共享变量。

还有一个我觉得很聪明的命令，值得单独提：

omarchy plugin clone omarchy.clock

它把内置的时钟复制到 ~/.config/omarchy/plugins/<你>.clock，改名、启用，并把所有引用原 id 的地方改指向你的副本，同时保留 bar 上的位置和设置。存盘就热重载，玩坏了 omarchy plugin remove <you>.clock 就把内置的还回来。这是「可配置的桌面」和「可编程的桌面」的区别：你不必 fork 整个发行版来挪一个控件。

对照着看：为什么不是别的

选项	你能拿到什么	你要付什么
Omarchy	Arch 底座 + 配好的 Hyprland + 预接的九个 agent CLI + agent 接入系统层	接受别人的默认值；必须关 Secure Boot；插件未沙箱
纯 Arch	完全的控制权	桌面要自己配，Hyprland 一套配下来是以天计的
Fedora Workstation	支持 Secure Boot，稳定，省心	没有 agent 层的接入；Node 版本要自己想办法
Ubuntu LTS	生态最熟，文档最多	Node 冻结，三个 agent 装完要自己补版本
macOS	生态和硬件最整齐	不是 Linux，agent 的沙箱原语是另一套

如果上面的表里你的答案落在「需要 Secure Boot」或者「每个决定我想自己拿」，那 Fedora Workstation 是更合适的答案，这不是敷衍。

诚实的那一半

这几条我认为必须写在前面，因为它们决定了这台机器适不适合你。

Secure Boot 和 TPM 必须关掉。 这是安装的必要条件，没有商量余地。手册自己的说法是这两套是微软给 Windows 和微软系发行版设计的安全方案。对一台要跑 AI agent 的机器来说，这是一笔需要你自己权衡的交换。

插件是未沙箱的任意代码。 这点 Omarchy 做得算诚实：安装前它会明确告诉你，插件是在你那个长期存活的 shell 进程里以任意代码运行的，会把 URL 显示出来，要你确认。安装器不执行任何 install hook，也不要 sudo。但结论不变：一个你没读过的 bar 控件，在你登录期间对你的用户账户有完全权限。

自家仓库还没有 PGP 签名链。 pkgs.omarchy.org 的配置是 SigLevel = Optional TrustAll，写这篇时 stable 仓库里 198 个包带 SHA-256 校验和但没有 PGP 签名。你的 Arch 包照旧有签名校验（core/extra/multilib 是 Required DatabaseOptional），Omarchy 自己这层是「传输和完整性有保障，但没有指向签名密钥的链条」。对第三方 Arch 仓库来说这很正常，而且它已经发了 omarchy-keyring、omarchy update 会取回并本地签名一个真密钥，地基是在的。

桌面壳建在 quickshell-git 上。 也就是说它跟的是上游 git 而不是某个打标签的发行版。把整个桌面押在一个移动依赖上是个真实的赌注。

Caps Lock 被拿掉了，这是有意的。 它被重映射成 xcompose 键，表情和补全的快捷键靠它工作。想要回来就在 ~/.config/hypr/input.lua 里改 compose 键，或者同时按两个 Shift 临时切换。

二、装 Omarchy

准备

ISO 从 iso.omarchy.org 下载，不到 6 GB。写盘用 balenaEtcher（Mac/Windows）或 caligula（Linux）。

装之前有四件事要办：

进 BIOS 关掉 Secure Boot 和/或 TPM。 不关装不了。
决定全盘还是自由空间。 全盘会抹掉你选的那块盘；要和 Windows 双系统就用自由空间那个选项，先在磁盘管理里缩好分区，并且关掉 BitLocker。
准备有线或 2.4GHz 键盘。 全盘加密不会在启动时接受蓝牙键盘输入的密码，理由和蓝牙键盘进不了 BIOS 一样。这条我建议在装之前就确认，装完再发现是个很糟糕的下午。
备份。 默认全盘加密，选错盘就是数据没了。

安装过程

从 U 盘启动，回答配置问题，确认，选盘，然后等。快机器上不到一分钟，老机器也不该超过五分钟。默认开加密。

安装器上有个隐藏菜单值得知道：在第一个界面（选键盘那一步）按 Ctrl + C，它会提出替你为另一个人准备这台机器——系统照常装，但键盘布局、用户名、密码这些个人设置全部推迟到对方第一次开机时再填，加密密码也是那时定的。在磁盘格式化确认那一步按 Ctrl + C，则切换到不加密安装。

要做虚拟机模板或者批量装机，ISO 还支持完全无人值守：把配置放在第二块盘上，安装器自己跑完。手册里叫 unattended installs。

第一次开机

Omarchy 会邀请你设置一个默认 agent。选一个、登录，然后就可以开始用了。

三、三个 agent 怎么装

先理解「已经预接」是什么意思

这是这篇最容易写错的地方，所以先把机制说清楚。

九个 CLI 是懒加载的 stub，不是装好的程序。你敲 codex 的第一次，才会去下载它。默认 agent 用 omarchy default agent <名字> 设定。

所以对大多数人来说，这一节的操作是零：codex、opencode、claude 三条命令开箱就能用。

那什么时候需要自己装？三种情况：你要一个和 Omarchy 当前固定的不一样的版本；你要跟着上游的最新版本走；或者你在别的机器（非 Omarchy）上要装同一套。

Codex CLI

Arch 官方仓库和 AUR 里都没有 Codex 的包，两条路：

# 路线 A：官方独立安装脚本
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# 路线 B：npm
npm install -g @openai/codex

独立安装器默认从 releases.openai.com 取，拉不到时回退到 GitHub Releases。想强制走 GitHub（比如前者不通）：

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

OpenCode

Arch 上有两条路，而且装的不是同一个大版本：

# 官方仓库：OpenCode 2
sudo pacman -S opencode

# AUR：OpenCode 1
paru -S opencode-bin

必须提前知道：OpenCode 1 和 OpenCode 2 都用 opencode 这个命令，默认不能并存。先决定要哪个大版本，别两边都装。当前版本分别是 2.1.3-1（官方 extra）和 1.19.4-1（AUR）。

Claude Code

# 路线 A：AUR
paru -S claude-code

# 路线 B：官方 native 安装器
curl -fsSL https://claude.ai/install.sh | bash

我建议先试 AUR 那条，因为包页面把可选依赖写清楚了，等于一份部署清单：bubblewrap 和 socat 标注为 sandboxing，ripgrep 是 enhanced file search，git 让 Claude 能用 git，github-cli 和 glab 分别接 GitHub 和 GitLab，tmux 是 agent team 的分屏。当前版本 2.1.310-1。

native 安装器那条的好处是会自动后台更新，你永远在最新版。取向不同，看你在意依赖清晰还是版本新鲜。

还有一条要提醒：Claude Code 的官方系统要求列表里列的是 macOS 13+、Windows 10 1809+、Ubuntu 20.04+、Debian 10+、Alpine 3.19+，Arch 不在里面。它能装能跑，但你遇到问题时官方文档不会给发行版相关的答案，AUR 包的评论区往往更有用。

如果你自装了，注意谁在 PATH 前面

Omarchy 的 stub 放在 ~/.local/bin/。如果你用 npm 全局装了一份，或者装了 AUR 包，系统里就同时存在多个同名可执行文件，最后跑哪个由 PATH 顺序决定。

确认方法：

which -a codex      # 列出 PATH 里所有同名命令，第一个是实际生效的

如果你要自己那份生效，把它所在目录放到 PATH 更靠前的位置。这类冲突不会报错，只会让你在某个版本上跑很久而没发现，所以装完顺手看一眼。

四、装完的验证清单

检查项	命令	预期
默认 agent 设好了	`omarchy default agent`	输出当前默认 agent
Codex	`codex --version`	输出版本号
OpenCode	`opencode --version`	2.x 或 1.x，与你装的那条路一致
Claude Code	`claude --version`	输出 2.1.x
沙箱依赖	`pacman -Q bubblewrap socat`	两个都列出，无报错
沙箱状态	进 Claude Code 后运行 `/sandbox`	面板有 Mode / Overrides / Config 三个标签页
用量面板	顶栏的 agents 图标	有过用量后出现

最后两条是关键。/sandbox 面板只显示一个 Dependencies 标签页就说明缺包，装上缺的那个再重启 Claude Code。顶栏的 agents 图标在系统发现 AI coding 用量之前不会出现，别以为是坏了。

五、六个 Omarchy 特有的坑

1. 不要直接跑 pacman -Syu 或 yay -Syu。 这会跳过更新前的快照、迁移脚本和配置更新。Omarchy 会主动拦你并把你引向 omarchy update，4.0 把这个拦截从提示升级成了 ALPM hook。知道自己在干什么的话可以用 OMARCHY_ALLOW_DIRECT_PACMAN=1 绕过，但默认别绕。

2. 快照只还原 root。 每次更新都会给你一个快照，可以从 Limine 启动菜单进去。但有两个必须记住的限制：它不还原 /home，也不动 ~/.config。所以一个改了配置格式的应用，回滚之后配置问题还是你自己的事。

3. 预接启动的 agent 是自动批准模式。 手册的原话提醒是「准备好它们真的会动手」。第一次跑之前值得先想清楚你要它在哪个目录里动手。

4. 从 $HOME 启动会落到 ~/Work。 因为 agent 通常不为整个家目录持久化信任。这不影响使用，但只有踩过的人才会知道。

5. Claude Code 的沙箱默认关着，而且读权限默认很宽。 沙箱要用 /sandbox 开，或者在 ~/.claude/settings.json 里设 sandbox.enabled 为 true。开了之后默认允许读机器上大部分文件，包括 ~/.ssh 和 ~/.aws/credentials；写权限限于工作目录、一个每用户临时目录和你额外加的目录；网络默认没有直连出口，要走本机代理逐个域名校验，允许列表初始是空的。所以开了沙箱不等于凭据安全了，读权限得自己收紧。

6. 卡住的时候先收集信息，别先重启。 Wi-Fi、蓝牙、音频、触控板挂了，用 Update > Hardware 单独重启对应子系统，多数「五分钟前还好好的」都能修好。要问人之前先跑 omarchy-debug，它收集的就是别人会问你要的东西。

写在最后

回到开头。我认为给 AI coding agent 选系统这件事，已经从个人偏好变成了能力边界的一部分，因为 agent 的沙箱依赖特定版本的 Linux 原语，而它的运行依赖不冻结的 Node 版本。

在这个前提下 Omarchy 的价值很具体：它把接缝做进了系统。bar 上有它的用量，崩溃路径的终点是它，随系统分发一个用来驱动这台机器的 skill。别的工具生态大多还在把 agent 往旁边挂。

代价也写清楚了：Secure Boot 要关、插件是未沙箱代码、自家仓库还没有签名链、桌面壳押在一个 git 依赖上。这几条我放在前面而不是脚注里，因为一篇只讲好处的系统教程，在真出事的时候会害人。

最后一句关于范围：这篇装的是环境和三个 agent 的入口，agent 各自怎么用、怎么配权限、怎么加技能，是另外的题目。

Linux on AI博士 万戈