OpenClaw

Hardened, containerized OpenClaw deployment following the official Docker guide and security recommendations.

Why Docker?

OpenClaw runs an AI agent with tool access — file reads, web search, shell execution. Running it directly on the host means the agent operates with your user's full permissions: your files, your SSH keys, your credentials.

Docker isolates this:

• The container can only see .openclaw/ (config) and sandbox/ (shared workspace) — nothing else on your filesystem
• Port is bound to 127.0.0.1 only — no network exposure
• Linux capabilities are dropped (NET_RAW, NET_ADMIN), privilege escalation is blocked
• Memory and CPU limits prevent runaway resource consumption
• The agent workspace is restricted with workspaceOnly: true — even inside the container, tools can't escape the workspace directory

Prerequisites

• Docker and Docker Compose v2
• Python 3 (for config generation)

Quick start

./dockerclaw.sh setup

This single command runs the full pipeline:

1. Onboard — interactive setup (auth, provider selection)
2. Harden — sets file permissions (700/600) on config directory
3. Configure — reads openclaw.ini, generates a JSON patch, deep-merges into the config
4. Start — launches the gateway container
5. Install skills — pulls skills from ClawHub
6. Dashboard — prints the tokenized dashboard URL
7. Pair — monitors for browser pairing request and auto-approves (60s timeout)

Open the dashboard URL in your browser when prompted. The setup will detect and approve the pairing request automatically.

Configure model provider

After setup, configure your model provider. For Claude Max/Pro subscriptions:

# On your host machine (not inside Docker), generate a setup token
claude setup-token

# Then configure the model provider
./dockerclaw.sh cli configure --section model

Select Anthropic as the provider and paste the setup-token when prompted. You can also use an API key or any other supported provider.

Claude Max token optimization

If you're running OpenClaw on a Claude Max/Pro setup-token, optimize for smaller prompts and fewer expensive turns:

• Default to claude-sonnet-4-6; keep claude-opus-4-6 as fallback/escalation only
• Disable session transcript recall unless you truly need cross-session memory
• Keep AGENTS.md, MEMORY.md, USER.md, and HEARTBEAT.md concise because OpenClaw injects them into every turn
• Avoid installing optional skills by default; each additional skill increases prompt overhead
• Start fresh sessions for unrelated tasks instead of letting one long-running session accumulate history

Important: Anthropic setup-token auth is convenient, but prompt-caching benefits are tied to API-key usage rather than Claude subscription setup-token flows. If you later switch to Anthropic API keys, revisit caching-oriented optimizations separately.

Reset and start over

./dockerclaw.sh prune
./dockerclaw.sh setup

Configuration

All settings live in two files:

• openclaw.ini — application config (gateway, tools, agents, hooks, skills)
• dockerclaw.env — container resource limits and Docker-level settings

Edit these files, then prune and setup to apply from scratch.

Security hardening (from official recommendations)

Setting	Value	Why
tools.fs.workspaceOnly	true	Restrict file access to workspace directory
tools.exec.security	deny	Disable shell execution
tools.exec.ask	always	Require approval for any exec
tools.elevated.enabled	false	Disable privileged operations
tools.deny	automation, runtime, sessions	Block dangerous control-plane tools
logging.redactSensitive	tools	Redact secrets in tool output logs
discovery.mdns.mode	minimal	Reduce info disclosure on LAN
File permissions	700/600	Config directory and files restricted to owner

Memory and compaction

Setting	Value	Why
compaction.memoryFlush.enabled	true	Flush durable memories to disk before context compaction
memorySearch.experimental.sessionMemory	false	Avoid replaying old session transcripts into Claude context by default
memorySearch.sources	memory	Prefer curated memory over full session-history recall

Hooks

• boot-md — loads a context file at session startup
• session-memory — auto-saves and recalls memory across sessions

For Claude-only setups, keep the boot files small. OpenClaw injects these workspace files into the prompt on every run:

• AGENTS.md
• SOUL.md
• TOOLS.md
• IDENTITY.md
• USER.md
• HEARTBEAT.md
• BOOTSTRAP.md
• MEMORY.md

Container hardening (docker-compose.yml)

Measure	Implementation
Network isolation	Port bound to 127.0.0.1 only
Capability dropping	NET_RAW, NET_ADMIN dropped
Privilege escalation	no-new-privileges: true
Resource limits	Configurable via dockerclaw.env (default 8 GB / 2 CPUs)
Health monitoring	/healthz endpoint checked every 30s
Filesystem isolation	Only .openclaw/ and sandbox/ mounted

Commands

./dockerclaw.sh <command>

  setup      — onboard + configure + start + pair (reads from openclaw.ini)
  prune      — remove all containers, volumes, and config
  start      — start the gateway
  stop       — stop all containers
  restart    — restart the gateway
  logs       — tail gateway logs
  status     — show container status
  get-token  — print the gateway auth token
  config     — manage configuration (pass args to openclaw-cli)
  skills     — manage skills (pass args to openclaw-cli)
  dashboard  — print dashboard URL and approve device pairing
  cli        — run any openclaw-cli command

Architecture

dockerclaw.sh         — CLI wrapper (setup, lifecycle, config, pairing)
openclaw.ini          — declarative app config (all settings in one place)
dockerclaw.env        — container resource limits and Docker settings
scripts/ini2json.py   — converts ini to JSON patch
docker-compose.yml    — official service definitions (gateway + cli)
.openclaw/            — runtime config and data (gitignored)
sandbox/              — shared host directory mounted into workspace

How config works

openclaw.ini → ini2json.py → JSON patch → deep-merge into .openclaw/openclaw.json

No containers are spawned for configuration. The ini is converted to a JSON patch on the host and merged directly into the config file. Skills are the only post-start step (they need ClawHub network access).

How device pairing works

The Control UI requires device pairing as a security measure. In Docker, browser connections arrive from the Docker bridge network, not loopback, so auto-approval doesn't apply. The setup and dashboard commands handle this by detecting pending pairing requests via openclaw-cli devices list and approving them with openclaw-cli devices approve.

References

• Official Docker docs
• Security hardening guide
• Agent workspace isolation
• Memory configuration
• Skills platform