diff --git a/CHANGELOG.md b/CHANGELOG.md
index 72cd7c319c3..15c068e3417 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -34,6 +34,7 @@ Docs: https://docs.openclaw.ai
- Gateway/sessions: use bounded tail reads for sessions-list transcript usage fallbacks and cap bulk title/last-message hydration, keeping large session stores responsive when rows request derived previews. Thanks @vincentkoc.
- Gateway/chat: bound chat-history transcript reads to the requested display window so large session logs no longer OOM the Gateway when clients ask for a small history page. Thanks @vincentkoc.
- Voice Call/Twilio: honor stored pre-connect TwiML before realtime webhook shortcuts and reject DTMF sequences outside conversation mode, so Meet PIN entry cannot be skipped or silently dropped. Thanks @donkeykong91 and @PfanP.
+- Docs/sandboxing: clarify that sandbox setup scripts (`sandbox-setup.sh`, `sandbox-common-setup.sh`, `sandbox-browser-setup.sh`) are only available from a source checkout, and add inline `docker build` commands for npm-installed users so sandbox image setup works without cloning the repo. Fixes #75485. Thanks @amknight.
- Google Meet/Voice Call: play Twilio Meet DTMF before opening the realtime media stream and carry the intro as the initial Voice Call message, so the greeting is generated after Meet admits the phone participant instead of racing a live-call TwiML update. Thanks @donkeykong91 and @PfanP.
- Google Meet/Voice Call: make Twilio setup preflight honor explicit `--transport twilio` and fail local/private Voice Call webhook URLs, including IPv6 loopback and unique-local forms, before joins. Thanks @donkeykong91 and @PfanP.
- Voice Call/Twilio: retry transient 21220 live-call TwiML updates and catch answered-path initial-greeting failures, so a fast answered callback no longer crashes the Gateway or drops the Twilio greeting/listen transition. (#74606) Thanks @Sivan22.
diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md
index 8849e6342e7..8f9aa861099 100644
--- a/docs/gateway/config-agents.md
+++ b/docs/gateway/config-agents.md
@@ -922,13 +922,15 @@ noVNC observer access uses VNC auth by default and OpenClaw emits a short-lived
Browser sandboxing and `sandbox.docker.binds` are Docker-only.
-Build images:
+Build images (from a source checkout):
```bash
scripts/sandbox-setup.sh # main sandbox image
scripts/sandbox-browser-setup.sh # optional browser image
```
+For npm installs without a source checkout, see [Sandboxing § Images and setup](/gateway/sandboxing#images-and-setup) for inline `docker build` commands.
+
### `agents.list` (per-agent overrides)
Use `agents.list[].tts` to give an agent its own TTS provider, voice, model,
diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md
index cc3e220eeff..4f3395e63c1 100644
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -333,7 +333,7 @@ cannot roll back unrelated user settings.
}
```
- Build the image first: `scripts/sandbox-setup.sh`
+ Build the image first — from a source checkout run `scripts/sandbox-setup.sh`, or from an npm install see the inline `docker build` command in [Sandboxing § Images and setup](/gateway/sandboxing#images-and-setup).
See [Sandboxing](/gateway/sandboxing) for the full guide and [full reference](/gateway/config-agents#agentsdefaultssandbox) for all options.
diff --git a/docs/gateway/sandboxing.md b/docs/gateway/sandboxing.md
index e953635e68a..39ad7a2f3e3 100644
--- a/docs/gateway/sandboxing.md
+++ b/docs/gateway/sandboxing.md
@@ -363,31 +363,66 @@ Example (read-only source + an extra data directory):
Default Docker image: `openclaw-sandbox:bookworm-slim`
+
+**Source checkout vs npm install**
+
+The `scripts/sandbox-setup.sh`, `scripts/sandbox-common-setup.sh`, and `scripts/sandbox-browser-setup.sh` helper scripts are only available when running from a [source checkout](https://github.com/openclaw/openclaw). They are not included in the npm package.
+
+If you installed OpenClaw via `npm install -g openclaw`, use the inline `docker build` commands shown below instead.
+
+
+ From a source checkout:
+
```bash
scripts/sandbox-setup.sh
```
+ From an npm install (no source checkout needed):
+
+ ```bash
+ docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
+ FROM debian:bookworm-slim
+ ENV DEBIAN_FRONTEND=noninteractive
+ RUN apt-get update && apt-get install -y --no-install-recommends \
+ bash ca-certificates curl git jq python3 ripgrep \
+ && rm -rf /var/lib/apt/lists/*
+ RUN useradd --create-home --shell /bin/bash sandbox
+ USER sandbox
+ WORKDIR /home/sandbox
+ CMD ["sleep", "infinity"]
+ DOCKERFILE
+ ```
+
The default image does **not** include Node. If a skill needs Node (or other runtimes), either bake a custom image or install via `sandbox.docker.setupCommand` (requires network egress + writable root + root user).
- OpenClaw does not silently substitute plain `debian:bookworm-slim` when `openclaw-sandbox:bookworm-slim` is missing. Sandbox runs that target the default image fail fast with a build instruction until you run `scripts/sandbox-setup.sh`, because the bundled image carries `python3` for sandbox write/edit helpers.
+ OpenClaw does not silently substitute plain `debian:bookworm-slim` when `openclaw-sandbox:bookworm-slim` is missing. Sandbox runs that target the default image fail fast with a build instruction until you build it, because the bundled image carries `python3` for sandbox write/edit helpers.
For a more functional sandbox image with common tooling (for example `curl`, `jq`, `nodejs`, `python3`, `git`):
+ From a source checkout:
+
```bash
scripts/sandbox-common-setup.sh
```
+ From an npm install, build the default image first (see above), then build the common image on top using the [`Dockerfile.sandbox-common`](https://github.com/openclaw/openclaw/blob/main/Dockerfile.sandbox-common) from the repository.
+
Then set `agents.defaults.sandbox.docker.image` to `openclaw-sandbox-common:bookworm-slim`.
+ From a source checkout:
+
```bash
scripts/sandbox-browser-setup.sh
```
+
+ From an npm install, build using the [`Dockerfile.sandbox-browser`](https://github.com/openclaw/openclaw/blob/main/Dockerfile.sandbox-browser) from the repository.
+
diff --git a/docs/install/ansible.md b/docs/install/ansible.md
index b9dcc686d52..732d302e322 100644
--- a/docs/install/ansible.md
+++ b/docs/install/ansible.md
@@ -202,9 +202,11 @@ This is idempotent and safe to run multiple times.
# Check sandbox image
sudo docker images | grep openclaw-sandbox
- # Build sandbox image if missing
+ # Build sandbox image if missing (requires source checkout)
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh
+ # For npm installs without a source checkout, see
+ # https://docs.openclaw.ai/gateway/sandboxing#images-and-setup
```
diff --git a/docs/install/docker.md b/docs/install/docker.md
index d7856be3c8e..d4e0864ca5a 100644
--- a/docs/install/docker.md
+++ b/docs/install/docker.md
@@ -452,18 +452,21 @@ For full configuration, images, security notes, and multi-agent profiles, see:
}
```
-Build the default sandbox image:
+Build the default sandbox image (from a source checkout):
```bash
scripts/sandbox-setup.sh
```
+For npm installs without a source checkout, see [Sandboxing § Images and setup](/gateway/sandboxing#images-and-setup) for inline `docker build` commands.
+
## Troubleshooting
Build the sandbox image with
[`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh)
+ (source checkout) or the inline `docker build` command from [Sandboxing § Images and setup](/gateway/sandboxing#images-and-setup) (npm install),
or set `agents.defaults.sandbox.docker.image` to your custom image.
Containers are auto-created per session on demand.