​

Sandboxing

​

무엇이 샌드박스화되는가

• 도구 실행(exec, read, write, edit, apply_patch, process 등).
• 선택적 샌드박스화된 브라우저(agents.defaults.sandbox.browser).
  • 기본적으로 샌드박스 브라우저는 브라우저 도구가 필요할 때 자동 시작되어(CDP 접근 가능 보장) 동작합니다. agents.defaults.sandbox.browser.autoStart 및 agents.defaults.sandbox.browser.autoStartTimeoutMs로 구성합니다.
  • agents.defaults.sandbox.browser.allowHostControl를 사용하면 샌드박스화된 세션이 호스트 브라우저를 명시적으로 대상으로 지정할 수 있습니다.
  • 선택적 허용 목록이 target: "custom"를 게이트합니다: allowedControlUrls, allowedControlHosts, allowedControlPorts.

• Gateway(게이트웨이) 프로세스 자체.
• 호스트에서 실행하도록 명시적으로 허용된 모든 도구(예: tools.elevated).
  • 상승된 exec 는 호스트에서 실행되며 샌드박스화를 우회합니다.
  • 샌드박스화가 꺼져 있으면 tools.elevated은 실행을 변경하지 않습니다(이미 호스트에서 실행). Elevated Mode를 참조하십시오.

​

모드

• "off": 샌드박스화 없음.
• "non-main": 메인 세션이 아닌 경우에만 샌드박스화(호스트에서 일반 채팅을 원할 때 기본값).
• "all": 모든 세션이 샌드박스에서 실행됩니다. 참고: "non-main"은 에이전트 id 가 아니라 session.mainKey 기준(기본값 "main")입니다. 그룹/채널 세션은 자체 키를 사용하므로 메인이 아닌 것으로 간주되어 샌드박스화됩니다.

​

범위

• "session" (기본값): 세션당 하나의 컨테이너.
• "agent": 에이전트당 하나의 컨테이너.
• "shared": 모든 샌드박스화된 세션이 하나의 컨테이너를 공유.

​

워크스페이스 접근

• "none" (기본값): 도구는 ~/.openclaw/sandboxes 아래의 샌드박스 워크스페이스를 봅니다.
• "ro": 에이전트 워크스페이스를 /agent에 읽기 전용으로 마운트합니다(write/edit/apply_patch 비활성화).
• "rw": 에이전트 워크스페이스를 /workspace에 읽기/쓰기 가능으로 마운트합니다.

​

사용자 지정 바인드 마운트

• 설정된 경우([] 포함), 브라우저 컨테이너에 대해 agents.defaults.sandbox.docker.binds를 대체합니다.
• 생략된 경우, 브라우저 컨테이너는 agents.defaults.sandbox.docker.binds로 폴백합니다(하위 호환).

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/run/docker.sock:/var/run/docker.sock"],
        },
      },
    },
    list: [
      {
        id: "build",
        sandbox: {
          docker: {
            binds: ["/mnt/cache:/cache:rw"],
          },
        },
      },
    ],
  },
}

• 바인드는 샌드박스 파일시스템을 우회하여 설정한 모드(:ro 또는 :rw) 그대로 호스트 경로를 노출합니다.
• 민감한 마운트(예: docker.sock, 비밀 값, SSH 키)는 절대적으로 필요하지 않은 한 :ro로 설정해야 합니다.
• 워크스페이스에 대한 읽기 접근만 필요하다면 workspaceAccess: "ro"와 함께 사용하십시오; 바인드 모드는 독립적으로 유지됩니다.
• 바인드가 도구 정책 및 상승된 exec 와 어떻게 상호작용하는지는 Sandbox vs Tool Policy vs Elevated를 참조하십시오.

​

이미지 + 설정

scripts/sandbox-setup.sh

scripts/sandbox-browser-setup.sh

​

setupCommand (컨테이너 1회 설정)

• 전역: agents.defaults.sandbox.docker.setupCommand
• 에이전트별: agents.list[].sandbox.docker.setupCommand

• 기본 docker.network는 "none"(이그레스 없음)이므로 패키지 설치가 실패합니다.
• readOnlyRoot: true은 쓰기를 방지합니다; readOnlyRoot: false로 설정하거나 사용자 지정 이미지를 사용하십시오.
• 패키지 설치를 위해서는 user가 root 여야 합니다(user을 생략하거나 user: "0:0"로 설정).
• 샌드박스 exec 는 호스트 process.env를 상속하지 않습니다. Skill API 키에는 agents.defaults.sandbox.docker.env(또는 사용자 지정 이미지)를 사용하십시오.

​

도구 정책 + 탈출구

• 유효한 샌드박스 모드, 도구 정책, 수정 구성 키를 확인하려면 openclaw sandbox explain를 사용하십시오.
• “왜 이게 차단되었는가?”에 대한 사고 모델은 Sandbox vs Tool Policy vs Elevated를 참조하십시오. 잠금을 유지하십시오.

​

멀티 에이전트 재정의

​

최소 활성화 예제

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

​

관련 문서

• Sandbox Configuration
• Multi-Agent Sandbox & Tools
• Security