Desktop Guardian
Full macOS GUI access and desktop automation for OpenClaw, powered by Hammerspoon.
What It Does
🖥️ GUI Access
- - Query all open windows, apps, and dialogs with full detail (titles, buttons, states)
- Close specific windows or tabs — not just kill entire apps
- Click buttons in system dialogs and popups (with safety guardrails)
- Send keypresses to any app
- Quit or force-quit apps programmatically
- Chrome DevTools Protocol integration for tab-level browser control
🛡️ Active Desktop Monitoring
- - Watches for system dialogs, permission prompts, error popups, and alerts in real-time
- Auto-dismisses known-safe dialogs (e.g., "app downloaded from internet")
- Alerts you via Telegram/chat when human input is needed (e.g., security prompts)
- Detects and closes unauthorized apps and excess browser windows/tabs
- Enforces configurable desktop policies via YAML rules
- Logs every action for full audit trail
Requirements
- - macOS (Tahoe or later)
- Hammerspoon (installed automatically) + Accessibility permission
- Python 3 + PyYAML (installed automatically)
- Optional: Chrome with
--remote-debugging-port=9222 for tab-level control
Installation
CODEBLOCK0
This will:
- 1. Install Hammerspoon if needed
- Install the DesktopGuardian Spoon
- Guide you through Accessibility permission
- Compile the Swift fallback for degraded mode
- Set up config, logs, and LaunchAgent
Configuration
Config file: INLINECODE1
See assets/config.example.yaml for all options. Key settings:
- - cleanup.enabled: Master switch for auto-cleanup (default: true)
- cleanup.apps.whitelist: Apps allowed to run; others get closed
- browsers.chrome.maxwindows/maxtabs: Limits before auto-close
- dialogs.autodismiss: Apps whose dialogs are safe to dismiss
- dialogs.ignore: Apps whose dialogs should be silently ignored
- alerts.notifyon_actions: Send notification for every auto-action
Chrome Tab Monitoring
For tab-level granularity, Chrome must run with CDP enabled:
CODEBLOCK1
Without CDP, only window counts are available.
Kill Switch
Instantly disable all actions:
CODEBLOCK2
Remove to re-enable:
CODEBLOCK3
Graceful Degradation
Without Hammerspoon, the skill runs in monitor-only mode using a Swift fallback binary. It can detect violations but cannot auto-close or dismiss anything.
helpers.py Subcommands
CODEBLOCK4
Security
- - Never interpolates shell variables into
hs -c commands - Hardcoded button blacklist: won't click Allow, Delete, Install, etc.
- Hardcoded app blacklist: won't dismiss SecurityAgent, Keychain Access, etc.
- All app names validated against INLINECODE4
- Config file mode 600, state uses atomic writes
- Full audit log of every action taken
Uninstall
CODEBLOCK5
Removes LaunchAgent, Spoon, and init.lua entries. Preserves config/logs unless you choose to remove them. Does NOT uninstall Hammerspoon.
Desktop Guardian
为OpenClaw提供完整的macOS GUI访问和桌面自动化功能，由Hammerspoon驱动。
功能概述
🖥️ GUI访问
- - 查询所有打开的窗口、应用和对话框，包含完整详细信息（标题、按钮、状态）
- 关闭特定窗口或标签页——而非直接终止整个应用
- 点击系统对话框和弹出窗口中的按钮（带安全防护机制）
- 发送按键到任意应用
- 以编程方式退出或强制退出应用
- Chrome DevTools协议集成，实现浏览器标签级控制
🛡️ 主动桌面监控
- - 实时监控系统对话框、权限提示、错误弹窗和警告
- 自动关闭已知安全对话框（例如从互联网下载的应用）
- 通过Telegram/聊天工具发送提醒，当需要人工干预时（如安全提示）
- 检测并关闭未经授权的应用及多余的浏览器窗口/标签页
- 通过YAML规则强制执行可配置的桌面策略
- 记录所有操作，提供完整审计追踪
系统要求
- - macOS（Tahoe或更高版本）
- Hammerspoon（自动安装）+ 辅助功能权限
- Python 3 + PyYAML（自动安装）
- 可选：Chrome启用--remote-debugging-port=9222以实现标签级控制
安装
bash
bash scripts/install.sh
该脚本将：
- 1. 按需安装Hammerspoon
- 安装DesktopGuardian Spoon
- 引导您授予辅助功能权限
- 编译Swift降级模式备用程序
- 配置配置文件、日志和LaunchAgent
配置
配置文件：~/.openclaw/skills/desktop-guardian/policy.yaml
所有选项详见assets/config.example.yaml。关键设置：
- - cleanup.enabled：自动清理主开关（默认：true）
- cleanup.apps.whitelist：允许运行的应用白名单，其他应用将被关闭
- browsers.chrome.maxwindows/maxtabs：自动关闭前的数量限制
- dialogs.autodismiss：可安全关闭对话框的应用列表
- dialogs.ignore：应静默忽略对话框的应用列表
- alerts.notifyon_actions：每次自动操作时发送通知
Chrome标签监控
如需标签级精细控制，Chrome必须启用CDP运行：
bash
open -a Google Chrome --args --remote-debugging-port=9222
未启用CDP时，仅能获取窗口数量信息。
紧急开关
立即禁用所有操作：
bash
touch ~/.openclaw/skills/desktop-guardian/KILL_SWITCH
移除以重新启用：
bash
rm ~/.openclaw/skills/desktop-guardian/KILL_SWITCH
优雅降级
未安装Hammerspoon时，该技能将使用Swift备用程序以仅监控模式运行。可检测违规行为，但无法自动关闭或忽略任何内容。
helpers.py子命令
parse_config — 以key=value格式输出配置
validate_config — 验证配置（退出码0/1）
check_quiet — 非静默时段退出码0
evaluate_snapshot — 对快照JSON应用策略 → 违规+操作
parse_query — 将快照转换为key=value格式
safehscommand — 生成安全的hs -c命令字符串
update_state — 更新提醒冷却状态
log_violation — 追加到违规日志
daily_summary — 生成每日摘要
list_apps — 列出上次快照中的应用
check_cooldown — 检查提醒冷却是否已过期
安全性
- - 绝不将shell变量插入hs -c命令
- 硬编码按钮黑名单：不会点击允许、删除、安装等按钮
- 硬编码应用黑名单：不会关闭SecurityAgent、钥匙串访问等应用
- 所有应用名称均通过^[a-zA-Z0-9 ._-]+$验证
- 配置文件权限600，状态使用原子写入
- 所有操作均有完整审计日志
卸载
bash
bash scripts/uninstall.sh
移除LaunchAgent、Spoon和init.lua条目。保留配置/日志，除非您选择删除。不会卸载Hammerspoon。
