Plugin agent tools

Plugin OpenClaw có thể đăng ký agent tools (các hàm JSON-schema) để cung cấp cho LLM trong quá trình chạy agent. Tools có thể là required (luôn khả dụng) hoặc optional (opt-in).

Agent tools được cấu hình trong phần tools của config chính, hoặc cho từng agent trong agents.list[].tools. Chính sách allowlist/denylist kiểm soát những tool nào agent có thể gọi.

Tool cơ bản

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

Optional tool (opt-in)

Optional tools không bao giờ được tự động bật. Người dùng phải thêm chúng vào allowlist của 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 },
  );
}

Bật optional tools trong agents.list[].tools.allow (hoặc tools.allow toàn cục):

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool", // tên tool cụ thể
            "workflow", // plugin id (bật tất cả tools từ plugin đó)
            "group:plugins", // tất cả plugin tools
          ],
        },
      },
    ],
  },
}

Các tùy chọn config khác ảnh hưởng đến tính khả dụng của tool:

• Allowlists chỉ liệt kê plugin tools được coi là plugin opt-ins; core tools vẫn được bật trừ khi các bạn cũng thêm core tools hoặc groups vào allowlist.
• tools.profile / agents.list[].tools.profile (base allowlist)
• tools.byProvider / agents.list[].tools.byProvider (allow/deny theo provider)
• tools.sandbox.tools.* (chính sách sandbox tool khi được sandbox)

Quy tắc + mẹo

• Tên tool không được trùng với tên core tool; các tool trùng tên sẽ bị bỏ qua.
• Plugin ids được dùng trong allowlists không được trùng với tên core tool.
• Nên dùng optional: true cho các tool kích hoạt side effects hoặc yêu cầu thêm binaries/credentials.