文档

OpenShell

OpenShell is a managed sandbox backend for OpenClaw. Instead of running Docker
containers locally, OpenClaw delegates sandbox lifecycle to the openshell CLI,
which provisions remote environments with SSH-based command execution.

The OpenShell plugin reuses the same core SSH transport and remote filesystem
bridge as the generic SSH backend. It adds
OpenShell-specific lifecycle (sandbox create/get/delete, sandbox ssh-config)
and an optional mirror workspace mode.

Prerequisites

The openshell CLI installed and on PATH (or set a custom path via
plugins.entries.openshell.config.command)
An OpenShell account with sandbox access
OpenClaw Gateway 网关 running on the host

快速开始

Enable the plugin and set the sandbox backend:

“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
agents: {
defaults: {
sandbox: {
mode: “all”,
backend: “openshell”,
scope: “session”,
workspaceAccess: “rw”,
},
},
},
plugins: {
entries: {
openshell: {
enabled: true,
config: {
from: “openclaw”,
mode: “remote”,
},
},
},
},
}


2. Restart the Gateway. On the next agent turn, OpenClaw creates an OpenShell
   sandbox and routes tool execution through it.

3. Verify:

```bash  theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw sandbox list
openclaw sandbox explain

Workspace modes

This is the most important decision when using OpenShell.

`mirror`

Use plugins.entries.openshell.config.mode: "mirror" when you want the local
workspace to stay canonical.

Behavior:

Before exec, OpenClaw syncs the local workspace into the OpenShell sandbox.
After exec, OpenClaw syncs the remote workspace back to the local workspace.
File tools still operate through the sandbox bridge, but the local workspace
remains the source of truth between turns.

Best for:

You edit files locally outside OpenClaw and want those changes visible in the
sandbox automatically.
You want the OpenShell sandbox to behave as much like the Docker backend as
possible.
You want the host workspace to reflect sandbox writes after each exec turn.

Tradeoff: extra sync cost before and after each exec.

`remote`

Use plugins.entries.openshell.config.mode: "remote" when you want the
OpenShell workspace to become canonical.

Behavior:

When the sandbox is first created, OpenClaw seeds the remote workspace from
the local workspace once.
After that, exec, read, write, edit, and apply_patch operate
directly against the remote OpenShell workspace.
OpenClaw does not sync remote changes back into the local workspace.
Prompt-time media reads still work because file and media tools read through
the sandbox bridge.

Best for:

The sandbox should live primarily on the remote side.
You want lower per-turn sync overhead.
You do not want host-local edits to silently overwrite remote sandbox state.

重要说明: if you edit files on the host outside OpenClaw after the initial seed,
the remote sandbox does not see those changes. Use
openclaw sandbox recreate to re-seed.

Choosing a mode

	`mirror`	`remote`
Canonical workspace	Local host	Remote OpenShell
Sync direction	Bidirectional (each exec)	One-time seed
Per-turn overhead	Higher (upload + download)	Lower (direct remote ops)
Local edits visible?	Yes, on next exec	No, until recreate
Best for	Development workflows	Long-running agents, CI

配置说明 reference

All OpenShell config lives under plugins.entries.openshell.config:

Key	Type	Default	Description
`mode`	`"mirror"` or `"remote"`	`"mirror"`	Workspace sync mode
`command`	`string`	`"openshell"`	Path or name of the `openshell` CLI
`from`	`string`	`"openclaw"`	Sandbox source for first-time create
`gateway`	`string`	—	OpenShell 网关 name (`--gateway`)
`gatewayEndpoint`	`string`	—	OpenShell 网关 endpoint URL (`--gateway-endpoint`)
`policy`	`string`	—	OpenShell policy ID for sandbox creation
`providers`	`string[]`	`[]`	Provider names to attach when sandbox is created
`gpu`	`boolean`	`false`	Request GPU resources
`autoProviders`	`boolean`	`true`	Pass `--auto-providers` during sandbox create
`remoteWorkspaceDir`	`string`	`"/sandbox"`	Primary writable workspace inside the sandbox
`remoteAgentWorkspaceDir`	`string`	`"/agent"`	Agent workspace mount path (for read-only access)
`timeoutSeconds`	`number`	`120`	Timeout for `openshell` CLI operations

Sandbox-level settings (mode, scope, workspaceAccess) are configured under
agents.defaults.sandbox as with any backend. See
Sandboxing for the full matrix.

Examples

Minimal remote setup

“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
agents: {
defaults: {
sandbox: {
mode: “all”,
backend: “openshell”,
},
},
},
plugins: {
entries: {
openshell: {
enabled: true,
config: {
from: “openclaw”,
mode: “remote”,
},
},
},
},
}


### Mirror mode with GPU

```json5  theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}

Per-agent OpenShell with custom 网关

“`json5 theme={“theme”:{“light”:”min-light”,”dark”:”min-dark”}}
{
agents: {
defaults: {
sandbox: { mode: “off” },
},
list: [
{
id: “researcher”,
sandbox: {
mode: “all”,
backend: “openshell”,
scope: “agent”,
workspaceAccess: “rw”,
},
},
],
},
plugins: {
entries: {
openshell: {
enabled: true,
config: {
from: “openclaw”,
mode: “remote”,
网关: “lab”,
网关Endpoint: “https://lab.example”,
policy: “strict”,
},
},
},
},
}


## Lifecycle management

OpenShell sandboxes are managed through the normal sandbox CLI:

```bash  theme={"theme":{"light":"min-light","dark":"min-dark"}}
# List all sandbox runtimes (Docker + OpenShell)
openclaw sandbox list

# Inspect effective policy
openclaw sandbox explain

# Recreate (deletes remote workspace, re-seeds on next use)
openclaw sandbox recreate --all

For remote mode, recreate is especially important: it deletes the canonical
remote workspace for that scope. The next use seeds a fresh remote workspace from
the local workspace.

For mirror mode, recreate mainly resets the remote execution environment because
the local workspace remains canonical.

When to recreate

Recreate after changing any of these:

agents.defaults.sandbox.backend
plugins.entries.openshell.config.from
plugins.entries.openshell.config.mode
plugins.entries.openshell.config.policy

bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw sandbox recreate --all

Current limitations

Sandbox browser is not supported on the OpenShell backend.
sandbox.docker.binds does not apply to OpenShell.
Docker-specific runtime knobs under sandbox.docker.* apply only to the Docker
backend.

How it works

OpenClaw calls openshell sandbox create (with --from, --gateway,
--policy, --providers, --gpu flags as configured).
OpenClaw calls openshell sandbox ssh-config <name> to get SSH connection
details for the sandbox.
Core writes the SSH config to a temp file and opens an SSH session using the
same remote filesystem bridge as the generic SSH backend.
In mirror mode: sync local to remote before exec, run, sync back after exec.
In remote mode: seed once on create, then operate directly on the remote
workspace.