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,只允许在工作区内操作
      }
    }
  }
}

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 实际应用场景


三、pdf:PDF 文档分析工具

3.1 能力介绍

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

3.2 执行模式

PDF 工具支持两种模式:

模式一:原生提供者模式(Native Provider)

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

模式二:提取回退模式(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 不仅能"读代码",还能"看图""读文档"!


参考来源


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