메인 콘텐츠로 건너뛰기

​
Sandbox vs Tool Policy vs Elevated

OpenClaw에는 서로 관련되어 있지만 역할이 다른 세 가지 제어 장치가 있습니다.
  1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*)는 도구가 어디에서 실행되는지를 결정합니다. (Docker vs host)
  2. Tool policy (tools.*, tools.sandbox.tools.*, agents.list[].tools.*)는 어떤 도구를 사용할 수 있는지를 결정합니다.
  3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*)는 샌드박스 안에 있을 때 호스트에서 실행하도록 하는 exec 전용 탈출구입니다.

​
빠른 디버깅

인스펙터를 사용하면 OpenClaw가 실제로 어떤 결정을 내리고 있는지 확인할 수 있습니다. 
openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json
출력에는 다음이 포함됩니다.
  • 실제 적용된 sandbox mode / scope / workspace access
  • 현재 세션이 샌드박스 대상인지 여부 (main vs non-main)
  • 실제 sandbox tool allow/deny 결과와 그 출처(agent/global/default)
  • elevated 게이트 상태와 수정할 설정 키 경로

​
Sandbox: 도구가 실행되는 위치

샌드박싱은 agents.defaults.sandbox.mode로 제어합니다.
  • "off": 모든 도구가 호스트에서 실행됩니다.
  • "non-main": non-main 세션만 샌드박스에 넣습니다. 그룹/채널에서 예상 밖으로 샌드박싱되는 흔한 이유입니다.
  • "all": 모든 세션을 샌드박스에 넣습니다.
전체 매트릭스(scope, workspace mount, image)는 Sandboxing을 참고하세요.

​
Bind mounts 보안 빠른 점검

  • docker.binds는 샌드박스 파일시스템을 관통합니다. 마운트한 경로는 지정한 모드(:ro 또는 :rw)로 컨테이너 안에서 그대로 보입니다.
  • 모드를 생략하면 기본값은 read-write입니다. 소스 코드나 시크릿은 가능하면 :ro를 사용하세요.
  • scope: "shared"에서는 agent별 bind가 무시되고 전역 bind만 적용됩니다.
  • /var/run/docker.sock를 바인드하면 사실상 샌드박스에 호스트 제어권을 넘기는 것과 같습니다. 의도한 경우에만 사용하세요.
  • workspace access (workspaceAccess: "ro" / "rw")는 bind mount 모드와는 별개입니다.

​
Tool policy: 어떤 도구가 존재하고 호출 가능한가

다음 계층을 함께 봐야 합니다.
  • Tool profile: tools.profile, agents.list[].tools.profile
  • Provider tool profile: tools.byProvider[provider].profile, agents.list[].tools.byProvider[provider].profile
  • Global / per-agent tool policy: tools.allow / tools.deny, agents.list[].tools.allow / agents.list[].tools.deny
  • Provider tool policy: tools.byProvider[provider].allow/deny, agents.list[].tools.byProvider[provider].allow/deny
  • Sandbox tool policy: 샌드박스 안에서만 적용되는 tools.sandbox.tools.allow/deny, agents.list[].tools.sandbox.tools.*
기억할 규칙:
  • deny가 항상 우선합니다.
  • allow가 비어 있지 않으면, 나머지는 모두 차단으로 간주합니다.
  • tool policy가 최종 차단선입니다. exec가 deny되어 있으면 /exec로도 되살릴 수 없습니다.
  • /exec는 권한 있는 발신자에 한해 세션 기본값만 바꿉니다. 도구 권한을 부여하지는 않습니다.
  • provider tool 키는 provider(예: google-antigravity) 또는 provider/model(예: openai/gpt-5.2) 형식을 모두 받을 수 있습니다.

​
도구 그룹 축약 표기

도구 정책(global, agent, sandbox)에서는 여러 도구를 묶는 group:* 표기를 지원합니다. 
{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}
사용 가능한 그룹:
  • group:runtime: exec, bash, process
  • group:fs: read, write, edit, apply_patch
  • group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
  • group:memory: memory_search, memory_get
  • group:ui: browser, canvas
  • group:automation: cron, gateway
  • group:messaging: message
  • group:nodes: nodes
  • group:openclaw: OpenClaw 내장 도구 전체(provider plugin 제외)

​
Elevated: exec만 호스트에서 실행

Elevated는 추가 도구를 허용하지 않습니다. 오직 exec에만 영향을 줍니다.
  • 샌드박스 상태라면 /elevated on 또는 elevated: true가 붙은 exec는 호스트에서 실행됩니다. 승인 절차는 여전히 적용될 수 있습니다.
  • /elevated full을 사용하면 해당 세션에서 exec 승인을 건너뜁니다.
  • 이미 direct 실행 상태라면 elevated는 사실상 no-op이지만, 게이트 자체는 여전히 적용됩니다.
  • Elevated는 skill 범위 기능이 아니며 tool allow/deny를 무시하지도 않습니다.
  • /exec는 elevated와 별개입니다. 권한 있는 발신자에 대해 세션별 exec 기본값만 조정합니다.
게이트:
  • 활성화: tools.elevated.enabled (선택적으로 agents.list[].tools.elevated.enabled)
  • 발신자 allowlist: tools.elevated.allowFrom.<provider> (선택적으로 agents.list[].tools.elevated.allowFrom.<provider>)
자세한 내용은 Elevated Mode를 참고하세요.

​
흔한 “sandbox jail” 해결법

​
”Tool X blocked by sandbox tool policy”

다음 중 하나를 고르세요.
  • 샌드박스를 끕니다: agents.defaults.sandbox.mode=off 또는 agent별 agents.list[].sandbox.mode=off
  • 샌드박스 안에서 해당 도구를 허용합니다.
    • tools.sandbox.tools.deny 또는 agents.list[].tools.sandbox.tools.deny에서 제거
    • 또는 tools.sandbox.tools.allow / agent별 allow에 추가

​
”main이라고 생각했는데 왜 샌드박스인가?”

"non-main" 모드에서는 group/channel key가 main이 아닙니다. sandbox explain으로 실제 main session key를 확인하거나 모드를 "off"로 바꾸세요.