OpenClaw工具拆解之 read+write

如果文章对你有帮助，请点个“关注”

一、read 工具

1.1 工具概述

功能：读取文件内容（支持文本和图片）核心特性：

• • 自适应分页读取（大文件自动分页）
• • 支持图片文件（作为附件发送）
• • 支持多种路径参数别名（path/file_path/filePath/file）
• • 工作目录限制（workspaceOnly 模式）

1.2 工具创建链

createReadTool (外部库 @mariozechner/pi-coding-agent)    ↓createOpenClawReadTool (OpenClaw 包装层)    ↓wrapToolWorkspaceRootGuard (工作目录限制)    ↓最终工具

1.3 OpenClaw 包装代码

位置：第 115027 行

functioncreateOpenClawReadTool(base, options) {return {        ...patchToolSchemaForClaudeCompatibility(base),execute: async (toolCallId, params, signal) => {// 1. 参数标准化（支持 path/file_path/filePath/file 别名）const normalized = normalizeToolParams(params);const record = normalized ?? (params && typeof params === "object" ? params : void0);// 2. 验证必填参数assertRequiredParams(record, CLAUDE_PARAM_GROUPS.read, base.name);// 3. 执行读取（支持自适应分页）const result = awaitexecuteReadWithAdaptivePaging({                base,                toolCallId,args: normalized ?? params ?? {},                signal,maxBytes: resolveAdaptiveReadMaxBytes(options)            });// 4. 处理文件路径const filePath = typeof record?.path === "string" ? String(record.path) : "<unknown>";// 5. 处理图片结果（如果是图片文件）returnsanitizeToolResultImages(awaitnormalizeReadImageResult(stripReadTruncationContentDetails(result),                     filePath                ), `read:${filePath}`,                 options?.imageSanitization            );        }    };}

1.4 自适应分页读取

位置：第 114782 行

asyncfunctionexecuteReadWithAdaptivePaging(params) {const userLimit = params.args.limit;// 1. 用户指定了 limit，直接返回if (typeof userLimit === "number" && Number.isFinite(userLimit) && userLimit > 0) {returnawait params.base.execute(params.toolCallId, params.args, params.signal);    }// 2. 自适应分页读取const offsetRaw = params.args.offset;let nextOffset = typeof offsetRaw === "number" && Number.isFinite(offsetRaw) && offsetRaw > 0 ? Math.floor(offsetRaw) : 1;let firstResult = null;let aggregatedText = "";let aggregatedBytes = 0;let capped = false;let continuationOffset;for (let page = 0; page < MAX_ADAPTIVE_READ_PAGES; page += 1) {// 读取下一页const pageArgs = { ...params.args, offset: nextOffset };const pageResult = await params.base.execute(params.toolCallId, pageArgs, params.signal);        firstResult ??= pageResult;const rawText = getToolResultText$1(pageResult);if (typeof rawText !== "string") return pageResult;// 检查是否被截断const truncation = extractReadTruncationDetails(pageResult);const canContinue = Boolean(truncation?.truncated) &&                            !truncation?.firstLineExceedsLimit &&                            (truncation?.outputLines ?? 0) > 0 &&                            page < MAX_ADAPTIVE_READ_PAGES - 1;const pageText = canContinue ? stripReadContinuationNotice(rawText) : rawText;// 聚合文本const delimiter = aggregatedText ? "\n\n" : "";const nextBytes = Buffer.byteLength(`${delimiter}${pageText}`, "utf-8");// 检查是否超过最大字节数if (aggregatedText && aggregatedBytes + nextBytes > params.maxBytes) {            capped = true;            continuationOffset = nextOffset;break;        }        aggregatedText += `${delimiter}${pageText}`;        aggregatedBytes += nextBytes;if (!canContinue || !truncation) returnwithToolResultText(pageResult, aggregatedText);        nextOffset += truncation.outputLines;        continuationOffset = nextOffset;if (aggregatedBytes >= params.maxBytes) {            capped = true;break;        }    }// 3. 返回聚合结果if (!firstResult) returnawait params.base.execute(params.toolCallId, params.args, params.signal);let finalText = aggregatedText;if (capped && continuationOffset) {        finalText += `\n\n[Read output capped at ${formatBytes(params.maxBytes)} for this call. Use offset=${continuationOffset} to continue.]`;    }returnwithToolResultText(firstResult, finalText);}

1.5 图片结果处理

位置：第 114832 行

functionrewriteReadImageHeader(text, mimeType) {if (text.startsWith("Read image file [") && text.endsWith("]")) {return`Read image file [${mimeType}]`;    }return text;}asyncfunctionnormalizeReadImageResult(result, filePath) {const content = Array.isArray(result.content) ? result.content : [];// 查找图片块const image = content.find((b) =>        !!b && typeof b === "object" &&         b.type === "image" && typeof b.data === "string" && typeof b.mimeType === "string"    );if (!image) return result;// 验证图片数据if (!image.data.trim()) {thrownewError(`read: image payload is empty (${filePath})`);    }// 检测真实 MIME 类型const sniffed = awaitsniffMimeFromBase64(image.data);if (!sniffed) return result;if (!sniffed.startsWith("image/")) {thrownewError(`read: file looks like ${sniffed} but was treated as ${image.mimeType} (${filePath})`);    }if (sniffed === image.mimeType) return result;// 修正 MIME 类型const nextContent = content.map((block) => {if (block && typeof block === "object" && block.type === "image") {return { ...block, mimeType: sniffed };        }if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {return { ...block, text: rewriteReadImageHeader(block.text, sniffed) };        }return block;    });return { ...result, content: nextContent };}

1.6 参数标准化

位置：第 114541 行

// 参数分组定义constCLAUDE_PARAM_GROUPS = {read: [{keys: ["path", "file_path", "filePath", "file"],label: "path alias"    }]};// 参数别名映射constCLAUDE_PARAM_ALIASES = [    { original: "path", alias: "file_path" },    { original: "path", alias: "filePath" },    { original: "path", alias: "file" }];// 标准化函数functionnormalizeToolParams(params) {if (!params || typeof params !== "object") return;const normalized = { ...params };// 提取结构化文本（处理嵌套对象）for (const key of ["path", "file_path", "filePath", "file"]) {normalizeTextLikeParam(normalized, key);    }// 转换别名为标准参数normalizeClaudeParamAliases(normalized);return normalized;}

1.7 沙盒读取操作

位置：第 115041 行

functioncreateSandboxReadOperations(params) {return {readFile: (absolutePath) => params.bridge.readFile({filePath: absolutePath,cwd: params.root        }),access: async (absolutePath) => {if (!await params.bridge.stat({filePath: absolutePath,cwd: params.root            })) {throwcreateFsAccessError("ENOENT", absolutePath);            }        },detectImageMimeType: async (absolutePath) => {const mime = awaitdetectMime({buffer: await params.bridge.readFile({filePath: absolutePath,cwd: params.root                }),filePath: absolutePath            });return mime && mime.startsWith("image/") ? mime : void0;        }    };}

1.8 执行流程图

read 工具调用    ↓1. 参数标准化   ├─ path/file_path/filePath/file → path   └─ 提取结构化文本（处理嵌套对象）    ↓2. 验证必填参数（path）    ↓3. 判断是否指定 limit   ├─ 是 → 直接读取指定行数   └─ 否 → 自适应分页读取    ↓4. 自适应分页   ├─ 读取第 1 页（默认 2000 行或 50KB）   ├─ 检查是否截断   ├─ 是 → 继续读第 2 页   ├─ 聚合文本   ├─ 重复直到不截断或达到最大页数   └─ 返回聚合结果    ↓5. 处理图片文件（如果是图片）   ├─ 检测 MIME 类型   ├─ 转换为 Base64   ├─ 修正 MIME 类型   └─ 作为附件发送    ↓6. 返回结果

1.9 返回结果格式

文本文件：

{"content":[{"type":"text","text":"文件内容..."}],"details":{"path":"/path/to/file.txt","lines":100,"truncated":false}}

图片文件：

{"content":[{"type":"text","text":"Read image file [image/png]"},{"type":"image","data":"base64...","mimeType":"image/png"}],"details":{"path":"/path/to/image.png"}}

二、write 工具

2.1 工具概述

功能：写入文件内容（创建或覆盖）核心特性：

• • 自动创建父目录
• • 支持多种路径参数别名
• • workspaceOnly 限制
• • 沙盒隔离支持

2.2 工具创建链

createWriteTool (外部库 @mariozechner/pi-coding-agent)    ↓wrapToolParamNormalization (参数标准化)    ↓wrapToolWorkspaceRootGuard (工作目录限制)    ↓最终工具

2.3 Host 写入操作

位置：第 115057 行

asyncfunctionwriteHostFile(absolutePath, content) {const resolved = path.resolve(absolutePath);await fs$1.mkdir(path.dirname(resolved), { recursive: true });await fs$1.writeFile(resolved, content, "utf-8");}functioncreateHostWriteOperations(root, options) {// 1. 无限制模式if (!(options?.workspaceOnly ?? false)) {return {mkdir: async (dir) => {const resolved = path.resolve(dir);await fs$1.mkdir(resolved, { recursive: true });            },writeFile: writeHostFile        };    }// 2. workspaceOnly 模式（限制只能访问工作区）return {mkdir: async (dir) => {const relative = toRelativeWorkspacePath(root, dir, { allowRoot: true });const resolved = relative ? path.resolve(root, relative) : path.resolve(root);awaitassertSandboxPath({filePath: resolved,cwd: root,                root            });await fs$1.mkdir(resolved, { recursive: true });        },writeFile: async (absolutePath, content) => {awaitwriteFileWithinRoot({rootDir: root,relativePath: toRelativeWorkspacePath(root, absolutePath),data: content,mkdir: true            });        }    };}

2.4 沙盒写入操作

位置：第 115068 行

functioncreateSandboxWriteOperations(params) {return {mkdir: async (dir) => {await params.bridge.mkdirp({filePath: dir,cwd: params.root            });        },writeFile: async (absolutePath, content) => {await params.bridge.writeFile({filePath: absolutePath,cwd: params.root,data: content            });        }    };}

2.5 参数标准化

// write 工具参数分组constCLAUDE_PARAM_GROUPS = {write: [        {keys: ["path", "file_path", "filePath", "file"],label: "path alias"        },        {keys: ["content"],label: "content"        }    ]};// write 工具参数别名constCLAUDE_PARAM_ALIASES = [    { original: "path", alias: "file_path" },    { original: "path", alias: "filePath" },    { original: "path", alias: "file" }];

2.6 执行流程图

write 工具调用    ↓1. 参数标准化   ├─ path/file_path/filePath/file → path   └─ 提取结构化文本（content）    ↓2. 验证必填参数（path, content）    ↓3. 解析路径（绝对/相对）    ↓4. 检查 workspaceOnly 限制   ├─ 是 → 验证路径在工作区内   └─ 否 → 允许任意路径    ↓5. 创建父目录（mkdir -p）    ↓6. 写入文件（覆盖模式）    ↓7. 返回成功结果

2.7 返回结果格式

成功：

{"content":[{"type":"text","text":"Successfully wrote 1234 bytes to /path/to/file.txt"}],"details":{"path":"/path/to/file.txt","bytesWritten":1234,"created":true}}

失败：

{"content":[{"type":"text","text":"Error: Cannot write outside workspace directory"}],"details":{"error":"workspace_violation","path":"/etc/passwd"}}

三、关键机制对比

3.1 参数标准化

3.2 安全限制

3.3 特殊处理

四、使用示例

4.1 read 工具调用

用户：读取 README.md 文件

大模型返回：

{"tool_call":{"name":"read","arguments":{"path":"README.md"}}}

执行结果：

{"content":[{"type":"text","text":"# Project Title\n\nDescription..."}],"details":{"path":"README.md","lines":50}}

4.2 write 工具调用

用户：创建一个新文件 test.txt，内容为 Hello World

大模型返回：

{"tool_call":{"name":"write","arguments":{"path":"test.txt","content":"Hello World"}}}

执行结果：

{"content":[{"type":"text","text":"Successfully wrote 11 bytes to test.txt"}],"details":{"path":"test.txt","bytesWritten":11,"created":true}}

五、常见错误

5.1 read 工具

5.2 write 工具

如果文章对你有帮助，请点个“关注”