omarchy

Omarchy Skill

管理 Omarchy Linux 系统 —— 一个漂亮、有趣、面向 Agent 的 Arch Linux 发行版，搭载 Hyprland。

本 skill 用于已安装系统上的最终用户自定义。 不适用于为 Omarchy 源代码做贡献。

主题指南

常见领域的深入说明就在本文件旁边。开始前请阅读 对应的指南：

• hyprland.md - 快捷键绑定、显示器、窗口规则及其他 Hyprland 配置
• plugins.md - Omarchy shell：状态栏布局、小组件、插件、空闲行为
• theming.md - 主题、背景和字体
• hooks.md - 在系统事件上运行的自动化钩子
• capture.md - 截图、屏幕录制、OCR 文本捕获和文件共享
• contributing.md - 报告 Omarchy bug 并向上游提交修复

关键安全规则

对于特权命令，请遵循下方的提权规则：当有终端可用于输入密码提示时使用 sudo，没有终端时使用 pkexec。不要对本身已负责提权的命令再做包装。

对于最终用户自定义任务，切勿修改 /usr/share/omarchy/ 中的任何内容 —— 但读取是安全的，而且值得鼓励。

该目录归 omarchy 软件包所有。任何本地更改都会在 下一次 omarchy update 时被覆盖。

/usr/share/omarchy/     # READ-ONLY - NEVER EDIT (reading is OK)
├── bin/                    # Command source (packaged binaries are on PATH)
├── config/                 # Default config templates
├── themes/                 # Stock themes
├── default/                # System defaults
├── shell/                  # Omarchy shell source and defaults
├── migrations/             # Update migrations
└── install/                # Installation scripts

读取 /usr/share/omarchy/ 是安全的，而且很有用 —— 可以放心地通过它来：

• 了解 omarchy 命令如何工作：omarchy theme set --help 或 cat $(which omarchy-theme-set)
• 在自定义之前查看默认配置：cat "$OMARCHY_PATH/config/omarchy/shell.json"
• 查看可供复制用于自定义的出厂主题文件
• 参考默认 hyprland 设置：cat /usr/share/omarchy/default/hypr/*

请始终改用这些安全位置：

• ~/.config/ - 用户配置（可安全编辑）
• ~/.config/omarchy/themes/<custom-name>/ - 自定义主题
• ~/.config/omarchy/hooks/ - 自定义自动化钩子

如果请求是开发 Omarchy 本身，则不在本 skill 的范围内。请遵循仓库开发说明，而不是本 skill。

提权

对于在可见终端中运行的交互式脚本或命令，请使用 sudo 进行 特权操作。Omarchy 可能会为特定命令授予免密码的 sudo 访问权限， 而需要密码时，终端正是请求密码的合适位置。

仅当调用方无法与终端交互、或无法在终端中输入密码时，才使用 pkexec， 例如由 Agent 或图形后台进程启动的命令。不要仅仅因为某条命令会改变系统状态，就用 pkexec 替换 sudo。

系统架构

Omarchy 构建于：

组件	用途	配置位置
Arch Linux	基础 OS	/etc/、~/.config/
Hyprland	Wayland 合成器/窗口管理器	~/.config/hypr/
Omarchy shell	状态栏 + 通知（Quickshell）	~/.config/omarchy/shell.json
启动器/菜单	Quickshell 菜单	~/.config/omarchy/extensions/omarchy-menu.jsonc
Alacritty/Foot/Kitty/Ghostty	终端	~/.config/<terminal>/
Omarchy OSD	屏幕显示	Quickshell 插件

命令发现

Omarchy 提供单一的 omarchy 命令行工具，通过 omarchy <group> <action> 分发到所有 omarchy-* 二进制文件。请始终优先使用这种形式 —— 它自文档化且稳定。底层的 omarchy-* 二进制文件仍然存在于 PATH 中，读取其源码依然安全。

# List every documented command and its summary (--all includes hidden commands)
omarchy commands

# Show the commands inside a group
omarchy theme --help
omarchy refresh --help
omarchy restart --help

# Show help for a specific command (does not execute it)
omarchy theme set --help

# Machine-readable listing (binary, route, summary, args, aliases)
omarchy commands --json

# Read a command's source to understand it
cat $(which omarchy-theme-set)

命令组

运行 omarchy --help 查看完整列表。最常用的命令组：

命令组	用途	示例
omarchy refresh	将配置重置为默认值（会先备份）	omarchy refresh shell
omarchy restart	重启服务/应用	omarchy restart shell
omarchy toggle	开关某项功能	omarchy toggle nightlight
omarchy theme	主题管理	omarchy theme set <name>
omarchy bar	状态栏布局与小组件	omarchy bar move omarchy.clock --section right
omarchy plugin	管理/克隆 shell 插件	omarchy plugin clone omarchy.clock
omarchy hook	安装自动化钩子	omarchy hook install theme-set <script>
omarchy install	安装可选软件 / 软件包	omarchy install docker dbs
omarchy launch	启动应用	omarchy launch browser
omarchy capture	截图和录屏	omarchy capture screenshot
omarchy reminder	桌面通知提醒	omarchy reminder 15 "Pickup Jack"
omarchy pkg	软件包管理	omarchy pkg add <pkg>
omarchy setup	交互式设置向导	omarchy setup security fingerprint
omarchy update	系统更新	omarchy update

配置文件位置

Hyprland 配置位于 ~/.config/hypr/ —— 参见 hyprland.md。 Omarchy shell（状态栏、通知、插件、空闲）在 ~/.config/omarchy/shell.json 中配置 —— 参见 plugins.md。

终端

~/.config/alacritty/alacritty.toml
~/.config/foot/foot.ini
~/.config/kitty/kitty.conf
~/.config/ghostty/config

命令： omarchy restart terminal

其他配置

应用	位置
btop	~/.config/btop/btop.conf
fastfetch	默认 /etc/fastfetch/config.jsonc；用户覆盖 ~/.config/fastfetch/config.jsonc
lazygit	~/.config/lazygit/config.yml
starship	~/.config/starship.toml
git	~/.config/git/config

安全的自定义模式

直接编辑用户配置

对于简单的更改，编辑 ~/.config/ 中的文件：

# 1. Read current config
cat ~/.config/hypr/bindings.lua

# 2. Backup before changes
cp ~/.config/hypr/bindings.lua ~/.config/hypr/bindings.lua.bak.$(date +%s)

# 3. Make changes with Edit tool

# 4. Apply changes
# - Hyprland: auto-reloads on save, but MUST validate with `hyprctl reload` and `hyprctl configerrors`
# - Omarchy shell: shell.json and user plugin code under ~/.config/omarchy/plugins/ hot-reload on save
# - Menus/launcher: ~/.config/omarchy/extensions/omarchy-menu.jsonc hot-reloads on save
# - Terminals: apply with `omarchy restart terminal` (reloads running terminals; foot picks changes up in new windows)

重置为默认值 —— 运行前务必先获得用户确认

当自定义配置出问题时：

# Reset specific config (creates backup automatically)
omarchy refresh shell
omarchy refresh hyprland

# The refresh command:
# 1. Backs up current config with timestamp
# 2. Copies default from $OMARCHY_PATH/config/
# 3. Restarts the component where the refresh needs it (e.g. `refresh shell`)

系统命令

omarchy update                  # Full system update
omarchy version                 # Show Omarchy version
omarchy debug --no-sudo --print # Debug info (ALWAYS use these flags)
omarchy system lock             # Lock screen
omarchy system shutdown         # Shutdown
omarchy system reboot           # Reboot

重要： 始终使用 --no-sudo --print 标志运行 omarchy debug，以避免交互式 sudo 提示导致终端挂起。

故障排查

# Get debug information (ALWAYS use these flags to avoid interactive prompts)
omarchy debug --no-sudo --print

# Reset specific config to defaults
omarchy refresh <app>

# Refresh specific config file
# config-file path is relative to ~/.config/
# eg. `omarchy refresh config hypr/hyprland.lua` will refresh ~/.config/hypr/hyprland.lua
omarchy refresh config <config-file>

# Full reinstall of configs (nuclear option)
omarchy reinstall

决策框架

当用户请求系统更改时：

1. 是 omarchy 内置命令吗？ 直接使用它
2. 是配置编辑吗？ 在 ~/.config/ 中编辑，绝不要编辑 /usr/share/omarchy/
3. 是主题自定义吗？ 遵循 theming.md；创建一个新的自定义主题目录
4. 是自动化吗？ 遵循 hooks.md；使用 omarchy hook install 和钩子 .d 目录
5. 是安装软件包吗？ 使用 omarchy pkg add <pkgs...>（仅限 AUR 的软件包使用 omarchy pkg aur add <pkgs...>）
6. 是内置 shell/插件代码吗？ 遵循 plugins.md；使用 omarchy plugin clone 克隆它，绝不要编辑打包的副本
7. 不确定命令是否存在？ 运行 omarchy commands（或运行 omarchy <group> --help 查看某个命令组）

提醒请求

当用户要求设置提醒时，直接使用 omarchy reminder <minutes> [message]。将自然语言时长转换为分钟，并在适当情况下将简短的提醒标签首字母大写。

omarchy reminder 15 "Pickup Jack"
omarchy reminder 60 "Check laundry"
omarchy reminder show
omarchy reminder clear

范围之外

本技能有意不涵盖 Omarchy 源码开发。请勿将本技能用于：

• 编辑 /usr/share/omarchy/ 中的文件（bin/、config/、default/、shell/、themes/、migrations/ 等）
• 创建或编辑迁移
• 运行 omarchy dev ... 命令

示例请求

• “把我的主题改成 catppuccin” -> omarchy theme set catppuccin
• “添加一个 Super+E 键绑定来打开文件管理器” -> 先检查现有绑定，然后在 ~/.config/hypr/bindings.lua 中使用 o.rebind 替换一个绑定，或使用 o.bind 添加一个绑定
• “配置我的外接显示器” -> 编辑 ~/.config/hypr/monitors.lua
• “把窗口间隙调小一些” -> 编辑 ~/.config/hypr/looknfeel.lua
• “打开夜灯” -> omarchy toggle nightlight（如需基于时间的计划，编辑 ~/.config/hypr/hyprsunset.conf 配置文件，然后执行 omarchy restart hyprsunset）
• “设置一个 15 分钟后接 Jack 的提醒” -> omarchy reminder 15 "Pickup Jack"
• “显示我的提醒” -> omarchy reminder show
• “清除所有提醒” -> omarchy reminder clear
• “自定义 catppuccin 主题颜色” -> 覆盖：将编辑过的 colors.toml 放入 ~/.config/omarchy/themes/catppuccin/，然后重新应用主题（参见 theming.md）
• “每次我更换主题时运行一个脚本” -> 使用 omarchy hook install theme-set <script> 安装它
• “更改工作区标签的渲染方式” -> 克隆 omarchy.workspaces，这会将状态栏切换为 <username>.workspaces，然后编辑该克隆
• “十分钟后锁定” -> 在 ~/.config/omarchy/shell.json 中将 idle.lock 设置为 600
• “将 shell/状态栏重置为默认值” -> omarchy refresh shell
• “录制我的屏幕” -> omarchy screenrecord --fullscreen，然后 omarchy screenrecord --stop-recording（参见 capture.md）
• “向 Omarchy 报告此 bug” -> 收集诊断信息和问题捕获，然后提交（参见 contributing.md）