<!-- source: https://deepwiki.com/qhkm/zeptoclaw/13.4-extending-zeptoclaw -->

# Extending ZeptoClaw

- .cargo/config.toml
- examples/riscv_smoke.rs
- landing/zeptoclaw/docs/src/content/docs/guides/migration.md
- src/channels/plugin.rs
- src/cli/migrate.rs
- src/migrate/config.rs
- src/migrate/mod.rs
- src/migrate/skills.rs
- src/skills/loader.rs
- src/skills/types.rs
- src/tools/binary_plugin.rs
- src/tools/custom.rs
- src/tools/delegate.rs
- src/tools/mcp/wrapper.rs
- src/tools/plugin.rs
- src/tools/registry.rs
- src/tools/types.rs

This page provides a comprehensive guide for developers who want to extend ZeptoClaw with new tools, channels, providers, and plugins. It covers the core extension mechanisms, required trait implementations, registration patterns, and migration from OpenClaw.

## Extension Points Overview

ZeptoClaw provides five primary extension mechanisms, each with different trade-offs between flexibility, performance, and implementation complexity:

### Natural Language to Code Entity Space: Extension Architecture

This diagram maps high-level extension concepts to their specific Rust entities and registry locations.

```

```

**Sources:** [src/tools/types.rs196-203](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L196-L203) [src/tools/registry.rs48-87](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L48-L87) [src/tools/binary_plugin.rs68-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L68-L96) [src/tools/custom.rs110-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L110-L128) [src/skills/loader.rs13-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/skills/loader.rs#L13-L16) [src/skills/types.rs7-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/skills/types.rs#L7-L20)

## Adding Built-in Tools

Built-in tools are Rust implementations of the `Tool` trait [src/tools/types.rs197-203](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L197-L203) compiled directly into the ZeptoClaw binary.

### Tool Trait Implementation

The `Tool` trait defines the interface for identification, documentation (JSON schema), and execution [src/tools/types.rs197-210](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L197-L210)

**Implementation workflow:**

1. Define Struct : Create a struct for your tool.
2. Implement Trait : Implement name() , description() , parameters() , and execute() .
3. Register : Add the tool to the ToolRegistry src/tools/registry.rs 83-87

**Example implementation (Delegate Pattern):**
The `DelegateTool` demonstrates complex built-in logic, creating sub-agent loops for task offloading [src/tools/delegate.rs45-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L45-L78) It uses a `Semaphore` to bound concurrency [src/tools/delegate.rs63-70](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L63-L70)

**Sources:** [src/tools/types.rs165-210](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/types.rs#L165-L210) [src/tools/registry.rs83-87](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L83-L87) [src/tools/delegate.rs1-138](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/delegate.rs#L1-L138)

## Adding Custom Tools

Custom tools are shell commands configured in `config.json`, requiring no code changes. They are managed by the `CustomTool` struct [src/tools/custom.rs110-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L110-L128)

### Configuration and Interpolation

Custom tools support template interpolation using `{{key}}` placeholders [src/tools/custom.rs87-107](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L87-L107)

- Standard : Values are shell-escaped by wrapping in single quotes src/tools/custom.rs 26-28
- Raw String : If a parameter type is set to "raw_string" , it is sanitized src/tools/custom.rs 40-77 but not escaped, allowing word-splitting for CLI flags src/tools/custom.rs 99-101

**Security**: Commands are validated against a `ShellSecurityConfig` blocklist before execution [src/tools/custom.rs201-206](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L201-L206)

**Sources:** [src/tools/custom.rs1-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L1-L128) [src/tools/custom.rs148-175](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L148-L175)

## Binary Plugin System

ZeptoClaw supports two types of binary plugins: Tool Plugins and Channel Plugins.

### 1. Tool Binary Plugins

`BinaryPluginTool` [src/tools/binary_plugin.rs68-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L68-L96) executes standalone executables via JSON-RPC 2.0 over stdin/stdout. The binary is spawned on-demand and expected to exit after one response [src/tools/binary_plugin.rs61-67](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L61-L67)

### 2. Channel Binary Plugins

`ChannelPluginAdapter` [src/channels/plugin.rs109-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/plugin.rs#L109-L130) implements the `Channel` trait by spawning a long-running process [src/channels/plugin.rs4-7](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/plugin.rs#L4-L7)

- Manifest : Plugins are discovered via manifest.json src/channels/plugin.rs 86-101
- Communication : Persistent JSON-RPC exchange over the lifetime of the channel src/channels/plugin.rs 190-216

**Sources:** [src/tools/binary_plugin.rs1-222](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L1-L222) [src/channels/plugin.rs1-130](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/plugin.rs#L1-L130)

## Skills System

Skills are Markdown-based extensions (`SKILL.md`) that provide context and metadata to agents [src/skills/types.rs7-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/skills/types.rs#L7-L20)

### Skill Loading and Gating

The `SkillsLoader` [src/skills/loader.rs13-16](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/skills/loader.rs#L13-L16) discovers skills in `~/.zeptoclaw/skills` and builtin directories [src/skills/loader.rs29-35](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/skills/loader.rs#L29-L35)

- Requirements : Skills can be gated by OS, required binaries in PATH , or environment variables src/skills/loader.rs 143-179
- OpenClaw Compatibility : Supports {baseDir} interpolation for local path references src/skills/loader.rs 197-201

**Sources:** [src/skills/loader.rs1-213](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/skills/loader.rs#L1-L213) [src/skills/types.rs51-97](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/skills/types.rs#L51-L97)

## OpenClaw Migration

ZeptoClaw provides automated migration utilities for users moving from OpenClaw.

### Configuration Migration

The `convert_config` function [src/migrate/config.rs18-21](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/migrate/config.rs#L18-L21) maps OpenClaw JSON fields to ZeptoClaw's `Config` struct:

- Providers : Maps models.providers to ProvidersConfig src/migrate/config.rs 145-166
- Compaction : Converts contextTokens to ZeptoClaw's CompactionConfig src/migrate/config.rs 49-58
- Channels : Migrates Telegram, Discord, and Slack (mapping token to bot_token ) src/migrate/config.rs 63-93

### Natural Language to Code Entity Space: Migration Flow

This diagram shows how the migration logic bridges the two configuration formats.

```

```

**Sources:** [src/migrate/config.rs1-188](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/migrate/config.rs#L1-L188) [src/migrate/mod.rs1-10](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/migrate/mod.rs#L1-L10)

## Extension Registry Summary

**Sources:** [src/tools/registry.rs83-87](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/registry.rs#L83-L87) [src/tools/binary_plugin.rs68-96](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/binary_plugin.rs#L68-L96) [src/tools/custom.rs110-128](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/tools/custom.rs#L110-L128) [src/channels/plugin.rs132-154](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/channels/plugin.rs#L132-L154) [src/skills/loader.rs68-80](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/skills/loader.rs#L68-L80)
