openclaw-openclaw/docs/cli/sandbox.md at cff46028f4e5b48e5fe616e648113e77f236fddf

mirror of https://github.com/openclaw/openclaw.git synced 2026-07-08 19:29:20 +08:00

Files

Peter Steinberger f7d7148cf0 docs: rewrite published docs grounded in current source (#100142 )

Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green.

Closes #100141

2026-07-05 00:32:47 -04:00

5.8 KiB

Raw Blame History

summary, title, read_when, status

summary	title	read_when	status
Manage sandbox runtimes and inspect effective sandbox policy	Sandbox CLI	You are managing sandbox runtimes or debugging sandbox/tool-policy behavior.	active

Manage sandbox runtimes for isolated agent execution: Docker containers, SSH targets, or OpenShell backends.

Commands

`openclaw sandbox list`

List sandbox runtimes with status, backend, config match, age, idle time, and associated session/agent.

openclaw sandbox list
openclaw sandbox list --browser  # browser containers only
openclaw sandbox list --json

`openclaw sandbox recreate`

Remove sandbox runtimes to force recreation with current config. Runtimes are recreated automatically the next time the agent is used.

openclaw sandbox recreate --all
openclaw sandbox recreate --agent mybot        # includes agent:mybot:* sub-sessions
openclaw sandbox recreate --session "agent:main:main"
openclaw sandbox recreate --browser --all      # only browser containers
openclaw sandbox recreate --all --force        # skip confirmation

Options:

--all: recreate all sandbox containers
--session <key>: recreate the runtime with this exact scope key (as shown by sandbox list); no short-name expansion
--agent <id>: recreate runtimes for one agent (matches agent:<id> and agent:<id>:*)
--browser: only affect browser containers
--force: skip the confirmation prompt

Pass exactly one of --all, --session, or --agent.

For ssh and OpenShell remote, recreate matters more than with Docker: the remote workspace is canonical after the initial seed, recreate deletes that canonical remote workspace for the selected scope, and the next run reseeds it from the current local workspace.

`openclaw sandbox explain`

Inspect the effective sandbox mode/scope/workspace access, sandbox tool policy, and elevated-tool gates (with fix-it config key paths).

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

Unlike recreate --session, this accepts short session names (for example main) and expands them against the resolved agent.

Why recreate is needed

Updating sandbox config does not affect running containers: existing runtimes keep their old settings, and idle runtimes are only pruned after prune.idleHours (default 24h). Regularly used agents can keep stale runtimes alive indefinitely. openclaw sandbox recreate removes the old runtime so the next use rebuilds it from current config.

Prefer `openclaw sandbox recreate` over manual backend-specific cleanup. It uses the Gateway's runtime registry and avoids mismatches when scope or session keys change.

Common triggers

Change	Command
Docker image update (`agents.defaults.sandbox.docker.image`)	`openclaw sandbox recreate --all`
Sandbox config (`agents.defaults.sandbox.*`)	`openclaw sandbox recreate --all`
SSH target/auth (`agents.defaults.sandbox.ssh.{target,workspaceRoot,identityFile,certificateFile,knownHostsFile,identityData,certificateData,knownHostsData}`)	`openclaw sandbox recreate --all`
OpenShell source/policy/mode (`plugins.entries.openshell.config.{from,mode,policy}`)	`openclaw sandbox recreate --all`
`setupCommand`	`openclaw sandbox recreate --all` (or `--agent <id>` for one agent)

Runtimes are automatically recreated when the agent is next used.

Registry migration

Sandbox runtime metadata lives in the shared SQLite state database. Older installs may have legacy registry files that regular reads no longer rewrite:

~/.openclaw/sandbox/containers.json
~/.openclaw/sandbox/browsers.json
one JSON shard per container/browser under ~/.openclaw/sandbox/containers/ or ~/.openclaw/sandbox/browsers/

Run openclaw doctor --fix to migrate valid legacy entries into SQLite. Invalid legacy files are quarantined so a corrupt old registry cannot hide current runtime entries.

Configuration

Sandbox settings live in ~/.openclaw/openclaw.json under agents.defaults.sandbox (per-agent overrides go in agents.list[].sandbox):

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all", // off, non-main, all
        "backend": "docker", // docker, ssh, openshell (plugin-provided)
        "scope": "agent", // session, agent, shared
        "docker": {
          "image": "openclaw-sandbox:bookworm-slim",
          "containerPrefix": "openclaw-sbx-",
          // ... more Docker options
        },
        "prune": {
          "idleHours": 24, // auto-prune after 24h idle
          "maxAgeDays": 7, // auto-prune after 7 days
        },
      },
    },
  },
}

5.8 KiB Raw Blame History

Commands

openclaw sandbox list

openclaw sandbox recreate

openclaw sandbox explain