OpenClaw工具拆解之host_workspace_write+host_workspace_edit

一、host_workspace_write 工具

1.1 工具概述

功能 :写入 host 工作区文件
核心特性:

  • 直接访问 host 文件系统
  • 支持 workspaceOnly 限制
  • 自动创建父目录
  • 参数标准化包装
  • 边界检查

1.2 创建函数

位置:第 115018 行

javascript 复制代码
function createHostWorkspaceWriteTool(root, options) {
    return wrapToolParamNormalization(createWriteTool(root, { 
        operations: createHostWriteOperations(root, options) 
    }), CLAUDE_PARAM_GROUPS.write);
}

1.3 Host 写入操作

位置:第 115057 行

javascript 复制代码
async function writeHostFile(absolutePath, content) {
    const resolved = path.resolve(absolutePath);
    await fs$1.mkdir(path.dirname(resolved), { recursive: true });
    await fs$1.writeFile(resolved, content, "utf-8");
}

function createHostWriteOperations(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);
            await assertSandboxPath({
                filePath: resolved,
                cwd: root,
                root
            });
            await fs$1.mkdir(resolved, { recursive: true });
        },
        writeFile: async (absolutePath, content) => {
            await writeFileWithinRoot({
                rootDir: root,
                relativePath: toRelativeWorkspacePath(root, absolutePath),
                data: content,
                mkdir: true
            });
        }
    };
}

1.4 包装链

复制代码
createWriteTool (外部库)
    ↓ (使用 Host 操作)
wrapToolParamNormalization (参数标准化)
    ↓ (CLAUDE_PARAM_GROUPS.write)
最终工具

1.5 workspaceOnly 模式

javascript 复制代码
// workspaceOnly = false(无限制)
├─ 可以写入任意路径
└─ 直接调用 fs.mkdir/fs.writeFile

// workspaceOnly = true(限制模式)
├─ 只能写入工作区内
├─ assertSandboxPath 检查边界
└─ writeFileWithinRoot 安全写入

1.6 执行流程图

复制代码
host_workspace_write 工具调用
    ↓
1. 参数标准化
   ├─ path/file_path/filePath/file → path
   └─ content → content
    ↓
2. 验证必填参数
    ↓
3. 检查 workspaceOnly 限制
    ├─ 是 → 验证路径在工作区内
    └─ 否 → 允许任意路径
    ↓
4. 创建父目录(mkdir -p)
    ↓
5. 写入文件(覆盖模式)
    ↓
6. 返回结果

二、host_workspace_edit 工具

2.1 工具概述

功能 :编辑 host 工作区文件
核心特性:

  • 直接访问 host 文件系统
  • 支持 workspaceOnly 限制
  • 支持编辑失败恢复
  • 参数标准化包装
  • 边界检查

2.2 创建函数

位置:第 115021 行

javascript 复制代码
function createHostWorkspaceEditTool(root, options) {
    return wrapToolParamNormalization(
        wrapEditToolWithRecovery(createEditTool(root, { 
            operations: createHostEditOperations(root, options) 
        }), {
            root,
            readFile: (absolutePath) => fs$1.readFile(absolutePath, "utf-8")
        }), 
        CLAUDE_PARAM_GROUPS.edit
    );
}

2.3 Host 编辑操作

位置:第 115099 行

javascript 复制代码
function createHostEditOperations(root, options) {
    // 1. 无限制模式
    if (!(options?.workspaceOnly ?? false)) {
        return {
            readFile: async (absolutePath) => {
                const resolved = path.resolve(absolutePath);
                return await fs$1.readFile(resolved);
            },
            writeFile: writeHostFile,
            access: async (absolutePath) => {
                const resolved = path.resolve(absolutePath);
                await fs$1.access(resolved);
            }
        };
    }
    
    // 2. workspaceOnly 模式(限制只能访问工作区)
    return {
        readFile: async (absolutePath) => {
            return (await readFileWithinRoot({
                rootDir: root,
                relativePath: toRelativeWorkspacePath(root, absolutePath)
            })).buffer;
        },
        writeFile: async (absolutePath, content) => {
            await writeFileWithinRoot({
                rootDir: root,
                relativePath: toRelativeWorkspacePath(root, absolutePath),
                data: content,
                mkdir: true
            });
        },
        access: async (absolutePath) => {
            let relative;
            try {
                relative = toRelativeWorkspacePath(root, absolutePath);
            } catch {
                return;
            }
            try {
                await (await openFileWithinRoot({
                    rootDir: root,
                    relativePath: relative
                })).fd;
            } catch {
                // 忽略错误
            }
        }
    };
}

2.4 编辑恢复包装

位置:第 114462 行(与 sandboxed_edit 共享)

javascript 复制代码
function wrapEditToolWithRecovery(base, options) {
    return {
        ...base,
        execute: async (toolCallId, params, signal, onUpdate) => {
            // 1. 读取参数
            const { pathParam, oldText, newText } = readEditToolParams(params);
            
            // 2. 解析绝对路径
            const absolutePath = typeof pathParam === "string" ? 
                resolveEditPath(options.root, pathParam) : void 0;
            
            // 3. 读取原始内容
            let originalContent;
            if (absolutePath && newText !== void 0) {
                try {
                    originalContent = await options.readFile(absolutePath);
                } catch {}
            }
            
            // 4. 执行编辑
            try {
                return await base.execute(toolCallId, params, signal, onUpdate);
            } catch (err) {
                // 5. 编辑失败处理
                if (!absolutePath) throw err;
                
                let currentContent;
                try {
                    currentContent = await options.readFile(absolutePath);
                } catch {}
                
                // 6. 判断编辑是否已应用
                if (typeof currentContent === "string" && newText !== void 0) {
                    if (didEditLikelyApply({
                        originalContent,
                        currentContent,
                        oldText,
                        newText
                    })) {
                        return buildEditSuccessResult(pathParam ?? absolutePath);
                    }
                }
                
                // 7. 添加不匹配提示
                if (typeof currentContent === "string" && 
                    err instanceof Error && 
                    shouldAddMismatchHint(err)) {
                    throw appendMismatchHint(err, currentContent);
                }
                
                throw err;
            }
        }
    };
}

2.5 参数标准化

javascript 复制代码
const CLAUDE_PARAM_GROUPS = {
    edit: [
        {
            keys: ["path", "file_path", "filePath", "file"],
            label: "path alias"
        },
        {
            keys: ["oldText", "old_string", "old_text", "oldString"],
            label: "oldText alias"
        },
        {
            keys: ["newText", "new_string", "new_text", "newString"],
            label: "newText alias",
            allowEmpty: true
        }
    ]
};

2.6 执行流程图

复制代码
host_workspace_edit 工具调用
    ↓
1. 参数标准化
   ├─ path 别名处理
   ├─ oldText 别名处理
   └─ newText 别名处理
    ↓
2. 验证必填参数
    ↓
3. 检查 workspaceOnly 限制
    ↓
4. 读取原始内容
    ↓
5. 执行编辑(精确替换)
    ↓
6. 编辑失败处理
   ├─ 读取当前内容
   ├─ 判断是否部分成功
   └─ 添加不匹配提示
    ↓
7. 返回结果

三、关键机制对比

3.1 功能定位

特性 host_workspace_write host_workspace_edit
用途 创建/覆盖文件 精确修改文件
写操作 覆盖写入 精确替换
恢复机制 不支持 支持

3.2 与沙盒工具对比

特性 Host 工具 沙盒工具
文件系统 Host 直接访问 Bridge 隔离访问
性能 更快 桥接开销
安全性 较低 较高
使用场景 非沙盒模式 沙盒模式

3.3 workspaceOnly 模式

javascript 复制代码
// workspaceOnly = false
├─ 可以访问任意路径
├─ 直接调用 fs 模块
└─ 无边界检查

// workspaceOnly = true
├─ 只能访问工作区
├─ assertSandboxPath 检查
├─ writeFileWithinRoot 安全写入
└─ readFileWithinRoot 安全读取

四、Host 工具系列总结

4.1 两个 Host 工具

工具 功能 操作
host_workspace_write 写入 Host 文件 fs.mkdir, fs.writeFile
host_workspace_edit 编辑 Host 文件 fs.readFile, fs.writeFile, fs.access

4.2 共同特点

  • 直接访问 host 文件系统
  • 支持 workspaceOnly 限制
  • 自动创建父目录
  • 参数标准化(CLAUDE 别名)
  • 边界检查(workspaceOnly 模式)

4.3 使用场景

复制代码
非沙盒模式时:
├─ 读取文件 → read (或 host_workspace_read 如果存在)
├─ 写入文件 → host_workspace_write
└─ 编辑文件 → host_workspace_edit

沙盒模式时:
├─ 读取文件 → sandboxed_read
├─ 写入文件 → sandboxed_write
└─ 编辑文件 → sandboxed_edit

五、使用示例

5.1 host_workspace_write 工具调用

用户 :在工作区创建文件

大模型返回:

json 复制代码
{
  "tool_call": {
    "name": "host_workspace_write",
    "arguments": { 
      "path": "src/main.js",
      "content": "console.log(\"Hello\");"
    }
  }
}

执行结果:

json 复制代码
{
  "content": [{
    "type": "text",
    "text": "Successfully wrote 27 bytes to src/main.js"
  }],
  "details": {
    "path": "src/main.js",
    "bytesWritten": 27,
    "workspaceOnly": true
  }
}

5.2 host_workspace_edit 工具调用

用户 :修改工作区中的文件

大模型返回:

json 复制代码
{
  "tool_call": {
    "name": "host_workspace_edit",
    "arguments": { 
      "path": "src/main.js",
      "oldText": "console.log(\"Hello\");",
      "newText": "console.log(\"Hello, World!\");"
    }
  }
}

执行结果:

json 复制代码
{
  "content": [{
    "type": "text",
    "text": "Successfully edited src/main.js"
  }],
  "details": {
    "path": "src/main.js",
    "workspaceOnly": true
  }
}
相关推荐
智联视频超融合平台22 分钟前
视频 AI 的误报之战,正在从调参数卷到改架构
人工智能·大模型·边缘计算·视频监控·安防
水如烟1 小时前
孤能子视角:智能的边界不在算法强弱,在可形式化性——从概率法到因果推理,选择池的边界一直在那里
人工智能
万里侯2 小时前
日志聚类之后别把 noise 扔掉:降噪应该改变视图,不抹掉证据
人工智能·微服务·ai·容器·k8s
澹锦汐2 小时前
纯前端秋日银杏与枫叶落叶色板智能聚类器:基于 K-Means 色彩量化与直方图自动配方提取
前端·人工智能·ai·语言模型·vue·react·k-means
Flynt10 小时前
AI 写的 Three.js 大屏,为什么越跑越卡?我在 Node 里复现了它的内存曲线
前端·ai编程·three.js
J船长10 小时前
AI 知识库的主流做法是 RAG,RAG怎么做
ai编程
小虎AI生活10 小时前
哇塞~24小时开机的WorkBuddy免费领,速来
aigc·ai编程
71777710 小时前
国内 AI 研发效能工具怎么选:2026 年基于公开信息的选型框架与 Gitee 实践
人工智能·gitee
Csvn10 小时前
换供应商要改一遍代码?把模型接入收进一层网关(C04)
人工智能·aigc·agent
孟健11 小时前
开源AutoClip切直播:1小时48分出19段,整月API只花0.08元
人工智能·开源·aigc