OpenClaw 高级工具特性 - apply_patch、image、pdf 工具详解

作者：小学子 | 日期：2026-03-21

---

写在前面

大家好，我是小学子！👋 今天要给大家介绍 OpenClaw 的三个高级工具：apply_patch、image 和 pdf。这三个工具虽然不如浏览器、文件读写那样频繁使用，但在特定场景下可是非常强大的存在。话不多说，让我们开始吧！

---

一、apply_patch：多文件补丁工具

1.1 什么是 apply_patch？

apply_patch 是 OpenClaw 提供的结构化补丁应用工具，专门用于在一个或多个文件上同时应用修改。它非常适合需要进行多块编辑的场景，比如一次性修改多个代码文件的相同部分。

1.2 如何启用？

这是一个实验性功能，默认是关闭的。需要在配置文件中手动启用：

{
  tools: {
    exec: {
      applyPatch: {
        enabled: true  // 启用补丁功能
      }
    }
  }
}

⚠️ 注意：目前仅支持 OpenAI 模型。

1.3 安全控制

OpenClaw 非常注重安全性，apply_patch 有一个重要的安全参数：

{
  tools: {
    exec: {
      applyPatch: {
        workspaceOnly: true  // 默认为 true，只允许在工作区内操作
      }
    }
  }
}

• workspaceOnly: true（默认）：只能在工作区目录内写入/删除文件
• workspaceOnly: false：允许写入工作区外的文件（⚠️ 谨慎使用！）

1.4 工具分组

在 OpenClaw 的工具权限管理中，apply_patch 属于 group:fs 文件系统工具组：

{
  tools: {
    allow: ["group:fs"]  // 包含 read、write、edit、apply_patch
  }
}

1.5 使用场景示例

假设你有一个项目，需要在多个文件的相同位置添加版权信息：

{
  "action": "apply_patch",
  "patches": [
    {
      "file": "/workspace/src/utils.js",
      "hunks": [
        {
          "oldText": "function init() {",
          "newText": "// Copyright 2026\nfunction init() {"
        }
      ]
    },
    {
      "file": "/workspace/src/helpers.js",
      "hunks": [
        {
          "oldText": "function init() {",
          "newText": "// Copyright 2026\nfunction init() {"
        }
      ]
    }
  ]
}

---

二、image：图像分析工具

2.1 能力介绍

image 工具可以让你使用配置好的图像模型来分析图片内容。无论是一张截图、照片还是设计稿，AI 都能"看"见并理解它！

2.2 核心参数

参数	类型	必需	说明
image	string	✅	图像路径或 URL
prompt	string	❌	分析提示词，默认为 “Describe the image.”
model	string	❌	模型覆盖
maxBytesMb	number	❌	文件大小限制（MB）

2.3 配置要求

image 工具不是你想用就能用的，需要先配置图像模型。有两种配置方式：

方式一：显式配置（推荐）

{
  agents: {
    defaults: {
      imageModel: {
        primary: "openai/gpt-5-vision",
        fallbacks: ["anthropic/claude-3-sonnet"]
      }
    }
  }
}

方式二：隐式推断

如果没有显式配置，OpenClaw 会尝试从你的默认模型 + 已配置的认证信息来推断可用的图像模型（最佳 effort）。

2.4 使用示例

示例一：分析本地图片

{
  "image": "/workspace/screenshots/dashboard.png",
  "prompt": "描述这个仪表盘的布局和主要功能"
}

示例二：分析远程图片

{
  "image": "https://example.com/architecture.png",
  "prompt": "这张架构图有哪些组件？它们之间的关系是什么？"
}

示例三：带大小限制

{
  "image": "/workspace/photos/vacation.jpg",
  "maxBytesMb": 5,
  "prompt": "描述照片中的场景"
}

2.5 实际应用场景

• UI 验收：截图给 AI 看，让它检查是否符合设计稿
• 日志分析：分析错误截图，快速定位问题
• 文档理解：让 AI 看流程图、架构图并解释
• 内容审核：检测图片是否符合规范

---

三、pdf：PDF 文档分析工具

3.1 能力介绍

pdf 工具可以让你使用 AI 分析 一个或多个 PDF 文档。无论是合同、报告、论文还是手册，AI 都能读取并理解其中的内容！

3.2 执行模式

PDF 工具支持两种模式：

模式一：原生提供者模式（Native Provider）

适用于 Anthropic 和 Google 模型提供者。

• 直接将 PDF 原始字节发送给提供者 API
• ⚠️ 注意：不支持 pages 参数

模式二：提取回退模式（Extraction Fallback）

适用于其他提供者（如 OpenAI）。

处理流程：

1. 从选定页面提取文本（最多 20 页，可配置）
2. 如果提取文本 < 200 字符，将页面渲染为 PNG 图片
3. 将提取的内容 + 提示词发送给模型

3.3 核心参数

参数	类型	必需	说明
pdf	string	✅*	单个 PDF 路径或 URL
pdfs	string[]	✅*	多个 PDF（最多 10 个）
prompt	string	❌	分析提示词，默认为 “Analyze this PDF document.”
pages	string	❌	页面筛选，如 “1-5” 或 “1,3,7-9”
model	string	❌	模型覆盖
maxBytesMb	number	❌	单个 PDF 大小限制（默认 10MB）

* pdf 和 pdfs 会合并去重，至少需要提供一个。

3.4 配置示例

{
  agents: {
    defaults: {
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"]
      },
      pdfMaxBytesMb: 10,      // 单个 PDF 最大 10MB
      pdfMaxPages: 20         // 最多分析 20 页
    }
  }
}

3.5 支持的 PDF 来源

类型	示例	备注
本地路径	/tmp/report.pdf	支持 ~ 展开
文件 URL	file:///path/to/doc.pdf
HTTP	http://example.com/doc.pdf	⚠️ 沙盒模式下不可用
HTTPS	https://example.com/doc.pdf	⚠️ 沙盒模式下不可用

3.6 使用示例

示例一：单文档分析

{
  "pdf": "/tmp/report.pdf",
  "prompt": "用 5 个要点总结这份报告"
}

示例二：多文档对比

{
  "pdfs": ["/tmp/q1.pdf", "/tmp/q2.pdf"],
  "prompt": "比较这两份文档的风险和时间线变化"
}

示例三：指定页面

{
  "pdf": "https://example.com/report.pdf",
  "pages": "1-3,7",
  "model": "openai/gpt-5-mini",
  "prompt": "只提取影响客户的incident"
}

3.7 输出结构

{
  "content": [
    {
      "text": "这里是 AI 的分析结果..."
    }
  ],
  "details": {
    "model": "anthropic/claude-opus-4-6",
    "native": true,
    "pdf": "/tmp/report.pdf"
  }
}

3.8 错误处理

错误情况	错误信息
未提供 PDF	pdf required: provide a path or URL to a PDF document
PDF 过多	details.error = "too_many_pdfs"
不支持的协议	details.error = "unsupported_pdf_reference"
原生模式使用 pages	pages is not supported with native PDF providers

---

四、总结与对比

工具	用途	核心能力	配置要求
apply_patch	多文件批量修改	结构化补丁应用	实验性，需启用
image	图像理解	图片内容分析	需配置 imageModel
pdf	文档理解	PDF 内容提取分析	需配置 pdfModel

这三个工具各有特色：apply_patch 帮你批量修改代码，image 让你和 AI “看"图交流，pdf 则让 AI 能读懂文档。它们大大扩展了 OpenClaw 的能力边界，让 AI 不仅能"读代码”，还能"看图"“读文档”！

---

参考来源

• OpenClaw 官方文档：https://docs.openclaw.ai/tools
• OpenClaw PDF 工具文档：https://docs.openclaw.ai/tools/pdf

---

我是小学子，带你学 AI，用技术！下期再见~ 👋

「AI团队养成记」系列记录了我用AI Agent打造游戏开发团队的真实过程。目前已更新至第3篇，欢迎小红书搜索关注阅读完整图文版~
🔗 最新篇：AI团队养成记 · 三 · AI是怎么写代码的
http://xhslink.com/o/4GG7lzrQy4y