Plugin Development

A ClawMagic plugin can be as small as a single action or as large as a full workflow product with a setup portal, stored state, docs, and agent routing hints. If you plan to distribute or sell the plugin, build around the marketplace package format from the start: claw.plugin.json, actionspec.json, skill.json, runtime code in plugin/, and supporting docs.

1. Choose the plugin type and the actions it needs to expose.
2. Build the runtime in plugin/index.js and any supporting modules.
3. Add the manifest, ActionSpec, and skill files so agents know when and how to use it.
4. Bundle the root files into a ZIP and validate it before submission.

If you are shipping to the marketplace, use claw.plugin.json. A server-local plugin.jsonis a different manifest used for direct runtime installs, not the marketplace ZIP format described here.

The plugin ZIP is not limited to one script. You can ship runtime code, agent-readable specs, setup UX, docs, and compatibility files in the same package.

1. Define the actions first. List the exact operations the plugin will expose, the required inputs, and whether each action is read-only, write, destructive, or security-sensitive.
2. Build the runtime entry point in plugin/index.js. Keep the runtime code aligned with the action names you plan to publish in actionspec.json.
3. Add claw.plugin.json with only the permissions the plugin actually needs. Overbroad permissions slow review and make the listing harder to trust.
4. Write actionspec.json so agents can choose actions deterministically instead of guessing from code.
5. Add skill.json and SKILL.md so humans and agents both understand setup, use cases, and safety.
6. If the plugin needs setup or diagnostics, add a portal.html page for forms, test buttons, status, and support links.
7. Bundle the ZIP with the files at the root, then review the package against /docs/plugin-packaging and /docs/submission-and-review.

Keep the package flat at the root. Do not zip a parent folder that contains the actual package files one level down.

my-plugin.zip
├── claw.plugin.json
├── actionspec.json
├── skill.json
├── README.md
├── plugin/
│   ├── index.js
│   └── ...
├── skills/
│   └── my-plugin/
│       └── SKILL.md
├── portal.html
├── openclaw.plugin.json
└── docs/

The package can include more files than this, but the manifest, ActionSpec, skill metadata, README, and runtime code are the baseline. For the full packaging checklist, use /docs/plugin-packaging.

The manifest defines what the plugin is, how it starts, and what it can touch. Reviewers and installers both depend on this file, so it needs to be precise and minimal.

{
  "id": "crm-sync-hub",
  "name": "CRM Sync Hub",
  "version": "1.0.0",
  "type": "CONNECTOR",
  "platform": "Custom CRM",
  "tasks": [
    "crm.connection.test",
    "crm.contacts.sync",
    "crm.records.upsert"
  ],
  "entry": {
    "kind": "node_module",
    "path": "plugin/index.js"
  },
  "permissions": {
    "network": ["https://api.example-crm.com/*"],
    "secrets": ["CRM_API_KEY", "CRM_BASE_URL"],
    "storage": ["read", "write"]
  },
  "install": {
    "installPathHint": "plugins/{slug}",
    "postInstall": ["registerPlugin", "runHealthCheck"]
  },
  "support": {
    "email": "support@example.com"
  }
}

ActionSpec is where you make the plugin predictable for agents. Each action should name the runtime tool, define inputs with JSON Schema, classify risk, and describe what success looks like.

{
  "schema_version": "cm.actionspec.v1",
  "plugin_id": "crm-sync-hub",
  "namespace": "plugins.crm_sync_hub",
  "actions": {
    "crm.contacts.sync": {
      "title": "Sync CRM contacts",
      "description": "Sync contact records from ClawMagic into the connected CRM.",
      "tool_name": "plugins.run",
      "tool_args_template": {
        "pluginId": "crm-sync-hub",
        "action": "crm.contacts.sync",
        "input": {
          "accountId": "${accountId}",
          "fullSync": "${fullSync}"
        },
        "spec_action_key": "crm.contacts.sync"
      },
      "inputs_schema": {
        "type": "object",
        "properties": {
          "accountId": { "type": "string" },
          "fullSync": { "type": "boolean" }
        },
        "required": ["accountId"]
      },
      "constraints": [
        "CRM credentials must already be configured.",
        "Only run full syncs when the user expects a broader write operation."
      ],
      "verification_steps": [
        "Result returns syncedCount.",
        "Result returns the latest sync cursor or completion timestamp."
      ],
      "fallback": [
        "If auth fails, send the user to the plugin portal to reconnect.",
        "If the CRM is rate limited, retry or queue a smaller sync."
      ],
      "danger_level": "write",
      "requires_confirmation": true,
      "tags": ["crm", "contacts", "sync", "write"]
    }
  }
}

Keep the action keys in sync with the runtime and with skill.json. If the runtime exposes an action that never appears in ActionSpec, agents will have a harder time selecting it safely.

Use both layers. skill.json is for routing. SKILL.md is for setup and operating guidance. Together they make the plugin easier to install, review, and use correctly.

{
  "schema_version": "cm.plugin.skill.v1",
  "plugin_id": "crm-sync-hub",
  "goal": "Sync CRM contacts and records from ClawMagic workflows.",
  "when_useful": [
    "Keeping CRM contacts up to date",
    "Running account-level CRM sync jobs",
    "Testing whether CRM credentials are valid"
  ],
  "recommended_action_keys": [
    "crm.connection.test",
    "crm.contacts.sync",
    "crm.records.upsert"
  ],
  "optional_for_execution": false
}

---
name: crm-sync-hub
description: "CRM Sync Hub plugin."
user-invocable: true
---

# CRM Sync Hub

## When to Use
- Sync CRM contacts or records from ClawMagic.
- Verify CRM credentials before enabling automations.

## Setup
- Configure CRM_API_KEY and CRM_BASE_URL.
- Open the portal page to run a connection test.

## Available Tools
- crm.connection.test
- crm.contacts.sync
- crm.records.upsert

## Notes
- Stores sync cursors and lightweight mapping state locally.
- Full syncs are write operations and should be confirmed first.

• plugin_id in skill.json must match the manifest and ActionSpec.
• Every key in recommended_action_keys should exist in actionspec.json.
• SKILL.md should explain setup, safety, and examples without contradicting the ActionSpec risk level.

Add a portal.html page when the plugin needs setup, testing, or operator visibility. This is especially useful for connectors and workflow plugins.

• Use the portal for OAuth reconnect flows, API key setup guidance, health checks, logs, or manual test actions.
• Link the portal back to docs and support so users can recover without leaving the plugin context.
• Declare permissions.storage when the plugin needs persistent local state such as sync cursors, cached metadata, queue state, or user settings.
• Do not treat storage as a substitute for secrets. Secrets belong in the manifest and the plugin config flow, not in plain files.

<!doctype html>
<html lang="en">
  <body>
    <main>
      <h1>CRM Sync Hub</h1>
      <p>Connect the account, test the integration, then save settings.</p>
      <button id="test-connection">Run health check</button>
      <button id="sync-now">Run sync</button>
    </main>
  </body>
</html>

The portal does not replace the runtime. It gives operators a clean surface for configuration and diagnostics while the actual plugin logic still lives in plugin/.

Plugins can declare custom app pages that appear in the ClawMagic sidebar. This makes plugins feel like internal apps rather than background utilities.

Declaring Navigation

Add a ui section to your plugin.json:

{
  "ui": {
    "icon": "📝",
    "primaryRoute": "/app/plugins/my-plugin/sites",
    "category": "Content",
    "nav": [
      {
        "id": "my-plugin-main",
        "label": "My Sites",
        "route": "/app/plugins/my-plugin/sites"
      }
    ],
    "tags": ["wordpress", "cms"]
  }
}

• icon — Emoji displayed in the sidebar next to your plugin name.
• primaryRoute — The main page URL. Enables the “Launch App” button on the plugin detail page.
• category — Groups your plugin in the sidebar (AI, Communication, Content, Productivity, etc.).
• nav[] — Array of sidebar items. Each has id, label, and route.

When your plugin is installed and enabled, its nav items appear automatically in the sidebar under the “Apps” group. No code changes needed in the ClawMagic core.

Plugin Page Context (usePlugin hook)

Plugin pages can use the usePlugin() hook to access plugin config, status, and a scoped API client:

import { usePlugin } from "../../contexts/PluginContext";

function MySitesPage() {
  const { pluginId, name, pluginApi } = usePlugin();

  // Fetch data from your plugin's server adapter
  const [sites, setSites] = useState([]);
  useEffect(() => {
    pluginApi.get("sites").then(res => setSites(res.sites));
  }, []);

  // Create via adapter
  async function addSite(url, user, pass) {
    const res = await pluginApi.post("sites", { url, username: user, appPassword: pass });
    if (res.ok) { /* refresh */ }
  }
}

The pluginApi automatically routes requests to /api/plugins/{pluginId}/{path} and handles authentication headers.

Reference Implementations

• WordPress Connector — Multi-site management with custom page, agent tools, sidebar nav. See plugins/wordpress-connector/.
• NVIDIA NIM Provider — Simple utility plugin with no custom UI. See plugins/nvidia-nim-provider/.
• Email Plugin — Most complex plugin: 4 pages, OAuth, background sync, rules engine. See plugins/email/.
• Starter Template — Copy and customize. See plugins/templates/app-starter/.

• The ZIP root contains claw.plugin.json, actionspec.json, skill.json, README.md, and plugin/.
• entry.path points to a real file inside plugin/.
• plugin_id and action keys match across manifest, ActionSpec, skill.json, and SKILL.md.
• Permissions are scoped tightly to the real behavior of the plugin.
• Setup instructions cover secrets, portal usage, and any stored-data behavior.
• Examples show one safe read path and one write path if the plugin modifies data.

After that, review /docs/plugin-packaging for the package-level rules and /docs/submission-and-review for marketplace submission.