合理配置 OpenClaw 的 fs-safe 文件安全策略，防止未授权的本地文件访问。默认情况下 OpenClaw 关掉了 fs-safe 的 Python 辅助进程，仅靠 Node.js 侧也能防御路径遍历、符号链接和父目录竞争攻击。如果你需要更强的同 UID 目录竞争防护，可以设置环境变量 OPENCLAW_FS_SAFE_PYTHON_MODE=require 强制启用 Python helper。使用 openclaw/plugin-sdk/* 辅助方法替代裸 fs 调用，可让安全策略自动生效。

OpenClaw fs-safe 文件安全操作：配置与原理

OpenClaw 使用 @openclaw/fs-safe 库处理本地文件读写、原子替换、压缩包解压、临时工作区、JSON 状态和机密文件等敏感操作。

这套库的目的是给信任的 OpenClaw 代码提供一个一致的访问护栏，确保即便收到不可信的路径名称也不会绕过规则。但它不是沙箱（sandbox）。宿主机的文件系统权限、操作系统用户、容器隔离、以及智能体/工具的策略仍然决定了真实的影响范围。

默认关闭 Python helper

OpenClaw 默认把 fs-safe 的 POSIX Python helper 设置为 关闭。

原因：

• 网关不应该自动启动一个持久的 Python 侧进程，除非运维人员主动启用；
• 很多部署场景并不需要额外的父目录变异保护；
• 关闭 Python 后，在桌面、Docker、CI 和打包应用环境中的运行时行为更可预测。

OpenClaw 只改了默认值。如果你显式设定了模式，fs-safe 会遵守：

# OpenClaw 默认行为：只用 Node.js 侧的 fs-safe 回退方案
OPENCLAW_FS_SAFE_PYTHON_MODE=off

# 当 helper 可用时启用，不可用时自动回退
OPENCLAW_FS_SAFE_PYTHON_MODE=auto

# 如果 helper 无法启动则报错关闭（fail closed）
OPENCLAW_FS_SAFE_PYTHON_MODE=require

# 可选：指定 Python 解释器路径
OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

通用 fs-safe 环境变量名也有效：FS_SAFE_PYTHON_MODE 和 FS_SAFE_PYTHON。

不启用 Python helper 时有哪些保护措施

即使关了 Python helper，OpenClaw 仍然使用 fs-safe 的 Node.js 层提供以下保护：

• 拒绝相对路径逃逸，例如 ..、绝对路径、以及只允许名称时出现的路径分隔符；
• 通过信任的根句柄（root handle）解析操作，而不是手写 path.resolve(...).startsWith(...) 检查；
• 在要求严格策略的 API 上拒绝符号链接和硬链接模式；
• 打开文件时做身份检查（identity checks），适用于 API 返回或消费文件内容的场景；
• 对状态/配置文件做原子级同临时目录写入；
• 对读取和解压操作设定字节数限制；
• 在需要私密模式的 API 中，为机密文件和状态文件使用私有文件模式。

这些保护覆盖了 OpenClaw 的正常威胁模型：信任的网关代码处理不可信的模型/插件/渠道路径输入，且运行在单一信任的运维人员边界内。

Python helper 增强了什么

在 POSIX 系统上，fs-safe 的可选 helper 会保持一个持久 Python 进程，并通过基于文件描述符（fd）的文件系统操作来处理父目录变异，例如重命名、删除、创建目录、状态/列表，以及部分写入路径。

这能缩小同一 UID 下的竞态窗口（race window）——其他进程有机会在验证和写入之间替换父目录。对于宿主机上存在不可信本地进程且这些进程可能修改 OpenClaw 正在操作的目录时，这套机制是深度防御手段。

如果你的部署存在上述风险，并且 Python 确保可用，请使用：

OPENCLAW_FS_SAFE_PYTHON_MODE=require

当 Python helper 是你安全策略的一部分时用 require 而非 auto。auto 会在 helper 不可用时主动回退到纯 Node.js 行为。

插件和核心代码安全建议

• 插件相关的文件访问：如果路径来自消息、模型输出、配置或插件输入，应通过 openclaw/plugin-sdk/* 辅助方法，不要直接使用裸 fs。
• 核心代码：应使用 src/infra/* 下的 fs-safe 包装器，确保 OpenClaw 的进程策略一致生效。
• 压缩包解压：使用 fs-safe 的归档辅助方法，并显式设置大小、条目数、链接和目标目录限制。
• 机密文件：使用 OpenClaw 的机密辅助方法或 fs-safe 的 secret/private-state 辅助方法，不要手动编写 fs.writeFile 模式检查。
• 需要隔离不信任的本地用户时，不要只依赖 fs-safe。应使用不同的 OS 用户/宿主机运行多个网关，或者使用沙箱方案。

延伸阅读：安全、沙箱、执行审批、机密管理。

常见问题

fs-safe 的路径逃逸防御在 Windows 上有效吗？

有效。fs-safe 的 Node.js 层在 Windows 上同样拒绝 ..、绝对路径和非法路径分隔符，但父目录竞态防护（Python helper）仅在 POSIX 系统生效。

为什么 OpenClaw 默认把 Python helper 关掉，而不是设为 auto？

为了让依赖行为更可预测。很多部署场景（Docker、CI、桌面应用）没有 Python 或 Python 版本不确定，默认关闭可避免意外回退导致的不可见行为差异。

我需要开启 fs-safe Python helper 来抵御所有攻击吗？

不需要。fs-safe 本身不是隔离方案。如果运行环境中存在不可信本地进程，应配合容器、沙箱或 OS 用户隔离使用。Python helper 仅在你想防御同 UID 目录竞态时才必要。