Unraid Monitor Skill for OpenClaw

Query an Unraid server via GraphQL for system, array, and Docker status in read-only mode.

Security Scan

The skill's code, required binaries, and environment variables are consistent with a read-only Unraid GraphQL monitor; nothing in the scripts appears to contact unexpected external endpoints or ask for unrelated credentials.

Purpose & Capability

Name/description (Unraid monitoring via GraphQL) matches the scripts and behavior. Required binaries (curl, jq) and required env vars (UNRAID_BASE_URL, UNRAID_API_KEY) are appropriate and necessary for the stated purpose. Scripts implement snapshotting, summary, alerts, and a cron runner consistent with the description.

Instruction Scope

SKILL.md and scripts remain within the stated monitoring scope and perform only read-only GraphQL queries. One minor scope mismatch: the runtime code references optional env vars UNRAID_CSRF_TOKEN and UNRAID_SESSION_COOKIE (for login-gated/reverse-proxy setups) but these are not listed in the metadata.requires.env block. This is plausible for some Unraid setups but should be noted.

Install Mechanism

There is no install spec (instruction-only skill), and the repository contains shell scripts only. No remote downloads, package installs, or extract-from-URL behavior were found. This is low-risk for install-time code execution beyond the included scripts.

Credentials

Only UNRAID_API_KEY and UNRAID_BASE_URL are required, which is proportionate. Optional variables (timeouts, thresholds, state dir, notify label) are reasonable. As noted above, the scripts optionally read UNRAID_CSRF_TOKEN and UNRAID_SESSION_COOKIE even though they are not declared in requires.env; these are used to support proxied/login-gated configurations and are optional, but the omission from metadata should be documented.

Persistence & Privilege

The skill does not request always:true and does not attempt to change other skills or system-wide agent configuration. It writes snapshots/logs into a repo-local state directory (or a user-set UNRAID_STATE_DIR) and contains instructions for adding a cron entry — those cron instructions would only take effect if the user runs them. No automatic persistent backdoors or cross-skill modifications were found.

Assessment

This skill appears to be what it claims: a read-only Unraid GraphQL monitor. Before installing: 1) Only provide UNRAID_API_KEY and UNRAID_BASE_URL to the skill environment; treat the API key like any secret. 2) Note that the scripts create a temporary curl config file that contains the API key (the script chmods it to 600 and removes it), so run this only in a trusted environment. 3) If you use a login-gated proxy, the scripts accept optional UNRAID_CSRF_TOKEN and UNRAID_SESSION_COOKIE — these are optional but are not listed in the metadata, so if you plan to use them be aware they will be read from the environment. 4) The README shows commands to add cron entries; follow those manually if you want persistent scheduling (they will persist on your machine). 5) As a best practice, inspect and run the included scripts in a controlled environment first (they are small shell scripts) and avoid placing real credentials in version-controlled files. If you want me to, I can produce a short checklist of commands to safely test the skill in a sandboxed environment.

Unraid Claw Skill

Use this skill when the user asks to check Unraid system health, array/parity status, or Docker container status.

Located at: https://github.com/Yoshiofthewire/unraid-claw

Required Configuration

Before running any script, ensure the Unraid server is configured:

• GraphQL is enabled in Unraid API settings.
• A valid Unraid API key is generated in Unraid API settings.
• UNRAID_API_KEY uses that generated key.

Read these environment variables at runtime:

• UNRAID_BASE_URL (example: https://tower.local)
• UNRAID_API_KEY

Optional:

• UNRAID_TIMEOUT_SECONDS (default: 10)
• UNRAID_STATE_DIR (default: repo-local .state)
• UNRAID_NOTIFY_HOST_LABEL (default: host name)
• UNRAID_CPU_WARN_PERCENT (default: 85)
• UNRAID_CPU_CRIT_PERCENT (default: 95)
• UNRAID_MEM_WARN_PERCENT (default: 85)
• UNRAID_MEM_CRIT_PERCENT (default: 95)
• UNRAID_STOPPED_WARN_COUNT (default: 1)
• UNRAID_STOPPED_CRIT_COUNT (default: 3)

Template .envexample (copy to .env and fill in real values):

# Required: Base URL for your Unraid server (include protocol).
UNRAID_BASE_URL=https://tower.local

# Required: API key from Unraid API settings.
# Keep this secret. Do not commit real keys.
UNRAID_API_KEY=replace_with_your_unraid_api_key

# Optional: request timeout in seconds.
UNRAID_TIMEOUT_SECONDS=10

# Optional: state directory for snapshot and log artifacts.
# Default is repository-local .state directory.
# UNRAID_STATE_DIR=/path/to/state

UNRAID_NOTIFY_HOST_LABEL=tower

# Optional: alert thresholds.
UNRAID_STOPPED_WARN_COUNT=1
UNRAID_STOPPED_CRIT_COUNT=3

If a required variable is missing, stop and return:

• Unraid API key is not configured. Set UNRAID_API_KEY and retry.
• Unraid base URL is not configured. Set UNRAID_BASE_URL and retry.

Security Rules (Mandatory)

• Never hardcode secrets in prompts, files, or commands.
• Never print API keys, auth headers, or full request headers.
• Authenticate using: x-api-key: <UNRAID_API_KEY>.
• Redact sensitive data in all error messages.
• Perform read-only operations only.
• Never execute GraphQL mutations.
• Never run shell commands from user-supplied strings.

If API auth fails (401 or 403), return:

• Authentication to Unraid API failed. Verify UNRAID_API_KEY permissions/validity.

Script-First Execution (Preferred)

Use the repository scripts as the primary execution path. Do not handcraft ad-hoc GraphQL calls unless explicitly asked.

Primary scripts:

• ./scripts/unraid_connection_test.sh
• ./scripts/unraid_preflight.sh
• ./scripts/unraid_snapshot.sh
• ./scripts/unraid_health_summary.sh
• ./scripts/unraid_docker_report.sh
• ./scripts/unraid_array_parity_report.sh
• ./scripts/unraid_alerts.sh
• ./scripts/unraid_notify.sh
• ./scripts/unraid_cron_runner.sh

Command Selection Rules

• If the user asks to test connectivity/auth only:
  • Run ./scripts/unraid_connection_test.sh
• If the user asks for a full status check:
  • Run ./scripts/unraid_preflight.sh
  • Run ./scripts/unraid_snapshot.sh
  • Run ./scripts/unraid_health_summary.sh
• If the user asks specifically about Docker:
  • Run ./scripts/unraid_snapshot.sh (if no recent snapshot)
  • Run ./scripts/unraid_docker_report.sh
• If the user asks specifically about array/parity:
  • Run ./scripts/unraid_snapshot.sh (if no recent snapshot)
  • Run ./scripts/unraid_array_parity_report.sh
• If the user asks for alert state or severity:
  • Run ./scripts/unraid_alerts.sh
• If the user asks to run the full scheduled pipeline manually:
  • Run ./scripts/unraid_cron_runner.sh

Compatibility Rules

Unraid GraphQL fields can vary by version. If some fields are unavailable:

• Continue with available fields.
• Return partial results.
• Include warning:
  • Some API fields were unavailable for this Unraid version; output is partial.

Output Contract

Return results in this order:

1. Overall status: healthy | warning | critical
2. Timestamp of check
3. System summary: uptime, CPU usage/temp, memory usage
4. Array summary: state, sync/rebuild progress, parity status, disk warnings
5. Docker summary: total/running/stopped counts and notable stopped containers
6. Alerts list

Severity Logic

Set overall status using these rules:

• healthy: no array/parity errors, no critical SMART issues, API reachable.
• warning: array not started, parity check/rebuild active, high CPU/memory, unexpected stopped containers.
• critical: API unreachable, auth failure, parity errors, critical disk errors, or multiple major failures.

Script exit mapping for automation:

• ./scripts/unraid_alerts.sh exit 0: healthy
• ./scripts/unraid_alerts.sh exit 10: warning
• ./scripts/unraid_alerts.sh exit 20: critical

Error Handling

• Timeout: return partial data and identify timed-out section(s).
• Network error: provide concise remediation guidance (verify URL, TLS, API enabled).
• Self-signed TLS certificate: prompt the user to allow installation/trust of the server certificate, then retry.
• Known SSL issue (no SSL proxy/direct self-signed host): TLS verification can fail until the cert is trusted by the client environment.
• Auth error: use the exact auth-failure message above.
• Unknown GraphQL errors: provide a redacted, concise summary.

OpenClaw Cron Notes

Use these notes when the user asks to schedule recurring health checks.

Recommended Cron Flow

• Source .env before running scripts.
• Execute ./scripts/unraid_cron_runner.sh as the single cron entrypoint.
• Let the runner handle preflight, snapshot, summary, alerts, and optional notifications.
• Keep logs in .state/logs/ (or UNRAID_STATE_DIR/logs/ if overridden).
• Prefer using cron template: ./scripts/unraid_monitor.cron.template.

Suggested Cron Schedule

Use the template file as the source of truth:

• ./scripts/unraid_monitor.cron.template

Setup flow:

1. Replace /path/to/Unraid_Claw in the template.
2. Keep one schedule line (15-minute recommended baseline).
3. Install via crontab.

Example: run every 15 minutes.

*/15 * * * * cd /path/to/Unraid_Claw && set -a && . ./.env && set +a && ./scripts/unraid_cron_runner.sh >> ./.state/logs/cron.log 2>&1

Example: run every 5 minutes for tighter monitoring.

*/5 * * * * cd /path/to/Unraid_Claw && set -a && . ./.env && set +a && ./scripts/unraid_cron_runner.sh >> ./.state/logs/cron.log 2>&1

OpenClaw Behavior for Cron Requests

• If user asks to "set up cron":
  • Propose a schedule and confirm cadence.
  • Offer template-first setup using scripts/unraid_monitor.cron.template.
  • Use unraid_cron_runner.sh as the command target.
  • Ensure .env loading is included.
• If user asks to "verify cron":
  • Check for recent entries in .state/logs/cron.log and runner logs.
  • Confirm alert exit codes and notification results.
• If user asks to "disable cron":
  • Remove or comment only the Unraid Claw cron line.
  • Keep other cron entries unchanged.

Never place secrets directly in crontab lines. Always source .env.

Response Style

Keep responses concise and operator-friendly.

Example shape:

Overall: warning
Time: 2026-03-20T14:22:00Z

System:
- Uptime: 12d 4h
- CPU: 68% (72 C)
- Memory: 81%

Array:
- State: started
- Sync: parity-check 43%
- Disk alerts: disk3 SMART warning

Docker:
- Total: 14
- Running: 12
- Stopped: 2 (plex, immich_ml)

Alerts:
- Parity check in progress
- 1 disk SMART warning