Sandboxing

Sandboxing 문서는 OpenClaw 공식 문서(gateway/sandboxing)를 한국어로 정리한 가이드입니다. How OpenClaw sandboxing works: modes, scopes, workspace access, and images 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

How OpenClaw sandboxing works: modes, scopes, workspace access, and images

한국어 가이드 범위: gateway/sandboxing 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What gets sandboxed
Modes, scope, and backend
Docker backend
Sandboxed browser
SSH backend
OpenShell backend
Workspace access
Multiple folders for one agent
Other bind behavior
Images and setup
setupCommand (one-time container setup)
Tool policy and escape hatches
Multi-agent overrides
Minimal enable example
관련 문서

상세 내용

본문

OpenClaw can run tool execution inside a sandbox backend to reduce blast radius. Sandboxing is off by default and controlled by agents.defaults.sandbox (global) or agents.entries.*.sandbox (per-agent). The Gateway process always stays on the host; only tool execution moves into the sandbox when enabled.

What gets sandboxed

주요 항목:

Tool execution: exec, read, write, edit, apply_patch, process, etc.
The optional sandboxed browser (agents.defaults.sandbox.browser).
The Gateway process itself.
Any tool explicitly allowed to run outside the sandbox via tools.elevated. Elevated exec bypasses sandboxing and runs on the configured escape path (gateway by default, or node when the exec target is node). If sandboxing is off, tools.elevated changes nothing since exec already runs on the host. See Elevated Mode.

Modes, scope, and backend

Three independent settings control sandbox behavior:

주요 항목:

off: no sandboxing.
non-main: sandbox every session except the agent's main session. The main session key is always agent:<agentId>:main (or global when session.scope is "global"); it is not configurable. Group/channel sessions use their own keys, so they always count as non-main and get sandboxed.
all: every session runs in a sandbox.
agent: one container per agent.
session: one container per session.
shared: one container shared by all sandboxed sessions (per-agent docker/ssh/browser overrides are ignored under this scope).

Setting	Key	Values	Default
Mode	`agents.defaults.sandbox.mode`	`off`, `non-main`, `all`	`off`
Scope	`agents.defaults.sandbox.scope`	`agent`, `session`, `shared`	`agent`
Backend	`agents.defaults.sandbox.backend`	`docker`, `ssh`, `openshell`	`docker`

	Docker	SSH	OpenShell
Where it runs	Local container	Any SSH-accessible host	OpenShell managed sandbox
Setup	`scripts/sandbox-setup.sh`	SSH key + target host	OpenShell plugin enabled
Workspace model	Bind-mount or copy	Remote-canonical (seed once)	`mirror` or `remote`
Network control	`docker.network` (default: none)	Depends on remote host	Depends on OpenShell
Browser sandbox	Supported	Not supported	Not supported yet
Bind mounts	`docker.binds`	N/A	N/A
Best for	Local dev, full isolation	Offloading to a remote machine	Managed remote sandboxes with optional two-way sync

Docker backend

Docker is the default backend once sandboxing is enabled. It runs tools and sandbox browsers locally through the Docker daemon socket (/var/run/docker.sock); isolation comes from Docker namespaces.

주요 항목:

Config requires host paths: openclaw.json workspace must contain the host's absolute path (e.g. /home/user/.openclaw/workspaces), not the internal Gateway container path. The Docker daemon evaluates paths relative to the host OS namespace, not the Gateway's own namespace.
Matching volume map required: The Gateway process also writes heartbeat and bridge files to that workspace path. Give the Gateway container an identical volume map (-v /home/user/.openclaw:/home/user/.openclaw) so the same host path resolves correctly from inside the Gateway container too. Mismatched mappings surface as EACCES when the Gateway tries to write its heartbeat.
Codex code mode: when an OpenClaw sandbox is active, OpenClaw disables Codex app-server native Code Mode, user MCP servers, and app-backed plugin execution for that turn (those run from the Gateway-host app-server process, not the OpenClaw sandbox backend), unless the sandbox tool policy exposes the required tools and you opt into the experimental sandbox exec-server path. Shell access then routes through OpenClaw sandbox-backed tools such as sandbox_exec and sandbox_process. Do not mount the host Docker socket into agent sandbox containers or custom Codex sandboxes. See Codex Harness for the full behavior.

Sandboxed browser

주요 항목:

The sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it. Configure via agents.defaults.sandbox.browser.autoStart (default true) and autoStartTimeoutMs (default 12s).
Sandbox browser containers use a dedicated Docker network (openclaw-sandbox-browser) instead of the global bridge network. Configure with agents.defaults.sandbox.browser.network.
agents.defaults.sandbox.browser.cdpSourceRange restricts container-edge CDP ingress with a CIDR allowlist (for example 172.21.0.1/32).
noVNC observer access is password-protected by default; OpenClaw emits a short-lived token URL that serves a local bootstrap page and opens noVNC with the password in the URL fragment (not query string or header logs).
agents.defaults.sandbox.browser.allowHostControl (default false) lets sandboxed sessions target the host browser explicitly.
Optional allowlists gate target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

SSH backend

Use backend: "ssh" to sandbox exec, file tools, and media reads on an arbitrary SSH-accessible machine.

주요 항목:

Lifecycle: OpenClaw creates a per-scope remote root under sandbox.ssh.workspaceRoot. On first use after create or recreate, it seeds that remote workspace from the local workspace once. After that, exec, read, write, edit, apply_patch, prompt media reads, and inbound media staging run directly against the remote workspace over SSH. OpenClaw does not sync remote changes back to the local workspace automatically.
Authentication material: identityFile/certificateFile/knownHostsFile reference existing local files. identityData/certificateData/knownHostsData accept inline strings or SecretRefs, resolved through the normal secrets runtime snapshot, written to temp files with mode 0600, and deleted when the SSH session ends. If both a *File and *Data variant are set for the same item, *Data wins for that session.
Remote-canonical consequences: the remote SSH workspace becomes the real sandbox state after the initial seed. Host-local edits made outside OpenClaw after the seed step are not visible remotely until you recreate the sandbox. openclaw sandbox recreate deletes the per-scope remote root and seeds again from local on next use. Browser sandboxing is not supported on this backend, and sandbox.docker.* settings do not apply to it.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Or use SecretRefs / inline contents instead of local files:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

OpenShell backend

Use backend: "openshell" to sandbox tools in an OpenShell-managed remote environment. OpenShell reuses the same SSH transport and remote filesystem bridge as the generic SSH backend, and adds OpenShell lifecycle (sandbox create/get/delete/ssh-config) plus an optional mirror workspace sync mode.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
        },
      },
    },
  },
}

Workspace access

agents.defaults.sandbox.workspaceAccess controls what the sandbox can see:

Value	Behavior
`none` (default)	Tools see an isolated sandbox workspace under `~/.openclaw/sandboxes`.
`ro`	Mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`).
`rw`	Mounts the agent workspace read/write at `/workspace`.

Multiple folders for one agent

Use Docker bind mounts when one sandboxed agent needs more than its primary workspace. Each entry maps a host folder to a container path with an explicit access mode:

주요 항목:

ro makes the mounted folder read-only inside the sandbox.
rw lets sandboxed tools and processes change the host folder.
The container path is the path the agent uses. Host paths are not exposed automatically.

Setting	Controls
`workspaceAccess: "none"`	Uses an isolated sandbox workspace; does not expose the agent workspace.
`workspaceAccess: "ro"`	Mounts the agent workspace read-only at `/agent`.
`workspaceAccess: "rw"`	Mounts the agent workspace read/write at `/workspace`.
`docker.binds` entry `:ro`/`:rw`	Controls only that additional host folder at its configured container path.

host-directory:container-directory:ro
host-directory:container-directory:rw

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
      },
    },
    list: [
      {
        id: "research",
        workspace: "/srv/openclaw/research-workspace",
        sandbox: {
          workspaceAccess: "rw",
          docker: {
            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],
            // Required because these sources are outside the agent workspace.
            dangerouslyAllowExternalBindSources: true,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

Other bind behavior

agents.defaults.sandbox.docker.binds configures global mounts. The format is the same host:container:mode form (예를 들어, "/home/user/source:/source:rw").

주요 항목:

Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (:ro or :rw).
OpenClaw blocks dangerous bind sources by default: system paths (/etc, /proc, /sys, /dev, /root, /boot), Docker socket directories (/run, /var/run, and their docker.sock variants), and common home-directory credential roots (~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm, ~/.ssh).
Validation normalizes the source path, then resolves it again through the deepest existing ancestor before re-checking blocked paths and allowed roots, so symlink-parent escapes fail closed even when the final leaf doesn't exist yet (e.g. /workspace/run-link/new-file still resolves as /var/run/... if run-link points there).
Bind targets that shadow the reserved container mount points (/workspace, /agent) are also blocked by default; override with agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets: true.
Bind sources outside the workspace/agent-workspace allowlisted roots are blocked by default; override with agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources: true. Allowed roots are canonicalized the same way, so a path that only looks inside the allowlist before symlink resolution is still rejected as outside allowed roots.
Sensitive mounts (secrets, SSH keys, service credentials) should be :ro unless absolutely required.
Combine with workspaceAccess: "ro" if you only need read access to the workspace; bind modes stay independent.
See Sandbox vs Tool Policy vs Elevated for how binds interact with tool policy and elevated exec.

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

Images and setup

Default Docker image: openclaw-sandbox:bookworm-slim

주요 항목:

--remote-debugging-address=127.0.0.1
--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
--user-data-dir=${HOME}/.chrome
--no-first-run
--no-default-browser-check
--disable-dev-shm-usage
--disable-background-networking
--disable-breakpad
--disable-crash-reporter
--no-zygote
--metrics-recording-only
--password-store=basic
--use-mock-keychain
--headless=new when browser.headless is enabled.
--no-sandbox --disable-setuid-sandbox when browser.noSandbox is enabled.
--disable-3d-apis, --disable-gpu, --disable-software-rasterizer by default; these graphics-hardening flags help containers without GPU support. Set OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 if your workload needs WebGL or other 3D features.
--disable-extensions by default; set OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 for extension-reliant flows.
--renderer-process-limit=2 by default; controlled by OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, where 0 keeps Chromium's default.
network: "host" is blocked.
network: "container:<id>" is blocked by default (namespace join bypass risk).
Break-glass override: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
    FROM debian:bookworm-slim
    ENV DEBIAN_FRONTEND=noninteractive
    RUN apt-get update && apt-get install -y --no-install-recommends \
      bash ca-certificates curl git jq python3 ripgrep \
      && rm -rf /var/lib/apt/lists/*
    RUN useradd --create-home --shell /bin/bash sandbox
    USER sandbox
    WORKDIR /home/sandbox
    CMD ["sleep", "infinity"]
    DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

setupCommand (one-time container setup)

setupCommand runs once after the sandbox container is created (not on every run). It executes inside the container via sh -lc.

주요 항목:

Global: agents.defaults.sandbox.docker.setupCommand
Per-agent: agents.entries.*.sandbox.docker.setupCommand
Default docker.network is "none" (no egress), so package installs will fail.
docker.network: "container:<id>" requires dangerouslyAllowContainerNamespaceJoin: true and is break-glass only.
readOnlyRoot: true prevents writes; set readOnlyRoot: false or bake a custom image.
user must be root for package installs (omit user or set user: "0:0").
Sandbox exec does not inherit host process.env. Use agents.defaults.sandbox.docker.env (or a custom image) for skill API keys.
Values in agents.defaults.sandbox.docker.env are passed as explicit Docker container environment variables. Anyone with Docker daemon access can inspect them with Docker metadata commands such as docker inspect. Use a custom image, mounted secret file, or another secret delivery path if that metadata exposure is not acceptable.

Tool policy and escape hatches

Tool allow/deny policies still apply before sandbox rules. If a tool is denied globally or per-agent, sandboxing doesn't bring it back.

주요 항목:

openclaw sandbox list shows sandbox containers, status, image match, age, idle time, and associated session/agent.
openclaw sandbox explain [--session <key>] [--agent <id>] inspects effective sandbox mode, host workspace, runtime workdir, Docker mounts, tool policy, and fix-it config keys. Its workspaceRoot field remains the configured sandbox root; effectiveHostWorkspaceRoot shows where the active workspace actually lives.
openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] removes containers/environments so they get recreated with current config on next use.
See Sandbox vs Tool Policy vs Elevated for the "why is this blocked?" mental model.

Multi-agent overrides

Each agent can override sandbox + tools: agents.entries.*.sandbox and agents.entries.*.tools (plus agents.entries.*.tools.sandbox.tools for sandbox tool policy). See Multi-Agent Sandbox & Tools for precedence.

Minimal enable example

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/sandboxing
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Or use SecretRefs / inline contents instead of local files:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
        },
      },
    },
  },
}

host-directory:container-directory:ro
host-directory:container-directory:rw

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
      },
    },
    list: [
      {
        id: "research",
        workspace: "/srv/openclaw/research-workspace",
        sandbox: {
          workspaceAccess: "rw",
          docker: {
            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],
            // Required because these sources are outside the agent workspace.
            dangerouslyAllowExternalBindSources: true,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

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

Sandboxing

핵심 요약

How OpenClaw sandboxing works: modes, scopes, workspace access, and images

한국어 가이드 범위: gateway/sandboxing 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

What gets sandboxed
Modes, scope, and backend
Docker backend
Sandboxed browser
SSH backend
OpenShell backend
Workspace access
Multiple folders for one agent
Other bind behavior
Images and setup
setupCommand (one-time container setup)
Tool policy and escape hatches
Multi-agent overrides
Minimal enable example
관련 문서

상세 내용

본문

What gets sandboxed

주요 항목:

Tool execution: exec, read, write, edit, apply_patch, process, etc.
The optional sandboxed browser (agents.defaults.sandbox.browser).
The Gateway process itself.
Any tool explicitly allowed to run outside the sandbox via tools.elevated. Elevated exec bypasses sandboxing and runs on the configured escape path (gateway by default, or node when the exec target is node). If sandboxing is off, tools.elevated changes nothing since exec already runs on the host. See Elevated Mode.

Modes, scope, and backend

Three independent settings control sandbox behavior:

주요 항목:

off: no sandboxing.
non-main: sandbox every session except the agent's main session. The main session key is always agent:<agentId>:main (or global when session.scope is "global"); it is not configurable. Group/channel sessions use their own keys, so they always count as non-main and get sandboxed.
all: every session runs in a sandbox.
agent: one container per agent.
session: one container per session.
shared: one container shared by all sandboxed sessions (per-agent docker/ssh/browser overrides are ignored under this scope).

Setting	Key	Values	Default
Mode	`agents.defaults.sandbox.mode`	`off`, `non-main`, `all`	`off`
Scope	`agents.defaults.sandbox.scope`	`agent`, `session`, `shared`	`agent`
Backend	`agents.defaults.sandbox.backend`	`docker`, `ssh`, `openshell`	`docker`

	Docker	SSH	OpenShell
Where it runs	Local container	Any SSH-accessible host	OpenShell managed sandbox
Setup	`scripts/sandbox-setup.sh`	SSH key + target host	OpenShell plugin enabled
Workspace model	Bind-mount or copy	Remote-canonical (seed once)	`mirror` or `remote`
Network control	`docker.network` (default: none)	Depends on remote host	Depends on OpenShell
Browser sandbox	Supported	Not supported	Not supported yet
Bind mounts	`docker.binds`	N/A	N/A
Best for	Local dev, full isolation	Offloading to a remote machine	Managed remote sandboxes with optional two-way sync

Docker backend

Docker is the default backend once sandboxing is enabled. It runs tools and sandbox browsers locally through the Docker daemon socket (/var/run/docker.sock); isolation comes from Docker namespaces.

주요 항목:

Config requires host paths: openclaw.json workspace must contain the host's absolute path (e.g. /home/user/.openclaw/workspaces), not the internal Gateway container path. The Docker daemon evaluates paths relative to the host OS namespace, not the Gateway's own namespace.
Matching volume map required: The Gateway process also writes heartbeat and bridge files to that workspace path. Give the Gateway container an identical volume map (-v /home/user/.openclaw:/home/user/.openclaw) so the same host path resolves correctly from inside the Gateway container too. Mismatched mappings surface as EACCES when the Gateway tries to write its heartbeat.
Codex code mode: when an OpenClaw sandbox is active, OpenClaw disables Codex app-server native Code Mode, user MCP servers, and app-backed plugin execution for that turn (those run from the Gateway-host app-server process, not the OpenClaw sandbox backend), unless the sandbox tool policy exposes the required tools and you opt into the experimental sandbox exec-server path. Shell access then routes through OpenClaw sandbox-backed tools such as sandbox_exec and sandbox_process. Do not mount the host Docker socket into agent sandbox containers or custom Codex sandboxes. See Codex Harness for the full behavior.

Sandboxed browser

주요 항목:

The sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it. Configure via agents.defaults.sandbox.browser.autoStart (default true) and autoStartTimeoutMs (default 12s).
Sandbox browser containers use a dedicated Docker network (openclaw-sandbox-browser) instead of the global bridge network. Configure with agents.defaults.sandbox.browser.network.
agents.defaults.sandbox.browser.cdpSourceRange restricts container-edge CDP ingress with a CIDR allowlist (for example 172.21.0.1/32).
noVNC observer access is password-protected by default; OpenClaw emits a short-lived token URL that serves a local bootstrap page and opens noVNC with the password in the URL fragment (not query string or header logs).
agents.defaults.sandbox.browser.allowHostControl (default false) lets sandboxed sessions target the host browser explicitly.
Optional allowlists gate target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.

SSH backend

Use backend: "ssh" to sandbox exec, file tools, and media reads on an arbitrary SSH-accessible machine.

주요 항목:

Lifecycle: OpenClaw creates a per-scope remote root under sandbox.ssh.workspaceRoot. On first use after create or recreate, it seeds that remote workspace from the local workspace once. After that, exec, read, write, edit, apply_patch, prompt media reads, and inbound media staging run directly against the remote workspace over SSH. OpenClaw does not sync remote changes back to the local workspace automatically.
Authentication material: identityFile/certificateFile/knownHostsFile reference existing local files. identityData/certificateData/knownHostsData accept inline strings or SecretRefs, resolved through the normal secrets runtime snapshot, written to temp files with mode 0600, and deleted when the SSH session ends. If both a *File and *Data variant are set for the same item, *Data wins for that session.
Remote-canonical consequences: the remote SSH workspace becomes the real sandbox state after the initial seed. Host-local edits made outside OpenClaw after the seed step are not visible remotely until you recreate the sandbox. openclaw sandbox recreate deletes the per-scope remote root and seeds again from local on next use. Browser sandboxing is not supported on this backend, and sandbox.docker.* settings do not apply to it.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Or use SecretRefs / inline contents instead of local files:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

OpenShell backend

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
        },
      },
    },
  },
}

Workspace access

agents.defaults.sandbox.workspaceAccess controls what the sandbox can see:

Value	Behavior
`none` (default)	Tools see an isolated sandbox workspace under `~/.openclaw/sandboxes`.
`ro`	Mounts the agent workspace read-only at `/agent` (disables `write`/`edit`/`apply_patch`).
`rw`	Mounts the agent workspace read/write at `/workspace`.

Multiple folders for one agent

Use Docker bind mounts when one sandboxed agent needs more than its primary workspace. Each entry maps a host folder to a container path with an explicit access mode:

주요 항목:

ro makes the mounted folder read-only inside the sandbox.
rw lets sandboxed tools and processes change the host folder.
The container path is the path the agent uses. Host paths are not exposed automatically.

Setting	Controls
`workspaceAccess: "none"`	Uses an isolated sandbox workspace; does not expose the agent workspace.
`workspaceAccess: "ro"`	Mounts the agent workspace read-only at `/agent`.
`workspaceAccess: "rw"`	Mounts the agent workspace read/write at `/workspace`.
`docker.binds` entry `:ro`/`:rw`	Controls only that additional host folder at its configured container path.

host-directory:container-directory:ro
host-directory:container-directory:rw

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
      },
    },
    list: [
      {
        id: "research",
        workspace: "/srv/openclaw/research-workspace",
        sandbox: {
          workspaceAccess: "rw",
          docker: {
            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],
            // Required because these sources are outside the agent workspace.
            dangerouslyAllowExternalBindSources: true,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

Other bind behavior

agents.defaults.sandbox.docker.binds configures global mounts. The format is the same host:container:mode form (예를 들어, "/home/user/source:/source:rw").

주요 항목:

Binds bypass the sandbox filesystem: they expose host paths with whatever mode you set (:ro or :rw).
OpenClaw blocks dangerous bind sources by default: system paths (/etc, /proc, /sys, /dev, /root, /boot), Docker socket directories (/run, /var/run, and their docker.sock variants), and common home-directory credential roots (~/.aws, ~/.cargo, ~/.config, ~/.docker, ~/.gnupg, ~/.netrc, ~/.npm, ~/.ssh).
Validation normalizes the source path, then resolves it again through the deepest existing ancestor before re-checking blocked paths and allowed roots, so symlink-parent escapes fail closed even when the final leaf doesn't exist yet (e.g. /workspace/run-link/new-file still resolves as /var/run/... if run-link points there).
Bind targets that shadow the reserved container mount points (/workspace, /agent) are also blocked by default; override with agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets: true.
Bind sources outside the workspace/agent-workspace allowlisted roots are blocked by default; override with agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources: true. Allowed roots are canonicalized the same way, so a path that only looks inside the allowlist before symlink resolution is still rejected as outside allowed roots.
Sensitive mounts (secrets, SSH keys, service credentials) should be :ro unless absolutely required.
Combine with workspaceAccess: "ro" if you only need read access to the workspace; bind modes stay independent.
See Sandbox vs Tool Policy vs Elevated for how binds interact with tool policy and elevated exec.

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

Images and setup

Default Docker image: openclaw-sandbox:bookworm-slim

주요 항목:

--remote-debugging-address=127.0.0.1
--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>
--user-data-dir=${HOME}/.chrome
--no-first-run
--no-default-browser-check
--disable-dev-shm-usage
--disable-background-networking
--disable-breakpad
--disable-crash-reporter
--no-zygote
--metrics-recording-only
--password-store=basic
--use-mock-keychain
--headless=new when browser.headless is enabled.
--no-sandbox --disable-setuid-sandbox when browser.noSandbox is enabled.
--disable-3d-apis, --disable-gpu, --disable-software-rasterizer by default; these graphics-hardening flags help containers without GPU support. Set OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 if your workload needs WebGL or other 3D features.
--disable-extensions by default; set OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 for extension-reliant flows.
--renderer-process-limit=2 by default; controlled by OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>, where 0 keeps Chromium's default.
network: "host" is blocked.
network: "container:<id>" is blocked by default (namespace join bypass risk).
Break-glass override: agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true.

scripts/sandbox-setup.sh

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
    FROM debian:bookworm-slim
    ENV DEBIAN_FRONTEND=noninteractive
    RUN apt-get update && apt-get install -y --no-install-recommends \
      bash ca-certificates curl git jq python3 ripgrep \
      && rm -rf /var/lib/apt/lists/*
    RUN useradd --create-home --shell /bin/bash sandbox
    USER sandbox
    WORKDIR /home/sandbox
    CMD ["sleep", "infinity"]
    DOCKERFILE

scripts/sandbox-common-setup.sh

scripts/sandbox-browser-setup.sh

setupCommand (one-time container setup)

setupCommand runs once after the sandbox container is created (not on every run). It executes inside the container via sh -lc.

주요 항목:

Global: agents.defaults.sandbox.docker.setupCommand
Per-agent: agents.entries.*.sandbox.docker.setupCommand
Default docker.network is "none" (no egress), so package installs will fail.
docker.network: "container:<id>" requires dangerouslyAllowContainerNamespaceJoin: true and is break-glass only.
readOnlyRoot: true prevents writes; set readOnlyRoot: false or bake a custom image.
user must be root for package installs (omit user or set user: "0:0").
Sandbox exec does not inherit host process.env. Use agents.defaults.sandbox.docker.env (or a custom image) for skill API keys.
Values in agents.defaults.sandbox.docker.env are passed as explicit Docker container environment variables. Anyone with Docker daemon access can inspect them with Docker metadata commands such as docker inspect. Use a custom image, mounted secret file, or another secret delivery path if that metadata exposure is not acceptable.

Tool policy and escape hatches

Tool allow/deny policies still apply before sandbox rules. If a tool is denied globally or per-agent, sandboxing doesn't bring it back.

주요 항목:

openclaw sandbox list shows sandbox containers, status, image match, age, idle time, and associated session/agent.
openclaw sandbox explain [--session <key>] [--agent <id>] inspects effective sandbox mode, host workspace, runtime workdir, Docker mounts, tool policy, and fix-it config keys. Its workspaceRoot field remains the configured sandbox root; effectiveHostWorkspaceRoot shows where the active workspace actually lives.
openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] removes containers/environments so they get recreated with current config on next use.
See Sandbox vs Tool Policy vs Elevated for the "why is this blocked?" mental model.

Multi-agent overrides

Minimal enable example

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

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/sandboxing
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // Or use SecretRefs / inline contents instead of local files:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote", // mirror | remote
        },
      },
    },
  },
}

host-directory:container-directory:ro
host-directory:container-directory:rw

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
      },
    },
    list: [
      {
        id: "research",
        workspace: "/srv/openclaw/research-workspace",
        sandbox: {
          workspaceAccess: "rw",
          docker: {
            binds: ["/srv/shared/reference:/reference:ro", "/srv/shared/drafts:/drafts:rw"],
            // Required because these sources are outside the agent workspace.
            dangerouslyAllowExternalBindSources: true,
          },
        },
      },
    ],
  },
}

openclaw sandbox recreate --agent research

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

Sandboxing

핵심 요약

문서 구성

상세 내용

본문

What gets sandboxed

Modes, scope, and backend

Docker backend

Sandboxed browser

SSH backend

OpenShell backend

Workspace access

Multiple folders for one agent

Other bind behavior

Images and setup

setupCommand (one-time container setup)

Tool policy and escape hatches

Multi-agent overrides

Minimal enable example

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Sandboxing

핵심 요약

문서 구성

상세 내용

본문

What gets sandboxed

Modes, scope, and backend

Docker backend

Sandboxed browser

SSH backend

OpenShell backend

Workspace access

Multiple folders for one agent

Other bind behavior

Images and setup

setupCommand (one-time container setup)

Tool policy and escape hatches

Multi-agent overrides

Minimal enable example

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드