OpenClaw 2026.3.x loads optional capabilities in Docker with stricter schema checks, explicit sandbox boundaries, and plugins that may now expose HTTP-routed surfaces instead of stdio-only helpers. Most regressions are small mismatches: an old setupCommand shape, an unset OPENCLAW_SANDBOX default, or route tables still pointing at pre-migration paths. This runbook orders work as: validate โ env toggle โ setupCommand โ HTTP routes โ doctor. For permission trims and onboard โ doctor โ fix on the same files, see
OpenClaw production hardening: minimal permissions, ClawHub imports, and reproducible doctor runbooks.
1. Always run config validate before you change images
Validate openclaw.json (and Compose-mounted fragments) using the same paths the container sees before you bump the image. Mount secrets and optional includes exactly as production does; validating a flat file from a developer Downloads folder hides keys that exist only in CI. Fail the pipeline on non-zero exit the way you would for Kubernetes manifests, attach the machine-readable report to the change request, and only then promote the tag. Splitting work so one PR adjusts JSON and a follow-up bumps the image makes rollbacks obvious when something still misbehaves at runtime.
2. Make OPENCLAW_SANDBOX an explicit switch in Compose and CI
Set OPENCLAW_SANDBOX=true|false explicitly in every profile โ dev overrides, staging Compose, production stacks, and GitHub Actions or Buildkite matrices โ so laptops, scheduled jobs, and one-off docker compose run shells agree. Implicit defaults produce โpasses locally, fails in CIโ when plugins lose expected filesystem visibility under the stricter path. When you must relax sandboxing for a narrow debugging window, gate it behind a named Compose profile or a branch-only workflow so the exception cannot linger on main unnoticed.
3. Normalize setupCommand so lifecycle hooks are deterministic
Prefer structured setupCommand entries with a fixed working directory and non-interactive shell; drop chained cd that depends on image layout, dedupe hooks, and move package installs to the image build when you can. One set -euo pipefail script plus a logged semver line keeps health-check flaps from re-running setup unpredictably across 2026.2.x โ 2026.3.x.
4. Plugin HTTP routes: migrate paths, then rehearse Streamable HTTP
When a plugin moves to HTTP, change manifest, Gateway route prefix, and reverse-proxy path stripping in one PR so you never land half of a migration. After deploy, curl from inside the container network, then from a tailnet peer, to separate bind-address mistakes from ACL or MagicDNS issues. Compare response codes and TLS errors at each hop โ a 401 at the proxy is not the same as a connection reset behind an idle timeout. Streamable-only timeouts or ENOENT usually mean PATH or working-directory drift between stdio and HTTP workers; rehearse the same tool invocation from both transports. For deeper transport notes see
OpenClaw MCP stdio vs Streamable HTTP, tool timeouts, and ENOENT troubleshooting.
5. Doctor-driven triage: shrink the search space in order
Run doctor only on the new image after validation passes; otherwise you burn time on network ghosts. Walk the same ordered checklist on every incident: state volume permissions and SELinux or AppArmor labels if applicable, listen-port collisions with sidecars, plugin registration versus the live route table, then outbound DNS, corporate TLS inspection, and HTTP proxies. Save stdout to the ticket so the next engineer sees the same shape; if doctor highlights an HTTP mismatch, correct routes and prefixes first, rerun doctor, and only then widen Gateway log levels.
- Volume UID/GID matches the container user?
OPENCLAW_SANDBOXmatches between shell and CI?- Legacy stdio plugin entries removed so HTTP routes are not duplicated?
6. Remote high-memory Mac: isolated rebuild beside CI
Offload heavy native rebuilds to a second high-RAM Mac: clean clone, same Node major as prod, lockfile install, then the same validate and doctor steps you run in Docker. Keep that host off the default self-hosted pool if possible โ sharing a worktree with a runner that constantly deletes node_modules creates flaky compiles that masquerade as OpenClaw bugs. Prefer maintenance windows or opt-in runner labels so burst rebuilds do not overlap peak PR fan-out; snapshot or prune DerivedData and temp dirs on the same cadence as CI so disk pressure does not starve both roles. Queue and disk patterns:
large-repo cold starts, blobless Git, and queue isolation on Mac CI.
Why Mac mini-class hosts still anchor this split
Validation and sandbox flags catch config mistakes early; native rebuilds and fat caches still benefit from Apple Silicon bandwidth and macOSโs Unix stack plus Gatekeeper, SIP, and FileVault for unattended hosts. Mac mini-class boxes idle at very low power and stay quiet under continuous duty โ a practical overflow node beside Docker-based Gateways. If you want dedicated high-RAM capacity without laptop sleep quirks, compare regions on the Macstripe home page and size a Mac mini M4 so rebuild windows no longer fight your CI queue.
