插件开发

为 Crab Claw 生态构建自定义插件

Crab Claw 支持通过插件扩展系统能力，包括添加新工具、频道适配、Hook 处理等。

插件架构

shell

~/.crabclaw/plugins/
  └── my-plugin/
      ├── plugin.json    ← 插件清单
      ├── tools/         ← 自定义工具
      ├── hooks/         ← Hook 处理器
      └── skills/        ← 插件技能
~/.crabclaw/plugins/
  └── my-plugin/
      ├── plugin.json    ← 插件清单
      ├── tools/         ← 自定义工具
      ├── hooks/         ← Hook 处理器
      └── skills/        ← 插件技能

插件清单

每个插件必须包含 plugin.json：

json

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的自定义插件",
  "author": "your-name",
  "capabilities": ["tools", "hooks"],
  "tools": [
    {
      "name": "my_custom_tool",
      "description": "自定义工具说明",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        }
      }
    }
  ],
  "hooks": [
    {
      "event": "before_tool_call",
      "handler": "hooks/validate.sh"
    }
  ]
}
{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "我的自定义插件",
  "author": "your-name",
  "capabilities": ["tools", "hooks"],
  "tools": [
    {
      "name": "my_custom_tool",
      "description": "自定义工具说明",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        }
      }
    }
  ],
  "hooks": [
    {
      "event": "before_tool_call",
      "handler": "hooks/validate.sh"
    }
  ]
}

创建插件

1. 创建目录

bash

mkdir -p ~/.crabclaw/plugins/my-plugin
cd ~/.crabclaw/plugins/my-plugin
mkdir -p ~/.crabclaw/plugins/my-plugin
cd ~/.crabclaw/plugins/my-plugin

2. 编写 plugin.json

定义插件元数据和能力声明（见上方示例）。

3. 实现工具

工具可以是任何可执行文件，Crab Claw 通过 stdin/stdout JSON 协议与之通信。

4. 注册插件

bash

crabclaw plugins install ~/.crabclaw/plugins/my-plugin
crabclaw plugins install ~/.crabclaw/plugins/my-plugin

插件管理

bash

# 列出已安装的插件
crabclaw plugins list

# 启用/禁用插件
crabclaw plugins enable my-plugin
crabclaw plugins disable my-plugin

# 更新插件
crabclaw plugins update my-plugin

# 卸载插件
crabclaw plugins remove my-plugin
# 列出已安装的插件
crabclaw plugins list

# 启用/禁用插件
crabclaw plugins enable my-plugin
crabclaw plugins disable my-plugin

# 更新插件
crabclaw plugins update my-plugin

# 卸载插件
crabclaw plugins remove my-plugin

插件 Hook

插件可以注册 Hook 来拦截或增强系统行为：

Hook 事件	触发时机
`before_tool_call`	工具调用前
`after_tool_call`	工具调用后
`on_message`	收到消息时
`on_session_start`	会话开始时
`on_session_end`	会话结束时

MCP 插件

Crab Claw 也支持通过 MCP (Model Context Protocol) 协议加载外部工具：

json

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "npx",
        "args": ["-y", "my-mcp-server"]
      }
    }
  }
}
{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "npx",
        "args": ["-y", "my-mcp-server"]
      }
    }
  }
}

MCP 工具会以 mcp_ 前缀注册到能力树中。