Managing Your OpenClaw Sandbox Containers

I have often found myself in a situation where I update a configuration file or a Docker image, but my environment keeps running the old version. It is frustrating to debug a problem only to realize the system is holding onto a stale container. If you are working with OpenClaw agents, you might run into this when your sandbox environments do not update as quickly as your code does.

The Sandbox CLI is the tool I use to fix this. It helps you manage the Docker-based containers where your agents run, making sure they stay in sync with your latest settings.

What You’ll Need

• OpenClaw installed and configured.
• Docker running on your machine.
• The openclaw CLI tool.
• A configuration file at ~/.openclaw/openclaw.json.

Quick Start

If you need to get your sandbox environments updated right now, follow these four steps.

1. Check your current settings

I always start by checking what OpenClaw thinks the current configuration is. This command shows the effective sandbox mode and workspace access.

openclaw sandbox explain

2. List your active containers

To see which containers are actually running and whether their images match your current config, use the list command.

openclaw sandbox list

3. Force a recreation

When you have changed your Docker image or setup commands, you need to clear out the old containers. I use the --all flag to wipe everything and start fresh.

openclaw sandbox recreate --all

4. Verify with JSON output

If you are building scripts or just want more detail, you can get the status of your containers in JSON format.

openclaw sandbox list --json

How to Handle Updates

When I pull a new Docker image or change the sandbox settings in openclaw.json, the existing containers do not always update automatically. Here is how I handle specific changes.

Updating Docker Images

If you pull a new version of your sandbox image, you need to tell OpenClaw to use it.

# Pull new image
docker pull openclaw-sandbox:latest
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim

# Recreate containers to apply the new image
openclaw sandbox recreate --all

Changing Agent-Specific Config

If you only changed the settings for one specific agent, like alfred, you do not have to reset everything. You can target just that agent.

openclaw sandbox recreate --agent alfred

Troubleshooting

Stale Containers

Problem: You updated your config, but the agent is still running in an old environment. Solution: OpenClaw only prunes containers after 24 hours of inactivity. To fix this immediately, use the recreate command with the force flag to skip the confirmation prompt.

openclaw sandbox recreate --all --force

Image Mismatches

Problem: The openclaw sandbox list output shows that your Docker image does not match your config. Solution: This usually happens after you edit agents.defaults.sandbox.docker.image in your JSON config. Run the recreate command to align the containers with your new configuration.

Manual Docker Cleanup Issues

Problem: You tried using docker rm manually and now OpenClaw is confused. Solution: I recommend using openclaw sandbox recreate instead of manual Docker commands. This ensures the Gateway’s container naming stays consistent even if your session keys change.

Need help getting your environment set up? Visit the AI Setup Assistant.

What’s Next

• Sandbox Documentation
• Agent Configuration
• Doctor Command