OpenClaw 插件中的 Agent 工具开发指南

Agent 工具是 OpenClaw 插件向大语言模型（LLM）暴露的可调用函数。这些工具通过 JSON Schema 定义输入参数，并在代理（agent）运行时按需执行，从而扩展 AI 的能力边界——例如调用本地服务、查询数据库、触发工作流等。

一、工具类型：必需 vs 可选

OpenClaw 支持两类插件工具：

类型	是否默认启用	用户是否需显式配置	适用场景
必需工具（Required）	✅ 是	❌ 否	安全、无副作用的基础功能
可选工具（Optional）	❌ 否	✅ 是	涉及敏感操作、依赖外部资源或有副作用的功能

📌 最佳实践：
若工具会触发外部系统变更、依赖额外二进制文件、或需要凭证权限，请始终标记为 optional: true。

二、注册一个基本工具（必需）

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

• name：工具唯一标识，必须为字母开头，仅含字母、数字、下划线或连字符。
• parameters：使用 TypeBox 或标准 JSON Schema 定义输入。
• execute：异步执行函数，返回符合 OpenClaw 内容格式的对象。

⚠️ 命名冲突：若插件工具名与内置（core）工具重名，该插件工具将被自动跳过。

三、注册一个可选工具（需用户显式启用）

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: `Running: ${params.pipeline}` }] };
      },
    },
    { optional: true } // 关键：标记为可选
  );
}

启用可选工具的方式

在全局 tools 或特定 agent 的 tools 配置中，通过 allowlist 显式启用：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "allow": [
            "workflow_tool",           // 启用单个工具
            "workflow",                // 启用整个插件的所有工具（插件 ID）
            "group:plugins"            // 启用所有插件工具（不包括 core）
          ]
        }
      }
    ]
  }
}

🔍 注意：

• 如果 allow 列表只包含插件工具，则内置（core）工具不会自动启用。
• 如需同时使用 core 和插件工具，必须显式包含 group:core 或具体 core 工具名。

四、工具可见性控制策略

除了 allow，OpenClaw 还支持多维度工具策略：

五、重要规则与建议

1. 避免命名冲突
   插件工具名不得与任何内置工具重名（如 search, read_file 等）。否则注册失败且无警告。

2. 插件 ID ≠ 工具名
   在 allowlist 中使用插件 ID（如 "voice-call"）可启用该插件注册的所有工具，但该 ID 本身也不能与 core 工具名冲突。

3. 优先使用 optional: true
   对于以下情况，务必设为可选：

   • 调用外部 API 或服务
   • 执行系统命令或脚本
   • 依赖未默认安装的二进制文件
   • 需要用户凭证（如 API Key）

4. 返回格式标准化
   execute 必须返回 { content: [...] } 结构，其中每个元素为 OpenClaw 支持的内容块（如文本、图像、引用等）。

六、示例：完整工作流工具配置

插件注册（workflow.plugin.ts）：

api.registerTool({
  name: "run_pipeline",
  description: "Execute a CI/CD pipeline by name",
  parameters: Type.Object({ name: Type.String() }),
  async execute(_, { name }) {
    await triggerPipeline(name);
    return { content: [{ type: "text", text: `Pipeline '${name}' started.` }] };
  }
}, { optional: true });

用户配置（openclaw.json）：

{
  "agents": {
    "list": [{
      "id": "dev-assistant",
      "tools": {
        "allow": ["run_pipeline"]
      }
    }]
  }
}

重启 Gateway 后，该 agent 即可在对话中调用 run_pipeline 工具。

七、总结

通过插件注册 Agent 工具，开发者可以安全、灵活地将外部能力注入 AI 代理流程。关键在于：

• 明确区分必需与可选工具
• 严格遵循命名规范
• 通过 allowlist 精细控制权限
• 始终将安全性放在首位

合理使用此机制，可构建出既强大又可控的智能代理系统。