Secure file operations

Secure file operations 문서는 OpenClaw 공식 문서(gateway/security/secure-file-operations)를 한국어로 정리한 가이드입니다. How OpenClaw handles local file access safely, and why the optional fs-safe Python helper is off by default 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

How OpenClaw handles local file access safely, and why the optional fs-safe Python helper is off by default

한국어 가이드 범위: gateway/security/secure-file-operations 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Default: no Python helper
Default OpenClaw behavior: Node-only fs-safe fallbacks.
Opt into the helper when available, falling back if unavailable.
Fail closed if the helper cannot start.
Optional explicit interpreter path.
What stays protected without Python
What Python adds
Plugin and core guidance

상세 내용

본문

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.

Default: no Python helper

OpenClaw sets the fs-safe POSIX Python helper to off by default:

주요 항목:

the gateway should not spawn a persistent Python sidecar unless an operator opts in;
most installs do not need the extra parent-directory mutation hardening;
disabling Python keeps runtime behavior predictable across desktop, Docker, CI, and bundled-app environments.

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 path.

OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3 ```

What stays protected without Python

With the helper off, OpenClaw still gets fs-safe's Node-only guardrails:

주요 항목:

rejects relative-path escapes (..), absolute paths, and path separators where only bare names are allowed;
resolves operations through a trusted root handle instead of ad-hoc path.resolve(...).startsWith(...) checks;
refuses symlink and hardlink patterns on APIs that require that policy;
opens files with identity checks where the API returns or consumes file contents;
writes state/config files via atomic sibling-temp + rename;
enforces byte limits for reads and archive extraction;
applies private file modes for secrets and state files where the API requires them.

What Python adds

On POSIX, the optional helper keeps one persistent Python process and uses fd-relative filesystem operations for parent-directory mutations: rename, remove, mkdir, stat/list, and some write paths.

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Plugin and core guidance

주요 항목:

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 fs-safe wrappers under src/infra/* so OpenClaw's process policy applies 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.
For hostile local-user isolation, do not rely on fs-safe alone. Run separate gateways under separate OS users/hosts, or use sandboxing.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/security/secure-file-operations
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

# 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 path.
OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Secure file operations

핵심 요약

How OpenClaw handles local file access safely, and why the optional fs-safe Python helper is off by default

한국어 가이드 범위: gateway/security/secure-file-operations 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Default: no Python helper
Default OpenClaw behavior: Node-only fs-safe fallbacks.
Opt into the helper when available, falling back if unavailable.
Fail closed if the helper cannot start.
Optional explicit interpreter path.
What stays protected without Python
What Python adds
Plugin and core guidance

상세 내용

본문

Default: no Python helper

OpenClaw sets the fs-safe POSIX Python helper to off by default:

주요 항목:

the gateway should not spawn a persistent Python sidecar unless an operator opts in;
most installs do not need the extra parent-directory mutation hardening;
disabling Python keeps runtime behavior predictable across desktop, Docker, CI, and bundled-app environments.

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 path.

OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3 ```

What stays protected without Python

With the helper off, OpenClaw still gets fs-safe's Node-only guardrails:

주요 항목:

rejects relative-path escapes (..), absolute paths, and path separators where only bare names are allowed;
resolves operations through a trusted root handle instead of ad-hoc path.resolve(...).startsWith(...) checks;
refuses symlink and hardlink patterns on APIs that require that policy;
opens files with identity checks where the API returns or consumes file contents;
writes state/config files via atomic sibling-temp + rename;
enforces byte limits for reads and archive extraction;
applies private file modes for secrets and state files where the API requires them.

What Python adds

On POSIX, the optional helper keeps one persistent Python process and uses fd-relative filesystem operations for parent-directory mutations: rename, remove, mkdir, stat/list, and some write paths.

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Plugin and core guidance

주요 항목:

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 fs-safe wrappers under src/infra/* so OpenClaw's process policy applies 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.
For hostile local-user isolation, do not rely on fs-safe alone. Run separate gateways under separate OS users/hosts, or use sandboxing.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/security/secure-file-operations
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

# 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 path.
OPENCLAW_FS_SAFE_PYTHON=/usr/bin/python3

OPENCLAW_FS_SAFE_PYTHON_MODE=require

Secure file operations

핵심 요약

문서 구성

상세 내용

본문

Default: no Python helper

Default OpenClaw behavior: Node-only fs-safe fallbacks.

Opt into the helper when available, falling back if unavailable.

Fail closed if the helper cannot start.

Optional explicit interpreter path.

What stays protected without Python

What Python adds

Plugin and core guidance

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Secure file operations

핵심 요약

문서 구성

상세 내용

본문

Default: no Python helper

Default OpenClaw behavior: Node-only fs-safe fallbacks.

Opt into the helper when available, falling back if unavailable.

Fail closed if the helper cannot start.

Optional explicit interpreter path.

What stays protected without Python

What Python adds

Plugin and core guidance

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드