Plugins

SwarmClaw has an extensible plugin system for adding custom logic at key points in the agent lifecycle. Plugins from OpenClaw are also natively supported.

Installing Plugins

Three ways to add plugins:

Marketplace

Browse and install approved plugins directly from Settings:

Go to Settings → Plugins → Marketplace tab
Browse available plugins and click Install
The plugin is downloaded, saved to data/plugins/, and enabled automatically

The marketplace registry is hosted at swarmclaw.ai/registry/plugins.json.

Install from URL

Install any plugin from an HTTPS URL:

Go to Settings → Plugins → Install from URL tab
Paste the URL to a .js plugin file
Choose a filename and click Install Plugin

Manual

Drop .js files directly into data/plugins/. They're loaded automatically on next agent start.

Plugin Format (SwarmClaw)

// data/plugins/my-plugin.js
module.exports = {
  name: "my-plugin",
  description: "What this plugin does",
  hooks: {
    beforeAgentStart({ session, message }) {
      // Called before an agent begins processing a message
    },
    afterAgentComplete({ session, response }) {
      // Called after an agent finishes generating a response
    },
    beforeToolExec({ toolName, input }) {
      // Called before a tool is executed. Return { abort: true } to cancel.
    },
    afterToolExec({ toolName, input, output }) {
      // Called after a tool completes execution
    },
    onMessage({ session, message }) {
      // Called on every message
    },
  },
};

OpenClaw Plugin Compatibility

SwarmClaw natively supports the OpenClaw plugin format. Drop an OpenClaw plugin into data/plugins/ and it works automatically — lifecycle hooks are mapped at load time:

OpenClaw Hook	SwarmClaw Hook
`onAgentStart`	`beforeAgentStart`
`onAgentComplete`	`afterAgentComplete`
`onToolCall`	`beforeToolExec`
`onToolResult`	`afterToolExec`
`onMessage`	`onMessage`

OpenClaw plugins use the activate(ctx) pattern:

module.exports = {
  name: "my-openclaw-plugin",
  version: "1.0.0",
  activate(ctx) {
    ctx.onAgentStart((data) => { /* ... */ });
    ctx.onToolCall((data) => { /* ... */ });
  },
  deactivate() { /* cleanup */ },
};

This means plugins written for OpenClaw work in SwarmClaw with zero changes, and vice versa for plugins that use the hook mapping.

Available Hooks

Hook	Trigger	Can Modify
`beforeAgentStart`	Agent receives a message	Agent config, session context
`afterAgentComplete`	Agent finishes response	Response text (return modified text)
`beforeToolExec`	Before a tool runs	Tool args; return `{ abort: true }` to cancel
`afterToolExec`	After a tool completes	Nothing (observation only)
`onMessage`	Every message in/out	Nothing (observation only)

Plugin API

GET  /api/plugins              # List installed plugins
POST /api/plugins              # Toggle plugin enabled/disabled
GET  /api/plugins/marketplace  # Browse marketplace registry
POST /api/plugins/install      # Install from URL { url, filename }

Examples

Logging plugin — log all tool executions:

module.exports = {
  name: "tool-logger",
  description: "Logs all tool executions to console",
  hooks: {
    beforeToolExec({ toolName, input }) {
      console.log(`[tool] executing ${toolName}`, input);
    },
    afterToolExec({ toolName, output }) {
      console.log(`[tool] ${toolName} completed`);
    },
  },
};

Gate plugin — block dangerous shell commands:

module.exports = {
  name: "shell-gate",
  description: "Blocks dangerous shell commands",
  hooks: {
    beforeToolExec({ toolName, input }) {
      if (toolName === "shell" && /rm\s+-rf\s+\//.test(input.command)) {
        return { abort: true, reason: "Blocked dangerous rm -rf command" };
      }
    },
  },
};