docs: clarify sandbox env + recreate guidance

docs/cli/sandbox.md

@@ -114,6 +114,9 @@ clawdbot sandbox recreate --agent alfred
 
 **Solution:** Use `clawdbot sandbox recreate` to force removal of old containers. They'll be recreated automatically with current settings when next needed.
 
+Tip: prefer `clawdbot sandbox recreate` over manual `docker rm`. It uses the
+Gateway’s container naming and avoids mismatches when scope/session keys change.
+
 ## Configuration
 
 Sandbox settings live in `~/.clawdbot/clawdbot.json` under `agents.defaults.sandbox` (per-agent overrides go in `agents.list[].sandbox`):

docs/gateway/sandboxing.md

@@ -105,6 +105,11 @@ Build it once:
 scripts/sandbox-setup.sh
 ```
 
+Note: 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).
+
 Sandboxed browser image:
 ```bash
 scripts/sandbox-browser-setup.sh
@@ -129,6 +134,8 @@ Common pitfalls:
 - Default `docker.network` is `"none"` (no egress), so package installs will fail.
 - `readOnlyRoot: true` prevents writes; set `readOnlyRoot: false` or bake a custom image.
 - `user` must be root for package installs (omit `user` or set `user: "0:0"`).
+- Sandbox exec does **not** inherit host `process.env`. Use
+  `agents.defaults.sandbox.docker.env` (or a custom image) for skill API keys.
 
 ## Tool policy + escape hatches
 Tool allow/deny policies still apply before sandbox rules. If a tool is denied

docs/gateway/troubleshooting.md

@@ -87,6 +87,17 @@ WhatsApp + Telegram channels require **Node**; Bun is unsupported. If your
 service was installed with Bun or a version-managed Node path, run `clawdbot doctor`
 to migrate to a system Node install.
 
+### Skill missing API key in sandbox
+
+**Symptom:** Skill works on host but fails in sandbox with missing API key.
+
+**Why:** sandboxed exec runs inside Docker and does **not** inherit host `process.env`.
+
+**Fix:**
+- set `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)
+- or bake the key into your custom sandbox image
+- then run `clawdbot sandbox recreate --agent <id>` (or `--all`)
+
 ### Service Running but Port Not Listening
 
 If the service reports **running** but nothing is listening on the gateway port,

docs/tools/skills-config.md

@@ -62,3 +62,14 @@ Per-skill fields:
 - Keys under `entries` map to the skill name by default. If a skill defines
   `metadata.clawdbot.skillKey`, use that key instead.
 - Changes to skills are picked up on the next agent turn when the watcher is enabled.
+
+### Sandboxed skills + env vars
+
+When a session is **sandboxed**, skill processes run inside Docker. The sandbox
+does **not** inherit the host `process.env`.
+
+Use one of:
+- `agents.defaults.sandbox.docker.env` (or per-agent `agents.list[].sandbox.docker.env`)
+- bake the env into your custom sandbox image
+
+Global `env` and `skills.entries.<skill>.env/apiKey` apply to **host** runs only.