工具（Tool）在 OpenClaw 中的地位

OpenClaw 的能力以工具为核心：模型通过工具执行文件读写、运行命令、调用外部 API。工具是 Agent 与外界交互的唯一桥梁，理解工具定义、注册与策略控制是开发自定义能力的起点。

工具的定义结构

一个工具通常包含名称、输入参数 Schema 与执行逻辑。OpenClaw 使用 JSON Schema 描述参数，让模型知道该传什么值。

{
  "name": "my_custom_tool",
  "description": "执行自定义业务操作",
  "parameters": {
    "type": "object",
    "properties": {
      "action": {"type": "string", "description": "要执行的动作"}
    },
    "required": ["action"]
  }
}

清晰的 description 能显著提升模型调用的准确率——模型依赖描述判断何时调用该工具。

注册与加载机制

工具通过配置或插件系统注册。OpenClaw 支持在会话配置中声明可用工具，并在模型上下文里暴露给当前会话。

# 会话配置片段
tools:
  - name: my_custom_tool
    source: ./tools/my_custom_tool.js

插件机制允许工具动态注册与热重载，无需重启网关即可新增能力。注册后可通过 tool_search 检索到该工具并实际调用。

策略过滤与审批

工具并非无条件可调。OpenClaw 通过策略（policy）过滤工具调用，并可为敏感命令设置执行审批。这与安全模型直接相关：越危险的工具越需要显式授权。

# 策略配置示例：对删除类命令要求审批
tools:
  exec:
    mode: require-approval

开发者应明确工具的风险等级，将破坏性操作纳入审批流程，而非默认放行。

用脚本实现一个简单工具

以 Node.js 实现一个”查询服务器状态”的工具为例：

// tools/server_status.js
module.exports = async function(args) {
  // args.host 由模型按 Schema 传入
  const data = await fetchStatus(args.host);
  return { ok: true, status: data };
};

定义好 Schema 与实现后注册进会话，即可让模型在合适时机调用它。

调试与最佳实践

开发自定义工具时，用 tool_describe 查看完整 Schema 确认字段正确，用 tool_search 验证工具是否可见。实践要点：

• 参数 Schema 字段名用简洁英文，避免歧义。
• description 明确”何时使用、何时不用”，减少误调用。
• 错误信息返回结构化 JSON，便于模型理解并重试。
• 涉及密钥与凭据时，通过安全通道注入，切勿硬编码进源码。

工具是 OpenClaw 能力的边界。清晰的 Schema、合理的策略与健壮的实现，共同决定 Agent 能否可靠地替你完成工作。