什么是 Desktop Guardian？

Desktop Guardian 是专为 Openclaw Skills 生态系统设计的综合自动化套件，利用 Hammerspoon 提供对 macOS 桌面环境的深度访问。它赋予 AI 智能体执行复杂任务的能力，如查询窗口状态、点击 UI 元素以及精准管理浏览器标签页。

除了简单的执行，它还充当主动坚控器，识别系统警报并执行用户定义的桌面策略以维持有序的工作空间。通过桥接 LLM 推理与 macOS 辅助功能 API，它为 Openclaw Skills 架构内的桌面管理提供了稳健的框架。

下载入口:https://github.com/openclaw/skills/tree/main/skills/s3rous/desktop-guardian

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Desktop Guardian 应用场景

• 使 AI 智能体能够与原生 macOS 应用程序和系统对话框交互
• 自动关闭非关键系统弹窗和权限提示
• 通过关闭未经授权的应用或过多的浏览器标签来维护桌面整洁
• 坚控需要人工干预的安全警报或硬件提示
• 在 Openclaw Skills 框架内简化 macOS 辅助功能工作流

1. 该技能通过 Hammerspoon 和后台 LaunchAgent 初始化，以坚控桌面状态。
2. 它通过 macOS 辅助功能 API 持续快照打开的窗口、活动应用和系统对话框。
3. 自动化引擎根据位于用户目录中的 YAML 策略文件评估这些快照。
4. 如果检测到违规（例如：浏览器标签过多或存在未经授权的应用），它会执行预定义的动作，如关闭窗口或发送按键。
5. 对于关键提示，它可以通过外部集成提醒用户，确保人类在敏感安全决策中保持参与。

Desktop Guardian 配置指南

要安装 Openclaw Skills 库的此组件，请在终端中执行以下命令：

bash scripts/install.sh

该脚本处理 Hammerspoon 安装、配置 DesktopGuardian Spoon 并设置必要的 LaunchAgents。在此过程中，系统将提示您授予 Hammerspoon 辅助功能权限。配置通过 ~/.openclaw/skills/desktop-guardian/policy.yaml 进行管理。

Desktop Guardian 数据架构与分类体系

该技能通过特定的目录结构和元数据分类来组织运行：

name: desktop-guardian
description: "macOS GUI automation and desktop control for OpenClaw, powered by Hammerspoon. Gives your agent full access to interact with the Mac desktop — query windows, manage apps, close browser tabs, click dialog buttons, dismiss popups, and send keypresses. Includes an always-on desktop guardian that actively monitors for system dialogs, permission prompts, error popups, and unauthorized apps, taking action automatically or alerting you when human input is needed. Use when: (1) your agent needs to interact with the macOS GUI, (2) monitoring and responding to desktop popups/dialogs/alerts, (3) managing open apps, browser windows, and tabs, (4) enforcing desktop cleanliness policies, (5) any macOS Accessibility automation from OpenClaw."

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 T@elegrimm/ch@t 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

bash scripts/install.sh

This will:

1. Install Hammerspoon if needed
2. Install the DesktopGuardian Spoon
3. Guide you through Accessibility permission
4. Compile the Swift fallback for degraded mode
5. Set up config, logs, and LaunchAgent

Configuration

Config file: ~/.openclaw/skills/desktop-guardian/policy.yaml

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.max_windows/max_tabs: Limits before auto-close
• dialogs.auto_dismiss: Apps whose dialogs are safe to dismiss
• dialogs.ignore: Apps whose dialogs should be silently ignored
• alerts.notify_on_actions: Send notification for every auto-action

Chrome Tab Monitoring

For tab-level granularity, Chrome must run with CDP enabled:

open -a "Google Chrome" --args --remote-debugging-port=9222

Without CDP, only window counts are available.

Kill Switch

Instantly disable all actions:

touch ~/.openclaw/skills/desktop-guardian/KILL_SWITCH

Remove to re-enable:

rm ~/.openclaw/skills/desktop-guardian/KILL_SWITCH

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

parse_config          — Output config as key=value pairs
validate_config       — Validate config (exit 0/1)
check_quiet           — Exit 0 if NOT in quiet hours
evaluate_snapshot     — Apply policy to snapshot JSON → violations + actions
parse_query           — Convert snapshot to key=value pairs
safe_hs_command       — Generate safe hs -c command string
update_state          — Update alert cooldown state
log_violation         — Append to violation log
daily_summary         — Generate daily summary
list_apps             — List apps from last snapshot
check_cooldown        — Check if alert cooldown has expired

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 ^[a-zA-Z0-9 ._-]+$
• Config file mode 600, state uses atomic writes
• Full audit log of every action taken

Uninstall

bash scripts/uninstall.sh

Removes LaunchAgent, Spoon, and init.lua entries. Preserves config/logs unless you choose to remove them. Does NOT uninstall Hammerspoon.