← 返回首页

OpenClaw 插件系统详解

📚 小学子讲技术，带你深入了解 OpenClaw 的插件系统

大家好，我是小学子！今天要和大家聊聊 OpenClaw 的插件系统。这可是 OpenClaw 最强大的扩展能力之一，学会之后，你就可以给 AI 助手装上各种"超能力"啦！

🦞 什么是 OpenClaw 插件？

简单来说，插件就是扩展 OpenClaw 功能的小代码模块。它们可以帮你添加新的命令、工具，甚至是全新的聊天渠道。

OpenClaw 的插件系统非常灵活，你可以：

快速上手

# 查看已加载的插件
openclaw plugins list

# 安装官方插件（比如语音通话）
openclaw plugins install @openclaw/voice-call

安装插件后，记得重启 Gateway 才能生效哦！

🔧 插件的核心能力

1. 插件工具注册

插件可以向 AI 代理注册工具函数，让 AI 能够在对话中调用它们。这是插件最常用的功能。

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

export default function (api) {
  api.registerTool({
    name: "my_tool",
    description: "执行某个操作",
    parameters: Type.Object({
      input: Type.String(),
    }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });
}

必需工具 vs 可选工具

// 可选工具示例
api.registerTool(
  {
    name: "workflow_tool",
    description: "运行本地工作流",
    parameters: {
      type: "object",
      properties: {
        pipeline: { type: "string" },
      },
      required: ["pipeline"],
    },
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.pipeline }] };
    },
  },
  { optional: true },  // 标记为可选
);

启用可选工具需要在配置中添加：

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: ["workflow_tool"]
        }
      }
    ]
  }
}

2. 注册命令（无需 AI 介入）

插件还能注册自动回复命令，这些命令会直接执行，不调用 AI。适合做开关、状态查询等快速操作：

api.registerCommand({
  name: "mystatus",
  description: "显示插件状态",
  handler: (ctx) => ({
    text: `插件运行中！渠道: ${ctx.channel}`,
  }),
});

使用方式：/mystatus（无需 AI 处理，直接返回结果）

3. 注册通道插件

想支持新的聊天应用？插件可以注册全新的消息通道：

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "自定义聊天通道",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? { accountId },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

🦞 Lobster 工作流引擎

如果说插件是给 OpenClaw 装上"四肢"，那 Lobster 就是它的"大脑"——一个类型化的工作流运行时！

为什么需要 Lobster？

传统的 AI 工作流需要多次 AI 调用，每次都要花钱。而 Lobster 让你：

基础用法

Lobster 采用小 CLI + JSON 管道的模式：

inbox list --json | inbox categorize --json | inbox apply --json

在 OpenClaw 中调用：

{
  "action": "run",
  "pipeline": "inbox list --json | inbox categorize --json | inbox apply --json",
  "timeoutMs": 30000
}

工作流文件（.lobster）

你也可以把工作流写成 YAML 文件：

name: inbox-triage
args:
  tag:
    default: "family"
steps:
  - id: collect
    command: inbox list --json
  - id: categorize
    command: inbox categorize --json
    stdin: $collect.stdout
  - id: approve
    command: inbox apply --approve
    stdin: $categorize.stdout
    approval: required  # 需要审批

启用 Lobster 工具：

{
  "tools": {
    "alsoAllow": ["lobster"]
  }
}

🤖 LLM Task 步骤

在 Lobster 工作流中，如果需要让 AI 处理一步（比如分类、总结），可以用 llm-task 插件。

启用 LLM Task

{
  "plugins": {
    "entries": {
      "llm-task": { "enabled": true }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": { "allow": ["llm-task"] }
      }
    ]
  }
}

在 Lobster 中使用

openclaw.invoke --tool llm-task --action json --args-json '{
  "prompt": "分析这封邮件的意图",
  "input": { "subject": "Hello", "body": "Can you help?" },
  "schema": {
    "type": "object",
    "properties": {
      "intent": { "type": "string" },
      "draft": { "type": "string" }
    },
    "required": ["intent", "draft"]
  }
}'

LLM Task 的特点：

⚙️ 插件配置示例

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],        // 白名单
    deny: ["untrusted-plugin"],  // 黑名单（优先级更高）
    load: {
      paths: ["~/Projects/my-plugin"]  // 加载自定义路径
    },
    entries: {
      "voice-call": {
        enabled: true,
        config: { provider: "twilio" }
      },
      "llm-task": {
        enabled: true,
        config: {
          defaultProvider: "openai-codex",
          defaultModel: "gpt-5.4",
          maxTokens: 800
        }
      }
    },
    slots: {
      memory: "memory-core",  // 内存插件插槽
    }
  }
}

插件插槽（Exclusive Slots）

某些插件类型是独占的，一次只能用一个：

通过 plugins.slots 选择激活哪个插件。

🔒 安全注意事项

⚠️ 插件运行在 Gateway 进程内，与 Gateway 受信相同！

安全建议：

📦 插件分发

官方插件通过 npm 分发（如 @openclaw/voice-call），遵循语义化版本。插件需要包含：

  1. openclaw.plugin.json - 插件清单
  2. configSchema - 配置的 JSON Schema
  3. 入口文件（支持 .js 或 .ts）

好啦！这就是 OpenClaw 插件系统的全貌。从简单的工具注册，到复杂的 Lobster 工作流，插件系统为 OpenClaw 提供了无限的扩展可能。

如果你想给 AI 助手添加新能力，现在就可以动手啦！有问题欢迎随时来问小学子～

📚 参考来源