安全文件操作

OpenClaw 使用 @openclaw/fs-safe 执行安全敏感的本地文件操作：限定在根目录内的读写、原子替换、归档提取、临时工作区、JSON 状态和机密文件处理。

它是供可信 OpenClaw 代码接收不可信路径名时使用的库级防护措施，而不是沙箱。主机文件系统权限、操作系统用户、容器以及智能体/工具策略仍决定实际影响范围。

默认：不使用 Python 辅助程序

OpenClaw 默认将 fs-safe 的 POSIX Python 辅助程序设为关闭：

• 除非操作员主动启用，否则 Gateway 网关不应生成持久的 Python 边车进程；
• 大多数安装不需要额外的父目录变更加固；
• 禁用 Python 可使桌面、Docker、CI 和内置应用环境中的运行时行为保持可预测。

OpenClaw 仅更改_默认值_。显式设置始终优先：

# OpenClaw 默认行为：仅使用 Node 的 fs-safe 回退机制。OPENCLAW_FS_SAFE_PYTHON_MODE=off # 在辅助程序可用时启用，不可用时回退。OPENCLAW_FS_SAFE_PYTHON_MODE=auto # 如果辅助程序无法启动，则以关闭方式失败。OPENCLAW_FS_SAFE_PYTHON_MODE=require # 可选的显式解释器路径。OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

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

当辅助程序属于你的安全防护体系时，请使用 require（而不是 auto）；如果辅助程序无法启动，auto 会静默回退到仅使用 Node 的行为。

不使用 Python 时仍有哪些保护

关闭辅助程序后，OpenClaw 仍可获得 fs-safe 仅使用 Node 的防护措施：

• 拒绝相对路径逃逸（..）、绝对路径，以及在仅允许纯名称的位置出现路径分隔符；
• 通过可信根目录句柄解析操作，而不是临时进行 path.resolve(...).startsWith(...) 检查；
• 对于要求实施相应策略的 API，拒绝符号链接和硬链接模式；
• 当 API 返回或使用文件内容时，通过身份检查打开文件；
• 通过同级临时文件加重命名的原子方式写入状态/配置文件；
• 对读取和归档提取实施字节数限制；
• 在 API 要求时，对机密文件和状态文件应用私有文件模式。

这涵盖了 OpenClaw 的常规威胁模型：可信 Gateway 网关代码在单一可信操作员边界内处理来自不可信模型、插件或渠道的路径输入。

Python 增加的保护

在 POSIX 上，可选辅助程序会保持一个持久的 Python 进程，并使用相对于文件描述符的文件系统操作执行父目录变更：重命名、删除、创建目录、获取状态/列出内容，以及部分写入路径。

在其他进程可于验证和变更之间替换父目录时，这会缩小同一 UID 下的竞态窗口——对于不可信本地进程能够修改 OpenClaw 所操作的相同目录的主机，这是一项纵深防御措施。

如果你的部署存在这种风险，并且能够保证 Python 可用，请设置：

OPENCLAW_FS_SAFE_PYTHON_MODE=require

插件和核心指南

• 当路径来自消息、模型输出、配置或插件输入时，面向插件的文件访问应通过 openclaw/plugin-sdk/* 辅助函数进行，而不是直接使用 fs。
• 核心代码应使用 src/infra/* 下的 fs-safe 封装器，以便一致应用 OpenClaw 的进程策略。
• 归档提取应使用 fs-safe 归档辅助函数，并明确设置大小、条目数、链接和目标位置限制。
• 机密信息应使用 OpenClaw 机密信息辅助函数，或 fs-safe 的机密信息/私有状态辅助函数；不要围绕 fs.writeFile 自行实现模式检查。
• 如需隔离恶意本地用户，请勿仅依赖 fs-safe。应在不同操作系统用户/主机下运行独立的 Gateway 网关，或使用沙箱隔离。

相关内容：安全、沙箱隔离、Exec 审批、机密信息。