快速开始
安全文件操作
OpenClaw 使用 @openclaw/fs-safe 来处理安全敏感的本地文件操作：受根目录边界约束的读写、原子替换、归档解压、临时工作区、JSON 状态以及密钥文件处理。
目标是为接收不受信任路径名的可信 OpenClaw 代码提供一致的库级防护边界。它不是沙箱。主机文件系统权限、操作系统用户、容器以及智能体/工具策略仍然定义真正的影响范围。
默认：不使用 Python 辅助程序
OpenClaw 默认将 fs-safe POSIX Python 辅助程序设为关闭。
原因：
- Gateway 网关 不应启动持久 Python 辅助进程，除非操作员明确选择启用；
- 许多安装不需要额外的父目录变更加固；
- 禁用 Python 可让包/运行时行为在桌面、Docker、CI 和内置应用环境中更可预测。
OpenClaw 只更改默认值。如果你显式设置模式，fs-safe 会遵循该设置：
# Default OpenClaw behavior: Node-only fs-safe fallbacks.
OPENCLAW_FS_SAFE_PYTHON_MODE=off
# Opt into the helper when available, falling back if unavailable.
OPENCLAW_FS_SAFE_PYTHON_MODE=auto
# Fail closed if the helper cannot start.
OPENCLAW_FS_SAFE_PYTHON_MODE=require
# Optional explicit interpreter.
OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3
通用 fs-safe 名称也可使用：FS_SAFE_PYTHON_MODE 和 FS_SAFE_PYTHON。
没有 Python 时仍受保护的内容
在辅助程序关闭时，OpenClaw 仍使用 fs-safe 的 Node 路径来：
- 拒绝相对路径逃逸，例如
..、绝对路径，以及在只允许名称的位置出现路径分隔符； - 通过可信根句柄解析操作，而不是使用临时的
path.resolve(...).startsWith(...)检查； - 在要求该策略的 API 上拒绝符号链接和硬链接模式；
- 在 API 返回或消费文件内容时，以身份检查方式打开文件；
- 对状态/配置文件执行原子同级临时文件写入；
- 对读取和归档解压设置字节限制；
- 在 API 要求时，对密钥和状态文件使用私有模式。
这些保护覆盖了常规 OpenClaw 威胁模型：可信 Gateway 网关代码在单一可信操作员边界内处理不受信任的模型/插件/渠道路径输入。
Python 增加了什么
在 POSIX 上，fs-safe 的可选辅助程序会保留一个持久 Python 进程，并对父目录变更使用相对于 fd 的文件系统操作，例如 rename、remove、mkdir、stat/list，以及部分写入路径。
这会缩小同 UID 竞态窗口，避免另一个进程在验证与变更之间替换父目录。对于不受信任的本地进程可以修改 OpenClaw 正在操作的相同目录的主机，这是深度防御。
如果你的部署存在这种风险且可以保证 Python 存在，请使用：
OPENCLAW_FS_SAFE_PYTHON_MODE=require
当辅助程序属于你的安全态势的一部分时，请使用 require 而不是 auto；如果辅助程序不可用，auto 会有意回退到仅 Node 行为。
插件和核心指南
- 面向插件的文件访问应通过
openclaw/plugin-sdk/*辅助函数进行，而不是原始fs，前提是路径来自消息、模型输出、配置或插件输入。 - 核心代码应使用
src/infra/*下的本地 fs-safe 包装器，以便一致应用 OpenClaw 的进程策略。 - 归档解压应使用 fs-safe 归档辅助函数，并显式设置大小、条目数量、链接和目标位置限制。
- 密钥应使用 OpenClaw 密钥辅助函数或 fs-safe 密钥/私有状态辅助函数；不要围绕
fs.writeFile手写模式检查。 - 如果你需要抵御恶意本地用户的隔离，不要只依赖 fs-safe。请在不同操作系统用户/主机下运行独立 Gateway 网关，或使用沙箱隔离。