Plugin Agent Tools

OpenClaw Plugin 可以注册 Agent Tool（JSON schema 函数），这些工具会在 Agent 运行时暴露给 LLM。Tool 可以是必需的（始终可用）或可选的（需要手动启用）。

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

基础工具

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 }] };
    },
  });
}

可选工具

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

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", // 具体的工具名称
            "workflow", // plugin id（启用该 plugin 的所有工具）
            "group:plugins", // 所有 plugin 工具
          ],
        },
      },
    ],
  },
}

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

• 如果白名单只包含 Plugin Tool，会被视为 Plugin 启用列表；核心工具仍然保持启用状态，除非你在白名单中也包含了核心工具或工具组。
• tools.profile / agents.list[].tools.profile（基础白名单）
• tools.byProvider / agents.list[].tools.byProvider（按 Provider 设置的允许/拒绝规则）
• tools.sandbox.tools.*（Sandbox 模式下的工具策略）

规则和提示

• Tool 名称不能与核心工具名称冲突；冲突的工具会被跳过。
• 白名单中使用的 Plugin ID 不能与核心工具名称冲突。
• 对于会触发副作用或需要额外二进制文件/凭证的工具，建议使用 optional: true。