OpenClaw Integration

Connect OpenClaw to Capsule Security for visibility into agent activity - tool calls, prompts, replies, session lifecycle, and the agent's workspace instructions and memory - with inline blocking of policy-violating tool calls, prompts, and installs.

The Capsule plugin is a native OpenClaw plugin. It runs inside the OpenClaw Gateway, forwards hook events to your Capsule tenant over HTTPS, and applies Capsule policy verdicts on the hooks that can be gated.

The following hooks are configured:

Once per session, the plugin also sends what the agent can load, shown on the agent and in the inventory:

• Instructions: AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, HEARTBEAT.md, BOOT.md, BOOTSTRAP.md, plus the AGENTS.md of the folder a session runs in when it differs from the workspace
• Memory: MEMORY.md, then the newest daily notes in memory/*.md
• Skills: the SKILL.md of every skill in the workspace, ~/.agents/skills, and OpenClaw's managed skills
• MCP servers: name, transport, command, arguments, and URL of each server in mcp.servers. Environment variables and headers are never sent, and credentials in arguments and URLs are redacted

Each file is capped at 32 KB, memory at 128 KB in total, and skills at 512 KB in total. Tool calls are recorded against the tool and, for MCP tools, the server that exposes them, and every event carries the model the run uses.

Before you begin, ensure you have:

• OpenClaw 2026.5.12 or later (2026.8.1 or later for images)
• A Capsule Security account with admin access
• Network access from the OpenClaw Gateway host to your Capsule agentsecurity endpoint

1. Log in to the Capsule Security portal

2. Navigate to Integrations and locate OpenClaw

3. Click Install - Capsule generates a token scoped to your tenant and OpenClaw environment, and shows the endpoint to send events to. Treat the token as a secret.

On the machine that runs the OpenClaw Gateway:

openclaw plugins install @capsulesecurity/openclaw-capsule

OpenClaw asks you to confirm the install source and the plugin's capabilities. For scripted or MDM installs, pass the confirmations explicitly:

openclaw plugins install @capsulesecurity/openclaw-capsule --force --accept-capabilities

Set the token in the Gateway's environment:

export CAPSULE_OPENCLAW_TOKEN="<token from Step 1>"

Merge the plugin entry into ~/.openclaw/openclaw.json. OpenClaw substitutes ${CAPSULE_OPENCLAW_TOKEN} from the environment:

{
  plugins: {
    entries: {
      capsule: {
        enabled: true,
        hooks: { allowConversationAccess: true },
        config: {
          endpoint: '<endpoint from Step 1>',
          token: '${CAPSULE_OPENCLAW_TOKEN}',
        },
      },
    },
  },
}

hooks.allowConversationAccess is an OpenClaw permission, not a Capsule option. OpenClaw only lets non-bundled plugins register before_agent_reply, before_agent_run and agent_end when it is true. Without it, Capsule still audits prompts through before_message_write but cannot block them.

With it, Capsule blocks prompts on every harness. On OpenClaw's own runner a blocked prompt's images stay out of later turns. On the Codex and Copilot harnesses OpenClaw keeps the blocked prompt in the conversation, so the model can see it as history on the next turn.

OpenClaw normally steers a message sent while the agent is working into the running turn, where no plugin can block it. On OpenClaw 2026.8.1 or later, the plugin therefore sets each session's queue mode to followup, so a message sent mid-run waits for its own turn and is checked like any other. Sessions with their own /queue setting, and channels configured with another mode (messages.queue.byChannel, else messages.queue.mode), keep their setting. The setting is stored on the session and stays if the plugin is removed; send /queue default in a session to clear it. A message you still steer on purpose (/steer, /queue steer) reaches the agent unchecked; Capsule records and analyzes it once the turn ends.

Restart the OpenClaw Gateway so it loads the plugin, then confirm it is active:

openclaw plugins inspect capsule

1. Start a new OpenClaw session and ask the agent to run a simple command, for example:

   List the files in your workspace

2. Log in to the Capsule Security portal

3. Navigate to Inventory > Agents and confirm your OpenClaw agent appears as OpenClaw/<agent id>/<user>

4. Open the agent and check:

   • The tool call in its activity
   • The workspace instructions and memory on the agent details

If events are not appearing:

1. Verify the endpoint is reachable from the Gateway host. Any HTTP status, including 401, means it is:

   curl -sS -o /dev/null -w "%{http_code}\n" -X POST "<endpoint from Step 1>"

2. Check the plugin loaded - openclaw plugins inspect capsule lists the registered hooks. The Gateway log shows capsule: forwarding OpenClaw hooks to ... on startup.

3. Check the config - the plugin logs an error and registers nothing when endpoint or token is missing. Confirm CAPSULE_OPENCLAW_TOKEN is set in the Gateway's environment, not only in your shell.

4. Check for timeouts - if your network has high latency to Capsule, increase timeoutMs or confirm failOpen is set appropriately.

5. Contact Capsule Security support if issues persist.

The Capsule plugin runs inside the OpenClaw Gateway and observes every tool call, prompt, and message. Before deploying:

1. Protect the token - anyone with the token can post events on behalf of your tenant. Rotate it through the portal if it is exposed.
2. Choose failOpen deliberately - failOpen: true (the default) prioritizes availability; failOpen: false prioritizes policy enforcement and blocks tool calls, prompts, and installs when Capsule is unreachable.
3. Review what leaves the host - messages and the images users send, tool parameters and results, the workspace instruction and memory files, skill files, and MCP server commands and URLs are sent to Capsule. Review the data residency and retention implications with your security and privacy teams.
4. Pin a plugin version in production with openclaw plugins install @capsulesecurity/openclaw-capsule@<version>, and review changes before upgrading.
5. Use TLS-only endpoints. The plugin sends a Bearer token on every request - never configure an http:// endpoint.

For help with this integration:

• Email: support@capsule.security
• Include: Your organization ID, integration status, plugin version, and any error messages

• OpenClaw Documentation
• OpenClaw Plugin Hooks
• Capsule OpenClaw Plugin on npm