外掛 agent 工具

OpenClaw 外掛可以註冊 agent 工具（JSON schema 函式），在 agent 執行期間提供給 LLM 使用。工具可以是必要的（始終可用）或可選的（需手動啟用）。

Agent 工具在主設定的 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", // 外掛 id（啟用該外掛的所有工具）
            "group:plugins", // 所有外掛工具
          ],
        },
      },
    ],
  },
}

影響工具可用性的其他設定：

• 僅列出外掛工具的允許清單會被視為外掛啟用清單；核心工具維持啟用，除非你在允許清單中也列出核心工具或群組。
• tools.profile / agents.list[].tools.profile（基礎允許清單）
• tools.byProvider / agents.list[].tools.byProvider（按 provider 的允許/拒絕）
• tools.sandbox.tools.*（沙箱中的工具策略）

規則與建議

• 工具名稱不得與核心工具名稱衝突；衝突的工具會被跳過。
• 允許清單中使用的外掛 id 不得與核心工具名稱衝突。
• 會觸發副作用或需要額外二進位檔/憑證的工具，建議使用 optional: true。