OpenClaw 보안 설정 가이드: Sandbox, Tool Policy, Elevated

개발을 하다 보면 보안과 편의성 사이에서 줄타기를 해야 할 때가 많죠. 특히 샌드박스 환경에서 도구가 제대로 작동하지 않거나, 반대로 권한이 너무 넓게 열려 있어 불안했던 경험, 다들 한 번쯤 있으실 겁니다.

OpenClaw의 샌드박스 및 도구 정책 설정을 이해하면 이런 고민을 깔끔하게 해결할 수 있습니다. 이 가이드를 통해 OpenClaw의 보안 제어 메커니즘을 확실하게 파악해 보세요.

빠른 디버깅 (Quick debug)

인스펙터를 활용하면 OpenClaw가 현재 어떤 작업을 수행 중인지 정확히 확인할 수 있습니다. 다음 명령어를 통해 상태를 점검해 보세요.

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

이 명령어는 다음 정보를 출력합니다:

• 유효한 샌드박스 모드, 범위 및 워크스페이스 접근 권한
• 현재 세션이 샌드박스 내부인지 여부 (main vs non-main)
• 유효한 샌드박스 도구 허용/차단 목록 (에이전트, 글로벌, 기본 설정 출처 확인 가능)
• Elevated 게이트 및 수정 키 경로

샌드박스: 도구가 실행되는 위치 (Sandbox: where tools run)

샌드박싱은 agents.defaults.sandbox.mode 설정을 통해 제어됩니다.

• "off": 모든 작업이 호스트에서 실행됩니다.
• "non-main": 메인 세션이 아닌 경우에만 샌드박스가 적용됩니다 (그룹이나 채널에서 흔히 발생하는 상황입니다).
• "all": 모든 작업이 샌드박스 내부에서 실행됩니다.

전체 매트릭스(범위, 워크스페이스 마운트, 이미지 등)는 Sandboxing 문서를 참고하세요.

바인드 마운트 (보안 체크)

1. docker.binds는 샌드박스 파일 시스템을 관통합니다. 마운트한 내용은 컨테이너 내부에서 설정한 모드(:ro 또는 :rw)로 보입니다.
2. 모드를 생략하면 기본값은 읽기-쓰기(read-write)입니다. 소스 코드나 보안 정보에는 :ro를 사용하는 것을 권장합니다.
3. scope: "shared" 설정 시 에이전트별 바인드는 무시되며 글로벌 바인드만 적용됩니다.
4. OpenClaw는 바인드 소스를 두 번 검증합니다. 정규화된 소스 경로를 먼저 확인하고, 가장 깊은 상위 경로까지 해결한 후 다시 확인합니다. 심볼릭 링크를 통한 경로 탈출은 차단된 경로 확인을 우회할 수 없습니다.
5. 존재하지 않는 리프 경로도 안전하게 체크합니다. 만약 /workspace/alias-out/new-file이 심볼릭 링크를 통해 차단된 경로로 연결된다면 바인드는 거부됩니다.
6. /var/run/docker.sock을 바인딩하면 샌드박스에 호스트 제어권이 넘어가므로, 의도적인 경우에만 사용하세요.
7. 워크스페이스 접근 권한(workspaceAccess: "ro"/"rw")은 바인드 모드와 독립적으로 작동합니다.

도구 정책: 도구의 존재 및 호출 가능 여부 (Tool policy: which tools exist/are callable)

도구 정책은 다음 두 가지 계층이 중요합니다:

• 도구 프로필: 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는 승인된 발신자의 세션 기본값만 변경할 뿐, 도구 접근 권한을 부여하지 않습니다. 제공자 도구 키는 provider 또는 provider/model 형식을 지원합니다.

도구 그룹 (단축어)

도구 정책은 여러 도구를 한 번에 확장할 수 있는 group:* 항목을 지원합니다.

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

사용 가능한 그룹:

• group:runtime: exec, process, code_execution (bash는 exec의 별칭으로 허용)
• group:fs: read, write, edit, apply_patch
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
• group:memory: memory_search, memory_get
• group:web: web_search, x_search, web_fetch
• group:ui: browser, canvas
• group:automation: cron, gateway
• group:messaging: message
• group:nodes: nodes
• group:agents: agents_list
• group:media: image, image_generate, video_generate, tts
• group:openclaw: 모든 내장 OpenClaw 도구 (제공자 플러그인 제외)

Elevated: exec 전용 “호스트 실행” (Elevated: exec-only “run on host”)

Elevated는 추가적인 도구 권한을 부여하지 않으며, 오직 exec에만 영향을 미칩니다.

• 샌드박스 내부일 때 /elevated on (또는 elevated: true를 포함한 exec)을 사용하면 샌드박스 외부에서 실행됩니다 (승인 절차는 여전히 적용될 수 있습니다).
• /elevated full을 사용하면 해당 세션의 exec 승인 절차를 건너뜁니다.
• 이미 직접 실행 중인 경우, Elevated는 사실상 아무런 효과가 없습니다 (여전히 게이트가 적용됨).
• Elevated는 스킬 범위에 제한받지 않으며, 도구 허용/차단 정책을 무시하지 않습니다.
• Elevated는 host=auto로부터 임의의 호스트 간 오버라이드를 허용하지 않습니다. 일반적인 exec 대상 규칙을 따르며, 대상이 이미 node인 경우에만 node를 유지합니다.
• /exec는 Elevated와 별개입니다. 이는 승인된 발신자를 위한 세션별 exec 기본값만 조정합니다.

게이트 설정:

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

자세한 내용은 Elevated Mode를 확인하세요.

샌드박스 문제 해결 (Common “sandbox jail” fixes)

“Tool X blocked by sandbox tool policy” 오류 발생 시

다음 수정 키 중 하나를 선택하세요:

1. 샌드박스 비활성화: agents.defaults.sandbox.mode=off (또는 에이전트별 agents.list[].sandbox.mode=off)
2. 샌드박스 내부에서 도구 허용:
   • tools.sandbox.tools.deny에서 해당 도구 제거
   • 또는 tools.sandbox.tools.allow에 해당 도구 추가

”메인 세션인 줄 알았는데 왜 샌드박스인가요?”

"non-main" 모드에서는 그룹이나 채널 키가 메인으로 간주되지 않습니다. sandbox explain 명령어로 확인되는 메인 세션 키를 사용하거나, 모드를 "off"로 변경하세요.

관련 문서 (See also)

• Sandboxing — 샌드박스 전체 참조 (모드, 범위, 백엔드, 이미지)
• Multi-Agent Sandbox & Tools — 에이전트별 오버라이드 및 우선순위
• Elevated Mode

더 궁금한 점이 있으시다면 AI Setup Assistant를 통해 언제든 문의해 주세요!