Plugins

Plugins extend Velaclaw with new capabilities: channels, model providers, tools, skills, speech, realtime transcription, realtime voice, media-understanding, image generation, video generation, web fetch, web search, and more. Some plugins are core (shipped with Velaclaw), others are external (published on npm by the community).

Quick start

See what is loaded

velaclaw plugins list

Install a plugin

# From npm
velaclaw plugins install @velaclaw/voice-call

# From a local directory or archive
velaclaw plugins install ./my-plugin
velaclaw plugins install ./my-plugin.tgz

Restart the Gateway

velaclaw gateway restart

Then configure under plugins.entries.\<id\>.config in your config file.

If you prefer chat-native control, enable commands.plugins: true and use:

/plugin install clawhub:@velaclaw/voice-call
/plugin show voice-call
/plugin enable voice-call

The install path uses the same resolver as the CLI: local path/archive, explicit clawhub:<pkg>, or bare package spec (ClawHub first, then npm fallback). If config is invalid, install normally fails closed and points you at velaclaw doctor --fix. The only recovery exception is a narrow bundled-plugin reinstall path for plugins that opt into velaclaw.install.allowInvalidConfigRecovery.

Plugin types

Velaclaw recognizes two plugin formats:

Format	How it works	Examples
Native	`velaclaw.plugin.json` + runtime module; executes in-process	Official plugins, community npm packages
Bundle	Codex/Claude/Cursor-compatible layout; mapped to Velaclaw features	`.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/`

Both show up under velaclaw plugins list. See Plugin Bundles for bundle details. If you are writing a native plugin, start with Building Plugins and the Plugin SDK Overview.

Official plugins

Installable (npm)

Plugin	Package	Docs
Matrix	`@velaclaw/matrix`	Matrix
Microsoft Teams	`@velaclaw/msteams`	Microsoft Teams
Nostr	`@velaclaw/nostr`	Nostr
Voice Call	`@velaclaw/voice-call`	Voice Call
Zalo	`@velaclaw/zalo`	Zalo
Zalo Personal	`@velaclaw/zalouser`	Zalo Personal

Core (shipped with Velaclaw)

Model providers (enabled by default)

anthropic, byteplus, cloudflare-ai-gateway, github-copilot, google, huggingface, kilocode, kimi-coding, minimax, mistral, qwen, moonshot, nvidia, openai, opencode, opencode-go, openrouter, qianfan, synthetic, together, venice, vercel-ai-gateway, volcengine, xiaomi, zai

Memory plugins

memory-core — bundled memory search (default via plugins.slots.memory)
memory-lancedb — install-on-demand long-term memory with auto-recall/capture (set plugins.slots.memory = "memory-lancedb")

Speech providers (enabled by default)

elevenlabs, microsoft

Other

browser — bundled browser plugin for the browser tool, velaclaw browser CLI, browser.request gateway method, browser runtime, and default browser control service (enabled by default; disable before replacing it)
copilot-proxy — VS Code Copilot Proxy bridge (disabled by default)

Looking for third-party plugins? See Community Plugins.

Configuration

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

Field	Description
`enabled`	Master toggle (default: `true`)
`allow`	Plugin allowlist (optional)
`deny`	Plugin denylist (optional; deny wins)
`load.paths`	Extra plugin files/directories
`slots`	Exclusive slot selectors (e.g. `memory`, `contextEngine`)
`entries.\<id\>`	Per-plugin toggles + config

Config changes require a gateway restart. If the Gateway is running with config watch + in-process restart enabled (the default velaclaw gateway path), that restart is usually performed automatically a moment after the config write lands.

Plugin states: disabled vs missing vs invalid

Disabled: plugin exists but enablement rules turned it off. Config is preserved.
Missing: config references a plugin id that discovery did not find.
Invalid: plugin exists but its config does not match the declared schema.

Discovery and precedence

Velaclaw scans for plugins in this order (first match wins):

Config paths

plugins.load.paths — explicit file or directory paths.

Workspace extensions

\<workspace\>/.velaclaw/<plugin-root>/*.ts and \<workspace\>/.velaclaw/<plugin-root>/*/index.ts.

Global extensions

~/.velaclaw/<plugin-root>/*.ts and ~/.velaclaw/<plugin-root>/*/index.ts.

Bundled plugins

Shipped with Velaclaw. Many are enabled by default (model providers, speech). Others require explicit enablement.

Enablement rules

plugins.enabled: false disables all plugins
plugins.deny always wins over allow
plugins.entries.\<id\>.enabled: false disables that plugin
Workspace-origin plugins are disabled by default (must be explicitly enabled)
Bundled plugins follow the built-in default-on set unless overridden
Exclusive slots can force-enable the selected plugin for that slot

Plugin slots (exclusive categories)

Some categories are exclusive (only one active at a time):

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable
      contextEngine: "legacy", // or a plugin id
    },
  },
}

Slot	What it controls	Default
`memory`	Active memory plugin	`memory-core`
`contextEngine`	Active context engine	`legacy` (built-in)

CLI reference

velaclaw plugins list                       # compact inventory
velaclaw plugins list --enabled            # only loaded plugins
velaclaw plugins list --verbose            # per-plugin detail lines
velaclaw plugins list --json               # machine-readable inventory
velaclaw plugins inspect <id>              # deep detail
velaclaw plugins inspect <id> --json       # machine-readable
velaclaw plugins inspect --all             # fleet-wide table
velaclaw plugins info <id>                 # inspect alias
velaclaw plugins doctor                    # diagnostics

velaclaw plugins install <package>         # install (ClawHub first, then npm)
velaclaw plugins install clawhub:<pkg>     # install from ClawHub only
velaclaw plugins install <spec> --force    # overwrite existing install
velaclaw plugins install <path>            # install from local path
velaclaw plugins install -l <path>         # link (no copy) for dev
velaclaw plugins install <plugin> --marketplace <source>
velaclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
velaclaw plugins install <spec> --pin      # record exact resolved npm spec
velaclaw plugins install <spec> --dangerously-force-unsafe-install
velaclaw plugins update <id>             # update one plugin
velaclaw plugins update <id> --dangerously-force-unsafe-install
velaclaw plugins update --all            # update all
velaclaw plugins uninstall <id>          # remove config/install records
velaclaw plugins uninstall <id> --keep-files
velaclaw plugins marketplace list <source>
velaclaw plugins marketplace list <source> --json

velaclaw plugins enable <id>
velaclaw plugins disable <id>

Bundled plugins ship with Velaclaw. Many are enabled by default (for example bundled model providers, bundled speech providers, and the bundled browser plugin). Other bundled plugins still need velaclaw plugins enable <id>. --force overwrites an existing installed plugin or hook pack in place. It is not supported with --link, which reuses the source path instead of copying over a managed install target. --pin is npm-only. It is not supported with --marketplace, because marketplace installs persist marketplace source metadata instead of an npm spec. --dangerously-force-unsafe-install is a break-glass override for false positives from the built-in dangerous-code scanner. It allows plugin installs and plugin updates to continue past built-in critical findings, but it still does not bypass plugin before_install policy blocks or scan-failure blocking. This CLI flag applies to plugin install/update flows only. Gateway-backed skill dependency installs use the matching dangerouslyForceUnsafeInstall request override instead, while velaclaw skills install remains the separate ClawHub skill download/install flow. Compatible bundles participate in the same plugin list/inspect/enable/disable flow. Current runtime support includes bundle skills, Claude command-skills, Claude settings.json defaults, Claude .lsp.json and manifest-declared lspServers defaults, Cursor command-skills, and compatible Codex hook directories. velaclaw plugins inspect <id> also reports detected bundle capabilities plus supported or unsupported MCP and LSP server entries for bundle-backed plugins. Marketplace sources can be a Claude known-marketplace name from ~/.claude/plugins/known_marketplaces.json, a local marketplace root or marketplace.json path, a GitHub shorthand like owner/repo, a GitHub repo URL, or a git URL. For remote marketplaces, plugin entries must stay inside the cloned marketplace repo and use relative path sources only. See velaclaw plugins CLI reference for full details.

Plugin API overview

Native plugins export an entry object that exposes register(api). Older plugins may still use activate(api) as a legacy alias, but new plugins should use register.

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
    api.registerChannel({
      /* ... */
    });
  },
});

Velaclaw loads the entry object and calls register(api) during plugin activation. The loader still falls back to activate(api) for older plugins, but bundled plugins and new external plugins should treat register as the public contract. Common registration methods:

Method	What it registers
`registerProvider`	Model provider (LLM)
`registerChannel`	Chat channel
`registerTool`	Agent tool
`registerHook` / `on(...)`	Lifecycle hooks
`registerSpeechProvider`	Text-to-speech / STT
`registerRealtimeTranscriptionProvider`	Streaming STT
`registerRealtimeVoiceProvider`	Duplex realtime voice
`registerMediaUnderstandingProvider`	Image/audio analysis
`registerImageGenerationProvider`	Image generation
`registerMusicGenerationProvider`	Music generation
`registerVideoGenerationProvider`	Video generation
`registerWebFetchProvider`	Web fetch / scrape provider
`registerWebSearchProvider`	Web search
`registerHttpRoute`	HTTP endpoint
`registerCommand` / `registerCli`	CLI commands
`registerContextEngine`	Context engine
`registerService`	Background service

Hook guard behavior for typed lifecycle hooks:

before_tool_call: { block: true } is terminal; lower-priority handlers are skipped.
before_tool_call: { block: false } is a no-op and does not clear an earlier block.
before_install: { block: true } is terminal; lower-priority handlers are skipped.
before_install: { block: false } is a no-op and does not clear an earlier block.
message_sending: { cancel: true } is terminal; lower-priority handlers are skipped.
message_sending: { cancel: false } is a no-op and does not clear an earlier cancel.

For full typed hook behavior, see SDK Overview.

Building Plugins — create your own plugin
Plugin Bundles — Codex/Claude/Cursor bundle compatibility
Plugin Manifest — manifest schema
Registering Tools — add agent tools in a plugin
Plugin Internals — capability model and load pipeline
Community Plugins — third-party listings

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Plugins

Plugins

Quick start

Plugin types

Official plugins

Installable (npm)

Core (shipped with Velaclaw)

Configuration

Discovery and precedence

Enablement rules

Plugin slots (exclusive categories)

CLI reference

Plugin API overview

​Plugins

​Quick start

​Plugin types

​Official plugins

​Installable (npm)

​Core (shipped with Velaclaw)

​Configuration

​Discovery and precedence

​Enablement rules

​Plugin slots (exclusive categories)

​CLI reference

​Plugin API overview

​Related

Plugins

Quick start

Plugin types

Official plugins

Installable (npm)

Core (shipped with Velaclaw)

Configuration

Discovery and precedence

Enablement rules

Plugin slots (exclusive categories)

CLI reference

Plugin API overview

Related