OpenClaw系列第14课:文件读写 – read / write / edit工具实战

这是「OpenClaw 教程课程」第 14 课。 前两课我们讲了 exec 和 browser：一个让 AI 执行命令，一个让 AI 操作网页。这一课回到最基础、但也最容易影响实际工作的能力：文件读写。

图：read / write / edit 是 Agent 处理文件的基础能力。读清楚、改准确、能验证，是文件操作最重要的三件事。

很多人第一次让 AI 改文件，会直接说：

帮我把这个文件改一下。

这当然可以。

但如果你想让 Agent 改得稳、改得少、改完可检查，就不能只把“改文件”看成一个动作。

在 OpenClaw 里，文件操作通常会拆成几类工具：

• read：读取文件内容
• write：创建或覆盖文件
• edit：对已有文件做精确替换

这三个工具看起来都和文件有关，但适用场景完全不同。

这一课我们就讲清楚：

什么时候用 read，什么时候用 write，什么时候用 edit，以及怎样避免让 AI 一不小心覆盖重要文件。

一、先说结论：文件修改前，通常应该先 read

如果今天只记一个习惯，我建议你记这个：

让 Agent 改文件前，先让它读文件。

为什么？

因为文件是当前状态。

当前状态是会变化的。

如果 Agent 没有读文件，就直接改，很容易出现这些问题：

• 不知道文件真实内容
• 误以为某段代码存在
• 覆盖掉用户刚刚改过的内容
• 改错位置
• 用旧上下文生成新文件
• 把格式、注释、缩进弄乱

所以文件修改最稳的流程通常是：

1. read：先看文件当前内容
2. 判断：确认要改哪一小块
3. edit：做精确修改
4. 验证：再读一次或运行测试 / grep / 构建

也就是说，文件工具不是“拿来就写”。

更好的心法是：

先观察，再修改，最后验证。

这和第 12 课的 exec、第 13 课的 browser 是同一个思路。

二、read：先看清文件内容

read 是最基础的文件工具。

它的作用很简单：

读取文件内容。

它适合这些场景：

• 查看配置文件
• 查看 Markdown 文章
• 查看代码片段
• 查看日志片段
• 确认某段内容是否存在
• 修改前先理解上下文

比如你可以说：

帮我读一下 articles/lesson-13-browser-tool-let-ai-operate-webpages-hexo.md 的标题和配图部分。

Agent 就可以读取对应文件，再告诉你结果。

read 不是无限读取

实际使用时，read 通常会有输出限制。

比如当前工具说明里就提到：

• 文本文件会被截断到一定行数或大小
• 大文件需要用 offset / limit 分段读取
• 图片文件可以作为图片附件读取

所以如果文件很大，Agent 不应该一次性硬读到底。

更好的方式是：

先读前 120 行，看看结构；如果需要，再继续读后面的相关部分。

或者：

先搜索目标关键词，再读取附近内容。

这样更省上下文，也更稳。

三、write：创建或覆盖整个文件

write 的作用是：

创建文件，或覆盖已有文件。

这句话里最重要的是“覆盖”。

write 很强，也很危险。

它适合这些场景：

• 新建一篇文章
• 新建一个配置示例
• 生成一个完整脚本
• 创建一个新 README
• 你明确希望重写整个文件

例如这篇教程，就是适合用 write 创建的新文件。

但如果你只是想改已有文件里的一句话，就不应该优先用 write。

因为 write 是整体覆盖。

如果 Agent 用 write 改一个已有文件，而它手里的内容不是完整、最新版本，就可能把原文件里的其他内容覆盖掉。

所以你可以先记住：

新建文件用 write；小范围修改已有文件，优先用 edit。

图：read 负责读取当前内容，write 适合新建或整体覆盖，edit 适合对已有文件做精确小改。

四、edit：对已有文件做精确替换

edit 是文件修改里非常重要的工具。

它的作用是：

用精确文本替换的方式修改文件。

你可以把它理解成：

找到一段完全匹配的旧文本，把它替换成新文本。

这种方式比整体覆盖更安全。

例如原文件里有一段：

## 下一课预告下一课我们会讲第 14 课。

你想改成：

## 下一课预告下一课我们会讲第 15 课。

这类任务就很适合 edit。

因为它只影响这几行，不会碰文件其他部分。

edit 的关键要求：oldText 必须精确匹配

edit 的核心是精确替换。

也就是说，Agent 需要提供：

• oldText：原文件里真实存在的一段文本
• newText：要替换成的新文本

而且 oldText 不能模糊。

如果原文是：

OpenClaw 是一个本地优先的 Agent 系统。

那 oldText 就必须和它一致。

少一个空格、多一个标点、换行不一样，都可能匹配失败。

这也是为什么 edit 前通常要先 read。

因为 Agent 需要拿到原文件里的真实文本。

五、write 和 edit 最大的区别

新手最容易混淆的就是 write 和 edit。

我们用一句话区分：

write 是重写整个文件，edit 是替换文件中的某一段。

write 更像“新建/整篇覆盖”

适合：

• 从零生成文章
• 从零生成脚本
• 覆盖一个确定要重写的草稿
• 生成完整配置模板

风险是：

• 覆盖掉原文件
• 丢失未读到的内容
• 覆盖用户刚刚手动修改的部分

edit 更像“手术刀”

适合：

• 改一句话
• 补一个段落
• 替换一个配置项
• 修改某个函数的小块逻辑
• 给文章补一张图占位

风险是：

• oldText 不唯一，可能不知道该改哪一处
• oldText 不匹配，修改失败
• 替换范围选太大，影响不该动的内容

所以推荐原则是：

能 edit，就不要 write；必须整体生成时，才用 write。

六、为什么 edit 要求 oldText 唯一？

在 OpenClaw 的工具说明里，edit 有一个很重要的要求：

每个 oldText 必须匹配原文件中唯一、不重叠的区域。

这是为了避免误改。

比如一个文件里有很多个：

下一课预告

如果只把 oldText 写成这四个字，工具就不知道你要改哪一个。

更安全的做法是把上下文带上：

## 下一课预告下一课我们继续讲第三模块里的基础工具组合：

这样匹配就更明确。

不过也不要为了唯一性，把半个文件都塞进 oldText。

最好选一个：

• 足够唯一
• 范围足够小
• 不包含太多无关内容

这就是好的 edit。

图：edit 更像手术刀。先定位唯一旧文本，再替换成新文本，尽量只影响必要范围。

七、一个最小实战：给文章补一张图占位

假设你有一篇 Markdown 文章，配图建议里写了 4 张图，但正文里只放了 3 张。

你想补上第 4 张图占位。

这是一个非常典型的 edit 场景。

安全流程应该是这样：

第一步：read 相关段落

先让 Agent 读取正文靠近“安全注意事项”或“配图建议”的部分。

请先读取第 13 课正文中“安全和隐私注意事项”附近内容，确认最后一张配图是否已经放入正文。

第二步：确认插入位置

比如确认应该插入在：

因为 CDP 控制能力非常强，暴露到公网风险很高。

后面。

第三步：用 edit 精确插入

把旧文本：

因为 CDP 控制能力非常强，暴露到公网风险很高。## 十六、适合新手的 browser 提问模板

替换成：

因为 CDP 控制能力非常强，暴露到公网风险很高。## 十六、适合新手的 browser 提问模板

这个例子很适合说明 edit 的价值：

• 没有重写整篇文章
• 只改一个明确位置
• 改动范围小
• 修改后可以再 read 验证图片数量

八、什么时候应该用 read + exec，而不是只用 read？

read 可以读文件内容。

但如果你要检查很多文件，或者要做统计，单靠 read 可能不够高效。

这时可以配合第 12 课讲过的 exec。

例如：

帮我统计 articles 目录里所有 lesson 文件的 title。

这类任务如果一个个 read，会很慢。

更适合用：

grep -R "^title:" articles/lesson-*.md

或者：

find articles -name 'lesson-*.md' -maxdepth 1 -type f

所以可以这样分工：

• 看一个具体文件：用 read
• 搜索多个文件：用 exec 跑 rg / grep
• 找到目标后：再用 read 看上下文
• 修改目标：用 edit

这套组合非常实用。

九、什么时候适合用 write？

虽然前面一直提醒不要滥用 write，但 write 不是坏工具。

它非常适合“从零生成”的任务。

例如：

1）新建文章

请写第 14 课，并保存成 articles/lesson-14-file-read-write-edit-tools-hexo.md。

这就是典型 write 场景。

因为目标文件本来不存在，或者你明确希望生成完整新稿。

2）生成示例配置

请生成一个 example.openclaw.json，作为教学示例，不要覆盖真实配置。

注意这里最好写成 example 文件，而不是直接写真实配置。

3）生成脚本草稿

请新建 scripts/check-articles.sh，用来检查 articles 目录里每篇文章是否有 title 和 description。

这种从零创建脚本，也适合 write。

4）重写一个确定可覆盖的草稿

例如：

这个 draft.md 是临时草稿，可以整体重写。请直接覆盖。

这里用户明确说可以覆盖，write 就合理。

十、什么时候不适合用 write？

下面这些情况，不建议直接 write。

1）修改真实配置文件

比如：

帮我改 ~/.openclaw/openclaw.json

这种配置文件很关键。

更稳的做法是：

• 先 read 或使用专门配置工具查看
• 说明要改哪些字段
• 尽量用专门配置工具或精确 edit
• 修改后验证

2）修改长代码文件中的一小段

如果只是改一个函数，不应该整体覆盖整个代码文件。

应该先 read 相关函数，再 edit 局部。

3）你不确定文件是否有用户手动改动

如果文件可能刚被人改过，直接 write 很容易覆盖掉对方修改。

这时必须先 read，必要时用 git diff 或其他方式检查。

4）文件太大，Agent 没读完整

文件没读完整，却要整体 write，是危险的。

因为 Agent 可能用“不完整理解”生成一个“看似完整”的文件。

这很容易丢内容。

十一、文件修改的推荐工作流

日常让 Agent 改文件，我建议用这套流程。

第一步：明确目标

不要只说：

帮我优化一下。

更好的是：

帮我把第 13 课正文里缺少的第 4 张配图占位补上，不要改其他内容。

目标越具体，修改越安全。

第二步：先 read

让 Agent 先读相关区域，而不是直接改。

先读取相关段落，确认插入位置。

第三步：小范围 edit

要求：

只用 edit 做最小范围修改，不要整篇覆盖。

第四步：验证

修改后可以让 Agent：

• 再 read 对应段落
• grep 图片占位数量
• 检查 Markdown 标题
• 运行构建或预览

比如：

修改后检查正文里是否有 4 个图片占位。

这一步非常关键。

因为文件修改不是“工具成功返回”就算完全结束。

你还需要确认结果符合目标。

图：安全的文件修改流程是明确目标、读取上下文、小范围编辑、最后验证。

十二、适合新手的文件操作提问模板

下面这些句式可以直接复制。

1）只读不改

请读取这个文件，帮我总结结构和可能需要修改的地方。不要修改文件。

2）先看再改

请先读取相关段落，告诉我你准备怎么改。等我确认后再修改。

3）小范围修改

请只修改这个文件里的指定段落，使用最小范围 edit，不要整体覆盖文件。

4）新建文件

请新建一个文件保存完整内容。如果目标文件已存在，先提醒我，不要直接覆盖。

5）修改后验证

修改后请重新读取相关位置，并说明实际改了哪些内容。

6）保护用户改动

修改前请先检查当前文件内容，不要覆盖我最近手动改过的部分。

这些模板背后的共同点是：

让 Agent 知道边界。

边界越清楚，文件操作越稳。

十三、常见坑

坑 1：没读文件就直接改

这是最常见的坑。

如果 Agent 没读文件，通常只是基于上下文或猜测在改。

正确做法：

改文件前先 read 当前内容。

坑 2：小改动却用 write 覆盖整篇

比如只想改一个标题，却把整篇文章重新写了一遍。

这会增加很多不必要风险。

正确做法：

小改动优先 edit。

坑 3：edit 的 oldText 太短

如果 oldText 太短，可能不唯一。

例如只匹配：

## 总结

很多文章里都可能有这个标题。

正确做法：

oldText 要包含足够上下文，但不要过大。

坑 4：页面或文件变化后还用旧上下文

如果用户刚刚又改过文件，Agent 之前读到的内容可能已经过期。

正确做法：

关键修改前重新 read 或检查 diff。

坑 5：修改后不验证

工具返回成功，只代表写入或替换动作完成。

不代表文章结构、代码逻辑、配置语法一定正确。

正确做法：

改完后做最小验证。

坑 6：让 Agent 直接改敏感配置

比如真实 token、认证文件、生产配置。

正确做法：

先说明风险，优先生成示例文件或 patch，确认后再应用。

十四、和 tool policy / sandbox 的关系

文件工具也受工具策略和运行环境影响。

如果 read、write、edit 没有被允许，Agent 就不能使用它们。

在 OpenClaw 的工具分组里，文件相关工具通常属于 group:fs，包括：

• read
• write
• edit
• apply_patch

如果当前 Agent 运行在 sandbox 中，它看到的文件范围也可能受 sandbox workspace 影响。

这意味着：

• 它不一定能读到宿主机所有文件
• 它可能只能访问工作区
• 它可能只能读，不能写
• 它可能需要额外权限才能改某些路径

所以当你发现 Agent 说“找不到文件”时，不一定是文件真的不存在。

也可能是当前执行环境看不到。

这个问题在后面的权限和 sandbox 课程里还会继续展开。

十五、read / write / edit 怎么和前两课配合？

到这里，第三模块的几个工具已经开始连起来了。

read / write / edit + exec

适合代码和文章工作流：

1. read 看文件
2. edit 修改文件
3. exec 跑测试、grep 或构建
4. 再根据结果继续改

例如：

帮我修改这篇 Markdown 的标题，然后检查 front matter 是否还完整。

read / write / edit + browser

适合网页发布和验收：

1. write 生成文章
2. edit 补图或改段落
3. 发布后用 browser 打开网页
4. 截图确认展示效果

例如：

帮我写完文章后，用 browser 打开预览页，检查配图和标题是否显示正常。

工具之间不是孤立的。

真正好用的 Agent，往往是把这些工具组合起来完成闭环。

图：文件工具可以和 exec、browser 组合使用，形成“读文件、改文件、运行验证、网页验收”的完整闭环。

十六、这一课最值得记住的一句话

如果今天只记一句话，我建议你记这句：

read 看清现状，write 生成整体，edit 精确小改。

再补一句安全原则：

已有文件小改优先 edit，整体覆盖必须先确认。

十七、总结

今天这节课，我们讲清楚了 OpenClaw 里的三个基础文件工具：

1. read 用来读取文件内容，是修改前的第一步。
2. write 用来新建或整体覆盖文件，适合从零生成。
3. edit 用来精确替换已有文件中的某段内容，适合小范围修改。
4. 改文件前先 read，可以避免基于旧上下文或猜测乱改。
5. 小改动优先 edit，不要轻易用 write 覆盖整篇。
6. edit 的 oldText 要唯一、精确、范围适中。
7. 修改后要验证，不能只看工具调用是否成功。
8. 文件工具会受到 tool policy、sandbox 和工作区权限影响。

学会 read / write / edit 之后，你就能更安全地让 OpenClaw 帮你写文章、改配置、修代码、补文档。

这类工具看起来基础，但它们决定了 Agent 能不能真正参与长期项目。

下一课预告

下一课我们继续讲第三模块最后一个工具主题：

第 15 课：TTS 语音——让 OpenClaw 开口说话

也就是：

• OpenClaw 怎么把文字转成语音
• TTS 适合哪些场景
• 语音回复和普通文字回复有什么区别
• 怎么避免语音通知打扰用户
• 什么时候应该用 voice note 风格输出

🦞 本文由八条撰写，持续更新中。