用户手册
AI
Omarchy 包含了下面这些编程智能体的启动器,但不会替你选择一个默认项。运行某个命令会在首次使用时安装其 CLI,然后在提示时完成身份验证。Hermes 是例外:首次使用时不会为它安装任何东西,选择它会安装 Hermes Desktop,正如下面的_桌面应用_所述。
| 命令 | 智能体 |
|---|---|
claude |
Claude Code |
codex |
OpenAI Codex |
opencode |
OpenCode |
agy |
Google Antigravity CLI |
amp |
Amp |
commandcode |
Command Code |
copilot |
GitHub Copilot CLI |
crush |
Crush |
cursor-agent |
Cursor CLI |
devin |
Devin CLI,来自 Cognition |
dsh |
DeepSeek Harness |
freebuff |
Freebuff,Codebuff 的免费、由广告支持的编程智能体 |
grok |
Grok Build,来自 xAI |
hermes |
Hermes,Nous Research 的智能体 |
kilo |
Kilo,一个基于 OpenCode 的编程智能体 |
kimi |
Kimi Code |
kiro-cli |
Kiro CLI |
mcode |
MiniMax Code,MiniMax 的编程智能体 |
muse |
Muse Code,Meta 的编程智能体 |
omp |
Oh My Pi |
ori |
Ori,OpenRouter 的 harness |
pi |
Mario Zechner’s Pi |
qwen |
Qwen Code,Alibaba 的编程智能体 |
ori 是其中与众不同的一员:它会让其他 harness 对着 OpenRouter 的整个模型目录运行,所以 ori claude、ori codex 或 ori opencode 会在你指定的任意模型上启动这些智能体,而 ori code 是 Ori 自己的智能体。
安装和更新智能体
Hermes 除外,这些智能体都使用 mise 的延迟安装:首次启动时安装 CLI,之后启动时重复使用它。mise 还会最多每四小时检查一次已安装的智能体是否有新版本,就在它启动之前,或者在 shell 提示符下在后台检查。如果更新失败或你处于离线状态,就会运行已安装的版本。omarchy update 会随 Omarchy 的其余部分一起更新已安装的智能体,而 mup 只更新 mise 管理的工具。
智能体自身的更新程序,例如 claude update、codex update,或应用中的更新按钮,不会更新 mise 管理的安装。codex update 会失败,而 claude update 可能会报告成功,却安装了一个 mise 并不跟踪的独立副本。如果你更愿意使用智能体原生的安装程序和更新程序,把它加入 disable_tools;请参阅预装的 CLI 工具。
要在需要之前安装所有已配置的延迟工具,运行 mise install --include-lazy。这包括 Omarchy 的其他默认 CLI 工具以及这些智能体。关于安装单个工具或使用你自己的安装,请参阅预装的 CLI 工具。
grok 通过 mise 的第一方 grok 包安装,与 claude 和 codex 的方式相同。运行 grok,或者在 Setup > Defaults > Agent 下选择它。不要用 x.ai 上的 curl | bash 安装程序。那条路径会在 ~/.grok/bin 里放上第二个副本,把它前置到 PATH 上,并覆盖 Omarchy 的包装器。
dsh 会在 127.0.0.1:3080 打开它的浏览器 UI,并以启动目录作为其默认工作区。它的浏览器 UI 不接受起始提示词,所以 omarchy agent prompt 打开它时,会把提示词放在你的剪贴板上供你粘贴。Omarchy 会使用 DeepSeek 的无需批准权限预设来启动它。当你使用 DeepSeek 的官方模型 API 时,DeepSeek Harness 会把会话日志上传到 DeepSeek;在它的浏览器 UI 中的 Settings > General > Upload Session Log 下可以关闭这一点。你发送给它的反馈也会随会话一并上传,除非你用 DSH_TELEMETRY_MODE=DISABLED 启动它。
默认智能体
用 omarchy default agent <name>,或者在 Omarchy 菜单(Super + Space)的 Setup > Defaults > Agent 下,选择你的默认智能体。如果该智能体尚未安装,选择它时会先安装它。全新的 Omarchy 会用一条一次性通知邀请你做出这个选择。
选择 Claude 时,还会尝试为 Chromium、Chrome、Brave、Brave Origin 和 Edge 设置它的浏览器扩展。扩展的设置适用于所有用户,可能会要求输入你的系统密码;取消操作或扩展安装失败,仍然会选中并启动 Claude。重启你的浏览器,如果提示就启用该扩展,并登录 Claude 以完成连接。在 Claude 中运行 /chrome 检查连接状态。Firefox 和 Zen 不支持此扩展。如果在这套设置加入之前 Claude 就已经是你的默认项,再次选择它即可安装该扩展。
选择之后,Super + Shift + Ctrl + A 会在一个专用终端窗口中启动默认智能体(或者,如果你还没有选择,就会调出选择器)。你也可以用 omarchy agent prompt "Review this project" 让它直接进入一项任务。Freebuff 和 DeepSeek Harness 不接受起始提示词,所以它们打开时改为把提示词放在你的剪贴板上供你粘贴。以这种方式启动的智能体会以它们各自的不停下来询问模式无人值守地运行,所以做好准备,它们真的会动手做事!MiniMax Code 的交互式会话没有这种模式,所以它会照常请求权限。而且,由于智能体拒绝记住对你主目录的信任,从 $HOME 启动时改为在 ~/Work 中开始。
也有终端快捷方式:a 在当前终端中内联运行默认智能体,而 c、cx 和 cy 则直接启动 OpenCode、Claude Code 和 Codex(同样处于它们的自动批准模式)。主题变化也会同步到这些智能体:当你切换 Omarchy 主题时,Claude Code、Pi、OpenCode 和 Hermes(一旦 Omarchy 已安装它)都会随之变化。
智能体面板
顶栏有一个智能体图标。在你设置好一个智能体之前,它的面板会引导你登录 Claude、Codex 或 Grok,其中第一个会成为你的默认智能体。在那之后,面板会把每个订阅都放在同一页上:每个智能体和账户连同其套餐、针对其 5 小时会话限额和每周限额中每一项的计量条以及距离重置的时间(悬停可查看确切百分比),或者剩余的预付余额,都位于一行文字下方,这行文字会轮换显示你在所有这些智能体上的使用情况,例如本周的 token 数和你最常用的模型。在 Make something 下,它提供了用于新建主题、插件或应用的入门提示词,会把任务交给你的默认智能体。应用的构建方式与 Omarchy 自己的 Hype、Monologue 和 Omacut 相同,使用 C++ 和 Qt Quick,遵循 omarchy-app agent skill,而它们所需的编译器和 Qt 组件都已预装。Claude Code、Codex、Grok、Kimi、Cursor 及其 Grok Bot 额度、GitHub Copilot、Muse、Antigravity、Kimchi 和 Devin 都开箱即用地得到了覆盖并显示其限额,而 Hermes、Mistral Vibe 和 Qwen Code 会在你使用过它们之后显示其会话和 token。你通过 pi、omp 或 opencode 使用的提供商套餐和密钥也会显示出来:OpenCode Zen 和 Go、Z.ai GLM Coding Plan、Ollama Cloud、MiniMax Token Plan 以及 Synthetic,连同它们的限额;Fireworks、OpenRouter 和 DeepSeek,连同它们的预付余额;以及你在自己的硬件上运行的模型,位于 Local models 下。每个智能体只按为其计费的一方计数一次,无论你通过多少个 harness 来驱动它。
左键单击栏图标打开面板,右键单击则启动你的默认智能体。它背后的使用记录每 15 分钟由 omarchy agent usage-update 重新生成一次,并且面板甚至可以通过一个同步文件夹合并来自你其他机器的使用情况。完整设置请参阅 $OMARCHY_PATH/shell/plugins/agents/ 下的 README。
多个订阅
如果你付费购买了不止一个 Claude、Codex 或 Grok 套餐 - - 比如说一个个人 Max 和一个工作用的 - - Omarchy 可以让它们全部保持登录状态,并在它们之间移动。用智能体面板中的 + 添加一个订阅,它会就在那里引导你完成,或者用 omarchy agent account add claude Work(或者 codex,或者 grok)。如果 CLI 缺失,它会安装它。某个提供商的第一个账户会通过你平常的浏览器,在 CLI 一直会查找的地方登录。此后的每一个账户都会通过一个隐私窗口登录,这样你浏览器已经登录的账户就不会被误选;在那里登录为你要添加的账户,并先关闭你已经打开的任何隐私窗口。千万不要为此登出 CLI:登出会撤销已保存的登录状态,那个账户就得重新添加。
要通过 SSH 把你的订阅登录信息复制到另一台 Omarchy 机器上,运行 omarchy agent account copy user@laptop。当目标机器没有安装接收端时,发送方会提供一个临时的接收端,所以较旧的 Omarchy 机器无需更新也能接收账户。已安装的接收端优先。此命令会复制所有 Claude、Codex 和 Grok 订阅;添加提供商名称可选择它们,例如 omarchy agent account copy laptop claude。账户名称和命令 ID 与源机器保持一致,包括目标机器上已经存在的账户。如果无关的目标账户名称冲突,它们会得到一个数字后缀,而设置、技能、插件和对话历史则保留在每台机器本地。
目标机器已有的凭据会被保留。已经在那里登录的源账户会同步其名称,但不会替换其凭据;其他账户会被添加到它旁边。要替换匹配账户的已保存凭据,先在目标机器上退出那个账户的会话,然后使用 omarchy agent account copy --replace laptop claude。全新的目标机器还会获得源机器的活动账户和切换偏好;已有数据的目标机器则保留自己的。
凭据通过 SSH 传输,并存储在目标机器的私有文件中,所以只复制到你信任的机器。这是一次性复制,不是持续同步。Codex 的刷新 token 可能会被另一台机器轮换,使复制的登录信息需要续期;对同时在多台机器上使用而言,分别登录仍然是最可靠的选择。请参阅 Codex 的账户身份验证指南。
每个提供商有一个活动账户,每个新会话都以它开始:cx、cy、普通的 claude、codex 或 grok、任何通过 omarchy agent 启动的东西,以及在 PATH 上找到该 CLI 的脚本或编辑器。用 omarchy agent account use work 切换(用 omarchy agent account use main 切回来),或者在面板中按一个账户的数字然后按 Enter(或者点击它的 Use 按钮)。已经在运行的会话会留在它们开始时所用的账户上。对话历史、设置、技能和插件在各账户之间共享,所以在同一文件夹中的 claude --continue 会在新账户上从你离开的地方继续。
当有多个账户时,面板会并排显示每个账户的限额,并标出活动的那一个。默认情况下,当活动账户超过某个限额的 95% 时,Omarchy 会通知你,点击该通知会切换到余量最多的账户。把鼠标悬停在面板中某个账户的行上,点击 Use 旁边出现的 Autoswitch(或者按 m),或者运行 omarchy agent account mode auto,可以让它改为自行切换;开启时,Autoswitch 会取代 Use 的位置,再次点击它就会回到通知方式。添加一个数字可以更改阈值,例如 omarchy agent account mode auto 90。如果每个账户都超过了阈值,你会收到一次通知,并得知哪个账户最先释放额度。当活动账户距离其阈值在 15 个百分点以内时(默认下为 80%),其限额会每三分钟检查一次,而不是每 15 分钟。
omarchy agent account list 显示每个账户及其最新限额,omarchy agent account remove work 忘记一个账户,omarchy agent account rename primary Hey 重命名一个账户(或者在面板中点击一个账户的名称)。这些命令作用于你默认智能体的账户;要访问另一个提供商,先点名它,例如 omarchy agent account use codex side。你已经在 ~/.claude 或 ~/.codex 中拥有的登录是 Main 账户,它会留在原地。一个账户闲置超过约八小时后可能会显示 Sign-in required;点击它可以直接在面板中重新登录该账户,或者在其中启动一个会话,它会自行刷新登录状态。在添加某个账户时你拥有的 MCP 服务器会随之带到该账户,但你后来用 claude mcp add 添加的那些只会到达你添加它们时所在的账户。Claude Desktop 和用 CLI 二进制文件的绝对路径配置的工具不会跟随切换。显式的 CLAUDE_CONFIG_DIR、CODEX_HOME 或 GROK_HOME 优先于所选账户。
崩溃诊断
Omarchy 会监视 systemd-coredump 的进程崩溃。当有东西段错误时,你会收到一条“Process crashed”通知 - - 点击它,崩溃就会连同 Omarchy 的 diagnose-crash skill 一起交给你的默认智能体,该 skill 会引导智能体从核心转储中查清事实,并判断这次崩溃是否值得向上游报告。你也可以用 omarchy agent crash <pid> 针对 coredumpctl list 中的任意 PID 手动运行它。
监视默认开启。在 Trigger > Toggle > Crash Capture 下(或者用 omarchy toggle crash-capture)关闭它,通知就会停止;omarchy agent crash <pid> 仍然可以手动使用。
崩溃也可以逐个程序地静默,这正是诊断在最后向你提供的选项。omarchy crash mute hyprland 只停止该程序的通知,omarchy crash mute hyprland off 把它们带回来,而单独运行 omarchy crash mute 会列出你已静默的内容。它接受二进制文件的路径和接受其名称一样愉快,所以 omarchy crash mute /usr/bin/hyprland 起同样的作用。用引号包住带空格的名称,例如 omarchy crash mute 'Some App'。其他一切仍会通知,而被静默的程序仍然会崩溃 - - 这只是隐藏提醒,它不会修复任何东西。
桌面应用
Install > AI 菜单还带有几个图形化的 AI 应用:ChatGPT 桌面应用、Claude 桌面应用(Anthropic 的 Linux 测试版,带有 Chat、Cowork 和 Claude Code 标签页)、用于与 xAI 的模型聊天的 Grok Bot、Hermes Desktop、OpenClaw、Perplexity 桌面应用和 T3 Code。Grok Bot 是桌面聊天应用。编程智能体是 grok 命令。
Hermes Desktop 是需要了解的那一个,因为一台机器只有一个 Hermes,而它是属于这个应用的:Hermes 只会通过这个应用安装,而默认智能体运行的 hermes 命令也是这个应用的。选择 Hermes 作为默认智能体会安装与 Install > AI 条目相同的东西:这个软件包,以及一个由 Hermes 自己的安装程序在 ~/.hermes 下设置的 Hermes 运行时,第一次需要几分钟。终端的 hermes 命令、默认智能体和这个应用用的都是这一个运行时,它通过 hermes update 自行更新,而不是等待 Omarchy 发布新版本。安装它还会把 Omarchy 主题作为一个名为 omarchy 的皮肤交给 Hermes,每个 Hermes 界面都会在你切换主题时随之变化;如果你不希望这样,在 Hermes 的 Appearance 设置下或者用 /skin 选择另一个,Omarchy 就不会干涉那个选择。在 Remove > AI 下移除这个应用会先关闭 Hermes,包括网关,并带走那个运行时,同时保留你的聊天、记忆以及 Hermes 为自己编写的技能,除非你另有指示:它会询问,默认为否,是否也要删除这些数据和你的连接设置。
OpenClaw 的桌面体验是它的 Control UI,它会作为一个由其自有本地网关支撑的 web 应用打开。OpenClaw 位于 ~/.openclaw 中,并自行更新:使用 Control UI 的“Update Gateway”按钮或者运行 openclaw update,网关会在新版本上重启。Omarchy 只选择全新安装从哪个版本开始。在 Remove > AI 下移除 OpenClaw 会带走网关服务和这个应用,然后询问是否也要删除 ~/.openclaw,因为那里保存了你的聊天和凭据,以及 OpenClaw 本身和它下载的插件运行时;默认会保留它,再次安装 OpenClaw 时会重新拾起它。
T3 Code 从其官方 AppImage 发布版运行,位于 ~/.local/share/t3code 中,而不是从某个软件包运行,所以它会自行更新。安装它时会询问是使用 Stable 还是 Nightly 通道;之后可在 T3 Code 的设置中切换。你的线程和设置位于 ~/.t3 中,在 Remove > AI 下移除 T3 Code 会带走它们。
本地 LLM
Omarchy 推荐两种运行本地 LLM 模型的方式:LM Studio 和 Ollama。LM Studio 提供了一个 GUI 界面,用于查找开放权重模型、安装它们并运行它们。这是一种轻松上手的好方法。Ollama 提供了 CLI 来类似地做到这一点。但如果你刚接触本地模型,我会从 LM Studio 开始。你可以在 Omarchy 菜单的 Install > AI 下安装其中任何一个。
Omarchy Skill
智能体技能帮助 AI 以特定的方式使用特定的工具,而 Omarchy 附带了一个用于定制系统的默认技能。比如调整你的 Hyprland 配置、调整栏,甚至从头创建一个新主题。它被符号链接到 Claude Code(~/.claude/skills)、Codex(~/.codex/skills)、Pi(~/.pi/agent/skills)、Antigravity(~/.gemini/config/skills)、Hermes(~/.hermes/skills 以及每个 ~/.hermes/profiles/*/skills)的技能目录中,以及通用的 ~/.agents/skills 位置,所以大多数 harness 都会自动拾起它。
但你应该把这个技能视为实验性的。不同的模型会以不同的效果使用它。最好先在 plan mode 中运行,这样你就能知道智能体想改什么。然后做好回滚更改的准备,甚至在智能体把一切弄得一团糟时调用 omarchy reinstall configs。