네이티브 macOS에 OpenClaw를 배포하는 운영자는 곧 배웁니다. “워크스페이스 전용 파일시스템 도구”라는 YAML 노브 하나 뒤에 에이전트 도구 필터, 게이트웨이 해석, 선택적 Docker 바인드 마운트라는 세 정책이 숨어 있다는 것을요. 본 2026-05-06 매트릭스는 tools.fs.workspaceOnly가 Mac mini M4 호스트 경로 정규화와 어떻게 상호작용하는지, 구성이 더 넓은 접근을 약속해도 Path escapes workspace root가 나타나는 이유, 비밀을 새지 않고 실패를 재현하는 방법을 보여 줍니다. 표 두 개, 트리아지 8단계, FAQ JSON-LD, 관측 가능성과 비밀 기사로 방어를 깊게 하는 링크가 포함됩니다.
게이트웨이 관측 및 비식별에서 이어가고, 비밀, 환경 변수, 키체인으로 자격 증명 자세를 조이고, 드레인·재시작·스모크 런북으로 업그레이드를 검증하면 파일시스템 회귀가 시끄러운 배포 창에 숨지 않습니다.
현장에서는 “모델이 파일을 못 쓴다”는 보고가 흔하지만, 먼저 의심해야 하는 것은 모델이 아니라 경로 정규화입니다. Docker가 끼면 컨테이너 안의 /workspace와 호스트 실경로가 같아 보여도 게이트웨이가 다른 절대 경로로 검증할 수 있습니다. HK·JP·KR·SG·US처럼 지역을 나눠도 설정 파일만 복사한다고 볼륨 UUID가 그대로라고 가정할 수 없습니다. 버전·절대 경로·실행 UID 세 가지가 맞으면 대부분의 “미스터리 거부”는 재현 가능해집니다.
파일시스템 정책이 Apple Silicon 운영자를 혼란스럽게 하는 이유
macOS는 심볼릭 링크, Firmlink, 대소문자 비구분 볼륨을 통해 경로를 해석하고 컨테이너는 다른 루트를 봅니다. 에이전트는 /workspace/out에 쓴다고 믿을 수 있지만 보안 패치 후 게이트웨이가 더 엄격한 호스트 규칙을 적용할 수 있습니다. Apple Silicon M4에서는 Activity Monitor에서 IO 지연이 “괜찮아” 보여도 샌드박스 도구가 메타데이터 업데이트를 직렬화할 수 있어 운영자는 정책 층이 아니라 모델이나 네트워크를 탓합니다. 강제 표면을 명시적으로 문서화하면 그 사각을 막습니다.
- 이중 스택 마운트: Docker Desktop 바인드 경로는 같은 호스트의 SSH 세션 경로와 미묘하게 다릅니다.
- 자동화 대 인간 시험: 엔지니어가 Terminal 별칭으로 시험하면 데몬이 헤드리스로 맞는 제약을 우회합니다.
- 감사 긴장: SecOps는 거부 기본을 원하고 개발자 경험은
~/Developer아래 빠른 편집을 원합니다.
인시던트 위생: 로그에 Path escapes workspace root가 보이면 절대 해석 경로, 소유 UID, 도구가 샌드박스 안에서 실행됐는지 세 가지를 기록하세요. 상류 유지관리자가 회귀와 의도된 조임을 구분하는 데 필요합니다.
매트릭스 A — 강제 층 대 운영자 가정 대 검증 습관
| 층 | 흔한 가정 | 검증 |
|---|---|---|
| 에이전트 허용·거부 목록 | 파일 쓰기가 YAML 그대로 | openclaw doctor와 최소 픽스처로 도구 호출 재생 |
| 게이트웨이 호스트 가드 | workspaceOnly:false가 항상 루트 검사 비활성 |
릴리스 노트 비교, 업그레이드 전후 설정 diff |
| Docker 샌드박스 볼륨 맵 | 컨테이너 경로가 macOS 경로와 같음 | 마운트 테이블 출력 후 두 루트를 수치로 대응 |
매트릭스 B — 증상 대 유력 층 대 소유자 행동 대 완화 패턴
| 증상 | 유력 층 | 소유자 | 완화 |
|---|---|---|---|
| 읽기 성공, 워크스페이스 밖 쓰기 차단 | 호스트 가드레일 회귀 | 플랫폼 | 정책이 문서와 맞을 때까지 게이트웨이 semver 고정, 최소 재현 제출 |
| 샌드박스 안에서만 무작위 경로 실패 | 바인드 마운트 누락 | 인프라 | 허용 마운트 확장 또는 해당 레인에서 샌드박스 제거 |
| 도구가 전체 서브트리를 간헐적으로 거부 | 워크스페이스 이동과 도구 실행 경합 | 자동화 | 파일 잠금으로 프로비저닝 직렬화, 2초 이상 안정 창 |
팀이 실제로 논쟁하는 정량 노브
- 워크스페이스 이동 예산: 사람 확인 없이 에이전트 세션당 자동 이동은 최대 1회.
- 병렬 도구 팬아웃: Mac mini M4 게이트웨이당 동시 파일 변경 도구를 4개로 제한해 인덱싱 작업 중 APFS 메타데이터 폭풍 방지.
- 회귀 SLA: 예상 밖 워크스페이스 거부가 릴리스 머지를 30분 넘게 막으면 P1.
8단계 트리아지(JSON-LD와 대응)
- 버전 캡처: CLI, 게이트웨이 플러그인, OS 빌드 번호.
- 해석된 워크스페이스 루트 출력: 호스트 데몬 대 샌드박스 자식.
- 설정 diff:
tools.fs.workspaceOnly와 동반 허용 목록. - 실패 분류: 탈출 오류, 권한 거부, 일시 IO.
- 최소 프로브: 통제된 temp만 건드림.
- Docker 격리 시 네트워크와 마운트 조정.
- 로그 비식별: 신뢰 경계 밖으로 보내기 전에.
- 자세 문서화: 브레이크아웃이 버그인지 정책인지 지원이 알도록.
FAQ
개발자에게 기본으로 호스트 전체 쓰기를 허용해야 하는가
아니오. 좁게 범위 지정한 스테이징 호스트나 주간 감사의 일시 브레이크아웃 레인을 발급하고 프로덕션 게이트웨이는 워크스페이스에 묶어 둔다.
심볼릭 링크 탈출을 안전하게 시험하려면
스크래치 볼륨 아래 일회 워크스페이스를 만들고 무해한 파일로 symlink 한 뒤 고객 데이터에 닿기 전에 강제가 횡단을 막는지 검증한다.
전용 Mac mini M4에서 OpenClaw를 실행하면 Apple 툴체인 기대를 지키며 샌드박스 경계를 실험할 수 있습니다. Apple Silicon은 파일 집약 에이전트의 지연을 예측 가능하게 하고, 네이티브 macOS는 libc 불일치 놀람을 줄이며, NodeMac의 SSH와 선택적 VNC는 헤드리스 로그가 거짓말할 때 경로 문제를 대화형으로 증명합니다. 홍콩, 일본, 한국, 싱가포르, 미국 리전에서 “엄격 워크스페이스” 프로덕션 게이트웨이와 연구 포드 전용 완화 샌드박스를 분리하면 블라스트 반경과 릴리스 간 tools.fs 동작 변화에 대한 평균 명료화 시간을 모두 줄입니다.
요약하면 OpenClaw 파일 도구는 YAML을 그대로 읽은 것처럼 동작하지 않습니다. 에이전트·게이트웨이·컨테이너 세 층이 각각 일관되면 중요하며, 충돌이 나면 먼저 버전과 경로 해석을 고정하고 다음으로 allowlist를 조정합니다. 운용이 성숙하면 연구용 넓은 경로와 프로덕션 좁은 경로를 조직적으로 명시할 수 있고 지원 문의도 설정 버그인지 정책인지 이진 탐색으로 수렴합니다.