OpenClaw는 보안에 민감한 로컬 파일 작업에Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
@openclaw/fs-safe를 사용합니다. 여기에는 루트 경계 읽기/쓰기, 원자적 교체, 아카이브 추출, 임시 워크스페이스, JSON 상태, 비밀 파일 처리가 포함됩니다.
목표는 신뢰할 수 없는 경로 이름을 받는 신뢰할 수 있는 OpenClaw 코드에 일관된 라이브러리 가드레일을 제공하는 것입니다. 샌드박스가 아닙니다. 호스트 파일시스템 권한, OS 사용자, 컨테이너, 에이전트/도구 정책이 여전히 실제 영향 범위를 정의합니다.
기본값: Python 헬퍼 없음
OpenClaw는 fs-safe POSIX Python 헬퍼를 기본적으로 꺼짐으로 설정합니다. 이유:- Gateway는 운영자가 명시적으로 선택하지 않은 한 지속 실행되는 Python 사이드카를 생성하지 않아야 합니다.
- 많은 설치 환경에는 추가적인 상위 디렉터리 변경 강화가 필요하지 않습니다.
- Python을 비활성화하면 데스크톱, Docker, CI, 번들 앱 환경 전반에서 패키지/런타임 동작을 더 예측 가능하게 유지할 수 있습니다.
FS_SAFE_PYTHON_MODE 및 FS_SAFE_PYTHON.
Python 없이도 보호되는 항목
헬퍼가 꺼져 있어도 OpenClaw는 다음에 fs-safe의 Node 경로를 계속 사용합니다..., 절대 경로, 이름만 허용되는 위치의 경로 구분자처럼 상대 경로 이탈을 거부합니다.- 임시
path.resolve(...).startsWith(...)검사 대신 신뢰할 수 있는 루트 핸들을 통해 작업을 확인합니다. - 해당 정책이 필요한 API에서 심볼릭 링크와 하드 링크 패턴을 거부합니다.
- API가 파일 내용을 반환하거나 소비하는 경우 ID 검사와 함께 파일을 엽니다.
- 상태/구성 파일에 대해 형제 임시 파일을 사용하는 원자적 쓰기를 수행합니다.
- 읽기와 아카이브 추출에 바이트 제한을 적용합니다.
- API가 요구하는 경우 비밀과 상태 파일에 private 모드를 적용합니다.
Python이 추가하는 것
POSIX에서 fs-safe의 선택적 헬퍼는 지속 실행되는 Python 프로세스 하나를 유지하고 rename, remove, mkdir, stat/list, 일부 쓰기 경로 같은 상위 디렉터리 변경에 fd 상대 파일시스템 작업을 사용합니다. 이는 다른 프로세스가 검증과 변경 사이에 상위 디렉터리를 바꿀 수 있는 같은 UID 경합 창을 좁힙니다. 신뢰할 수 없는 로컬 프로세스가 OpenClaw가 작업 중인 동일한 디렉터리를 수정할 수 있는 호스트를 위한 심층 방어입니다. 배포 환경에 그런 위험이 있고 Python이 존재함이 보장된다면 다음을 사용하세요.auto 대신 require를 사용하세요. auto는 헬퍼를 사용할 수 없는 경우 의도적으로 Node 전용 동작으로 폴백합니다.
Plugin 및 코어 지침
- Plugin 대상 파일 접근은 경로가 메시지, 모델 출력, 구성, Plugin 입력에서 오는 경우 원시
fs가 아니라openclaw/plugin-sdk/*헬퍼를 통해 이루어져야 합니다. - 코어 코드는 OpenClaw의 프로세스 정책이 일관되게 적용되도록
src/infra/*아래의 로컬 fs-safe 래퍼를 사용해야 합니다. - 아카이브 추출은 명시적인 크기, 항목 수, 링크, 대상 제한과 함께 fs-safe 아카이브 헬퍼를 사용해야 합니다.
- 비밀은 OpenClaw 비밀 헬퍼 또는 fs-safe 비밀/private-state 헬퍼를 사용해야 합니다.
fs.writeFile주변에 모드 검사를 직접 구현하지 마세요. - 적대적인 로컬 사용자 격리가 필요하다면 fs-safe만으로는 충분하지 않습니다. 별도의 OS 사용자/호스트에서 별도의 Gateway를 실행하거나 샌드박싱을 사용하세요.