擴展 OpenClaw：如何為 Agent 開發自定義工具 (Plugin agent tools)

寫 Agent 最頭痛的，就是 LLM 雖然聰明，但沒辦法直接動手做事。你可能想要它幫你抓個資料、跑個腳本，或是處理某些特定的業務邏輯，但又不想把所有邏輯都塞進 Prompt 裡。

透過 OpenClaw 的 Plugin 系統，你可以註冊 agent tools（基於 JSON-schema 的函數）。這些工具會在 Agent 運行時暴露給 LLM，讓它能根據需求自行調用。你可以決定哪些工具是預設開啟的，哪些需要手動啟用。

需要準備的東西

• OpenClaw 開發環境
• 對 JSON-schema 或 TypeBox 的基礎認識

快速開始

要在 Plugin 中增加工具，你可以使用 api.registerTool。

1. 註冊基礎工具

這是一個最簡單的工具範例，它會接收一個字串並回傳相同的內容：

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

2. 註冊選用工具 (Optional)

選用工具預設不會被啟用，使用者必須在設定檔中手動將它們加入 allowlist。對於有副作用或需要額外權限的工具，建議使用這種方式。

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

3. 在配置中啟用工具

你可以在全域的 tools 或特定 Agent 的 agents.list[].tools 中設定 allow 列表：

{
  agents: {
    list: [
      {
        id: "main",
        tools: {
          allow: [
            "workflow_tool", // 特定工具名稱
            "workflow", // Plugin ID (啟用該 Plugin 的所有工具)
            "group:plugins", // 啟用所有 Plugin 工具
          ],
        },
      },
    ],
  },
}

疑難排解

• 工具名稱衝突：如果你的工具名稱與系統核心工具 (core tool) 重複，該工具會被跳過。請確保你的工具名稱具備唯一性。
• Plugin ID 衝突：在 allowlist 中使用的 Plugin ID 如果與核心工具名稱相同，可能會導致解析錯誤。
• 工具未顯示：檢查你的工具是否設定了 optional: true。如果是，記得在設定檔的 allow 列表中明確加入它。
• 沙盒限制：如果你在沙盒環境運行，請確認 tools.sandbox.tools.* 的權限設定是否允許該工具執行。

有任何設定上的問題嗎？試試 AI Setup Assistant。

下一步

• Plugin 核心概念
• 設定檔完整指南