How to Use OpenClaw with OpenShell Sandboxes

OpenShell is for operators who want OpenClaw tool execution in managed remote sandboxes instead of local Docker containers. The Gateway still runs on your host, but file tools and exec can be routed through an OpenShell-provisioned environment. That can reduce local setup burden and make long-running or remote-canonical workflows easier to operate.

30-second answer

Install the openshell CLI, enable the OpenShell plugin, set agents.defaults.sandbox.backend to openshell, choose sandbox mode and scope, then choose plugins.entries.openshell.config.mode as mirror or remote. Verify with openclaw sandbox list and openclaw sandbox explain. Remember that OpenShell does not support sandboxed browser yet.

When this pays off

Use OpenShell when Docker is not the right runtime, when you want managed remote environments, or when a team prefers sandbox lifecycle outside the Gateway host. It is especially relevant for coding and ops agents that need tool execution but should not run directly on a developer laptop or production server.

Operator runbook

1. Check prerequisites first. The docs require the openshell CLI on PATH or a custom command path in plugins.entries.openshell.config.command, an OpenShell account with sandbox access, and a running OpenClaw Gateway. If the CLI cannot create sandboxes, OpenClaw cannot paper over that layer.
2. Enable the backend in agent sandbox config. Set agents.defaults.sandbox.mode to all or the scope you need, backend to openshell, scope to session or agent, and workspaceAccess according to your risk model. The Gateway stays local; tool execution is what moves into the sandbox backend.
3. Enable the openshell plugin. The docs show plugins.entries.openshell.enabled true with config such as from: openclaw and mode: remote. Restart the Gateway so the plugin and sandbox backend are active on the next agent turn.
4. Choose remote or mirror carefully. remote seeds the OpenShell workspace once and then treats the remote workspace as canonical. mirror keeps the local workspace canonical by syncing local to remote before exec and syncing remote back after exec. The wrong choice can make edits appear missing or overwritten.
5. Know current limitations. OpenShell reuses the SSH transport and remote filesystem bridge, but sandboxed browser is not supported yet and Docker-specific bind/runtime knobs do not apply. If your workflow depends on browser automation inside the sandbox, use a supported backend or redesign the tool boundary.
6. Verify before trusting it. Run openclaw sandbox list and openclaw sandbox explain. Then start a low-risk agent turn that reads and writes a test file inside the expected workspace. Confirm the file behavior matches the selected workspace mode before real project work starts.

Verification

The proof is a Gateway that starts cleanly, an OpenShell sandbox visible in sandbox list, sandbox explain showing openshell as the backend, and a test exec/file operation happening in the sandbox rather than on the host. For mirror mode, verify sync-back. For remote mode, verify host-local edits after seeding do not magically appear until recreate.

Common mistakes

Do not assume remote mode syncs host edits every turn. Do not configure Docker-specific binds and expect OpenShell to honor them. Do not enable sandboxing and forget workspaceAccess. And do not use OpenShell as a perfect security boundary; the sandboxing docs say sandboxing materially limits blast radius, not that it solves every trust problem.

Turn it into a repeatable operating system

The Playbook helps pick the right backend for each agent: host, Docker, SSH, or OpenShell. The decision depends on workspace ownership, cost, browser needs, speed, and blast radius. OpenShell is powerful when those tradeoffs are explicit.

Before rollout

Before rollout, decide whether the sandbox output must persist locally. If the answer is yes, mirror mode may fit. If the answer is no and the remote environment should be canonical, remote mode may fit. Write that choice down before real code changes happen.