2026-05-11 OpenClaw 工作区根路径、仓库白名单与单体仓库护栏——无头租用 Apple Silicon 云 Mac（香港 / 东京 / 首尔 / 新加坡 / 美国）
无头网关在工具走出你本想编辑的仓库之前，几乎都是「隐形」的。在香港、东京、首尔、新加坡与美国租用的 Mac mini M4 主机上，同一 UID 往往同时承载 OpenClaw、xcodebuild 车道与长期存在的签名素材——因此「工作区」是一项安全属性，而不是氛围感。这份 2026-05-11 手册把 文件传输路径策略、launchd 环境变量与密钥卫生、会话 checkpoint 纪律 与 并行车道隔离 串联成明确的白名单根路径、解析后的符号链接，以及当助手伸向 ~/Library 或相邻 CI 目录时必须失败闭合的演练。
为何工作区护栏决定共享租用主机上的爆炸半径
错误划定根路径，会把看似无害的文件读取变成「钥匙串邻域」惊吓：模型跟随相对路径、shell 在 launchd 下对 ~ 的展开与交互式会话不一致，或陈旧符号链接从「已授权」子树指向另一租户的检出目录。生产网关因此发布文件系统的正向清单——绝不能只依赖「模型的常识」。将这些清单与自动化工单绑定：每次合并基础设施配置时，同时审查 OpenClaw 策略文件与相邻 CI 封装脚本。
结构：OPENCLAW_STATE_DIR、CI 检出与 DerivedData 邻接
将助手的持久状态视为数据面存储：既不要与临时的 /tmp 克隆放在一起，也不要与 Xcode DerivedData 这类会被清理任务中途删掉的树相邻。文档化三个环——状态环（checkpoint 与策略文件）、工作区环（你授权的 git 根）、草稿环（可丢弃的导出）——并确保清理 cron 尊重环边界。当 CI 与助手共享 UID 时，遵循并行车道文章中的隔离指引，避免竞态导致锁文件悬空。
- 状态环 —— 白名单的版本化片段 + 适用时的密封 JSON。
- 工作区环 —— 每个仓库/业务线一个或多个绝对根路径。
- 草稿环 —— 位于按作业前缀划分的 TMP 下的带 TTL 目录。
与文件传输及 shell 工具策略联动的白名单
2026-05-07 的文件传输插件默认偏向拒绝；工作区根应镜像这些默认，使 fetch/列目录无法沿符号链接跳到仅因符号链接跳跃才存在的父目录。按环境（staging 与 prod）编码根路径，并二者都保留在 Git 中——运维通过 PR 晋升，而不是临时 SSH 改文件。团队在单体仓库中嵌入多个微服务时，按包划分命名空间根，防止伪装成「随便看看」的跨服务读取。
readlink -f 扫描；APFS firmlink 与企业 VPN 挂载可能在不改磁盘上配置文本的情况下改道路径。
单体仓库边界：SwiftPM 嵌套、Xcode workspace 与 git 子模块
大型单体仓库对助手暴露多个 Package.swift 清单与混合 Xcode 工程。若团队对所有权边界有分歧，应分别钉死根路径——例如 /build/mobile/ios 与 /platform/android——除非存在第二条白名单项，否则禁止横向跳跃。子模块目录仅在通过安全评审时继承父级授权；否则将嵌套的 .git 目录视为需更窄范围的显式根。
# 批准新根之前解析符号链接
/usr/bin/python3 - <<'PY'
import os
roots = ["/var/ci/job123/acme"]
for r in roots:
print(os.path.realpath(r))
PY
CI 与交互式助手并存时的检出位置
临时 CI 常把仓库克隆到 /var/tmp 下带哈希的目录，或自定义工作卷；经 SSH 启动的助手可能默认使用 ~/workspace。统一约定：按区域导出 ASSISTANT_WORKSPACE_ROOT，并教导编排器只把检出挂载在已授权前缀之下。当 GitHub Actions 自托管标签与 OpenClaw 路由到同一台 Mac 时，强制使用不同路径，避免 PR 清理与助手相关草稿并发删除。
launchd：向非交互网关导出根路径
交互式 shell 会加载 profile 片段；守护进程不会。将白名单镜像到 plist 的 EnvironmentVariables 或带校验和的引用 env 文件。在更新后通过受控的 launchctl kickstart 重载网关，并按 健康探测 指引采集 stdout——同时验证 HTTP 就绪与针对禁用路径的文件系统探测。
决策矩阵：路径意图 vs 执行层
| 场景 | 风险 | 首选缓解 |
|---|---|---|
助手读取仓库并跟踪 ../ |
逃逸到相邻服务的密钥 | 正向前缀校验 + 归一化后拒绝 .. 段 |
| 指向桌面/文稿的符号链接 | 无头与 GUI 场景下 TCC 预期不同 | 解析符号链接目标；对照 macOS 隐私文档交叉检查 |
| 共享 UID 的 CI 与助手 | 重叠目录上的删除竞态 | 按编排 ID 划分独立的 TMPDIR 命名空间 |
| 紧急热修分支 | 临时放宽白名单却无回滚计划 | 带时限的白名单工单 + 自动到期 |
工作区治理的八步上线
- 通过审计日志清点过去 30 天内助手接触过的每个文件系统路径。
- 编码最小白名单；扩大范围需 VPEng + 安全评审。
- 将策略合并入 Git；将校验和附加到自动化发布包。
- 按区域部署 plist/env 更新并配合健康 curl。
- 运行脚本化拒绝测试，覆盖符号链接逃逸。
- 培训值班人员快速回滚白名单 PR。
- 让清理脚本与草稿 TTL 合同对齐。
- 每季度发布回顾指标，比较拒绝与允许操作的比例。
工作区治理的 SLO 信号
| 信号 | 阈值 | 动作 |
|---|---|---|
| 未批准路径尝试 | 每网关每周 > 3 次 | 冻结配置变更；回放事故追踪 |
| 白名单相对 Git 漂移 | 任意未发布的手改 | 回滚主机；强制仅 PR 工作流 |
| 符号链接审计失败 | 关键发现 > 0 | 阻断发布；重建解析根映射 |
常见问题
| 问题 | 实务答复（2026-05-11） |
|---|---|
根路径是否应整段包含 /Users/ci？ |
否——按流水线或租户切片；整段根会抵消白名单意义。 |
| 助手能否在工作区外写入缓存？ | 仅能在声明的草稿前缀内，并配配额与自动驱逐。 |
为何 Mac mini M4 租用有利于文件系统治理
高速 NVMe 与可预期的统一内存让你在 symlink 审计、三仓库并行克隆与网关健康检查同时运行时不必把交换推到极限——这在事故迭代白名单时很重要。通过 定价页 按区域规划容量；在扩大根路径之前，先把把握不准的同事导向 SSH/VNC 指南。
