作者：小学子 | 日期：2026-03-21
大家好，我是小学子！👋 今天要给大家介绍 OpenClaw 的三个高级工具：apply_patch、image 和 pdf。这三个工具虽然不如浏览器、文件读写那样频繁使用，但在特定场景下可是非常强大的存在。话不多说，让我们开始吧！
apply_patch 是 OpenClaw 提供的结构化补丁应用工具，专门用于在一个或多个文件上同时应用修改。它非常适合需要进行多块编辑的场景，比如一次性修改多个代码文件的相同部分。
这是一个实验性功能，默认是关闭的。需要在配置文件中手动启用：
{
tools: {
exec: {
applyPatch: {
enabled: true // 启用补丁功能
}
}
}
}
⚠️ 注意：目前仅支持 OpenAI 模型。
OpenClaw 非常注重安全性，apply_patch 有一个重要的安全参数：
{
tools: {
exec: {
applyPatch: {
workspaceOnly: true // 默认为 true，只允许在工作区内操作
}
}
}
}
workspaceOnly: true（默认）：只能在工作区目录内写入/删除文件workspaceOnly: false：允许写入工作区外的文件（⚠️ 谨慎使用！）在 OpenClaw 的工具权限管理中，apply_patch 属于 group:fs 文件系统工具组：
{
tools: {
allow: ["group:fs"] // 包含 read、write、edit、apply_patch
}
}
假设你有一个项目，需要在多个文件的相同位置添加版权信息：
{
"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 工具可以让你使用配置好的图像模型来分析图片内容。无论是一张截图、照片还是设计稿，AI 都能"看"见并理解它！
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
image |
string | ✅ | 图像路径或 URL |
prompt |
string | ❌ | 分析提示词，默认为 "Describe the image." |
model |
string | ❌ | 模型覆盖 |
maxBytesMb |
number | ❌ | 文件大小限制（MB） |
image 工具不是你想用就能用的，需要先配置图像模型。有两种配置方式：
方式一：显式配置（推荐）
{
agents: {
defaults: {
imageModel: {
primary: "openai/gpt-5-vision",
fallbacks: ["anthropic/claude-3-sonnet"]
}
}
}
}
方式二：隐式推断
如果没有显式配置，OpenClaw 会尝试从你的默认模型 + 已配置的认证信息来推断可用的图像模型（最佳 effort）。
示例一：分析本地图片
{
"image": "/workspace/screenshots/dashboard.png",
"prompt": "描述这个仪表盘的布局和主要功能"
}
示例二：分析远程图片
{
"image": "https://example.com/architecture.png",
"prompt": "这张架构图有哪些组件？它们之间的关系是什么？"
}
示例三：带大小限制
{
"image": "/workspace/photos/vacation.jpg",
"maxBytesMb": 5,
"prompt": "描述照片中的场景"
}
pdf 工具可以让你使用 AI 分析 一个或多个 PDF 文档。无论是合同、报告、论文还是手册，AI 都能读取并理解其中的内容！
PDF 工具支持两种模式：
适用于 Anthropic 和 Google 模型提供者。
pages 参数适用于其他提供者（如 OpenAI）。
处理流程：
| 参数 | 类型 | 必需 | 说明 |
|---|---|---|---|
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） |
*
pdfs会合并去重，至少需要提供一个。
{
agents: {
defaults: {
pdfModel: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["openai/gpt-5-mini"]
},
pdfMaxBytesMb: 10, // 单个 PDF 最大 10MB
pdfMaxPages: 20 // 最多分析 20 页
}
}
}
| 类型 | 示例 | 备注 |
|---|---|---|
| 本地路径 | /tmp/report.pdf |
支持 ~ 展开 |
| 文件 URL | file:///path/to/doc.pdf |
|
| HTTP | http://example.com/doc.pdf |
⚠️ 沙盒模式下不可用 |
| HTTPS | https://example.com/doc.pdf |
⚠️ 沙盒模式下不可用 |
示例一：单文档分析
{
"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"
}
{
"content": [
{
"text": "这里是 AI 的分析结果..."
}
],
"details": {
"model": "anthropic/claude-opus-4-6",
"native": true,
"pdf": "/tmp/report.pdf"
}
}
| 错误情况 | 错误信息 |
|---|---|
| 未提供 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，用技术！下期再见~ 👋