手冊
AI
Omarchy 內含下方編程 agent 的啟動器,但不會替你選定預設值。執行某個指令會在首次使用時安裝其 CLI,然後在出現提示時進行驗證。Hermes 是例外:首次使用時不會為它安裝任何東西,選擇它會安裝 Hermes Desktop,如下方 Desktop apps 一節所述。
| Command | Agent |
|---|---|
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 from Cognition |
dsh |
DeepSeek Harness |
freebuff |
Freebuff, Codebuff’s free, ad-supported coding agent |
grok |
Grok Build from xAI |
hermes |
Hermes, Nous Research’s agent |
kilo |
Kilo, an OpenCode-based coding agent |
kimi |
Kimi Code |
kiro-cli |
Kiro CLI |
mcode |
MiniMax Code, MiniMax’s coding agent |
muse |
Muse Code, Meta’s coding agent |
omp |
Oh My Pi |
ori |
Ori, OpenRouter’s harness |
pi |
Mario Zechner’s Pi |
qwen |
Qwen Code, Alibaba’s coding agent |
ori 是其中的異類:它會用其他的 harness 來執行 OpenRouter 的整個模型目錄,所以 ori claude、ori codex 或 ori opencode 會在你指定的任何模型上啟動那些 agent,而 ori code 則是 Ori 自己的 agent。
安裝與更新 agent
除了 Hermes 之外,這些 agent 都使用 mise 的 lazy installation:第一次啟動時會安裝 CLI,之後的啟動則會重複使用它。mise 也會最多每四小時檢查一次已安裝的 agent 是否有新版本,檢查時機就在它啟動之前,或是在 shell 提示字元下於背景檢查。如果該次更新失敗或你處於離線狀態,就會執行已安裝的版本。omarchy update 會連同 Omarchy 的其他部分一起更新已安裝的 agent,而 mup 則只會更新由 mise 管理的工具。
agent 自己的更新程式,例如 claude update、codex update,或是應用程式中的更新按鈕,並不會更新由 mise 管理的安裝。codex update 會失敗,而 claude update 可能會回報成功,卻安裝了一份 mise 沒有追蹤的獨立副本。如果你寧願使用 agent 原生的安裝程式與更新程式,請將它加入 disable_tools;請參閱 預先安裝的 CLI 工具。
若要在需要之前安裝所有已設定的 lazy 工具,請執行 mise install --include-lazy。這不僅包括這些 agent,也包括 Omarchy 的其他預設 CLI 工具。如需安裝單一工具或使用你自己的安裝,請參閱 預先安裝的 CLI 工具。
grok 是透過 mise 的第一方 grok 套件安裝的,方式與 claude 和 codex 相同。請執行 grok,或在 Setup > Defaults > Agent 下選擇它。跳過 x.ai 上的 curl | bash 安裝程式。那條路徑會在 ~/.grok/bin 放第二份副本、把它加到 PATH 的最前面,並覆寫 Omarchy 的 wrapper。
dsh 會在 127.0.0.1:3080 開啟它的瀏覽器 UI,並以啟動目錄作為其預設 workspace。它的瀏覽器 UI 不接受起始 prompt,所以 omarchy agent prompt 會開啟它,並把 prompt 放在你的剪貼簿中讓你貼上。Omarchy 會以 DeepSeek 的 no-approval 權限預設集啟動它。當你使用 DeepSeek Harness 的官方模型 API 時,它會把 session 記錄上傳到 DeepSeek;請在它的瀏覽器 UI 中的 Settings > General > Upload Session Log 下關閉此功能。你傳送給它的意見回饋也會連同 session 一起上傳,除非你用 DSH_TELEMETRY_MODE=DISABLED 啟動它。
預設 agent
使用 omarchy default agent <name>,或在 Omarchy Menu(Super + Space)的 Setup > Defaults > Agent 下,選擇你的預設 agent。如果該 agent 尚未安裝,選擇它會先將它安裝起來。全新的 Omarchy 會透過一次性的通知邀請你進行這項選擇。
選擇 Claude 時,系統也會嘗試為 Chromium、Chrome、Brave、Brave Origin 和 Edge 設定它的瀏覽器擴充功能。擴充功能的設定會套用到所有使用者,且可能會要求你輸入系統密碼;取消或擴充功能安裝失敗,仍然會選定並啟動 Claude。重新啟動你的瀏覽器,若出現提示,請啟用該擴充功能,並登入 Claude 以完成連接。在 Claude 中執行 /chrome 即可檢查連接狀態。Firefox 和 Zen 不支援此擴充功能。如果在加入此設定之前 Claude 就已經是你的預設值,請再次選擇它以安裝擴充功能。
完成選擇後,Super + Shift + Ctrl + A 會在專用的終端機視窗中啟動預設 agent(若你還沒有進行選擇,則會開啟選擇器)。你也可以用 omarchy agent prompt "Review this project" 直接讓它進入某項任務。Freebuff 和 DeepSeek Harness 不接受起始 prompt,所以它們會改為把 prompt 放在你的剪貼簿中開啟,讓你貼上。以這種方式啟動的 agent 會在各自「不要停下來詢問」的模式下無人值守地執行,所以請做好心理準備,它們真的會動手做事!MiniMax Code 的互動式 session 沒有這種模式,所以它會照常詢問權限。又因為 agent 拒絕記住對你的家目錄的信任,從 $HOME 啟動時會改為在 ~/Work 中開始。
也有終端機快捷方式:a 會在目前的終端機中內嵌執行預設 agent,而 c、cx 和 cy 則直接啟動 OpenCode、Claude Code 和 Codex(同樣是在它們的自動核准模式下)。主題變更也會同步到這些 agent:當你切換 Omarchy 主題時,Claude Code、Pi、OpenCode 和 Hermes(一旦 Omarchy 已安裝它)都會跟著變更。
agent 面板
頂部列有一個 agent 圖示。在你設定好 agent 之前,它的面板會引導你登入 Claude、Codex 或 Grok,第一個登入的就會成為你的預設 agent。之後,面板會把每一個訂閱都放在同一個頁面上:每個 agent 和帳戶連同其方案、各項 5 小時 session 限制與每週限制的計量表以及距離重置還剩的時間(將滑鼠懸停在上面可看到確切的百分比),或是剩餘的預付餘額,全都在一行輪替顯示你所有帳戶總用量(例如本週的 tokens 和你最常用的模型)的文字之下。在 Make something 之下,它會提供起始 prompt,用來製作新主題、plugin 或 app,並把任務交給你的預設 agent。這些 app 的建構方式就跟 Omarchy 自己的 Hype、Monologue 和 Omacut 一樣,使用 C++ 和 Qt Quick,遵循 omarchy-app agent skill,而它們所需的 compiler 和 Qt 元件都會隨附安裝。Claude Code、Codex、Grok、Kimi、Cursor 及其 Grok Bot 額度、GitHub Copilot、Muse、Antigravity、Kimchi 和 Devin 及其限制皆開箱即用地受到涵蓋,而 Hermes、Mistral Vibe 和 Qwen Code 則會在你使用過它們之後顯示其 session 和 tokens。你透過 pi、omp 或 opencode 使用的 Provider 方案和金鑰也會顯示出來:OpenCode Zen 和 Go、Z.ai GLM Coding Plan、Ollama Cloud、MiniMax Token Plan 和 Synthetic 及其限制;Fireworks、OpenRouter 和 DeepSeek 及其預付餘額;以及你在自己硬體上執行的模型,位於 Local models 之下。每個 agent 只會計算一次,歸在向它收費的一方名下,無論你透過多少個 harness 來驅動它。
左鍵點擊列上的圖示可開啟面板,右鍵點擊則可啟動你的預設 agent。它背後的使用記錄每 15 分鐘由 omarchy agent usage-update 重新產生一次,面板甚至可以透過同步資料夾合併來自你其他機器的用量。完整的設定請參閱 $OMARCHY_PATH/shell/plugins/agents/ 下的 README。
多個訂閱
如果你付費訂閱了不只一個 Claude、Codex 或 Grok 方案 - - 比方說,一個個人的 Max 和一個工作的方案 - - Omarchy 可以讓它們全部保持登入,並在它們之間切換。用 agent 面板中的 + 新增一個訂閱,它會直接在那裡引導你完成,或是使用 omarchy agent account add claude Work(或 codex,或 grok)。如果 CLI 不存在,它會將其安裝。某個 Provider 的第一個帳戶會透過你一般的瀏覽器登入,就在 CLI 一直以來查看的位置。之後的每一個帳戶則會透過私密視窗登入,因此你瀏覽器已經登入的帳戶不會被誤選;在那裡以你要新增的帳戶登入,並先關閉你已開啟的任何私密視窗。切勿為了這樣做而登出 CLI:登出會撤銷已儲存的登入狀態,該帳戶就必須重新新增。
若要透過 SSH 將你的訂閱登入資訊複製到另一台 Omarchy 機器,請執行 omarchy agent account copy user@laptop。當目的地沒有安裝接收端時,傳送端會提供一個暫時的接收端,所以較舊的 Omarchy 機器無需更新就能接收帳戶。已安裝的接收端會優先使用。這會複製所有的 Claude、Codex 和 Grok 訂閱;加入 Provider 名稱即可選取它們,例如 omarchy agent account copy laptop claude。帳戶名稱和指令 ID 會與來源一致,包括目的地已經存在的帳戶。若不相關的目的地帳戶名稱衝突,則會獲得數字尾碼,而設定、skills、plugins 和對話記錄則會保留在每台機器本地。
目的地現有的憑證會被保留。某個來源帳戶若已在那裡登入,其名稱會被同步,而不會取代其憑證;其他帳戶則會加在它旁邊。若要取代相符帳戶已儲存的憑證,請在結束目的地該帳戶的 session 後,使用 omarchy agent account copy --replace laptop claude。全新目的地也會取得來源目前使用的帳戶和切換偏好設定;已建立的目的地則會保留它自己的。
憑證會透過 SSH 傳輸,並以私密檔案儲存在目的地,所以只能複製到你信任的機器。這是一次性的複製,不是持續的同步。Codex 的 refresh token 可能會被另一台機器輪替,使複製過去的登入需要更新;若要在多台機器上同時使用,分別登入仍然是最可靠的選擇。請參閱 Codex 的帳戶驗證指南。
每個 Provider 同時只有一個作用中的帳戶,而每個新的 session 都會以它開始:cx、cy、普通的 claude、codex 或 grok、任何透過 omarchy agent 啟動的東西,以及在 PATH 上找到該 CLI 的 scripts 或編輯器。用 omarchy agent account use work 切換(並用 omarchy agent account use main 切換回來),或是在面板中按下某個帳戶的數字再按 Enter(或點擊它的 Use 按鈕)。已經在執行的 session 會維持它們啟動時所用的帳戶。對話記錄、設定、skills 和 plugins 在各帳戶之間共用,所以在同一個資料夾中的 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 則會為某個帳戶重新命名(或在面板中點擊帳戶的名稱)。這些指令作用於你的預設 agent 的帳戶;若要存取另一個 Provider,請先指出它的名稱,例如 omarchy agent account use codex side。你已經在 ~/.claude 或 ~/.codex 中持有的登入是 Main 帳戶,並且會維持原位。一個閒置超過約八小時的帳戶可能會顯示 Sign-in required;點擊它即可直接在面板中重新登入該帳戶,或是在該帳戶中開始一個 session,它會自行重新整理登入狀態。帳戶新增時你所擁有的 MCP servers 會跟著複製過去,但你之後用 claude mcp add 新增的伺服器只會到達你新增它們時所在的那個帳戶。Claude Desktop 和以絕對路徑設定到某個 CLI 二進位檔的工具不會跟隨切換。明確指定的 CLAUDE_CONFIG_DIR、CODEX_HOME 或 GROK_HOME 優先於所選的帳戶。
崩潰診斷
Omarchy 會監看 systemd-coredump 是否有處理程序崩潰。當某個程式發生 segfault 時,你會收到一個「Process crashed」通知 - - 點擊它,崩潰就會連同 Omarchy 的 diagnose-crash skill 一起交給你的預設 agent,該 skill 會引導 agent 從 core dump 建立事實,並判定該崩潰是否值得向上游回報。你也可以用 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'。其他所有程式仍然會發出通知,被靜音的程式也仍然會崩潰 - - 這只是隱藏提醒,並不會修正任何問題。
Desktop apps
Install > AI 選單也包含一些圖形化的 AI app:ChatGPT desktop app、Claude desktop app(Anthropic 的 Linux beta,含有 Chat、Cowork 和 Claude Code 分頁)、用於與 xAI 的模型聊天的 Grok Bot、Hermes Desktop、OpenClaw、Perplexity desktop app 和 T3 Code。Grok Bot 是桌面聊天 app。編程 agent 則是 grok 指令。
Hermes Desktop 是需要特別了解的一個,因為一台機器只有一個 Hermes,而且它屬於這個 app:Hermes 只能透過該 app 安裝,而預設 agent 執行的 hermes 指令也是該 app 的。將 Hermes 選為預設 agent 會安裝與 Install > AI 項目安裝的相同東西:該套件,以及一個由 Hermes 自己的安裝程式設定、位於 ~/.hermes 下的 Hermes runtime,第一次安裝需要幾分鐘的時間。那個 runtime 就是終端機的 hermes 指令、預設 agent 和該 app 共同使用的那一個 Hermes,而且它會用 hermes update 自行更新,而不用等 Omarchy 發布新版。安裝它還會把 Omarchy 主題交給 Hermes,作為名為 omarchy 的 skin,每個 Hermes 的介面都會在你切換主題時跟著變;如果你不想讓它這樣做,請在 Hermes 的 Appearance 設定下或用 /skin 選擇另一個,Omarchy 會尊重那個選擇,不去動它。在 Remove > AI 下移除該 app 會先關閉 Hermes(包括 gateway)、把那個 runtime 一併帶走,並保留你的聊天、記憶,以及 Hermes 為自己寫的 skills,除非你另有指示:它會詢問,預設為否,詢問那些資料和你的連接設定是否也應該一併刪除。
OpenClaw 的桌面體驗是它的 Control UI,它會以 web app 的形式開啟,並由其自有的本地 gateway 提供支援。OpenClaw 位於 ~/.openclaw 中,並會自行更新:使用 Control UI 的「Update Gateway」按鈕,或執行 openclaw update,gateway 就會在新版本上重新啟動。Omarchy 只會選擇全新安裝的起始版本。在 Remove > AI 下移除 OpenClaw 會把 gateway 服務和該 app 一併帶走,然後詢問 ~/.openclaw 是否也應該刪除,因為那裡除了 OpenClaw 本身及其下載的 plugin runtime 之外,還包含你的聊天和憑證;預設會保留它,重新安裝 OpenClaw 時會再次取用它。
T3 Code 不是從套件安裝,而是從其位於 ~/.local/share/t3code 中的官方 AppImage 版本執行,所以它會自行更新。安裝它時會詢問你要在 Stable 還是 Nightly 頻道上開始;之後可以在 T3 Code 的設定中切換。你的 threads 和設定位於 ~/.t3 中,並且在 Remove > AI 下移除 T3 Code 會把它們一併帶走。
Local LLMs
Omarchy 推薦兩種執行本地 LLM 模型的方式:LM Studio 和 Ollama。LM Studio 提供一個 GUI 介面,用於尋找開放權重模型、安裝它們,並執行它們。這是輕鬆入門的好方法。Ollama 則提供一個 CLI 以類似的方式進行。但如果你是本地模型的新手,我會建議從 LM Studio 開始。你可以在 Omarchy Menu 的 Install > AI 下安裝其中任一種。
The Omarchy Skill
Agent skills 幫助 AI 以特定方式使用特定工具,而 Omarchy 隨附了一個用於量身打造系統的預設 skill。就像是調整你的 Hyprland 設定、調整列,或甚至是從頭建立一個新主題。它被 symlink 進 Claude Code(~/.claude/skills)、Codex(~/.codex/skills)、Pi(~/.pi/agent/skills)、Antigravity(~/.gemini/config/skills)、Hermes(~/.hermes/skills 和每個 ~/.hermes/profiles/*/skills),以及通用的 ~/.agents/skills 位置的 skill 目錄中,所以大多數 harness 都會自動取用它。
但你應該把這個 skill 視為實驗性的。不同的模型會以不同程度發揮它的效果。最好先在 plan mode 中執行,這樣你就能對 agent 想要變更的內容有個概念。然後準備好回復變更,甚至在 agent 把一切弄得一團糟時,呼叫 omarchy reinstall configs。