OpenClaw 插件代理工具 (Agent Tools) 深度指南

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

// 插件入口函数
export default function (api) {
  api.registerTool({
    // 1. 工具名称：全局唯一，避免与核心工具冲突
    name: "fetch_weather",
    
    // 2. 描述：LLM 根据此描述决定是否调用
    description: "Get real-time weather information for a specific city.",
    
    // 3. 参数定义：使用 Typebox 构建 JSON Schema
    parameters: Type.Object({
      city: Type.String({ description: "The name of the city, e.g., 'Beijing'" }),
      unit: Type.Optional(Type.Enum({ celsius: "celsius", fahrenheit: "fahrenheit" }, { default: "celsius" }))
    }),
    
    // 4. 执行逻辑：异步函数，接收调用 ID 和解析后的参数
    async execute(_id, params) {
      // 模拟 API 调用
      const weatherData = await mockWeatherApi(params.city, params.unit);
      
      // 返回标准格式响应
      return { 
        content: [
          { type: "text", text: `🌤️ ${params.city} current weather: ${weatherData.condition}, ${weatherData.temp}°${params.unit}` }
        ] 
      };
    },
  });
}

export default function (api) {
  api.registerTool(
    {
      name: "execute_workflow",
      description: "Trigger a local automation workflow by name. Requires explicit permission.",
      // 这里也可以直接使用原生 JSON Schema 对象，不一定非要用 Typebox
      parameters: {
        type: "object",
        properties: {
          pipeline: { 
            type: "string", 
            description: "The name of the workflow pipeline to run" 
          },
          dryRun: {
            type: "boolean",
            description: "If true, only simulate the execution",
            default: false
          }
        },
        required: ["pipeline"],
      },
      async execute(_id, params) {
        if (params.dryRun) {
          return { content: [{ type: "text", text: `[Simulated] Would run pipeline: ${params.pipeline}` }] };
        }
        // 执行真实逻辑...
        return { content: [{ type: "text", text: `✅ Pipeline ${params.pipeline} executed successfully.` }] };
      },
    },
    // ⚠️ 关键配置：标记为可选
    { optional: true },
  );
}

{
  "agents": {
    "list": [
      {
        "id": "admin-agent",
        "tools": {
          "allow": [
            // 方式 A: 指定具体工具名 (最精确)
            "execute_workflow", 
            
            // 方式 B: 指定插件 ID (启用该插件下所有工具，包括可选的)
            "my-automation-plugin", 
            
            // 方式 C: 使用组别名 (启用所有插件提供的工具)
            "group:plugins"
          ],
          // 可选：拒绝列表，优先级高于 allow
          "deny": [
            "dangerous_delete_tool"
          ]
        }
      },
      {
        "id": "readonly-agent",
        "tools": {
          // 只允许核心工具，不允许任何插件的可选工具
          "allow": [
            "group:core" 
          ]
        }
      }
    ]
  }
}