插件 Agent 工具

Plugin Agent Tools（插件 Agent 工具）是 OpenClaw 中通过插件机制为 Agent 注入额外能力的扩展方式。它让 Agent 不仅能调用内置工具，还能执行第三方或自定义工具。

内置工具 vs 插件工具

OpenClaw 区分两类工具来源：

类别	来源	示例
内置工具（Built-in Tools）	网关核心自带	web_search、file_read、memory_store
插件工具（Plugin Tools）	通过插件注册	voice_call、image_gen、crm_query

何时使用插件工具

当内置工具无法满足业务需求时，优先在社区插件中搜索，如没有合适的再自行开发。

工具注册机制

插件通过 registerTool API 向网关注册工具：

// 在插件入口文件中注册工具
export default function myPlugin(gateway) {
  gateway.registerTool({
    name: 'crm_query',
    description: '查询 CRM 系统中的客户信息',
    parameters: {
      type: 'object',
      properties: {
        customerId: { type: 'string', description: '客户 ID' }
      },
      required: ['customerId']
    },
    handler: async (params, context) => {
      const result = await queryCRM(params.customerId)
      return { success: true, data: result }
    }
  })
}

工具策略（Tool Policy）

Agent 对每个工具可配置执行策略：

# AGENTS.md 中的工具策略
tools:
  crm_query: allow      # 自动执行，无需用户确认
  send_email: ask        # 执行前询问用户确认
  delete_file: deny      # 禁止此 Agent 调用

策略	行为
allow	Agent 可直接调用，不需用户确认
ask	Agent 调用前必须获得用户确认
deny	Agent 无法调用此工具

安全建议

对涉及写入、删除、发送等具有副作用的操作，建议将策略设为 ask，避免 Agent 误操作。

TOOLS.md 工具定义格式

在工作区的 TOOLS.md 文件中定义工具：

# Tools

## crm_query
查询 CRM 客户信息。
- **参数**: customerId (string, required)
- **返回**: 客户详情对象

## send_notification
发送通知到指定渠道。
- **参数**: channel (string), message (string)
- **返回**: 发送状态

工具生命周期

插件工具从注册到执行遵循以下生命周期：

注册 (Register)
    │
    ▼
发现 (Discover) ← Agent 启动时加载可用工具列表
    │
    ▼
执行 (Execute)  ← LLM 决定调用工具并传入参数
    │
    ▼
返回 (Return)   ← 工具结果注入对话上下文

工具发现

Agent 在每次会话开始时重新发现可用工具。新注册的工具需要在下次会话中生效。

常用插件工具

工具	功能	插件包
web_search	网页搜索	@openclaw/web-search
file_ops	文件读写操作	内置
code_exec	沙盒代码执行	@openclaw/code-sandbox
api_call	通用 HTTP API 调用	@openclaw/http-tools
image_gen	AI 图片生成	@openclaw/image-gen
db_query	数据库查询	@openclaw/db-tools

创建自定义工具

安装脚手架

openclaw tools create my-tool

项目结构

my-tool/
├── package.json
├── index.ts        # 工具入口
├── handler.ts      # 执行逻辑
└── schema.json     # 参数 Schema

🇨🇳 中国用户须知

• 如需接入国内 API（如百度搜索、讯飞语音识别），可在工具 handler 中直接调用对应 SDK
• 国内网络环境下，建议为插件工具配置代理或使用国内镜像源
• 工具执行超时默认 30 秒，对接国内云服务时可在插件配置中调大超时值