#9657: fix(doctor): warn when sandbox mode enabled without Docker
commands
size: S
trusted-contributor
experienced-contributor
Cluster:
Sandbox Enhancements and Fixes
## Summary
Fixes #9543
When sandbox mode is enabled (`agents.defaults.sandbox.mode: "non-main"` or `"all"`) but Docker is not available, OpenClaw previously showed a mild message: "Docker not available; skipping sandbox image checks." This was misleading because it implied everything was fine when in fact isolated sessions would fail.
This PR improves the warning to:
- Clearly state sandbox mode is enabled but won't function
- Explain Docker is required for sandbox mode
- Warn that isolated sessions (cron jobs, sub-agents) will fail
- Provide actionable remediation options
**Before:**
```
Docker not available; skipping sandbox image checks.
```
**After:**
```
Sandbox mode is enabled (mode: "non-main") but Docker is not available.
Docker is required for sandbox mode to function.
Isolated sessions (cron jobs, sub-agents) will fail without Docker.
Options:
- Install Docker and restart the gateway
- Disable sandbox mode: openclaw config set agents.defaults.sandbox.mode off
```
## Test plan
- [x] Added test `doctor-sandbox.warns-sandbox-enabled-without-docker.test.ts` with 4 test cases
- [x] All tests pass
- [x] Build passes
- [x] Lint passes
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This change updates `maybeRepairSandboxImages` (`src/commands/doctor-sandbox.ts`) so that when sandbox mode is enabled but Docker is unavailable, the doctor output clearly warns that sandboxing will not work and that isolated sessions (e.g. cron jobs / sub-agents) will fail, with remediation steps (install Docker + restart gateway, or disable sandbox mode).
A new Vitest suite (`src/commands/doctor-sandbox.warns-sandbox-enabled-without-docker.test.ts`) exercises the new warning behavior across sandbox modes (`non-main`, `all`, `off`) and the Docker-available case by mocking the Docker version check.
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk.
- Changes are localized to doctor messaging when Docker is unavailable, with a straightforward early return and accompanying tests covering key configurations.
- No files require special attention
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#23400: Onboarding: set sandbox defaults when Docker is available
by bmendonca3 · 2026-02-22
78.8%
#13873: fix(sandbox): prevent Windows PATH from poisoning docker exec
by alessandrorodi · 2026-02-11
78.5%
#8186: fix(sandbox): validate setupCommand to prevent shell injection
by yubrew · 2026-02-03
78.1%
#4226: Fix/sandbox containerworkdir rw access
by ozgur-polat · 2026-01-29
78.0%
#20991: fix(sandbox): fall back to gateway UID:GID when no user is configur...
by cluster2600 · 2026-02-19
77.8%
#4897: fix: config logic issues (#4689, #4654)
by lailoo · 2026-01-30
77.3%
#11878: fix: add missing error handler to execDocker child process
by Yida-Dev · 2026-02-08
76.5%
#16509: Fix sandbox path validation rejecting Docker bind mount paths
by Clawborn · 2026-02-14
76.5%
#8161: fix(sandbox): block dangerous environment variables from Docker con...
by yubrew · 2026-02-03
76.2%
#16922: fix: remove incorrect sandbox file tool guidance
by carrotRakko · 2026-02-15
76.1%