vigilnz-openclaw-plugin

VigilNZ runtime security for OpenClaw agents — intercepts tool calls, tool results, agent spawns, LLM requests/responses, and sessions in real time, forwarding events to VigilNZ AgentGuard for risk scoring, policy enforcement, and session-level threat detection.

How it works

OpenClaw Agent
      │
      │  Plugin SDK hooks (7 hooks — see below)
      ▼
vigilnz-openclaw-plugin
      │
      │  1. Fetches full config from AgentGuard on startup
      │     GET /api/openclaw/plugin-config  (x-plugin-key: <key>)
      │
      │  2. Forwards every hook event
      │     POST /api/openclaw/event
      ▼
VigilNZ AgentGuard
      │
      ├── Server-side event classification
      ├── Risk scoring + policy evaluation
      ├── Toxic flow pattern detection (multi-event chain analysis)
      ├── LLM content scanning (sena-engine)
      │
      └── Decision: allow | block | pending_approval
              │
              ├── block            → plugin stops the tool call / spawn immediately
              ├── allow            → OpenClaw proceeds normally
              └── pending_approval → plugin polls for human approval

All settings (fail-open behaviour, payload limits, approval polling) are server-controlled — fetched from AgentGuard at startup. Only the API key and base URL are configured locally.

Every session, its events, risk scores, and blocked actions are visible in the VigilNZ Dashboard → AgentSecure → OpenClaw Sessions.

Prerequisites

| Requirement | Version | |---|---| | OpenClaw | >= 2026.5.20 | | VigilNZ AgentGuard | self-hosted or cloud |

Installation

openclaw plugin install vigilnz-openclaw-plugin

Quick start

1. Create an OpenClaw workflow in VigilNZ

1. Log in to the VigilNZ Dashboard
2. Navigate to AgentSecure → Workflows → New Workflow
3. Select OpenClaw Runtime mode
4. Configure the auto-block risk threshold (default: 70 / 100)
5. Copy the generated API key — you will need it in the next step

2. Set your API key

Add to ~/.openclaw/openclaw.json under the env.vars block:

"env": {
  "vars": {
    "VIGILNZ_OPENCLAW_PLUGIN_KEY": "<your key from AgentGuard dashboard>"
  }
}

Self-hosted AgentGuard? Also add:

"VIGILNZ_API_URL": "http://your-agentguard-host:8080"

3. Restart the gateway

openclaw gateway restart

That's it. The plugin loads automatically on startup (activation.onStartup: true) and fetches its full configuration from AgentGuard — no code changes to your agent are required.

Configuration reference

Only two values are configured locally. All other settings are fetched from AgentGuard at startup via GET /api/openclaw/plugin-config.

| Variable | Required | Default | Description | |---|---|---|---| | VIGILNZ_OPENCLAW_PLUGIN_KEY | Yes | — | API key from the VigilNZ dashboard | | VIGILNZ_API_URL | No | https://api.vigilnz.com | AgentGuard base URL (override for self-hosted) | | AGENTGUARD_URL | No | — | Backward-compatible alias for VIGILNZ_API_URL |

Server-controlled settings (configured per-tenant in AgentGuard):

| Setting | Description | |---|---| | failOpen | Allow events through if AgentGuard is unreachable (default: false) | | approvalEnabled | Enable human-in-the-loop approval polling | | approvalPollIntervalMs | How often to poll for approval decisions | | approvalTimeoutMs | Max wait time before auto-blocking a pending approval | | maxPayloadBytes | Max size of tool args / LLM previews sent per event |

What gets intercepted

The plugin registers 7 OpenClaw hooks automatically — no manual wiring needed.

session_start / session_end

Registers and closes the agent session in AgentGuard. Maintains an internal sessionKey → sessionId map used to resolve parent sessions during agent spawns.

before_tool_call

Every tool invocation is evaluated before execution. AgentGuard classifies the tool type and risk server-side.

Return values:

• allow → OpenClaw proceeds normally
• block → { block: true, blockReason: "[VigilNZ] <reason>" } — call is cancelled
• pending_approval → plugin polls until approved/rejected/timed out

after_tool_call

Tool results are scanned after execution. Fire-and-forget (non-blocking) — does not delay the agent but surfaces result risk scores in the dashboard.

llm_input

Scans the prompt sent to the LLM (system prompt + latest message). Fire-and-forget. Content is truncated to maxPayloadBytes before leaving the process.

llm_output

Scans the LLM's response text. Fire-and-forget. Truncated to maxPayloadBytes.

subagent_spawning

Every agent spawn is gated. The plugin resolves the parent session UUID from the internal session map and sends it to AgentGuard for spawn-chain tracking.

Return values:

• allow → spawn proceeds
• block → { status: "error", error: "[VigilNZ] <reason>" } — spawn is cancelled

Payload scrubbing

Before any event leaves the process, tool arguments and results are scrubbed client-side. The following keys are always redacted to [REDACTED]:

api_key, apikey, key, secret, password, passwd, token, authorization, auth, credential, credentials, private_key, access_token, refresh_token, client_secret, bearer, jwt, session_token

Payloads exceeding maxPayloadBytes are replaced with a truncation summary — the raw content never leaves the agent process.

Risk scoring

AgentGuard maintains a cumulative session risk score (0–100) across all events in a session. When the score exceeds the auto-block threshold set in your workflow (default: 70), the session is blocked and all subsequent events are rejected immediately.

Toxic flow detection

AgentGuard analyses the sequence of events across a session to detect known multi-step attack patterns. Detection is non-blocking — results appear in the dashboard session timeline.

Examples of detected patterns:

• Reconnaissance → privilege escalation → data exfiltration
• Repeated tool calls with escalating permissions
• Deep agent spawn chains attempting to escape monitoring

Human-in-the-loop approvals

When approvalEnabled is set server-side, AgentGuard can return pending_approval for borderline events. The plugin will:

1. Pause the tool call or spawn
2. Poll GET /api/openclaw/approvals/:id at the configured interval
3. Resume or block based on the operator's decision in the dashboard
4. Automatically block after approvalTimeoutMs if no decision is made

Approve or reject from AgentSecure → OpenClaw Sessions → Session Detail → Pending Approvals.

Monitoring sessions

| View | Path | |---|---| | Session list | AgentSecure → OpenClaw Sessions | | Session detail + event timeline | Session → <session id> | | Pending approvals | Session detail → Approvals tab | | Block a session manually | Session detail → Block Session |

Self-hosted AgentGuard

Set VIGILNZ_API_URL to your AgentGuard instance. The plugin needs access to:

GET  <VIGILNZ_API_URL>/api/openclaw/plugin-config     (startup)
POST <VIGILNZ_API_URL>/api/openclaw/event             (every hook)
GET  <VIGILNZ_API_URL>/api/openclaw/approvals/:id     (approvals only)

The plugin uses a 10-second timeout per event POST and a 5-second timeout per approval poll, with up to 3 automatic retries on 5xx errors.

Troubleshooting

Plugin not loading after install

• Confirm vigilnz-security is in plugins.allow in ~/.openclaw/openclaw.json
• Restart the gateway: openclaw gateway restart
• Check gateway logs for remote_config_loaded — confirms the plugin connected to AgentGuard

Events not appearing in the dashboard

• Confirm VIGILNZ_API_URL or AGENTGUARD_URL is reachable from the agent host
• Check that an OpenClaw workflow exists and is active in the dashboard
• Look for [vigilnz-openclaw-plugin] log lines in gateway stdout

All tool calls are being blocked

• The session risk score exceeded the workflow's auto-block threshold
• Review the session timeline in the dashboard for the triggering event
• Lower the threshold in the workflow settings if needed

no_plugin_key warning on startup

• VIGILNZ_OPENCLAW_PLUGIN_KEY is not set — add it to ~/.openclaw/openclaw.json under env.vars

Development

git clone https://github.com/Vigilnz/openclaw-plugin
cd openclaw-plugin

bun install
bun run dev      # watch mode
bun run build    # production build → dist/
bun test         # run tests

Project structure

src/
├── index.ts              # Plugin entry — registers all 7 OpenClaw hooks
├── agentguard-client.ts  # HTTP client — remote config fetch, event posting, approval polling
├── config.ts             # Bootstrap config — API key + URL resolution
├── types.ts              # Shared TypeScript interfaces
├── utils.ts              # Client-side payload scrubbing (secrets/PII redaction)
├── logger.ts             # Structured JSON logger (stdout/stderr)
└── *.test.ts             # Tests

Security

• Tool arguments and results are scrubbed client-side before leaving the process
• Secrets matching known key names are replaced with [REDACTED]
• All communication is over HTTP/HTTPS — use HTTPS in production
• Rotate VIGILNZ_OPENCLAW_PLUGIN_KEY from the dashboard under Workflows → Rotate API Key

License

MIT © Vigilnz