插件代理工具（Plugin Agent Tools）

OpenClaw 插件可以注册代理工具（agent tools）（JSON schema 函数），这些工具会在代理运行期间暴露给 LLM。工具可以是必需的（required）（始终可用）或可选的（optional）（需要选择加入）。

代理工具在主配置中的 tools 下配置，或在每个代理下的 agents.list[].tools 中配置。白名单/黑名单策略控制代理可以调用哪些工具。

基本工具

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

export default function (api) {
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({
      input: Type.String(),
    }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });
}

可选工具（需要选择加入）

可选工具永远不会自动启用。用户必须将它们添加到代理白名单中。

export default function (api) {
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a local workflow",
      parameters: {
        type: "object",
        properties: {
          pipeline: { type: "string" },
        },
        required: ["pipeline"],
      },
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

在 agents.list[].tools.allow（或全局 tools.allow）中启用可选工具：

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool",  // specific tool name
            "workflow",       // plugin id (enables all tools from that plugin)
            "group:plugins"   // all plugin tools
          ]
        }
      }
    ]
  }
}

影响工具可用性的其他配置选项：

  • 仅包含插件工具名称的白名单被视为插件选择加入；核心工具保持启用状态，除非你在白名单中也包含核心工具或组。
  • tools.profile / agents.list[].tools.profile（基础白名单）
  • tools.byProvider / agents.list[].tools.byProvider（特定提供者的允许/拒绝）
  • tools.sandbox.tools.*（沙箱环境下的工具策略）

规则 + 提示

  • 工具名称不得与核心工具名称冲突；冲突的工具将被跳过。
  • 白名单中使用的插件 ID 不得与核心工具名称冲突。
  • 对于触发副作用或需要额外二进制文件/凭据的工具，建议使用 optional: true。
← 返回文档首页