功能描述

macOS GUI automation and desktop control for OpenClaw, powered by Hammerspoon. Gives your agent full access to interact with the Mac desktop — query windows,...

使用说明 (SKILL.md)

Desktop Guardian

Name: Desktop Guardian
Author: s3rous

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

bash scripts/install.sh

This will:

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: ~/.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.

安全使用建议

This skill is plausible for desktop automation, but take these precautions before installing: - Inspect the package contents: install.sh expects a DesktopGuardian.spoon under Spoons/ which is not present in the provided manifest — verify the Spoon files exist and inspect them before copying into ~/.hammerspoon. - Review helpers.py functions that build hs command strings (safe_hs_command / _safe_hs_close_window) to confirm they strictly validate and escape inputs; the monitor uses eval "$HS_CMD" to run those strings which is risky if any input can be manipulated. Prefer not to run code that uses eval on generated shell strings unless you have audited the generator. - Back up ~/.hammerspoon/init.lua before installation; the installer will append lines to it. - Be cautious granting Accessibility and enabling Hammerspoon: this skill will be able to control your GUI, click buttons, and quit apps. Only grant those permissions if you fully trust the code. - The LaunchAgent runs every 60s and can take actions autonomously; if you prefer manual control, do not install the LaunchAgent or run monitor.sh interactively first to observe behavior. - Chrome CDP: enabling --remote-debugging-port exposes Chrome internals on localhost; only enable it if you understand the implications. If you are not comfortable auditing the Spoon and the hs-command-building code, run the skill in degraded/monitor-only mode (no Accessibility/Hammerspoon) or avoid installing it. If you proceed, inspect logs at ~/Library/Logs/desktop-guardian and verify actions before enabling auto-cleanup.

功能分析

Type: OpenClaw Skill Name: desktop-guardian Version: 2.0.0 The skill is classified as suspicious due to its high privilege requirements (macOS Accessibility for Hammerspoon) and the use of `eval` in `scripts/monitor.sh` to execute commands. While the `scripts/helpers.py` module implements robust input sanitization (`_lua_escape`, `validate_app_name`, `re.match` for tab IDs) to prevent shell injection into the `hs -c` commands, the presence of `eval` still represents a significant vulnerability surface. A flaw in this sanitization could lead to arbitrary command execution. The skill also establishes persistence via a LaunchAgent (`com.openclaw.desktop-guardian.plist`) for its 'always-on' monitoring, which is a high-risk capability, though transparently declared for its stated purpose.

能力评估

ℹ Purpose & Capability

The declared purpose (macOS GUI automation via Hammerspoon and a monitor agent) aligns with the files and instructions: it installs Hammerspoon, configures a Spoon, compiles a Swift fallback, and installs a LaunchAgent to run monitor cycles. That level of system access (Accessibility permission, LaunchAgent, modifying ~/.hammerspoon/init.lua) is proportionate to the stated goal of active desktop monitoring and automated GUI actions.

⚠ Instruction Scope

Monitor and install instructions perform powerful system actions (create LaunchAgent, modify ~/.hammerspoon/init.lua, grant Accessibility, install Homebrew casks and pip packages). The monitor runs every 60s and will autonomously execute pre-built hs commands to click UI elements and close apps. The monitor script uses eval "$HS_CMD" to run commands produced by helpers.py; despite claims that shell interpolation is never used, using eval on generated strings increases risk if any builder of those strings can be influenced. The skill also suggests opening Chrome with --remote-debugging-port, which exposes Chrome internals on localhost and is a separate security consideration.

ℹ Install Mechanism

There is no remote download of arbitrary code; install.sh uses Homebrew to install Hammerspoon, pip to install PyYAML, and compiles a local Swift fallback. That's reasonable. However, install.sh copies a DesktopGuardian Spoon from $PROJECT_DIR/Spoons/DesktopGuardian.spoon — the provided file manifest does not include a Spoons directory or the Spoon contents, which is an inconsistency that will cause install errors or unexpected outcomes. The script also requires Homebrew to be present and will abort if missing.

✓ Credentials

The skill requests no environment variables or external credentials. It writes user-scoped files under the home directory and modifies user Hammerspoon configuration and LaunchAgents — these are expected for local desktop automation. No unrelated cloud credentials or secrets are requested.

ℹ Persistence & Privilege

The skill installs a LaunchAgent that runs monitor.sh every 60 seconds and adds a Spoon load to ~/.hammerspoon/init.lua. That gives continuous, autonomous capability to observe and act on the desktop (including auto-closing apps and dismissing dialogs). 'always' is false, but the agent will act autonomously when installed — this is consistent with the monitoring purpose but increases blast radius if combined with other implementation issues (see eval usage).

版本历史

v2.0.0

Initial release

元数据

Slug desktop-guardian

版本 2.0.0

许可证 —

累计安装 1

当前安装数 1

历史版本数 1

常见问题