如何使用 read/edit/write 工具操作文件

read、edit、write 是 OpenClaw 最常用的三个工具，让 AI 能够直接读写编辑你电脑上的文件。本文详解它们的用法和最佳实践。

工具概览

工具	作用	使用场景
read	读取整个文件内容	查看文件、分析代码
write	覆盖写入整个文件	创建新文件、完全重写
edit	精确编辑文件的一部分	修改代码、替换文本

read – 读取文件

用法

read(file_path: string)

参数：

• file_path – 文件路径，相对于当前 workspace 根目录

返回： 文件内容

示例

AI 提示：

帮我读取一下 package.json 文件，看看当前依赖版本

它会调用：

{"name": "read", "parameters": {"file_path": "package.json"}}

write – 写入文件

用法

write(file_path: string, content: string)

参数：

• file_path – 文件路径，相对于 workspace
• content – 要写入的完整内容

⚠️ 警告： write 会覆盖整个文件！如果你只想修改一部分，用 edit。

示例

创建一个新的 README.md：

{"name": "write", "parameters": {
  "file_path": "README.md",
  "content": "# My Project\n\nThis is my project."
}}

edit – 精确编辑

用法

edit(file_path: string, old_text: string, new_text: string)

参数：

• file_path – 文件路径，相对于 workspace
• old_text – 要替换的旧文本（必须完全匹配，包括空格和换行）
• new_text – 新文本

工作原理

OpenClaw 在服务端做：

1. 读取整个文件
2. 查找 old_text 第一个完全匹配的位置
3. 替换成 new_text
4. 写回文件

如果找不到完全匹配，会返回错误，AI 会尝试重新匹配。

示例

把文件中的 const axios = require('axios'); 改成 import axios from 'axios';:

{"name": "edit", "parameters": {
  "file_path": "app.js",
  "old_text": "const axios = require('axios');",
  "new_text": "import axios from 'axios';"
}}

最佳实践

1. 大文件先用 read，再 edit

不要让 AI 盲改，先读取文件内容看看，确认后再编辑。这样不容易错。

2. old_text 一定要完全匹配

包括：

• 空格
• 缩进
• 换行
• 注释

差一个字符都匹配不上。复制原文最可靠。

3. 一次只改一处

edit 一次只替换一处。如果要改多个地方，调用多次 edit 比一次替换一大块更可靠。

4. 创建新文件用 write，修改用 edit

• 新建文件 → write
• 修改现有文件 → edit
• 完全重写 → write

5. 文件路径相对于 workspace

如果你在 /Users/you/.openclaw/workspace，那么：

• README.md → /Users/you/.openclaw/workspace/README.md
• src/app.js → /Users/you/.openclaw/workspace/src/app.js

如果要编辑绝对路径，需要配置允许访问。

常见问题

Q: edit 提示 “old_text not found”

原因： 文本不匹配，可能是：

• 空格/缩进不对
• 换行符不对
• 内容已经被修改过了

解决：

1. 重新 read 文件获取最新内容
2. 从文件中直接复制要替换的文本
3. 再次调用 edit

Q: 改写坏了怎么办？

OpenClaw 不会自动备份，但 git 可以帮你：

git diff  # 看看改了什么
git checkout -- <file>  # 恢复原状

养成改之前 git commit 的好习惯。

Q: 可以编辑大文件吗？

建议：

• 文件小于 100KB → 没问题
• 几百 KB → 可以读，但编辑可能很慢
• 几 MB → 不建议直接编辑，拆分文件更好

权限说明

默认情况下，OpenClaw 只能编辑你 workspace 目录内的文件。这是安全限制，防止误改系统文件。

如果你需要编辑其他目录，可以在配置中调整。

总结

掌握 read/edit/write 这三个工具，OpenClaw 就能帮你：

• 分析现有代码
• 创建新文件
• 修改代码 bug
• 重构代码结构

这是 AI 辅助开发的基础，用好它们能极大提升效率。