Skip to main content

​
Plugins (Extensions)

Clawdbot plugins are TypeScript modules loaded at runtime via jiti. They can register:
  • Gateway RPC methods
  • Agent tools
  • CLI commands
  • Background services
  • Optional config validation
Plugins run in‑process with the Gateway, so treat them as trusted code.

​
Discovery & precedence

Clawdbot scans, in order:
  1. Global extensions
  • ~/.clawdbot/extensions/*.ts
  • ~/.clawdbot/extensions/*/index.ts
  1. Workspace extensions
  • <workspace>/.clawdbot/extensions/*.ts
  • <workspace>/.clawdbot/extensions/*/index.ts
  1. Config paths
  • plugins.load.paths (file or directory)

​
Package packs

A plugin directory may include a package.json with clawdbot.extensions: 
{
  "name": "my-pack",
  "clawdbot": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}
Each entry becomes a plugin. If the pack lists multiple extensions, the plugin id becomes name/<fileBase>. If your plugin imports npm deps, install them in that directory so node_modules is available (npm install / pnpm install).

​
Plugin IDs

Default plugin ids:
  • Package packs: package.json name
  • Standalone file: file base name (~/.../voice-call.ts → voice-call)
If a plugin exports id, Clawdbot uses it but warns when it doesn’t match the configured id.

​
Config

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } }
    }
  }
}
Fields:
  • enabled: master toggle (default: true)
  • allow: allowlist (optional)
  • deny: denylist (optional; deny wins)
  • load.paths: extra plugin files/dirs
  • entries.<id>: per‑plugin toggles + config
Config changes require a gateway restart.

​
CLI

clawdbot plugins list
clawdbot plugins info <id>
clawdbot plugins install <path>
clawdbot plugins enable <id>
clawdbot plugins disable <id>
clawdbot plugins doctor
Plugins may also register their own top‑level commands (example: clawdbot voicecall).

​
Plugin API (overview)

Plugins export either:
  • A function: (api) => { ... }
  • An object: { id, name, configSchema, register(api) { ... } }

​
Register a tool

import { Type } from "@sinclair/typebox";

export default function (api) {
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({
      input: Type.String(),
    }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });
}

​
Register a gateway RPC method

export default function (api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true });
  });
}

​
Register CLI commands

export default function (api) {
  api.registerCli(({ program }) => {
    program.command("mycmd").action(() => {
      console.log("Hello");
    });
  }, { commands: ["mycmd"] });
}

​
Register background services

export default function (api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

​
Naming conventions

  • Gateway methods: pluginId.action (example: voicecall.status)
  • Tools: snake_case (example: voice_call)
  • CLI commands: kebab or camel, but avoid clashing with core commands

​
Skills

Plugins can ship a skill in the repo (skills/<name>/SKILL.md). Enable it with plugins.entries.<id>.enabled (or other config gates) and ensure it’s present in your workspace/managed skills locations.

​
Example plugin: Voice Call

This repo includes a voice‑call plugin (Twilio or log fallback):
  • Source: extensions/voice-call
  • Skill: skills/voice-call
  • CLI: clawdbot voicecall start|status
  • Tool: voice_call
  • RPC: voicecall.start, voicecall.status
  • Config (twilio): provider: "twilio" + twilio.accountSid/authToken/from (optional statusCallbackUrl, twimlUrl)
  • Config (dev): provider: "log" (no network)
See extensions/voice-call/README.md for setup and usage.

​
Safety notes

Plugins run in-process with the Gateway. Treat them as trusted code:
  • Only install plugins you trust.
  • Prefer plugins.allow allowlists.
  • Restart the Gateway after changes.