Tools
Openclaw_event_server_plugin
By Event server plugin for OpenClaw
Install
npm install
npmConfiguration Example
{
"plugins": {
"entries": {
"event-server-plugin": {
"enabled": true,
"config": {
"webhooks": [
{
"url": "https://example.com/events",
"method": "POST"
}
],
"queue": {
"maxSize": 1000,
"flushIntervalMs": 5000,
"persistToDisk": false
},
"status": {
"workingWindowMs": 30000,
"sleepingWindowMs": 600000,
"tickIntervalMs": 5000,
"subagentIdleWindowMs": 300000
},
"redaction": {
"enabled": false,
"replacement": "[REDACTED]",
"fields": ["content", "params", "token", "authorization"]
},
"eventLog": {
"enabled": true,
"path": ".event-server/events.ndjson",
"maxFileSizeMb": 30,
"format": "full-json",
"minLevel": "debug",
"includeRuntimeLogs": true
},
"security": {
"ws": {
"bindAddress": "127.0.0.1",
"requireAuth": false,
"authToken": "",
"allowedOrigins": [],
"allowedIps": []
},
"hmac": {
"enabled": false,
"secretFilePath": ".event-plugin-hmac.secret",
"algorithm": "sha256"
}
},
"retry": {
"maxAttempts": 3,
"initialDelayMs": 1000,
"maxDelayMs": 30000,
"backoffMultiplier": 2
},
"filters": {
"includeTypes": [],
"excludeTypes": []
},
"hookBridge": {
"enabled": false,
"dryRun": false,
"allowedActionDirs": ["/absolute/path/to/hooks"],
"localScriptDefaults": {
"timeoutMs": 10000,
"maxPayloadBytes": 65536
},
"actions": {
"sudo-alert": {
"type": "webhook",
"url": "https://example.com/hook/sudo-alert",
"method": "POST"
},
"wake-parent": {
"type": "local_script",
"path": "/absolute/path/to/hooks/wake-parent.sh",
"args": []
}
},
"rules": [
{
"id": "notify-sudo",
"when": {
"eventType": "tool.called",
"toolName": "exec",
"contains": {
"data.params.command": "sudo"
}
},
"action": "sudo-alert",
"cooldownMs": 60000
}
],
"toolGuard": {
"enabled": false,
"dryRun": false,
"timeoutMs": 15000,
"onError": "allow",
"rules": [
{
README
# OpenClaw Event Server Plugin
Most teams using OpenClaw hit the same wall: important agent activity is hard to operationalize because it lives in logs, scattered channels, or manual checks. This plugin solves that by turning agent behavior into clean, real-time events (WebSocket or webhook) that your automations can consume immediately, plus configurable Tool Guard controls to block risky tool calls and require human approval when needed. In practice, you install it, point events to your systems, and define guard rules.
Use cases:
- Send Slack alerts when tool calls fail or agents error.
- Feed `agent.status` and `agent.activity` into dashboards for live visibility.
- Trigger downstream jobs from session lifecycle events (`session.start`, `session.end`).
- Require human approval for risky tools (`web_search`, `web_fetch`, `browser`, `exec` with `sudo`).
- Write normalized events to long-term storage for audit, compliance, or analytics.
- Wake a sleeping parent agent when their sub agent stalls, finishes or times out
- Cost guardrails: monitor high-frequency tool loops and block when token/tool usage crosses per-session budgets.
- Knowledge capture: when a run succeeds after multiple failures, auto-log the successful tool sequence to docs/wiki.
- subsequent agent setup. Bot A finishes a writing a youtube script and goes idle, event server triggers an alert to Bot B to review script and make adjustments, OR if bot A fails or stalls, retries Bot A.
User senarios:
- Live content studio control room: a creator runs multiple agents for research, scripting, clipping, and posting. Event Server becomes the “producer dashboard” that shows who is working, who is stuck, and when a draft is ready. Tool Guard adds a human checkpoint before anything publishes or sends outreach.
- Founder daily ops autopilot: a small business owner uses agents for inbox triage, lead follow-up, and report generation. Event streams turn this into a visible operations timeline, so they can see bottlenecks and response speed. Tool Guard keeps high-risk actions (sending, spending, exporting) human-approved.
- Streamer has an openclaw agent monitoring his chat and uses it to manage interactivity in his live stream, Event server is feeding status updates and if the agent dies, stalls or goes inactive, calls a script to spawn a new agent with little to no downtime.
- Creative memory engine: every finished run emits structured “what worked” events into a reusable idea bank. Over time, creators build a searchable playbook of winning hooks, formats, and campaign patterns.
How does it actually work?
Openclaw Event Server Plugin is built around 3 things:
1. Event server; This simply finds all the various events throughout openclaw and presents them in an easy to consume format.
2. Hook Bridge; execute a script file or webhook when an event is captured
3. Tool Guard; Openclaw ships with exec approval by default, but it does not have anything for other tools, this plugin fills that gap and allows users to create approval workflows or block possibly dangerous tool calls
It emits:
- Raw internal hook events (`message:*`, `command:*`, `agent:*`, `gateway:startup`)
- Raw plugin hook events (`before_tool_call`, `after_tool_call`, `tool_result_persist`, session/subagent/gateway typed hooks)
- Synthetic events (`agent.activity`, `agent.status`, `agent.sub_agent_spawn`)
## Transport
- WebSocket broadcast server (default ports: `9011,9012,9013,9014,9015,9016`)
- HTTP webhooks with retry/queue support
## Event Model
All emitted events use one canonical envelope so consumers can parse every event type consistently.
All emitted events use a canonical envelope:
- `eventId`
- `schemaVersion`
- `timestamp`
- `type`
- `eventCategory`
- `eventName`
- `source`
- `agentId`, `sessionId`, `sessionKey`, `runId`, `toolCallId` (when available)
- `correlationId`
- `result`/`error` (when relevant)
- `data`
- `metadata`
### Supported event types
Synthetic event types are computed by this plugin and are not native upstream gateway events.
- Message: `message.received`, `message.transcribed`, `message.preprocessed`, `message.sent`
- Tool: `tool.called`, `tool.guard.matched`, `tool.guard.allowed`, `tool.guard.blocked`, `tool.completed`, `tool.error`, `tool.result_persist`
- Command: `command.new`, `command.reset`, `command.stop`
- Session: `session.start`, `session.end`
- Subagent: `subagent.spawning`, `subagent.spawned`, `subagent.ended`
- Subagent synthetic: `subagent.idle`
- Agent: `agent.bootstrap`, `agent.error`, `agent.session_start`, `agent.session_end`
- Gateway: `gateway.startup`, `gateway.start`, `gateway.stop`
- Synthetic: `agent.activity`, `agent.status`, `agent.sub_agent_spawn`
- Legacy aliases preserved for compatibility: `session.spawned`, `session.completed`, `session.error`
## Install
Choose one install path:
1. Install from npm (recommended for most users; no local build needed):
```bash
openclaw plugins install openclaw-event-server-plugin
```
2. Install from local source (for contributors/dev):
```bash
npm install
npm run build
openclaw plugins install -l /absolute/path/to/openclaw_event_server_plugin
```
When installing from local source, `dist/` must be built before installation.
## Compatibility
Compatibility is pinned to a known OpenClaw hook surface and enforced by contract tests.
- Pinned hook-surface fixture: OpenClaw commit `7b5e64ef2e369258e2a4a613b7a62db3c21e5160`.
- Compatibility is enforced by fixture-driven contract tests (`tests/contract/openclaw-hook-surface.test.ts`).
- Additional versions can be documented by adding new hook-surface fixtures when validated.
## Configure
Use this as the primary runtime config for transport, retries, logging, security, filtering, redaction, status timing, and automation behavior.
In `~/.openclaw/openclaw.json`:
```json
{
"plugins": {
"entries": {
"event-server-plugin": {
"enabled": true,
"config": {
"webhooks": [
{
"url": "https://example.com/events",
"method": "POST"
}
],
"queue": {
"maxSize": 1000,
"flushIntervalMs": 5000,
"persistToDisk": false
},
"status": {
"workingWindowMs": 30000,
"sleepingWindowMs": 600000,
"tickIntervalMs": 5000,
"subagentIdleWindowMs": 300000
},
"redaction": {
"enabled": false,
"replacement": "[REDACTED]",
"fields": ["content", "params", "token", "authorization"]
},
"eventLog": {
"enabled": true,
"path": ".event-server/events.ndjson",
"maxFileSizeMb": 30,
"format": "full-json",
"minLevel": "debug",
"includeRuntimeLogs": true
},
"security": {
"ws": {
"bindAddress": "127.0.0.1",
"requireAuth": false,
"authToken": "",
"allowedOrigins": [],
"allowedIps": []
},
"hmac": {
"enabled": false,
"secretFilePath": ".event-plugin-hmac.secret",
"algorithm": "sha256"
}
},
"retry": {
"maxAttempts": 3,
"initialDelayMs": 1000,
"maxDelayMs": 30000,
"backoffMultiplier": 2
},
"filters": {
"includeTypes": [],
"excludeTypes": []
},
"hookBridge": {
"enabled": false,
"dryRun": false,
"allowedActionDirs": ["/absolute/path/to/hooks"],
"localScriptDefaults": {
"timeoutMs": 10000,
"maxPayloadBytes": 65536
},
"actions": {
"sudo-alert": {
"type": "webhook",
"url": "https://example.com/hook/sudo-alert",
"method": "POST"
},
"wake-parent": {
"type": "local_script",
"path": "/absolute/path/to/hooks/wake-parent.sh",
"args": []
}
},
"rules": [
{
"id": "notify-sudo",
"when": {
"eventType": "tool.called",
"toolName": "exec",
"contains": {
"data.params.command": "sudo"
}
},
"action": "sudo-alert",
"cooldownMs": 60000
}
],
"toolGuard": {
"enabled": false,
"dryRun": false,
"timeoutMs": 15000,
"onError": "allow",
"rules": [
{
"id": "approve-exec",
"when": {
"toolName": "exec"
},
"action": "wake-parent"
}
]
}
}
}
}
}
}
}
```
## Environment Variables
Use environment variables for quick overrides in containers, CI, and one-off debugging.
- `EVENT_PLUGIN_WEBHOOKS` comma-separated webhook URLs
- `EVENT_PLUGIN_AUTH_TOKEN` bearer token applied to env-defined webhooks
- `EVENT_PLUGIN_DEBUG` enable debug logging
- `EVENT_PLUGIN_INCLUDE_TYPES` comma-separated include filters
- `EVENT_PLUGIN_EXCLUDE_TYPES` comma-separated exclude filters
- `EVENT_PLUGIN_ENABLED` enable/disable plugin
- `EVENT_PLUGIN_WS_PORTS` comma-separated WS fallback order
- `EVENT_PLUGIN_DISABLE_WS` disable WS server
- `EVENT_PLUGIN_DISABLE_STATUS_TICKER` disable periodic synthetic status ticks (tests/CI)
- `EVENT_PLUGIN_TOOL_GUARD_TRACE` set `1`/`true` to emit verbose Tool Guard evaluation/action traces
- `EVENT_PLUGIN_STATUS_WORKING_WINDOW_MS` override working activity window
- `EVENT_PLUGIN_STATUS_SLEEPING_WINDOW_MS` override sleeping wind
... (truncated)
tools
Comments
Sign in to leave a comment