@capsulesecurity/openclaw-capsule

Capsule plugin for OpenClaw. Forwards every OpenClaw hook event to your Capsule agentsecurity tenant and applies async hook verdicts (block, params rewrite, approval prompt) returned by Capsule policy.

Install

npm i @capsulesecurity/openclaw-capsule

Configure

Add the plugin to your OpenClaw plugin config:

{
  "plugins": [
    {
      "package": "@capsulesecurity/openclaw-capsule",
      "config": {
        "endpoint": "https://agents.capsule.security",
        "token": "<jwt-signed-with-tenant-OPENCLAW_SECRET>",
        "blockOnRisk": true,
        "failOpen": true,
        "timeoutMs": 5000,
        "allowConversationAccess": false,
      },
    },
  ],
}

| Option | Default | Description | | ------------------------- | --------------------------------- | ---------------------------------------------------------------------------- | | endpoint | — | Capsule agentsecurity base URL. | | token | — | JWT with tid (tenant) and eid (env external ID) claims. | | blockOnRisk | true | Apply server block verdicts. Set to false for shadow mode. | | failOpen | true | Allow the agent to proceed when Capsule is unreachable. | | timeoutMs | 5000 | Per-request timeout in ms. | | allowConversationAccess | false | When true, parse ~/.openclaw/agents/{id}/sessions/{sid}.jsonl and forward. | | pluginVersion | package version | Tag every event with a custom plugin identifier. | | user | process.env.USER or "unknown" | User identifier sent on every event. |

Hooks

• Blocking (priority 100): before_tool_call, before_agent_reply, before_install
• Synchronous audit (priority 100, fire-and-forget): before_message_write
• Observation (priority 10, fire-and-forget): after_tool_call, agent_end, session_start, session_end, before_compaction, after_compaction, model_call_started, model_call_ended

Server contract

The plugin POSTs to POST {endpoint}/v1/openclaw/hooks/events with:

{
  "hook": {
    "hook_event_name": "before_tool_call",
    "context": { "agent_id": "..." },
    "tool_name": "...",
    "params": {}
  },
  "user": "[email protected]",
  "transcript_lines": [],
  "plugin_version": "1.2.0"
}

The server response is mapped directly back to the OpenClaw plugin SDK return shape — { block, blockReason }, { params } rewrite, or { requireApproval: { ... } } for before_tool_call; { cancel, syntheticReply, reason } for before_agent_reply; { block, blockReason } for before_install.

before_message_write is synchronous in OpenClaw. The plugin forwards it to Capsule for audit, but it cannot apply an async server verdict inline for that hook.

License

Apache-2.0