内置工具全解：16个核心工具的能力边界与适用场景

第14章：内置工具全解——16个核心工具的能力边界与适用场景

概述

OpenClaw 内置 16 个原生工具，覆盖文件操作、命令执行、浏览器控制、网页搜索、定时调度、记忆管理和多 Agent 协调等所有核心能力。理解每个工具的边界和适用场景，是构建高效 Agent 工作流的前提。

14.1 工具总览

14.2 read — 文件读取

功能说明

读取本地文件系统中文件的内容，支持文本和二进制文件。

接口定义

{
  "tool": "read",
  "input": {
    "path": "/path/to/file",
    "encoding": "utf-8",
    "start_line": 1,
    "end_line": 100,
    "max_bytes": 102400
  }
}

参数说明

适用场景

• 读取配置文件、日志文件、源代码文件
• 加载数据文件进行分析
• 检查文件是否存在及其内容

限制

• 默认不能读取沙箱外路径（受工具策略控制）
• 大文件建议使用 start_line/end_line 分段读取
• 二进制文件需指定 encoding: "base64"

14.3 write — 文件写入

功能说明

创建新文件或覆盖现有文件的全部内容。

接口定义

{
  "tool": "write",
  "input": {
    "path": "/path/to/output.txt",
    "content": "文件内容在此",
    "encoding": "utf-8",
    "create_dirs": true,
    "overwrite": true
  }
}

适用场景

• 创建新文件
• 生成配置文件、报告、代码文件
• 写入完整替换内容（当需要部分修改时用 edit）

限制

• overwrite: false 时若文件存在则报错
• 不适合对大文件的局部修改（用 edit）

14.4 edit — 精准文件编辑

功能说明

对文件进行精准的局部内容修改，支持字符串替换、行号替换和正则替换。

接口定义

{
  "tool": "edit",
  "input": {
    "path": "/path/to/file.py",
    "operations": [
      {
        "type": "replace_string",
        "old": "def old_function():",
        "new": "def new_function():",
        "replace_all": false
      },
      {
        "type": "replace_lines",
        "start_line": 42,
        "end_line": 45,
        "new_content": "# 新的代码块\nprint('hello')"
      },
      {
        "type": "insert_after_line",
        "line": 10,
        "content": "# 插入的注释"
      }
    ]
  }
}

read vs edit vs write 的选择逻辑

需要读取文件内容？
    --> 使用 read

需要修改文件？
    --> 需要修改整个文件？
        --> 使用 write
    --> 只需要修改特定部分？
        --> 使用 edit
            --> 知道确切的字符串？使用 replace_string
            --> 知道行号范围？使用 replace_lines

14.5 exec — Shell 命令执行

功能说明

执行单个 Shell 命令，带沙箱控制和超时管理。

接口定义

{
  "tool": "exec",
  "input": {
    "command": "ls -la /workspace",
    "cwd": "/workspace",
    "env": {
      "MY_VAR": "value"
    },
    "timeout_seconds": 30,
    "capture_output": true
  }
}

输出格式

{
  "stdout": "文件列表内容...",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 142
}

14.6 bash — Bash 脚本块执行

功能说明

执行多行 Bash 脚本，支持管道、变量和复杂逻辑。

接口定义

{
  "tool": "bash",
  "input": {
    "script": "#!/bin/bash\nset -e\ncd /workspace\nfor f in *.py; do\n  echo \"Processing: $f\"\n  python -m py_compile \"$f\"\ndone",
    "timeout_seconds": 60,
    "cwd": "/workspace"
  }
}

exec vs bash 的差异

重要：两者在执行前都会剥离危险环境变量，包括 DYLD_*、LD_*、NODE_OPTIONS 等。

14.7 process — 进程管理

功能说明

启动、停止、查询后台进程，适合需要长期运行的服务。

接口定义

{
  "tool": "process",
  "input": {
    "action": "start",
    "command": "python server.py",
    "cwd": "/workspace",
    "name": "my-server",
    "restart_on_crash": true,
    "log_file": "/var/log/my-server.log"
  }
}

操作类型

适用场景

• 启动 Web 服务器、数据库
• 管理长期运行的 Worker
• 在 Agent 工作流中启动辅助服务

14.8 browser — 浏览器控制

功能说明

通过 Playwright/Puppeteer 控制无头浏览器，实现 Web 自动化操作。

坐标点击

{
  "tool": "browser",
  "input": {
    "action": "click",
    "selector": "#submit-button",
    "x": 450,
    "y": 320,
    "click_type": "left"
  }
}

表单填写

{
  "tool": "browser",
  "input": {
    "action": "fill_form",
    "fields": [
      {"selector": "#username", "value": "admin"},
      {"selector": "#password", "value": "${SECRET_PASSWORD}"},
      {"selector": "#remember-me", "action": "check"}
    ]
  }
}

完整操作集

{
  "tool": "browser",
  "input": {
    "action": "navigate",
    "url": "https://example.com"
  }
}

适用场景

• 自动化登录、数据提取（Web Scraping）
• 填写在线表单、提交申请
• 对 Web 应用进行 E2E 测试
• 截图监控页面状态

14.9 web_search — 网页搜索

功能说明

集成多个搜索引擎和内容抓取服务，获取实时网络信息。

支持的后端

接口定义

{
  "tool": "web_search",
  "input": {
    "query": "OpenClaw Agent framework 2026",
    "backend": "tavily",
    "max_results": 5,
    "include_content": true,
    "time_range": "month"
  }
}

输出示例

{
  "results": [
    {
      "title": "OpenClaw v3.0 Release Notes",
      "url": "https://docs.openclaw.dev/changelog",
      "snippet": "OpenClaw 3.0 introduces...",
      "content": "Full page content...",
      "published_date": "2026-03-15"
    }
  ],
  "total_results": 5
}

14.10 message — 消息发送

功能说明

向用户、系统日志或外部 Webhook 发送消息，支持多种消息类型。

接口定义

{
  "tool": "message",
  "input": {
    "target": "user",
    "content": "任务已完成，请查看结果",
    "type": "info",
    "attachments": [
      {"type": "file", "path": "/output/report.pdf"}
    ]
  }
}

消息目标

消息类型

14.11 cron — 定时任务调度

功能说明

创建、管理和删除定时任务，支持标准 Cron 表达式。

Cron 表达式语法

┌─────────── 分钟 (0-59)
│ ┌─────────── 小时 (0-23)
│ │ ┌─────────── 日 (1-31)
│ │ │ ┌─────────── 月 (1-12)
│ │ │ │ ┌─────────── 星期 (0-6, 0=周日)
│ │ │ │ │
* * * * *

接口定义

{
  "tool": "cron",
  "input": {
    "action": "create",
    "name": "daily-report",
    "schedule": "0 9 * * 1-5",
    "task": {
      "type": "agent_run",
      "agent": "report-generator",
      "input": {"date": "${today}"}
    },
    "timezone": "Asia/Shanghai",
    "enabled": true
  }
}

常用 Cron 表达式示例

# 每天早上 9 点（工作日）
0 9 * * 1-5

# 每小时执行一次
0 * * * *

# 每 15 分钟执行一次
*/15 * * * *

# 每月 1 号零点执行
0 0 1 * *

# 每周日凌晨 2 点执行备份
0 2 * * 0

# 每天下午 3 点和 6 点
0 15,18 * * *

Cron 操作类型

14.12 memory_search — 语义搜索记忆

功能说明

在 Agent 记忆库中进行语义相似度搜索，返回最相关的记忆片段。

接口定义

{
  "tool": "memory_search",
  "input": {
    "query": "用户偏好的输出格式设置",
    "top_k": 5,
    "threshold": 0.7,
    "namespace": "user_preferences",
    "filters": {
      "created_after": "2026-01-01",
      "tags": ["preferences", "format"]
    }
  }
}

输出示例

{
  "memories": [
    {
      "id": "mem_abc123",
      "content": "用户偏好 JSON 格式输出，缩进为 2 空格",
      "similarity": 0.92,
      "created_at": "2026-02-15T10:23:00Z",
      "tags": ["preferences", "format"]
    }
  ]
}

14.13 memory_get — 读取指定记忆文件

功能说明

通过 ID 或路径精准读取特定的记忆条目，不进行语义搜索。

接口定义

{
  "tool": "memory_get",
  "input": {
    "id": "mem_abc123",
    "path": "user_preferences/output_format.md",
    "namespace": "global"
  }
}

memory_search vs memory_get 的选择

你知道需要什么记忆？
    |
    +-- 知道确切 ID 或文件名 --> 使用 memory_get（精准、快速）
    |
    +-- 知道大概含义但不知道具体位置 --> 使用 memory_search（语义搜索）
    |
    +-- 需要批量扫描相关记忆 --> 先 memory_search，再对结果使用 memory_get

14.14 sessions_spawn — 生成子 Agent

功能说明

创建独立的子 Agent 会话，实现并行任务处理或专业化分工。

接口定义

{
  "tool": "sessions_spawn",
  "input": {
    "agent_config": {
      "name": "code-reviewer",
      "model": "anthropic/claude-opus-4-6",
      "system_prompt": "你是专业代码审查 Agent，专注于安全漏洞检测",
      "tools": ["read", "web_search"],
      "max_turns": 20
    },
    "initial_message": "请审查 /workspace/src 目录下的所有 Python 文件",
    "delivery_mode": "background",
    "on_complete_notify": true
  }
}

交付模式

使用模式

模式 A：并行任务分解

// 主 Agent 同时spawn多个子Agent处理不同模块
{
  "tool": "sessions_spawn",
  "input": {
    "agent_config": {"name": "frontend-agent"},
    "initial_message": "优化 React 组件性能"
  }
}
// 同时
{
  "tool": "sessions_spawn",
  "input": {
    "agent_config": {"name": "backend-agent"},
    "initial_message": "优化 API 接口性能"
  }
}

模式 B：专业化分工

{
  "tool": "sessions_spawn",
  "input": {
    "agent_config": {
      "name": "security-auditor",
      "system_prompt": "专注安全审计，只使用 read 工具",
      "tools": ["read"],
      "tool_policy": "allowlist"
    }
  }
}

14.15 Canvas 控制工具组

Canvas 工具用于操作 OpenClaw 视觉工作区，支持创建交互式数据看板和工作流可视化。

主要操作

{
  "tool": "canvas_create_node",
  "input": {
    "type": "text",
    "content": "数据分析结果",
    "x": 100,
    "y": 200,
    "width": 300,
    "height": 150
  }
}

14.16 Node 设备控制工具组

Node 工具用于控制物理设备和 IoT 节点，适合边缘计算和工业自动化场景。

{
  "tool": "node_send_command",
  "input": {
    "node_id": "sensor-hub-01",
    "command": "read_temperature",
    "params": {"unit": "celsius"}
  }
}

14.17 工具组合使用模式

模式 A：代码生成与验证

web_search（查文档）
    --> read（读取现有代码）
    --> write/edit（生成新代码）
    --> exec（运行测试）
    --> message（报告结果）

模式 B：定时数据收集

cron（触发调度）
    --> web_search（搜索最新数据）
    --> write（保存原始数据）
    --> sessions_spawn（异步分析Agent）
    --> message（发送分析报告）

模式 C：自动化 Web 操作

browser（导航到目标页面）
    --> browser（填写表单）
    --> browser（截图确认）
    --> write（保存截图）
    --> message（通知完成）

本章小结

• read/write/edit 构成完整的文件操作三角：读取、全覆盖写入、精准局部修改
• exec vs bash：单命令用 exec，多步骤脚本用 bash，两者都会剥离危险环境变量
• browser 工具支持坐标点击和表单批量填写，是 Web 自动化的核心
• web_search 支持 Exa/Tavily/Firecrawl 等多个后端，按需选择
• cron 支持标准 Cron 表达式，支持时区配置
• memory_search 做语义检索，memory_get 做精准读取
• sessions_spawn 是实现多 Agent 并行协作的关键工具

下一章 将深入讲解工具策略：Allow/Deny 规则、沙箱配置与 elevated 标志。