OpenClaw Integration

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Connect OpenClaw to Capsule Security for complete visibility into AI coding agent activity, including tool execution, agent replies, session lifecycle, and message writes — with optional inline blocking on policy-violating actions for async hooks.

Overview

This integration uses OpenClaw's plugin system to capture and govern AI coding agent activity. The Capsule plugin runs in-process inside the OpenClaw runtime, forwards every hook event to your Capsule tenant over HTTPS, and applies policy verdicts for OpenClaw hooks that support async decisions.

The following hooks are configured:

Prerequisites

Before you begin, ensure you have:

• OpenClaw installed (Node.js 18 or later)
• A Capsule Security account with admin access
• Network access from your developer machines to your Capsule agentsecurity endpoint (e.g. https://agents.capsule.security)

Step 1: Generate a Plugin Token

1. Log in to the Capsule Security portal

2. Navigate to Integrations and locate OpenClaw

3. Click Install — Capsule generates a JWT scoped to your tenant and OpenClaw environment. The token contains the tenant and environment claims required by the agentsecurity endpoint; treat it as a secret.

4. Copy the generated token. You will reference it from your OpenClaw plugin configuration in the next step.

Step 2: Install the Plugin

Install the published Capsule plugin in the project or environment where OpenClaw runs:

npm install @capsulesecurity/openclaw-capsule

Or with yarn:

yarn add @capsulesecurity/openclaw-capsule

Step 3: Configure the Plugin

Register the plugin in your OpenClaw configuration. The plugin reads its options from the standard OpenClaw plugin config block:

import { capsulePlugin } from "@capsulesecurity/openclaw-capsule";

export default {
  plugins: [
    {
      plugin: capsulePlugin,
      config: {
        endpoint: "https://agents.capsule.security",
        token: process.env.CAPSULE_OPENCLAW_TOKEN,
        blockOnRisk: true,
        failOpen: true,
        timeoutMs: 5000,
        allowConversationAccess: false,
      },
    },
  ],
};

Configuration Options

Token Storage

Never commit the JWT to version control. Recommended approaches:

• Read the token from an environment variable (process.env.CAPSULE_OPENCLAW_TOKEN)
• Source it from your secret manager (1Password, AWS Secrets Manager, HashiCorp Vault) at runtime
• For MDM-managed deployments, deliver it through the same channel that distributes the OpenClaw configuration

Step 4: Restart OpenClaw

For the plugin to take effect, restart any running OpenClaw sessions:

1. Exit OpenClaw
2. Restart OpenClaw with the updated configuration

Step 5: Verify the Installation

1. Start a new OpenClaw session and execute a simple task to generate activity:

   Create a new file called test.txt with the content "Hello World"

2. Log in to the Capsule Security portal

3. Navigate to Inventory > Agents and confirm your OpenClaw agent appears

4. Click on the agent and review the audit logs to verify events are captured:

   • Session start event
   • Tool execution (Write tool)
   • Agent reply
   • Session activity

5. To view the full conversation, navigate to Observability and filter by Activity Type — Session (requires allowConversationAccess: true)

Troubleshooting

If events are not appearing:

1. Verify the endpoint is reachable from the host running OpenClaw:

   curl -sS -o /dev/null -w "%{http_code}\n" https://agents.capsule.security/health

2. Verify the token is set — the plugin will not start without a valid token. Check the OpenClaw logs for plugin initialization errors.

3. Check for timeouts — if your network has high latency to the Capsule endpoint, increase timeoutMs or confirm failOpen is set appropriately.

4. Confirm the plugin is loaded — OpenClaw lists active plugins on startup; the Capsule plugin registers under id capsule.

5. Inspect OpenClaw logs for hook execution errors. The plugin logs structured warnings when requests fail.

6. Contact Capsule Security support if issues persist.

Security Considerations

The Capsule plugin runs in-process inside OpenClaw and observes every tool call, agent reply, and message write. Before deploying:

1. Protect the JWT — 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 developer productivity; failOpen: false prioritizes policy enforcement and will block agent activity when Capsule is unreachable.
3. Decide on conversation access explicitly — allowConversationAccess: true forwards session transcript lines to Capsule. Enable this only after reviewing the data residency and retention implications with your security and privacy teams.
4. Pin a plugin version in production. Use a lockfile (package-lock.json / yarn.lock) and review changelogs before upgrading.
5. Use TLS-only endpoints. The plugin sends a Bearer token on every request — never configure an http:// endpoint.

Support

For help with this integration:

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

References

• OpenClaw Documentation
• OpenClaw Plugin SDK
• Capsule OpenClaw Plugin on npm