OpenClaw 도구가 막힐 때｜샌드박스·도구 정책·Elevated 권한을 구분하는 법

OpenClaw에서 어떤 작업이 막혔을 때 “권한이 부족한가?”라고만 보면 원인을 놓치기 쉽습니다. 공식 문서는 샌드박스, 도구 정책, Elevated 실행을 서로 다른 제어로 구분합니다. 이름은 비슷하지만 답하는 질문이 다릅니다.

이 글은 특정 환경에서 설정을 바꾸거나 우회한 경험담이 아니라, 공식 문서의 구분을 한국어 독자가 먼저 진단 순서로 이해하도록 풀어 쓴 해설입니다. 특히 팀이나 공유 Gateway에서는 넓은 권한을 켜기 전에 어떤 층에서 멈췄는지 확인하는 편이 안전합니다.

먼저 세 가지 질문으로 나눕니다

• 작업이 어디에서 실행되는가? → 샌드박스
• 그 세션에 어떤 도구가 보이고 호출 가능한가? → 도구 정책
• 샌드박스 밖 실행이 필요한 exec를 허용할 수 있는가? → Elevated

한 층을 통과했다고 다음 층까지 자동으로 열리는 것은 아닙니다. 예를 들어 도구가 보인다고 해서 호스트에서 실행되는 것은 아니고, Elevated가 가능하다고 해서 새 도구가 생기는 것도 아닙니다.

1. 샌드박스는 ‘어디에서 실행할지’를 정합니다

공식 문서에서 샌드박스는 도구가 호스트에서 실행되는지, 격리된 환경에서 실행되는지를 정하는 장치입니다. 기본 모드는 모든 세션을 끄거나, 메인이 아닌 세션만 격리하거나, 모두 격리하는 식으로 나뉠 수 있습니다.

작업공간 접근도 별도입니다. 샌드박스 안에서 작업공간을 전혀 보지 못하게 할지, 읽기만 허용할지, 쓰기까지 허용할지를 따로 정할 수 있습니다. 폴더를 bind mount했다고 해도 그 폴더는 격리 경계를 관통하므로, 필요한 범위와 읽기 전용 여부를 먼저 점검해야 합니다.

또한 운영자 역할이 샌드박스를 필수로 요구하는 경우가 있습니다. 이 경우에는 뒤에서 설명할 Elevated 실행으로도 그 필수 격리를 건너뛸 수 없습니다. 막힌 이유를 모른 채 모드를 넓히기보다, 해당 역할의 정책을 먼저 확인해야 합니다.

2. 도구 정책은 ‘무엇을 호출할 수 있는지’를 정합니다

도구 정책은 exec, 브라우저, 파일 도구처럼 어떤 도구 이름을 세션에 허용할지 결정합니다. 기본 도구 프로필, 전역 또는 에이전트별 allow/deny, 제공자별 정책, 샌드박스 안에서만 적용되는 추가 정책처럼 여러 층이 함께 적용될 수 있습니다.

기억할 규칙은 간단합니다. deny가 항상 우선하고, allow 목록이 비어 있지 않으면 목록 밖 도구는 차단된다는 점입니다. 따라서 “도구가 없어요”라는 상황은 실행 환경 문제가 아니라 정책상 해당 도구가 걸러진 것일 수 있습니다.

반대로 exec 자체가 허용되었다고 해서 명령의 부작용이 자동으로 읽기 전용이 되는 것도 아닙니다. 공식 문서는 도구 정책이 도구 이름을 걸러 주는 것이지, 허용된 exec 안의 모든 동작을 세밀하게 검사하는 장치는 아니라고 설명합니다. 공유 환경에서는 필요한 최소 도구만 허용하는 이유가 여기에 있습니다.

3. Elevated는 exec 전용의 별도 문입니다

Elevated는 일반적인 샌드박스 밖에서 exec를 실행할 수 있게 하는 별도 통로입니다. 하지만 이것은 exec에만 적용됩니다. 브라우저나 파일 도구를 새로 주지 않으며, 도구 정책이 이미 차단한 exec를 되살리지도 않습니다.

Elevated 실행도 켜짐 여부와 요청자 허용 목록 같은 게이트를 통과해야 합니다. 이미 호스트에서 실행되는 세션이라면 효과가 없을 수 있고, 앞서 말한 필수 샌드박스 역할에는 적용되지 않습니다. “Elevated를 켜면 모든 권한이 생긴다”는 식으로 이해하면 실제 정책을 잘못 읽게 됩니다.

막혔을 때는 설정 변경보다 현재 상태를 먼저 읽습니다

1. 오류가 도구 자체의 차단인지, 샌드박스 안의 실행 제한인지 구분합니다.
2. 관리자가 사용할 수 있다면 openclaw sandbox explain으로 현재 세션의 적용 모드·작업공간 접근·도구 allow/deny·Elevated 게이트를 확인합니다.
3. Gateway 로그의 도구 정책 기록에서 어떤 규칙과 설정 키가 도구를 막았는지 확인합니다.
4. 필요한 작업 범위가 분명할 때만 최소한의 정책 변경을 검토하고, 공유 환경의 관리자 승인 범위를 벗어나지 않습니다.

이 순서는 “권한을 크게 열어 보기”보다 원인을 재현하고 설명하기 쉽습니다. OpenClaw의 기본 구조가 궁금하다면 OpenClaw란 무엇인가 글도 함께 보면 좋습니다.

정리

샌드박스는 실행 장소와 파일 경계, 도구 정책은 호출 가능한 도구, Elevated는 exec의 별도 실행 경로를 다룹니다. 세 가지는 연결되어 있지만 서로 대신하지 않습니다. 막힌 상황에서는 먼저 어느 질문의 답이 필요한지 구분하면, 불필요하게 넓은 권한을 주지 않고도 다음 확인 지점을 찾을 수 있습니다.

---

이 글은 OpenClaw 공식 문서 Sandbox vs tool policy vs elevated와 설치본 docs/gateway/sandbox-vs-tool-policy-vs-elevated.md를 바탕으로 작성한 해설입니다. 특정 설치·운영·보안 효과를 직접 경험한 것처럼 주장하지 않습니다.