mirror of
https://github.com/openclaw/openclaw.git
synced 2026-08-03 23:01:52 +00:00
edecdbd05e
* refactor(config): consolidate media model lists * refactor(config): unify memory configuration * refactor(config): consolidate TTS ownership * refactor(config): move typing policy to agents * refactor(config): retire product-level config surfaces * refactor(config): share scoped tool policy type * chore(config): refresh generated baselines * fix(config): honor agent typing overrides * fix(config): migrate sibling config consumers * refactor(infra): keep base64url decoder private * fix(config): strip invalid legacy TTS values * chore(config): refresh rebased baseline hash * fix(doctor): route legacy messages.tts.realtime voice to talk during tts move * refactor(config): polish final layout names * refactor(config): freeze retired tuning defaults * feat(config): add fast mode default symmetry * refactor(config): key agent entries by id * docs(config): update final layout reference * test(config): cover final layout migrations * chore(config): refresh final layout baselines * fix(config): align final layout runtime readers * fix(config): align remaining readers * fix(config): stabilize final layout migrations * fix(config): finalize config projection proof * fix(config): address final layout review * docs(release): preserve historical config names * fix(config): complete keyed agent migration * fix(config): close final migration gaps * fix(config): finish full-branch review * fix(config): complete runtime secret detection * fix(config): close final review findings * fix(config): finish canonical docs and heartbeat migration * fix(config): integrate latest main after rebase * refactor(env): isolate test-only controls * refactor(env): isolate build and development controls * refactor(env): collapse process identity indirection * refactor(env): remove duplicate config and temp aliases * docs(env): define the operator-facing allowlist * ci(env): ratchet production variable count * fix(env): remove stale provider helper import * fix(env): make ratchet sorting explicit * test(env): keep test seam in dead-code audit * test(env): cover ratchet growth and boundary; document surface budgets * docs(config): document tier-eval consolidations * docs(config): clarify speech preference ownership * test(memory): align retired tuning fixtures * refactor(memory): freeze engine heuristics * refactor(config): apply tier-eval tranche * refactor(tts): move persona shaping to providers * refactor(compaction): move prompt policy to providers * test(config): align hookified prompt fixtures * chore(deadcode): classify test-only exports * chore(github): remove unused spawn helper * chore(deadcode): classify queue diagnostics * chore(deadcode): remove unused lane snapshot export * chore(plugin-sdk): ratchet consolidated surface * fix(config): integrate latest main after rebase
126 lines
6.1 KiB
Markdown
126 lines
6.1 KiB
Markdown
---
|
|
summary: "Manage sandbox runtimes and inspect effective sandbox policy"
|
|
title: Sandbox CLI
|
|
read_when: "You are managing sandbox runtimes or debugging sandbox/tool-policy behavior."
|
|
status: 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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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).
|
|
|
|
The report keeps `workspaceRoot` as the configured sandbox root and separately shows the effective host workspace, backend runtime workdir, and Docker mount table. For `workspaceAccess: "rw"`, the effective host workspace is the agent workspace rather than a directory below `workspaceRoot`.
|
|
|
|
```bash
|
|
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.
|
|
|
|
<Tip>
|
|
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.
|
|
</Tip>
|
|
|
|
## 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) |
|
|
|
|
<Note>
|
|
Runtimes are automatically recreated when the agent is next used.
|
|
</Note>
|
|
|
|
## 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.entries.*.sandbox`):
|
|
|
|
```jsonc
|
|
{
|
|
"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
|
|
},
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
## Related
|
|
|
|
- [CLI reference](/cli)
|
|
- [Sandboxing](/gateway/sandboxing)
|
|
- [Agent workspace](/concepts/agent-workspace)
|
|
- [Doctor](/gateway/doctor): checks sandbox setup.
|