setupCommand (one-time container setup)

The hook that runs once after a sandbox container is created, and the defaults that most often make it fail.

setupCommand (one-time container setup)

setupCommand runs once after the sandbox container is created (not on every run). It executes inside the container via sh -lc.

If access is revoked before setup completes, OpenClaw retains the container and its saved data for inspection. Later requests reject that incomplete container instead of restarting it or replaying setup. Preserve any needed container data before explicitly recreating the sandbox.

Paths:

• Global: agents.defaults.sandbox.docker.setupCommand
• Per-agent: agents.entries.*.sandbox.docker.setupCommand

Common pitfalls

• Default docker.network is "none" (no egress), so package installs will fail.
• docker.network: "container:<id>" requires dangerouslyAllowContainerNamespaceJoin: true and is break-glass only.
• readOnlyRoot: true prevents writes; set readOnlyRoot: false or bake a custom image.
• user must be root for package installs. Docker can omit user or set user: "0:0"; rootful Podman must set user: "0:0" because its default preserves workspace ownership. Rootless Podman rejects zero-valued users; bake packages into the image or use rootful Podman.
• Sandbox exec does not inherit host process.env. Use agents.defaults.sandbox.docker.env (or a custom image) for skill API keys.
• Values in agents.defaults.sandbox.docker.env remain visible through container metadata commands such as docker inspect or podman inspect. Docker and Podman require portable environment names and single-line, non-NUL values because secure engine environment files are line-delimited; config validation and openclaw doctor reject invalid entries before sandbox use. Rename invalid keys, use single-line values, or deliver multiline material through a mounted file or custom image; this requires manual remediation because doctor --fix cannot safely preserve the original value. SSH and OpenShell backends still support multiline values. Use a custom image, mounted secret file, or another secret delivery path if metadata exposure is not acceptable.