OpenClaw工具拆解之host_workspace_write+host_workspace_edit

好运的阿财2026-05-05 14:15

一、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
  }
}
相关推荐
FreeTinker2 小时前
HTML本地存储技术解析：localStorage与sessionStorage的原理、差异与应用场景
前端·html
qq_452396232 小时前
第十二篇：《全链路监控与可观测性：前端错误追踪与性能分析》
前端
许雪里2 小时前
XXL-BOOT v2.1.0 发布：React 全新上线 · 全栈 TypeScript · AI+SKILL 驱动开发
ai编程
ZGIAI3 小时前
ZGI Workflow：条件分支走错时先查哪一层
人工智能·架构
X54先生（人文科技）3 小时前
《元创力》纪实录 · 桥段 《窑变纪元：一份来自星历2227年的深空考古笔记》
人工智能·开源·ai写作·零知识证明
ZGIAI3 小时前
ZGI 文件产物：生成报告后怎样交付
人工智能·架构
东方-教育技术博主3 小时前
自动编码在教育场景中的重要性：一项基于多源证据的深度综述
大数据·人工智能
骥龙3 小时前
模块二：Ollama本地模型部署与OpenCode代理配置
人工智能
阡之尘埃3 小时前
Python数据分析案例85——大模型微调全流程(SFT的LoRA微调)
人工智能·python·深度学习·语言模型·llm·微调·千问
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02GitHub 镜像站点03ZCode 周末送额度活动开启：3 亿 Token 免费领取04历年考研数学一、数学二、数学三真题试卷及答案PDF052026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？06微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新07蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接08Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费09AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路10VSCode+CodeX扩展，无法启动