샌드박스와 도구 정책 및 권한 상승 비교

1. 샌드박스 (agents.defaults.sandbox.* / agents.list[].sandbox.*)는 도구가 실행되는 위치(샌드박스 백엔드 또는 호스트)를 결정합니다.
2. 도구 정책 (tools.*, tools.sandbox.tools.*, agents.list[].tools.*)은 사용 가능하거나 허용되는 도구를 결정합니다.
3. 권한 상승 (tools.elevated.*, agents.list[].tools.elevated.*)은 샌드박스 환경에서 샌드박스 외부로 실행하기 위한 exec 전용 탈출구입니다(exec 대상이 node로 구성된 경우에는 node, 기본적으로는 gateway).

​

빠른 디버깅

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

• 적용되는 샌드박스 모드/범위/워크스페이스 접근 권한
• 세션이 현재 샌드박스화되어 있는지 여부(기본 세션과 기본이 아닌 세션)
• 적용되는 샌드박스 도구 허용/거부 설정 및 설정 출처(에이전트/전역/기본값)
• 권한 상승 게이트와 수정에 사용할 키 경로

​

샌드박스: 도구가 실행되는 위치

• "off": 모든 항목이 호스트에서 실행됩니다.
• "non-main": 기본 세션이 아닌 세션만 샌드박스화됩니다(그룹/채널에서 흔히 발생하는 “예상 밖”의 동작).
• "all": 모든 항목이 샌드박스화됩니다.

​

바인드 마운트(빠른 보안 확인)

• docker.binds는 샌드박스 파일 시스템을 _관통_합니다. 마운트한 모든 항목은 설정한 모드(:ro 또는 :rw)로 컨테이너 내부에 표시됩니다.
• 모드를 생략하면 기본값은 읽기-쓰기입니다. 소스/비밀 정보에는 :ro를 권장합니다.
• scope: "shared"는 에이전트별 바인드를 무시합니다(전역 바인드만 적용됨).
• OpenClaw는 바인드 소스를 두 번 검증합니다. 먼저 정규화된 소스 경로에서 검증한 다음, 존재하는 가장 깊은 상위 경로를 통해 확인된 경로에서 다시 검증합니다. 상위 경로의 심볼릭 링크를 통한 이탈로는 차단 경로나 허용된 루트 검사를 우회할 수 없습니다.
• 존재하지 않는 말단 경로도 안전하게 검사합니다. /workspace/alias-out/new-file이 심볼릭 링크인 상위 경로를 통해 차단된 경로나 구성된 허용 루트 외부로 확인되면 바인드가 거부됩니다.
• /var/run/docker.sock을 바인딩하면 사실상 샌드박스에 호스트 제어 권한을 넘기는 것입니다. 의도한 경우에만 수행하세요.
• 워크스페이스 접근 권한(workspaceAccess)은 바인드 모드와 별개입니다.

​

도구 정책: 존재하고 호출 가능한 도구

• 도구 프로필: tools.profile 및 agents.list[].tools.profile(기본 허용 목록)
• 제공자 도구 프로필: tools.byProvider[provider].profile 및 agents.list[].tools.byProvider[provider].profile
• 전역/에이전트별 도구 정책: tools.allow/tools.deny 및 agents.list[].tools.allow/agents.list[].tools.deny
• 제공자 도구 정책: tools.byProvider[provider].allow/deny 및 agents.list[].tools.byProvider[provider].allow/deny
• 샌드박스 도구 정책(샌드박스화된 경우에만 적용): tools.sandbox.tools.allow/tools.sandbox.tools.deny 및 agents.list[].tools.sandbox.tools.*

• deny가 항상 우선합니다.
• allow가 비어 있지 않으면 그 외 모든 항목은 차단된 것으로 처리됩니다.
• 도구 정책은 최종 차단 장치입니다. /exec로 거부된 exec 도구를 재정의할 수 없습니다.
• 도구 정책은 이름을 기준으로 도구의 사용 가능 여부를 필터링하며, exec 내부의 부작용은 검사하지 않습니다. exec가 허용되어 있다면 write, edit 또는 apply_patch를 거부해도 셸 명령이 읽기 전용으로 바뀌지는 않습니다.
• /exec는 권한이 있는 발신자의 세션 기본값만 변경하며, 도구 접근 권한을 부여하지 않습니다.
• 제공자 도구 키에는 provider(예: google-antigravity) 또는 provider/model(예: openai/gpt-5.4)을 사용할 수 있습니다.
• 도구 정책 단계에서 도구가 제거되거나 샌드박스 도구 정책이 호출을 차단하면 Gateway 로그에 agents/tool-policy 감사 항목이 포함됩니다. openclaw logs를 사용하여 규칙 레이블, 구성 키 및 영향을 받는 도구 이름을 확인하세요.

​

도구 그룹(축약 표기)

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

​

권한 상승: exec 전용 “호스트에서 실행”

• 샌드박스화된 경우 /elevated on(또는 elevated: true가 설정된 exec)은 샌드박스 외부에서 실행됩니다(승인이 여전히 필요할 수 있음).
• 세션의 exec 승인을 건너뛰려면 /elevated full을 사용하세요.
• 이미 직접 실행 중이라면 권한 상승은 사실상 아무 효과가 없습니다(게이트는 계속 적용됨).
• 권한 상승은 Skills 범위로 제한되지 않으며, 도구 허용/거부를 재정의하지도 않습니다.
• 권한 상승은 host=auto에서 임의의 호스트 간 재정의를 허용하지 않습니다. 일반적인 exec 대상 규칙을 따르며, 구성된 대상이나 세션 대상이 이미 node인 경우에만 node를 유지합니다.
• /exec는 권한 상승과 별개입니다. 권한이 있는 발신자의 세션별 exec 기본값만 조정합니다.

• 활성화: tools.elevated.enabled(선택적으로 agents.list[].tools.elevated.enabled)
• 발신자 허용 목록: tools.elevated.allowFrom.<provider>(선택적으로 agents.list[].tools.elevated.allowFrom.<provider>)

​

일반적인 “샌드박스 감옥” 문제 해결

​

”샌드박스 도구 정책에 의해 도구 X가 차단됨”

• 샌드박스 비활성화: agents.defaults.sandbox.mode=off(또는 에이전트별 agents.list[].sandbox.mode=off)
• 샌드박스 내부에서 도구 허용:
  • tools.sandbox.tools.deny에서 제거(또는 에이전트별 agents.list[].tools.sandbox.tools.deny)
  • 또는 tools.sandbox.tools.allow에 추가(또는 에이전트별 허용 목록)
• openclaw logs에서 agents/tool-policy 항목을 확인하세요. 해당 항목에는 샌드박스 모드와 허용 또는 거부 규칙 중 어느 것이 도구를 차단했는지가 기록됩니다.

​

”기본 세션인 줄 알았는데 왜 샌드박스화되어 있나요?”

​

관련 문서

• 샌드박스화 — 전체 샌드박스 참고 자료(모드, 범위, 백엔드, 이미지)
• 다중 에이전트 샌드박스 및 도구 — 에이전트별 재정의 및 우선순위
• 권한 상승 모드