@capsulesecurity/openclaw-capsule

Capsule plugin for OpenClaw. Forwards OpenClaw hook events to your Capsule tenant and applies Capsule policy verdicts: blocking tool calls and installs, and answering prompts in place of the model.

Install

openclaw plugins install @capsulesecurity/openclaw-capsule

Non-interactive installs need --force --accept-capabilities.

Configure

Merge into ~/.openclaw/openclaw.json (JSON5), with the endpoint and token from the Capsule portal (Integrations > OpenClaw):

{
  plugins: {
    entries: {
      capsule: {
        enabled: true,
        hooks: { allowConversationAccess: true },
        config: {
          endpoint: 'https://agentsecurity.<region>.capsulesecurity.io/v1/openclaw/hooks/events',
          token: '${CAPSULE_OPENCLAW_TOKEN}',
        },
      },
    },
  },
}

| Option | Default | Description | | ------------- | --------------------------------- | --------------------------------------------------------------------- | | endpoint | - | Capsule OpenClaw hooks URL. A bare agentsecurity base URL also works. | | token | - | Token issued by the Capsule portal (tid and eid claims). | | blockOnRisk | true | Apply Capsule block verdicts. Set to false for observe-only mode. | | failOpen | true | Let the agent proceed when Capsule is unreachable. | | timeoutMs | 5000 | Per-request timeout in ms. | | user | process.env.USER or "unknown" | User identifier sent on every event. |

hooks.allowConversationAccess is OpenClaw's own grant. Without it OpenClaw refuses before_agent_reply and agent_end for non-bundled plugins, so prompts are still audited through before_message_write but cannot be blocked.

Hooks

• Blocking (priority 100): before_tool_call, before_agent_reply (needs the grant), and before_install, which sends the incoming skill's SKILL.md, the plugin's manifest, or a single-file plugin (up to 256 KB, marked when cut) so Capsule can judge it before it lands; an archive source is reported as not inspected
• Audit (priority 10, fire-and-forget): before_message_write (user and assistant messages; OpenClaw runs it synchronously, so it cannot be gated), after_tool_call, agent_end (needs the grant), session_start, session_end, before_compaction, after_compaction, model_call_started, model_call_ended

after_tool_call results are analyzed for detections (for example prompt injection in fetched content), but a tool that already ran cannot be blocked.

Once per session, on the first hook that carries the agent workspace, the plugin also sends:

• the workspace's instruction files (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, HEARTBEAT.md, BOOT.md, BOOTSTRAP.md), plus the AGENTS.md of the folder the session runs in when it differs from the workspace
• its memory (MEMORY.md, then the newest memory/*.md notes)
• the SKILL.md of every skill in the workspace, ~/.agents/skills, and OpenClaw's managed skills
• the mcp.servers config (name, transport, command, args, url), never env or headers; credentials in args (--api-key <value>, TOKEN=<value>) and URLs (userinfo, query values) are redacted

Each file is capped at 32 KB, memory at 128 KB, and skills at 512 KB in total. An emptied file is sent with empty content so Capsule drops what it stored. Every event carries the run's model, and MCP tool calls carry the server they belong to.

Server contract

The plugin normalizes OpenClaw's (event, ctx) hook arguments and POSTs them to {endpoint}:

{
  "hook": {
    "hook_event_name": "before_tool_call",
    "context": { "agent_id": "main", "session_key": "agent:main:main", "session_id": "...", "model": "claude-opus-5-5" },
    "timestamp": "2026-10-15T10:00:00.000Z",
    "tool_name": "docs__search",
    "mcp_server": "docs",
    "mcp_tool": "search",
    "params": {}
  },
  "user": "[email protected]",
  "plugin_version": "2.1.0",
  "instructions": [{ "path": "/home/user/.openclaw/workspace/AGENTS.md", "content": "..." }],
  "memories": [{ "path": "/home/user/.openclaw/workspace/MEMORY.md", "content": "..." }],
  "skills": [{ "path": "/home/user/.openclaw/workspace/skills/weather/SKILL.md", "content": "..." }],
  "mcp_servers": [{ "name": "docs", "url": "https://mcp.acme.com/mcp", "transport": "streamable-http" }]
}

The server answers with the OpenClaw hook result shape: { block, blockReason }, { params } or { requireApproval } for before_tool_call, { handled, reply, reason } for before_agent_reply, and { block, blockReason } for before_install.

License

Apache-2.0