插件智能体工具

OpenClaw 插件可以注册智能体工具(JSON schema 函数),这些工具在智能体运行期间会暴露给 LLM。工具可以是必需的(始终可用)或可选的(可选启用)。

智能体工具在主配置的 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。