Secure file operations：总控室这一层在盯什么

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：OpenClaw uses @openclaw/fs-safe for 安全守门员-sensitive local file operations: root-bounded reads/writes, atomic replacemen…。

OpenClaw uses @openclaw/fs-safe for security-sensitive local file operations: root-bounded reads/writes, atomic replacement, archive extraction, temp workspaces, JSON state, and secret-file handling.

The goal is a consistent **library guardrail** for trusted OpenClaw code that receives untrusted path names. It is not a sandbox. Host filesystem permissions, OS users, containers, and the agent/tool policy still define the real blast radius.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：OpenClaw defaults the fs-safe POSIX Python helper to **off**. Why: OpenClaw only changes the default. If you explicitly…。

OpenClaw defaults the fs-safe POSIX Python helper to **off**.

Why:

• the gateway should not spawn a persistent Python sidecar unless an operator opted into it;
• many installs do not need the extra parent-directory mutation hardening;
• disabling Python keeps package/runtime behavior more predictable across desktop, Docker, CI, and bundled app environments.

OpenClaw only changes the default. If you explicitly set a mode, fs-safe honors it:

# 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

The generic fs-safe names also work: FS_SAFE_PYTHON_MODE and FS_SAFE_PYTHON.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：With the helper off, OpenClaw still uses fs-safe's Node paths for: These protections cover the normal OpenClaw threat 聪…。

With the helper off, OpenClaw still uses fs-safe's Node paths for:

• rejecting relative-path escapes such as .., absolute paths, and path separators where only names are allowed;
• resolving operations through a trusted root handle instead of ad-hoc path.resolve(...).startsWith(...) checks;
• refusing symlink and hardlink patterns on APIs that require that policy;
• opening files with identity checks where the API returns or consumes file contents;
• atomic sibling-temp writes for state/config files;
• byte limits for reads and archive extraction;
• private modes for secrets and state files where the API requires them.

These protections cover the normal OpenClaw threat model: trusted gateway code handling untrusted model/plugin/channel path input inside a single trusted operator boundary.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：On POSIX, fs-safe's optional helper keeps one persistent Python process and uses fd-relative filesystem operations for…。

On POSIX, fs-safe's optional helper keeps one persistent Python process and uses fd-relative filesystem operations for parent-directory mutations such as rename, remove, mkdir, stat/list, and some write paths.

That narrows same-UID race windows where another process can swap a parent directory between validation and mutation. It is defense in depth for hosts where untrusted local processes can modify the same directories OpenClaw is operating in.

If your deployment has that risk and Python is guaranteed to exist, use:

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Use require rather than auto when the helper is part of your security posture; auto intentionally falls back to Node-only behavior if the helper is unavailable.

如果把这一段摆成一个小场景，你会看到几样东西正在互相打招呼、拦路或者传东西。别急着记名词，先抓住它此刻到底在发生什么：Related: 安全守门员, Sandboxing, Exec approvals, Secrets. ---。

• Plugin-facing file access should go through openclaw/plugin-sdk/* helpers, not raw fs, when a path comes from a message, model output, config, or plugin input.
• Core code should use the local fs-safe wrappers under src/infra/* so OpenClaw's process policy is applied consistently.
• Archive extraction should use the fs-safe archive helpers with explicit size, entry-count, link, and destination limits.
• Secrets should use OpenClaw secret helpers or fs-safe secret/private-state helpers; do not hand-roll mode checks around fs.writeFile.
• If you need hostile local-user isolation, do not rely on fs-safe alone. Run separate gateways under separate OS users/hosts or use sandboxing.

Related: Security, Sandboxing, Exec approvals, Secrets.

---