2026 OpenClaw v2026.5.3 파일 전송 플러그인:
file_fetch / file_write 경로 정책, symlink 방어, 일 단위 macOS 격리 리허설

01. 세 가지 고통 포인트

1) 루트가 너무 넓음: ~/에 대해 재귀 dir_fetch를 돌리면 쓰기가 없어도 SSH 설정·브라우저 프로필·크래시 덤프가 프롬프트로 끌려 옵니다. 명시적 허용 목록, 최대 깊이, CI와 동일한 ignore 글로브로 고치고, 사건 중 임시 제외를 추가하지 마세요.

2) 심볼릭 링크 탈출: 오염된 의존성이 저장소 안처럼 보이지만 다른 곳을 가리키는 링크를 둘 수 있습니다. v2026.5.3은 symlink 방어를 강조합니다. 편의를 위해 끄면 기록된 위험 결정이지 조용한 토글 변경이 아닙니다.

3) 리허설 호스트에 프로덕션 비밀: 살아 있는 openclaw.json을 렌탈 홈에 복사하고 file_write를 돌리면 나중에 지울 수 없는 경로가 로그에 남습니다. 마스킹된 프로필과 별도 토큰을 쓰고, 서드파티 Skills 시험처럼 와이프하세요.

MCP가 또 다른 파일 표면을 노출하면 어떤 읽기가 MCP·번들 file_*·제어된 exec인지 우선순위를 문서화하세요. 같은 경로에 세 종류의 거부 메시지가 뜨면 트리아지가 무너집니다.

02. 기능 선택 매트릭스

5분 스탠드업에서 도구를 의도적으로 고르기 위한 표입니다.

v2026.5.4 음성 스택을 함께 올릴 때는 파일 도구 탓하기 전에 IPv6 점검으로 Gateway 기동 순서를 검증하세요.

03. 7단계 리허설

1. 허용 목록 동결: 변경 리뷰에 포함, 말로만 “그냥 / 추가” 금지.
2. doctor 기준선: 업그레이드 직후 저장. 플러그인 검색·지연 로드 줄.
3. 샌드박스 트리:~/oc-file-sandbox/project에 마스킹된 클론만.
4. 이중 세션 부하: 한 세션은 dir_fetch 연타, 다른 세션은 작은 file_write 아티팩트. 큐와 디스크 관찰.
5. symlink 레드팀: 샌드박스 밖을 가리키는 링크로 거부 코드 확인.
6. 거부보내기: CSV를 티켓에 첨부.
7. 와이프: 샌드박스, 임시 토큰, 호스트를 식별할 수 있는 보낸 산출물 삭제.

mkdir -p ~/oc-file-sandbox/project && cd ~/oc-file-sandbox/project
ln -s /etc/passwd ./evil.link
# 에이전트로 file_fetch 시도, 구조화된 거부 로그 기대

여유 디스크가 16 GB 미만이면 큰 읽기에서 일시 I/O 오류가 정책 오판으로 보일 수 있습니다. 먼저 ~/Library/Logs와 오래된 DerivedData 정리. 연결은 FAQ.

브라우저 자동화와 같은 호스트를 쓰면 무거운 디렉터리 순회와 TCC 민감 UI 작업을 분리하세요. macOS 노드 권한 리허설 참고.

04. 거부 신호 표

05. 지표와 오해

• 지표 1: “파일 도구 고장” 티켓의 약 31~46%는 저장소·inode 압박이었고 정책 버그가 아니었습니다.
• 지표 2:명시 허용 목록+최대 깊이를 쓴 팀은 넓은 루트 대비 비밀 읽기 사고(및 미수)가 38~55% 감소(정책 의존).
• 지표 3: 샌드박스에서 첫 리허설을 한 프로젝트는 롤백 중앙값이 21~33% 단축.

오해 A:file_write가 더 안전하니 경로를 넓혀도 된다.오해 B: 모든 거부는 오탐.오해 C: 프로덕션 홈에서 리허설해도 된다.

정책 변경은 자동 업데이트·wrapper 창과 같은 변경 창에 넣어 반쪽짜리 Gateway 트리를 피하세요.

05b. 1~3일 리스 간트

1일차: 허용 목록 동결, doctor 기준선, 샌드박스 클론. 저녁까지 허용 루트 해시.

2일차: 이중 세션 스트레스, symlink 레드팀, 거부 CSV. CPU·디스크 피크 기록.

3일차: 프로덕션 설정에 최소 병합 후 샌드박스 삭제. 인수: 허용 목록 diff, 레드팀 목록, 거부 샘플, 병합 JSON 조각, 롤백 담당.

Compose를 쓰면 볼륨 마운트 표를 첨부해 업그레이드 후 드리프트로 정책과 실제 마운트가 어긋나지 않게 하세요.

06. Linux 점프 vs 일 단위 Mac

Linux 점프호스트의 rsync는 저렴하지만 Apple FS 의미·Keychain 인접 워크플로·Finder 수준 권한 확인까지 필요하면 숨은 비용이 큽니다. 리허설 기간에 비용을 맞추려면 일 단위 네이티브 macOS가 낫습니다. 요금: Mac mini M4 요금 가이드. 위생: 무잔류 5단계.

07. 지연 로딩과 타임아웃

v2026.5.3은 플러그인 검색·cron·스키마를 지연 로드해 콜드 스타트를 줄입니다. 기동 직후 file_fetch 폭주는 레지스트리 미완성과 겹칠 수 있으니 기동 후 30·60·120초 로그를 모은 뒤 경로를 넓힐지 결정하세요.

본 트래픽 전에 file_fetch 등록을 확인하는 헬스 프로브를 두고, 프로브는 스테이징이나 렌탈에만.

메인 채팅 큐를 지키려면 무거운 디렉터리 순회는 sessions_spawn 자식 컨텍스트로 넘기세요.

08. MCP 공존과 우선순위

MCP 파일 서버와 번들 file_*가 함께 있으면 README에 우선순위 매트릭스를 게시하고 티켓에도 복사하세요. 없으면 같은 경로에 세 가지 거부 형식이 날아 운영이 길을 잃습니다.

원격 인증·스트리밍 때문에 MCP에만 남길 작업과 localhost 지연을 위해 file_*로 옮길 작업을 구분해 적으세요.

09. CI 산출물 정책 정렬

CI가 .zip/.tar.zst만 배포하는데 에이전트가 서명 없는 .dmg를 file_write하면 공증·배포 게이트에서 거절됩니다. 바이트 이동만으로 컴플라이언스 소유권은 바뀌지 않습니다.

확장자 허용 목록을 CI와 Gateway policy JSON에 맞춰 “파이프라인 OK·어시스턴트 NG” 분열을 막으세요.

10. 티켓 템플릿

활성 프로필, 허용 루트, symlink 모드, Gateway 버전, 여유 디스크 GB, MCP 파일 도구 사용 여부를 나열하고 거부 CSV와 리허설 호스트 이름을 링크하세요.

롤백 줄에 JSON을 되돌릴 담당과 필요 시 OPENCLAW_NO_AUTO_UPDATE로 Gateway를 재시작할 담당을 적습니다.

11. 성능 가드레일

세션당 동시 dir_fetch 작업 수를 제한하고, UI 요약용 목록은 반환 행 상한을 둡니다. 렌탈 호스트 I/O 지표와 함께 보면 포화와 정책을 분리할 수 있습니다.

모노레포 색인은 개발자 머신과 같은 ignore 규칙을 써서 한 에이전트가 전체 히스토리 저장소를 걷지 않게 하세요.

12. 머지 후 재점검

머지 30일 후 doctor와 짧은 symlink 레드팀을 다시 돌려 무관 업그레이드로 생긴 정책 드리프트를 잡으세요. policy JSON 해시를 git에 두고 사후 분석에서 비교합니다.

실험이 성공해도 리허설 토큰은 교체하고, 렌탈 장비는 장수명 자격증명 없이 풀로 반환하세요.

13. 오염 워크스페이스 위협 모델

클론한 저장소의 postinstall이 symlink나 숨은 dotfile로 민감 위치를 겨냥할 수 있다고 가정하세요. 레드팀 날에는 /etc/passwd뿐 아니라 중첩 디렉터리의 ../../.ssh 상대 점프도 포함합니다. 허용·거부 모두에서 해석된 경로를 로그에 남겨 macOS 버전별 파서 불일치를 잡습니다.

렌탈 풀을 공유하면 사용자별 홈 분리를 강제해 UID 재사용이나 공통 /tmp 접두로 다른 팀 샌드박스가 읽히지 않게 하세요. 다음 임차인이 예측 가능한 빈 상태를 받도록 정리 명령 목록을 티켓에 적습니다.

14. 관측 가능성

Gateway 로그를 에이전트 세션 ID와 모델 공급자 요청 ID와 상관시키세요. 집계기가 JSON 파싱에서 필드를 떨어뜨리면 거부가 재시도 전후인지 증명할 수 없습니다. 리허설 기간에만 파일 작업에 짧은 추적 헤더를 추가할 수 있습니다.

시간당 거부 사유 히스토그램을 보내 잘못된 ignore로 비싼 순회 후 거부가 반복되는지 봅니다.

15. 모노레포 용량

수백만 소형 파일 모노레포는 바이트 처리량이 작아도 inode 캐시를 포화시킵니다. 에이전트 워크플로에 재귀 목록을 켜기 전 깊이 상한으로 벤치하고 벽시계와 inode churn을 측정하세요. 깊이 대 지연이 초선형이면 겹치지 않는 서브트리로 세션을 나눕니다.

Apple Silicon 렌탈 계층의 SSD 여유도 함께 확인하고, APFS 조각화보다 메타데이터용 여유 inode 고갈을 우려하세요.

16. 허용 목록 거버넌스

합의된 샌드박스 밖으로 쓰기 루트를 넓히는 변경은 2인 검토를 요구하세요. 단독 승인이 프로덕션 홈을 리허설 표적으로 만드는 전형입니다. 프로덕션 비밀 로테이션과 같은 거버넌스에 올리세요.

분기마다 무작위 10세션을 샘플링해 거부가 문서화된 정책 매트릭스와 일치하는지 검증합니다.

17. 컨테이너와 호스트 경로

Gateway가 컨테이너에서 돌고 file_*가 호스트 bind mount를 보면 컨테이너와 호스트 시각의 경로 정규화가 달라질 수 있습니다. 거부 시 두 절대 경로를 모두 로그에 남기세요. 베이스 이미지 업그레이드 후에는 libc/Node 패치가 realpath 가장자리를 바꿀 수 있으니 symlink 레드팀을 재실행합니다.

file_write가 시크릿 bind mount를 써야 하는지 문서화하고 기본값은 아니오.

18. 교육·문서 부채

모든 운영자가 doctor를 돌리고 샌드박스를 만들며 의도적 거부 한 번을 일으켜 로그를보내는 30분 랩을 분기에 넣으세요. 읽기만으로는 symlink 방어와 일반 권한 오류를 구분하는 근육 기억이 생기지 않습니다.

Gateway 버전·플러그인 번들 해시·policy JSON 커밋 SHA를 잇는 살아 있는 다이어그램을 유지해 “어떤 조합이 라이브였는지” 추측하지 않게 하세요.

19. 인접 릴리스 업그레이드 순서

v2026.5.3에서 v2026.5.4까지 같은 유지보수 창에서 자주 올립니다. 두 번째 범프 후 파일 거부가 바뀌면 추적할 수 있도록 업그레이드 전 policy JSON과 플러그인 매니페스트 tarball을 확보하세요. 한 밤에 무관 위험을 쌓지 마세요.

음성 플러그인이 네트워크 무거운 경로를 추가해도 IPv6 문제 때문에 파일 타임아웃을 전역으로 조이지 마세요. 노브를 분리해 관측 가능성을 지킵니다.

20. 리허설 생략 비용

렌탈 리허설을 건너뛰면 몇 시간은 절약되지만 본장애·경영 커뮤니케이션·고객 신뢰 비용으로 외부화됩니다. 하루 렌탈 기대값과 단일 sev-2 중앙 시간을 비교해 보세요. 대부분 팀에서 렌탈이 더 쌉니다.

거부 로그가 유출을 막은 근접 사례를 기록해 재무가 반복 리허설 예산을 승인하기 쉽게 하세요.

21. 보안 검토 인수인계

검토자는 폭발 반경을 알고 싶어 하지 기능 흥분을 원하지 않습니다. 허용 목록 diff, symlink 모드, 거부 샘플 경로, 리허설 호스트에 프로덕션 토큰이 없었다는 증거를 묶으세요. 리스 시작·종료 시 여유 디스크 스크린샷으로 공유 스토리지를 몰래 채우지 않았음을 보여줍니다.

모델 부착 도구를 다루는 내부 데이터 분류 정책 단락에 링크해 “AI 어시스턴트”라는 모호한 설명에 추론을 맡기지 마세요.

리허설보내기와 같은 분의 Gateway 버전 문자열과 플러그인 매니페스트 해시를 첨부해 “테스트 중에 우리가 올렸다”는 감사의 회색지대를 없앱니다.

22. policy JSON 회귀

policy JSON을 git으로 관리하고 CI에서 스키마 검증을 하세요. Gateway와 동일한 리졸버에 합성 경로를 넣는 작은 테스트 하네스를 두어 리팩터가 루트를 조용히 넓히지 못하게 합니다. 정책 편집이 아닌 PR이라도 공유 라이브러리를 건드리면 하네스를 돌립니다.

로캘라이즈로 오류 문자열이 바뀌어도 로그 파서는 안정 코드를 키로 삼으세요. 자연어 부분 일치는 깨지기 쉽습니다.

운영 메모: policy JSON 저장소의 단일 오너를 정하고 Gateway 릴리스 노트 검토에도 같은 사람이 참여하게 하세요. 책임 분리는 “프로덕션 트래픽에 새 번들 도구가 들어간 뒤 몇 주간 아무도 모른다”는 상태를 낳습니다.

렌탈 계층에서 macOS 마이너 업그레이드가 있으면 7단계 리허설을 다시 실행하세요. Apple 보안 업데이트가 정책 테스트가 암묵적으로 의존하던 샌드박스 동작을 조일 수 있습니다.

각 policy 스냅샷에 Gateway의 정확한 버전 문자열을 붙여 감사인이 거부된 symlink 시도와 당시 플러그인 의미론을 대조할 수 있게 하세요.