远程 Mac（VNC）上的八步 Runbook 与可勾选验收表
v2026.5.3把 Agent 工作流里最敏感的一类能力——跨目录读文件与枚举目录树——从「默认可用」改成默认拒绝 + 显式白名单，并引入配对节点（pairing node）来描述「哪两台机器之间允许建立受控的文件拉取/写回通道」。若你已在 5.3-beta 上修过 LaunchAgent 与 Gateway 冷启动路径，本文是文件侧工具链的增量清单：先对齐发行说明里 file_fetch / dir_fetch 的拒绝语义与审计字段，再按工单把路径前缀、最大深度、符号链接解析策略、配对指纹写进配置，最后在与 Gateway 同用户的 VNC 图形会话里完成工具面板与拖拽试验的交叉验证。文中与《v2026.5.7 插件发布链》、《v2026.5.3-beta.2 LaunchAgent》、《SecretRef 审计》、《多项目隔离》互链，便于你把「装得上」与「读得安全」放在同一变更单里验收。
在真实项目里，Agent 往往会在一次会话中多次触发「读构建产物、扫配置目录、对比 lockfile」等动作；若工具层默认放行，任何提示词注入或插件供应链抖动，都可能把读取范围从 ~/Projects/foo 悄悄扩大到 ~/.ssh、浏览器配置或企业内网凭据文件。5.3 以前你只能靠事后日志与人工 code review 去猜「当时到底读了什么」；5.3 起，拒绝是基线、允许是例外，并把每次解析后的真实路径写进审计事件，降低合规与内审成本。
默认拒绝：未出现在白名单前缀表中的路径，file_fetch 直接返回结构化错误码，而不是模糊超时，便于值班脚本分流。
目录枚举边界：dir_fetch 需显式声明最大深度与可接受扩展名集合，避免「为了找 package.json 把整个 home 扫一遍」的隐性 DoS。
符号链接与挂载点：审计必须记录解析后 canonical path；遇到跨卷挂载或循环链接时，工具应短路并打标 SYMLINK_ESCAPE 类事件。
配对节点：跨机器拉取时，除白名单外还要校验对端节点指纹与一次性 pairing token，防止「同一配置文件被复制到另一台租机后继续生效」的误用。
与 SecretRef 协同：文件工具不负责解密 SecretRef，但若路径白名单与 exec 工作目录不一致，仍会出现「工具可读、运行时不可解析」的假阴性——需要与 SecretRef 审计清单合并评审。
远程 Mac 特有问题：租用节点上常有多用户、多 Gateway 实例、不同 launchd 标签；若 SSH 会话与 VNC 会话用户不一致，你会看到「配置已改但工具仍按旧白名单缓存工作」的错觉，验收必须强制同用户交叉。
| 场景 | 仅 SSH | SSH + 同用户 VNC | 配对节点额外价值 |
|---|---|---|---|
| 改白名单 JSON 并 reload | 足够 | 推荐交叉核对 UI 缓存 | 不涉及 |
| 验证 Gateway 工具面板拒绝语义 | 易漏（无浏览器同源上下文） | 推荐 | 不涉及 |
| 跨租机从 CI 产物目录拉 zip | 可写脚本 | 核对拖拽路径与真实 cwd | 必须：指纹 + token |
| 多项目同机隔离 | 依赖 umask 与独立 HOME | 目视确认 Finder 侧根目录 | 每项目独立 pairing profile |
| 审计导出给内审 | grep 审计文件 | 截屏工具面板「拒绝样例」 | 附对端节点 ID |
这张表的目的不是「SSH 不好」，而是避免你把配置正确性与交互层缓存一致性混在同一张工单里：前者可以自动化，后者在远程桌面场景里往往要靠 VNC 目视一次就省掉两小时扯皮。
文件类工具的 bug 很少表现为「进程挂了」，更多表现为「读了你以为没读的文件」——所以默认拒绝比任何事后告警都便宜。
冻结与备份：导出 OPENCLAW_HOME（或等价目录）、当前 openclaw --version、Gateway 与 CLI 互证截图；远程节点在工单首行写租约 ID 与主机指纹。
升级到 5.3 并 doctor：关注发行说明中「文件工具默认拒绝」迁移提示；若从 5.2 跳变，先对照 Breaking 升级文检查备份顺序是否冲突。
建立最小白名单：仅为 CI 产物目录、单一 monorepo 根、以及明确需要的 package.json / pyproject.toml 路径添加前缀；禁止一上来就放行 / 或 ~ 全文。
配置 dir_fetch 边界：设置 maxDepth、单目录最大条目数、可接受扩展名；对 node_modules 与构建缓存目录默认建议显式排除而不是依赖深度截断。
启用配对节点（若需要跨机）：在双方节点生成 pairing profile，交换公钥指纹；为每个 profile 绑定只读或读写能力与独立 token 滚动策略。
Gateway 会话烟测：在测试会话里分别触发「应拒绝路径」与「应允许路径」，核对返回码、审计 JSON 行与 UI 工具提示是否一致。
与 5.7 插件链对齐（若已升 5.7）：文件类插件若经 ClawHub 安装，发布后按 5.7 文做一次 semver 矩阵截图，避免「插件版本新、但内置 file_fetch 策略仍是旧默认」的半升级状态。
回滚证明：保留升级前后白名单 diff、三段审计样例（拒绝 / 允许 / 符号链接逃逸），写入工单附件，便于与 灰度与回滚文衔接。
openclaw --version openclaw doctor openclaw tools list | rg -n "file_fetch|dir_fetch" openclaw audit tail --since 15m | rg -n "PATH_DENIED|SYMLINK_ESCAPE|PAIRING"
上述命令里的子命令名称应以你实际安装版本 CLI 为准；若 doctor 提示弃用字段，请优先以发行说明中的迁移表替换，而不是在社交平台上复制过期的 YAML 片段。
| 核对项 | VNC 侧证据 | SSH 侧证据 | 通过标准 |
|---|---|---|---|
| 工具面板「拒绝」提示 | 录屏 10 秒 + 路径展示 | 审计 JSON 含 PATH_DENIED | 文案与错误码一致 |
| 允许路径读取 | 拖拽文件到测试会话 | 审计 canonical path 命中白名单 | 无越权前缀 |
| 符号链接探针 | 手工造一条指向白名单外的 symlink | SYMLINK_ESCAPE 或等价事件 | 工具未静默跟随 |
| 配对节点握手 | （可选）对端控制台一次成功 icon | PAIRING_OK 与指纹匹配 | token 单次使用策略生效 |
| Gateway 与 CLI 版本 | 关于页脚注 | openclaw --version | 与 5.3 发行矩阵一致 |
验收表刻意要求「短录屏」而不是长文档，是因为文件类回归在远程团队里最常见的争议点是「当时 UI 到底提示了什么」；10 秒带路径的录屏往往比两千字说明更快终结责任归属。
若你还在并行验证 5.6 的 Fetch 元数据与 Gateway 超时，请把「网络拉取」与「本地读盘」分两张子表记录证据包，避免在排障时把 DNS 抖动误判为白名单失效。
对于需要在远程节点上长期保留构建缓存的团队，建议把缓存目录放在独立卷或子卷并在白名单里用显式挂载点路径登记；这样当运维执行磁盘清理脚本时，审计仍能通过卷 ID 对齐历史路径，减少「路径被移动后白名单看似失效」的噪声工单。
若你受企业出站代理影响，仍应保留 出站代理文作为并行证据包；文件工具默认拒绝不会自动修复「拉不到远端制品」的网络问题，但能让失败模式从「静默读错文件」变成「显式拒绝或显式网络错误」。
本文不覆盖剪贴板与用户工程目录的边界——那类能力与主题 29 系列长文更贴近；此处专注显式文件路径工具链与配对节点。
ClawHub 校验与发布后版本矩阵。
阅读 →凭据解析与 exec 路径一致性。
阅读 →工作目录与 API Key 分环境。
阅读 →把风险前移到白名单评审；拒绝路径返回结构化错误码，便于自动化分流与内审抽样。
白名单约束本机可见目录；配对节点约束跨机关系与指纹，两者叠加覆盖跨仓库拉取。
配置与审计 tail 可 SSH；工具面板与拖拽试验建议同用户 VNC 交叉，避免 UI 缓存假阴性。
字面路径命中白名单不代表真实读盘范围安全；审计需记录 canonical path 与逃逸类事件。
v2026.5.3 在文件工具上的取舍，本质是把「Agent 能读哪里」从默契变成可审计的合同：默认拒绝、白名单、配对节点与符号链接解析，都是在压缩误读敏感文件的概率。若缺少图形化会话与同用户交叉，你很难在远程环境里证明「缓存与 UI 提示真的跟审计一致」，排障成本会迅速超过工具本身带来的效率。
自有 Mac 或自建 Runner 仍要你承担折旧、睡眠策略、办公室出口带宽以及「谁坐在屏幕前点授权」的人力调度；在可租用的远程 Apple Silicon 上，你可以把在线率与基线镜像交给服务商，同时保留对配置与密钥的控制，并把 Gateway 控制台、系统弹窗与审计 tail 放在同一桌面会话里对齐——这正是文件类安全特性最省验收时间的姿势。
若你需要一台便于完成本文第五节同款图形化验收的远程 Mac，可通过 VNCMac 下单：主按钮进入中文站购买页；连接与 SSH-VNC 说明见帮助中心。