OpenClaw Getting Started: First Success on Docker (One Machine)

What this page helps you do

This page gives you one bounded goal: get OpenClaw running on Docker on a single machine, then prove it survives restart with state intact.

By the end, you should have:

• one working Docker-based OpenClaw instance
• a known persistence boundary for config/state/workspace
• a dashboard session you can reopen after restart

Who this is for / not for

Use this page if you want the shortest believable Docker path for first success.

This page is not for:

• swarm or Kubernetes setups
• reverse proxy design
• production multi-host architecture

If you want the fastest non-Docker local path, use:

• /getting-started/quick-start

If you need deeper operations after first success, continue to:

• /guides/docker-deployment

Before you start

Confirm these basics first:

1. Docker is installed and running:

docker --version
docker compose version

2. You can clone and run scripts in a local repo.
3. Port 18789 is available on your machine.

One canonical Docker path

Use this one path first. Do not optimize anything yet.

1. Clone the OpenClaw repo and enter it:

git clone https://github.com/openclaw/openclaw.git
cd openclaw

2. Run the official Docker setup script:

./docker-setup.sh

This path builds the image, runs onboarding in container context, starts the gateway with Docker Compose, and keeps the gateway token with the running Docker environment.

3. Open the dashboard through the current tokenized entrypoint:

• use the tokenized dashboard link printed by the setup/current dashboard flow
• if you are using the host CLI, run openclaw dashboard and open the URL it prints

Treat http://127.0.0.1:18789/ as a reachability fallback only. If the raw URL asks for a token or shows unauthorized, refresh from a tokenized dashboard link before manually entering stored token material.

Persistence sanity (config/state/workspace)

For first success, keep persistence simple and explicit:

• Config + state root: ~/.openclaw/
• Primary config file: ~/.openclaw/openclaw.json
• Default workspace: ~/.openclaw/workspace

Why this matters:

• if ~/.openclaw/ is not persisted on the host, restart behaves like a new machine
• if workspace is not writable/persistent, runs may appear to succeed but files disappear

Quick host check:

ls -la ~/.openclaw
ls -la ~/.openclaw/workspace

First-success verification

Call first success only when all checks pass:

1. Gateway container is running:

docker compose ps

2. Dashboard opens from a fresh tokenized entrypoint and reaches the local gateway.
3. Restart once, then re-check dashboard and persisted directories:

docker compose restart openclaw-gateway
docker compose ps
ls -la ~/.openclaw

If these still pass after restart, you have a valid one-machine Docker baseline.

First failure branches

A) Dashboard shows unauthorized

• reopen from a fresh tokenized dashboard entrypoint, then retry
• if the tokenized entrypoint and the running gateway disagree, use /guides/control-ui-auth-and-pairing
• if still blocked, use /guides/openclaw-deployment-troubleshooting

B) Files or state disappear after restart

• confirm ~/.openclaw/ is host-persistent and actually mounted in your Docker path
• then follow /guides/openclaw-state-workspace-and-memory

C) Gateway does not stay healthy

• check container status and logs:

docker compose ps
docker compose logs -f openclaw-gateway

• then route by symptom via /guides/openclaw-deployment-troubleshooting

What to do next

After first success, choose one next step:

• Docker day-2 operations and safer upgrades:
  • /guides/docker-deployment
• Persistence and permissions deep dive:
  • /guides/openclaw-state-workspace-and-memory
• Fast symptom-first troubleshooting:
  • /guides/openclaw-deployment-troubleshooting