@upx-us/shield

OpenClaw Shield

OpenClaw Shield is a paid security service by UPX. Start your free 60-day trial (no credit card required) at upx.com/en/lp/openclaw-shield-upx.

OpenClaw Shield is the first SIEM-powered security solution built for AI agents — not to control what they can do, but to detect what they did.

While agent sandboxes block at the gate, Shield watches from inside: every tool call, file read, command execution, and outbound request is ingested, enriched, and matched against behavioral detection rules in real time. Anomalies become cases. Cases get playbooks.

What you get:

• 🔍 90+ detection rules tuned for OpenClaw agents — continuously curated and expanded by UPX security experts
• 📋 Automated case generation with remediation playbooks
• 🔒 Cryptographic event integrity (HMAC-SHA256, AES-256-GCM)
• 🏷️ Full trigger attribution — who prompted what, when, and why
• 🧹 Built-in data redaction before events leave the host
• ☁️ Powered by Google SecOps (Chronicle) — the same enterprise SIEM trusted by security teams worldwide

Shield is designed to complement the security controls built into OpenClaw and any Claw-based solution — not replace them. Zero-trust policies, sandboxed execution, and private routing control what your agent can do. Shield adds what they can't: a continuous forensic record of what it did, with behavioral detection and automated case management on top.

Works alongside any hardening strategy, out of the box. For example, solutions like NemoClaw control the perimeter. Shield owns the forensics.

Shield is a local collector. It captures agent activity, redacts sensitive data, and forwards clean telemetry to the UPX platform at uss.upx.com — where security rules, correlation, alerting, playbooks, and case management give your team full visibility. The plugin itself stays lean and transparent; all the heavy lifting happens on the platform side.

Your Agent → Shield (local: capture + redact) → UPX Platform → Google SecOps (detection, cases, forensics)

Features

Feature	Description
Real-time monitoring	Captures all agent tool calls, file operations, messages, and sessions
On-device redaction	Hostnames, usernames, secrets, and paths replaced with deterministic tokens before transmission
Local event buffer	Rolling log of recent events — inspect via openclaw shield logs without platform access
Case notifications	Automatic alerts when detection rules fire — agent notifies you of new cases
Case resolution	Close cases with categorization (resolution + root cause) directly from your agent
False positive learning	Mark cases as false positive — Shield remembers and auto-suppresses identical future alerts
Host inventory	Discovers all agents and workspaces on the machine — view via openclaw shield vault show
Auto-update	Patch and minor updates install automatically with rollback on failure
Encrypted vault	Redaction mappings stored locally with AES-256-GCM — UPX cannot reverse tokens

Prerequisites

• OpenClaw Gateway installed and running (openclaw gateway status)
• An Installation Key provided by your Shield administrator (looks like: A1B2C3D4E5F6...)

Installation

Prerequisites

• OpenClaw Gateway installed and running (openclaw gateway status)
• An Installation Key from your Shield dashboard at uss.upx.com → APPS → OpenClaw Shield

Commands Reference

Command	Description
openclaw shield activate <KEY>	Activate with your Installation Key (one-time)
openclaw shield status	Show monitoring status, event counts, and health
openclaw shield flush	Trigger an immediate poll cycle
openclaw shield logs	Show recent events from local buffer (--last N, --type, --since, --format)
openclaw shield investigate <case-id>	Guided investigation: fetch case detail, step-by-step path, and resolution examples
openclaw shield resolve <case-id> --reason <text>	Mark a case as resolved with a reason (e.g. authorized-maintenance)
openclaw shield close <case-id> --reason <reason>	Dismiss a case as a false positive or other reason
openclaw shield help	Full command reference (INVESTIGATION, RESOLUTION, DISCOVERY sections)
openclaw shield cases	List open security cases from the platform
openclaw shield cases show <ID>	Full case detail with events, rule info, and playbook
openclaw shield cases resolve <ID>	Resolve a case (--resolution, --root-cause, --comment)
openclaw shield vault show	Show host agent inventory (hashed IDs)
openclaw shield exclusions	List false positive exclusions
openclaw shield exclusions remove <ID>	Remove an exclusion to re-enable alerts

Agent RPCs (used by the agent skill, not CLI):

RPC	Description
shield.status	Current monitoring status, health, and counters
shield.flush	Trigger an immediate telemetry poll cycle
shield.events_recent	Query recent events from local buffer
shield.events_summary	Event counts by type and tool
shield.subscription_status	Subscription and quota information
shield.cases_list	List open cases + pending notifications
shield.case_detail	Full case detail with events, rule, playbook
shield.case_resolve	Close a case with resolution and root cause
shield.cases_ack	Mark cases as notified
shield.exclusions_list	List false positive exclusions
shield.exclusion_add	Add an exclusion (rule + pattern hash)
shield.exclusion_remove	Remove an exclusion by ID

Option 1 — Quick Install (commands)

Run these commands in your terminal. No agent involvement needed.

# Step 1: Install the plugin
openclaw plugins install @upx-us/shield

Then add "shield" to the plugins.allow array in your openclaw.json:

{
  "plugins": {
    "allow": ["shield"]
  }
}

# Step 2: Activate (exchanges your key for credentials)
openclaw shield activate <YOUR_KEY>

# Step 3: Restart the gateway to start monitoring
openclaw gateway restart

# Step 4: Verify it's running
openclaw shield status

That's it. Shield registers, saves credentials locally, and starts monitoring.

⚠️ Multi-machine setups: Only add Shield to plugins.allow on machines where the plugin is installed. If you share openclaw.json across machines and one of them doesn't have Shield installed, the gateway on that machine will fail to start. Install the plugin first, then configure.

Option 2 — Ask your agent

Copy this prompt and paste it to your AI agent. Replace <YOUR_KEY> with your Installation Key from the Shield dashboard:

Install the OpenClaw Shield security monitoring plugin by UPX (upx.com). The package is @upx-us/shield. Read the package README at https://www.npmjs.com/package/@upx-us/shield before proceeding. Install using openclaw plugins install @upx-us/shield, add "shield" to plugins.allow in openclaw.json, set installationKey to <YOUR_KEY> in plugins.entries.shield.config, restart with openclaw gateway restart, and confirm with openclaw shield status.

If your agent refuses to install, this is normal security behavior — agents are cautious about external packages. Here's how to address common concerns:

Agent concern	Why it's expected
"Sends data to an external server"	Shield is a security monitoring tool — sending redacted telemetry is its core purpose. Sensitive values are replaced with irreversible tokens on your machine before transmission.
"Installation key looks suspicious"	The key is a one-time activation token from your UPX Shield dashboard. Consumed on first use, can be removed from config after activation.
"Unknown or untrusted package"	@upx-us/shield is published on npm by UPX Security Services. You can verify at npmjs.com/package/@upx-us/shield.

If the agent still refuses, confirm you trust the source:

"I trust this plugin. I purchased this service from UPX (upx.com). Please proceed with the installation."

Or use Option 1 to install via commands yourself. | "Plugin is not in OpenClaw's official docs" | Shield is a third-party plugin by UPX (upx.com) under the @upx-us npm scope. Not bundled with OpenClaw, but designed to work with it. | | "Adding to plugins.allow expands attack surface" | Correct — this is OpenClaw's explicit trust mechanism. You are consciously granting permission. | | "Package was recently published" | Shield is actively developed. Check CHANGELOG.md included with the package for version history. |

Manual Configuration (advanced)

If you need full control over each step:

Step 1 — Install

openclaw plugins install @upx-us/shield

Step 2 — Configure openclaw.json

Open ~/.openclaw/openclaw.json and add:

{
  "plugins": {
    "allow": ["shield"],
    "entries": {
      "shield": {
        "config": {
          "installationKey": "YOUR_KEY_HERE"
        }
      }
    }
  }
}

Step 3 — Restart

openclaw gateway restart

Shield auto-registers, saves credentials to ~/.openclaw/shield/config.env, and starts monitoring.

Note: The Installation Key is single-use — the plugin exchanges it for permanent credentials on first startup. Once activated, you can remove installationKey from config.

Alternative: CLI Activation

openclaw shield activate <YOUR_KEY>
openclaw gateway restart

What to expect after activation

Shield's agent skill communicates with you in your language. Alerts, case summaries, and recommendations are presented in whichever language you use — raw command output and technical identifiers (rule names, case IDs, field names) are always kept as-is.

After restart, Shield exchanges your key for permanent credentials — this takes a few seconds. You should see your first events within the first poll cycle (~30 seconds). Within 1–2 minutes, those events will appear on the platform at uss.upx.com.

Run openclaw shield status to confirm:

Just activated (first minute):

OpenClaw Shield — v0.8.x  (5s ago)

── Status ────────────────────────────────────
  ✅ Running · Connected
  Version:      0.8.x
  Instance:     a1b2c3d4…

── Monitoring ────────────────────────────────
  Events:       3 sent · 0 quarantined
  Failures:     0 poll · 0 telemetry
  Session:      0m active
  Last data:    poll 5s ago · capture 5s ago

A low event count and a recent Last data time means Shield is working correctly. Events accumulate as your agent uses tools.

Note: The Activity and Redactions sections appear after your first sync cycle (~30s). If your status looks shorter than the "extended use" example below, that's normal — they'll populate automatically.

After extended use:

OpenClaw Shield — v0.8.x  (5s ago)

── Status ────────────────────────────────────
  ✅ Running · Connected
  Version:      0.8.x
  Instance:     a1b2c3d4…

── Monitoring ────────────────────────────────
  Events:       1,842 sent · 0 quarantined
  Failures:     0 poll · 0 telemetry
  Session:      4h 12m active
  Last data:    poll 5s ago · capture 14s ago

── Activity ──────────────────────────────────

📡 Last sync  (29s ago — 5 events)
  exec                 ████████  3
  file                 █████     2

📊 This session  (since restart 4h 12m ago — 142 events)
  TOOL_CALL            ████████  78
  TOOL_RESULT          ███████   64

🔒 Redactions  (10x this session)
  hostname data            redacted 5x
  username data            redacted 5x
  (original values stored encrypted locally — never transmitted)

When not activated:

OpenClaw Shield — v0.8.x

  Status: Loaded (not activated)

  To activate, provide your Installation Key:
    1. openclaw shield activate <YOUR_KEY>
    2. Add to openclaw.json:
         plugins.entries.shield.config.installationKey = "<YOUR_KEY>"
       Then: openclaw gateway restart

  Get your key at: https://uss.upx.com → APPS → OpenClaw Shield

Understanding the status output

Event types

Shield captures what your agent does — tool invocations and their results — not what it says.

The Activity section shows two levels:

• Session-level (TOOL_CALL, TOOL_RESULT) — every tool invocation and result, shown in the "This session" summary
• Sync-level (exec, file, web, etc.) — the specific event type after parsing, shown in "Last sync"

exec: 2 in Last sync means 2 of those synced events were shell commands. Those same 2 are also counted within the TOOL_CALL total in the session view. They are not separate.

Event type	What it means
TOOL_CALL	A tool was invoked by the agent
TOOL_RESULT	The result returned from a tool call
exec	Shell command executed
file	File read, written, or edited
web	URL fetched, web search, or browser action
message	Message sent via a channel (Telegram, WhatsApp, etc.)
sessions_spawn	A sub-agent was launched
browser	Browser automation action
cron	A scheduled task fired

Quarantine

Quarantine counts events that failed local schema validation and were held back rather than forwarded to the platform. They are not lost — written to ~/.openclaw/shield/data/quarantine.jsonl for inspection. A non-zero quarantine count usually means a plugin version mismatch; upgrading Shield typically resolves it.

Redactions

Redaction runs locally before anything leaves your machine. The counts shown are occurrences — how many times sensitive data was detected and replaced with a reversible token (e.g. host:a3f9b1c2, user:7b2c4a1f). Original values are stored in an encrypted local vault and never transmitted.

All-time vs. session

• Events sent / Quarantine = all-time totals, persisted across gateway restarts
• This session = since the last gateway restart
• Last sync = the most recent poll cycle only

Warnings

When status shows ⚠️ Capture health degraded, the plugin is connected but capture activity is not syncing successfully. This is not triggered by idle sessions.

Use Last capture as the first diagnostic:

• Recent Last capture + warning present → investigate sync pipeline health
• Old Last capture + no warning → normal idle behavior

Local Event Buffer

Shield stores a rolling log of recently sent events locally for offline inspection and debugging.

Location: ~/.openclaw/shield/data/event-log.jsonl

Defaults:

• Last 250 events or 24 hours (whichever limit is reached first)
• Enabled by default
• Events are stored after redaction — same data sent to the platform

CLI usage:

openclaw shield logs                  # last 10 events
openclaw shield logs --last 20        # last N events
openclaw shield logs --type TOOL_CALL # filter by event type
openclaw shield logs --since 30m      # events from last 30 minutes
openclaw shield logs --format json    # JSON output for piping

Configuration (in config.env or environment variables):

Variable	Default	Description
SHIELD_LOCAL_EVENT_BUFFER	true	Set to false to disable local storage
SHIELD_LOCAL_EVENT_LIMIT	250	Maximum number of events to retain

What data is collected

Shield captures agent activity locally, applies on-device redaction, and forwards telemetry to the UPX platform.

Data type	Captured	Redacted on-device before transmission
Tool name	✅	—
Command strings	✅	✅ secrets, paths replaced with tokens
File paths	✅	✅ username segment replaced with token
Tool result output	✅	✅ truncated and redacted
Hostname	✅	✅ replaced with token
Username	✅	✅ replaced with token
URLs	✅	—
API keys detected in commands	✅	✅ replaced with token

How redaction works: sensitive values are replaced with deterministic category:hash tokens before leaving your machine. Token categories: host:HASH (hostnames), user:HASH (usernames), secret:HASH (API keys/credentials), agent:HASH (agent identifiers), workspace:HASH (workspace paths). The mapping from token → original value is stored in an encrypted local vault (~/.openclaw/shield/data/redaction-vault.json, AES-256-GCM) so your team can reverse-lookup locally if needed. Original values are never transmitted to the platform. Run openclaw shield vault show to inspect current token mappings.

Authorship & Event Source

Shield captures the source of every event — who or what triggered the agent action being monitored.

Each event is tagged with an authorship category:

Category	Description
Communication channel	A user interacted with the agent via a messaging platform (e.g. Telegram, Discord, WhatsApp)
Scheduled job	The action was triggered by a scheduled or automated task
Heartbeat	The action was triggered by a periodic health check
Sub-agent	The action originated from a child agent spawned by a parent
Autonomous	The agent acted on its own initiative without a direct human trigger

This information appears alongside every event in your security dashboard, enabling you to answer "who caused this?" for any alert or case.

What is sent to the platform

Shield uses two separate channels with different privacy properties:

Telemetry (operational identity)

Sent every ~5 minutes over HTTPS. This tells the platform where the instance is running, not what it does. It does not pass through the redaction pipeline.

{
  "machine": {
    "hostname": "openclaw-agent",
    "os": "linux",
    "arch": "x64",
    "node_version": "v22.x.x",
    "public_ip": "1.2.3.4"
  },
  "software": {
    "plugin_version": "0.3.x",
    "openclaw_version": "2026.x.x",
    "agent_label": "main",
    "instance_name": "openclaw-agent"
  }
}

Telemetry fields like hostname, public_ip, and instance_name are operational identity signals used for geo-correlation in detection rules and instance health monitoring. They travel over HTTPS and are never exposed publicly.

Events (behavioural data)

Sent every poll cycle over HTTPS. This is the data stream subject to the full redaction pipeline. Per-event fields include: tool name, redacted command/path/output, timestamp, session ID, and action type. Sensitive values are replaced with category:hash tokens before transmission.

The distinction: telemetry = who/where the instance is (slim, operational). Events = what the agent did (redacted, privacy-protected).

How your data is protected

Redaction runs locally before any data leaves your machine. The redactor detects hostnames, usernames, file paths, API keys, and secrets — replacing them with deterministic category:hash tokens. The token→original mapping is stored in an AES-256-GCM encrypted vault (~/.openclaw/shield/data/redaction-vault.json, mode 0600).

Authentication uses HMAC-SHA256 with a per-instance key. Every request is signed — requests with invalid signatures are rejected.

Credentials are stored locally at ~/.openclaw/shield/config.env (mode 0600) and are never transmitted.

Upgrading

Manual upgrade

openclaw plugins update shield
openclaw shield status

Cursors and credentials are preserved across upgrades. See the CHANGELOG (available on the Shield portal at uss.upx.com) for version history.

"Integrity drift detected" during upgrade is expected — OpenClaw warns when plugin files change, which always happens on a legitimate upgrade. This only indicates a real problem if you see it without having explicitly upgraded.

Auto-update

Shield can check for and install newer versions automatically.

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "shield": {
        "config": {
          "autoUpdate": "notify-only"
        }
      }
    }
  }
}

Mode	Behavior
false	Disabled. No version checks.
"notify-only"	Logs available updates but does not install.
true	(default) Automatically installs patch and minor versions. Major updates require manual upgrade.

When autoUpdate is true, Shield backs up the current version before installing and automatically rolls back if anything fails. Gateway is restarted after a successful update.

Troubleshooting

Shield shows "not activated" → Get your Installation Key at uss.upx.com → APPS → OpenClaw Shield → Install → Add to openclaw.json and restart the gateway (see Manual Installation above)

Activated but no events after 5 minutes → Run openclaw shield status — check Failures count and Last sync time → Check Last capture: if it's recent, Shield is capturing but may have a sync issue — restart the gateway → If Last capture is old, your agent may not have used any tools yet — try running a command and check again → Enable debug logging: LOG_LEVEL=debug openclaw start

High CPU or memory usage → Increase poll interval: "pollIntervalMs": 60000 in plugin config (default: 30000ms)

Cursor file issues → To reset: rm ~/.openclaw/shield/data/cursor.json — Shield reinitializes on next poll

Dry-run mode (no events sent) → Add "dryRun": true to plugin config — events are processed and logged but never transmitted

Investigation & Case Management

When Shield detects suspicious activity, a case is created and you receive an alert. Use the following commands to investigate and resolve:

Guided investigation

openclaw shield investigate <case-id>

Fetches case detail from the platform and walks you through:

• What rule fired and why
• A step-by-step investigation path (log review, timestamp correlation, intent assessment)
• Resolution examples (resolve, dismiss as false positive)

Falls back gracefully when the platform API is unreachable — all steps remain useful offline.

Resolving a case

# Authorized operation
openclaw shield resolve <case-id> --reason authorized-maintenance

# False positive
openclaw shield close <case-id> --reason false-positive

resolve marks a case as benign or user-initiated. close is a convenience alias for dismissing false positives.

Full command reference

openclaw shield help

Prints all available commands organized into INVESTIGATION, RESOLUTION, and DISCOVERY sections.

FAQ

How long until I see my first event on the platform? Within 1–2 minutes of activation. Shield polls every ~30 seconds; the platform processes events within seconds of receipt.

How do I verify it's working end-to-end? Run openclaw shield status and check that Events sent is increasing and Last capture is recent. Then visit uss.upx.com and check your instance — you should see events flowing within 2 minutes.

What if I don't see any events after 5 minutes? Check openclaw shield status for elevated Failures or a stale Last sync. If failures are high, restart the gateway. If Last capture is old, your agent hasn't used any tools — run a command to generate activity.

Can I run Shield alongside other plugins? Yes. Shield runs as a passive observer — it hooks into the event stream and does not interfere with other plugins or agent behavior.

Is my Installation Key burned if activation fails? No. The key is consumed only on the first successful activation. If the attempt fails (network issue, config error), you can fix the issue and retry with the same key.

Where is the changelog? See CHANGELOG.md included with the plugin.

Subscription expiry

When a subscription lapses or the monthly event quota is exhausted, Shield detects this on the next ingest call and will:

• Log a clear warning
• Pause delivery and retain cursor position so events can be retried after service is restored
• Show elevated consecutive failures in openclaw shield status

Renew your subscription at uss.upx.com and restart the gateway to resume delivery.

Uninstalling

1. Remove the plugin

openclaw plugins uninstall shield

2. Remove local Shield data (optional — recommended for privacy hygiene)

rm -rf ~/.openclaw/shield/

This removes all local files Shield writes at runtime:

File	Contents
config.env	Signing key and instance fingerprint
data/cursor.json	Event cursor positions per log source
data/public-ip.cache	Cached public IP for telemetry
data/instance-cache.json	Cached instance metadata
data/exclusions.json	Allowlist entries (suppress specific patterns)
data/case-monitor-state.json	Case notification state (acknowledged case IDs)
data/event-log.jsonl	Local event ring buffer (24h)
data/redaction-vault.json	Redaction token → original value mapping

⚠️ Redaction vault: data/redaction-vault.json maps redaction tokens back to original values (secrets, hostnames, file paths). Once deleted, you cannot reverse-lookup redacted values from past events. Retain this file for as long as your data retention policy requires before deleting.

3. Deactivate the platform instance

Removing local files does not automatically deactivate your registration on the UPX platform.

To fully remove your instance: log in to uss.upx.com → Instances → Delete.

Until deactivated, the instance remains registered and may count against your subscription quota.

Need help?

Visit uss.upx.com or contact your Shield administrator.

License & Distribution

The skill wrapper is distributed under MIT-0 on ClaWHub as required by the platform. The underlying plugin and platform remain proprietary UPX Technologies, Inc. IP.