OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

快速开始

构建插件

插件可以扩展 OpenClaw，而无需更改核心。插件可以添加消息 渠道、模型提供商、本地 CLI 后端、智能体工具、钩子、媒体提供商， 或其他由插件拥有的能力。

你无需将外部插件添加到 OpenClaw 仓库。将包发布到 ClawHub，用户可通过以下命令安装：

bash
openclaw plugins install clawhub:<package-name>

在发布切换期间，裸包规范仍会从 npm 安装。当你希望使用 ClawHub 解析时，请使用 clawhub: 前缀。

要求

  • Node 22.19+、Node 23.11+ 或 Node 24+，以及 npm 或 pnpm。
  • TypeScript ESM 模块。
  • 对于仓库内内置插件工作，请克隆仓库并运行 pnpm install。 源码检出插件开发仅支持 pnpm，因为 OpenClaw 会从 extensions/* 工作区包发现内置插件。

选择插件形态

Channel plugin

将 OpenClaw 连接到消息平台。
Provider plugin

添加模型、媒体、搜索、抓取、语音或实时提供商。
CLI backend plugin

通过 OpenClaw 模型回退运行本地 AI CLI。
Tool plugin

注册智能体工具。

快速开始

通过注册一个必需的智能体工具来构建最小工具插件。这是最短的实用插件形态， 并覆盖包、清单、入口点和本地验证。

  • Create package metadata

    package.json
    {"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"openclaw": {"extensions": ["./index.ts"],"compat": {"pluginApi": ">=2026.3.24-beta.2","minGatewayVersion": "2026.3.24-beta.2"},"build": {"openclawVersion": "2026.3.24-beta.2","pluginSdkVersion": "2026.3.24-beta.2"}}}
    openclaw.plugin.json
    {"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

    已发布的外部插件应将运行时入口指向构建后的 JavaScript 文件。 完整入口点契约见 SDK 入口点。

    每个插件都需要清单，即使没有配置。运行时工具必须出现在 contracts.tools 中，这样 OpenClaw 无需急切加载每个插件运行时即可发现所有权。 请有意设置 activation.onStartup；此示例会在 Gateway 网关启动时加载。

    主机信任的插件表面同样由清单控制，并要求已安装插件显式声明： api.registerAgentToolResultMiddleware(...) 需要在 contracts.agentToolResultMiddleware 中列出每个目标运行时， api.registerTrustedToolPolicy(...) 需要在 contracts.trustedToolPolicies 中列出每个策略 ID。这些声明使安装时检查与运行时注册保持一致。

    关于每个清单字段，请参见 插件清单。

  • Register the tool

    index.ts
    import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

    对非渠道插件使用 definePluginEntry。渠道插件则改用 openclaw/plugin-sdk/core 中的 defineChannelPluginEntry。

  • Test the runtime

    对于已安装或外部插件，请检查已加载的运行时：

    bash
    openclaw plugins inspect my-plugin --runtime --json

    如果插件注册了 CLI 命令，也请运行该命令并确认输出， 例如 openclaw demo-plugin ping。

    对于本仓库中的内置插件，OpenClaw 会从 extensions/* 工作区发现源码检出插件包。 运行最接近的定向测试：

    bash
    pnpm test extensions/my-plugin/pnpm check

  • Test the package install

    在发布可打包插件之前，请测试用户将获得的相同安装形态。 首先添加构建步骤，将 openclaw.extensions 等运行时入口指向构建后的 JavaScript（如 ./dist/index.js），并确保 npm pack 包含该 dist/ 输出。 TypeScript 源码入口仅适用于源码检出和本地开发路径。

    然后打包插件，并使用 npm-pack: 安装 tarball：

    bash
    npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

    npm-pack: 使用 OpenClaw 管理的按插件划分 npm 项目，因此它能捕获源码检出测试可能隐藏的运行时依赖错误。 它证明的是包和依赖形态，而不是与目录关联的官方信任。 运行时导入必须位于 dependencies 或 optionalDependencies； 仅留在 devDependencies 中的依赖不会为托管运行时项目安装。

    不要将原始归档或路径安装作为官方或特权插件行为的最终验证。 原始源码适合本地调试，但无法证明与 npm 或 ClawHub 安装相同的依赖路径。 如果你的插件依赖可信官方插件状态，请通过基于目录的官方安装或记录官方信任的已发布包路径添加第二项验证。 安装根和依赖所有权详情见 插件依赖解析。

  • Publish

    发布前验证包：

    bash
    clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

    规范的 ClawHub 包片段位于 docs/snippets/plugin-publish/。

  • Install

    通过 ClawHub 安装已发布的包：

    bash
    openclaw plugins install clawhub:your-org/your-plugin

    • 注册工具

    工具可以是必需或可选的。插件启用后，必需工具始终可用。 可选工具需要用户显式选择加入后，OpenClaw 才会加载所属插件运行时。

    typescript
    register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      async execute(_id, params) {        return { content: [{ type: "text", text: params.pipeline }] };      },    },    { optional: true },  );}

    通过 api.registerTool(...) 注册的每个工具也必须在插件清单中声明：

    json
    {  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

    用户通过 tools.allow 选择加入：

    json5
    {  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

    可选工具控制工具是否暴露给模型。当工具或钩子应在模型选择后、动作运行前请求批准时， 请使用 插件权限请求。

    对具有副作用、不常见二进制文件或默认不应暴露的能力使用可选工具。 工具名称不得与核心工具名称冲突；冲突会被跳过，并在插件诊断中报告。 格式错误的注册也会以相同方式跳过并报告：缺失非空 name、非函数 execute， 或没有 parameters 对象的工具描述符。

    工具工厂会接收运行时提供的上下文对象。当工具需要记录、显示或适配当前轮次的活跃模型时， 请使用 ctx.activeModel；它可能包含 provider、modelId 和 modelRef。 请将其视为信息性的运行时元数据，而不是对本地操作员、已安装插件代码或被修改的 OpenClaw 运行时的安全边界。 敏感本地工具仍应要求显式的插件或操作员选择加入，并在活跃模型元数据缺失或不适用时 fail closed。

    清单声明所有权和发现；执行仍会调用实时注册的工具实现。 请保持 toolMetadata.<tool>.optional: true 与 api.registerTool(..., { optional: true }) 一致，这样 OpenClaw 可以在工具被显式加入允许列表之前避免加载该插件运行时。

    导入约定

    从聚焦的插件 SDK 子路径导入：

    typescript

    不要从已弃用的根 barrel 导入：

    typescript

    在你的插件包内部，请使用 api.ts 和 runtime-api.ts 等本地 barrel 文件进行内部导入。 不要通过 SDK 路径导入你自己的插件。提供商特定的辅助函数应保留在提供商包中，除非该边界确实是通用的。

    自定义 Gateway 网关 RPC 方法是高级入口点。请将其保持在插件特定前缀下； 核心管理员命名空间（如 config.*、exec.approvals.*、operator.admin.*、wizard.* 和 update.*） 保持保留，并解析到 operator.admin。 openclaw/plugin-sdk/gateway-method-runtime 桥接仅保留给声明 contracts.gatewayMethodDispatch: ["authenticated-request"] 的插件 HTTP 路由。

    完整导入映射见 插件 SDK 概览。

    提交前检查清单

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json 具有正确的 openclaw 元数据 OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json 清单存在且有效 OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s 入口点使用 defineChannelPluginEntry 或 definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

    OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s 所有导入都使用聚焦的 plugin-sdk/<subpath> 路径 OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page