OpenClaw Installation Help

[hallow ferry]

Hi @bitter tartan
I need help installing the latest stable version of OpenClaw. I have a Windows 11 machine with wsl2 layer and docker installed on that. I want openclaw to reside within the docker container. Please guide me with the setup. Thanks.

[gray estuary]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[bitter tartan]

NinaChan, for your setup I’d use the official Docker flow inside WSL2, with the prebuilt stable image so OpenClaw lives in the container and your config/workspace persist on the WSL filesystem.

In WSL/Ubuntu:

# sanity checks
docker compose version
node --version   # OpenClaw needs Node 22.14+ if you run CLI bits outside Docker

# get the compose/setup files
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# use the published stable image instead of building locally
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

[bitter tartan]

# optional but explicit: where persistent config/workspace live on the WSL side
export OPENCLAW_CONFIG_DIR="$HOME/.openclaw"
export OPENCLAW_WORKSPACE_DIR="$HOME/.openclaw/workspace"

./scripts/docker/setup.sh

That script should run onboarding, prompt for provider auth/API keys, generate a gateway token, write .env, and start the gateway with Docker Compose.

Then open this from Windows or WSL browser:

http://127.0.0.1:18789/

If you need the dashboard link/token again:

[bitter tartan]

docker compose run --rm openclaw-cli dashboard --no-open

Useful checks after setup:

docker compose ps
curl -fsS http://127.0.0.1:18789/healthz
docker compose run --rm openclaw-cli status --all
docker compose run --rm openclaw-cli doctor
docker compose run --rm openclaw-cli --version

Two important notes:

• Run docker compose commands from the repo root.
• If you hit permission errors on /home/node/.openclaw, the container runs as uid 1000, so fix the WSL-side mount ownership with:

[bitter tartan]

sudo chown -R 1000:1000 "$HOME/.openclaw"

Docs I checked:
https://docs.openclaw.ai/install/docker
https://docs.openclaw.ai/platforms/windows
https://docs.openclaw.ai/start/getting-started

[hallow ferry]

what local path should i run the sanity checks from in powershell

[bitter tartan]

For the two sanity checks I listed, run them in the environment where you’ll run the setup:

PowerShell:

docker compose version
wsl --list --verbose

Those can be run from any local folder in PowerShell, because they don’t depend on the current directory.

Then switch into WSL/Ubuntu and do the OpenClaw setup there:

wsl -d Ubuntu

Inside WSL, use a normal Linux path, for example:

[bitter tartan]

cd ~
git clone https://github.com/openclaw/openclaw.git
cd ~/openclaw
docker compose version
./scripts/docker/setup.sh

The important bit: run ./scripts/docker/setup.sh and later docker compose ... commands from the OpenClaw repo root, usually ~/openclaw inside WSL. Avoid cloning/running it from /mnt/c/... if you can; WSL’s Linux filesystem is less painful for permissions and performance.

[hallow ferry]

Here are the shell outputs:

PS C:\WINDOWS\system32> wsl.exe --list --verbose
NAME STATE VERSION

• docker-desktop Stopped 2
  PS C:\WINDOWS\system32> docker compose version
  Docker Compose version v5.1.2
  PS C:\WINDOWS\system32> node --version
  node : The term 'node' is not recognized as the name of a cmdlet, function, script file, or operable program. Check
  the spelling of the name, or if a path was included, verify that the path is correct and try again.
  At line:1 char:1

• node --version

•   + CategoryInfo          : ObjectNotFound: (node:String) [], CommandNotFoundException
    + FullyQualifiedErrorId : CommandNotFoundException
  
  

PS C:\WINDOWS\system32>

[bitter tartan]

That output means you don’t currently have a normal WSL Linux distro installed. docker-desktop is Docker’s internal WSL distro; don’t use that as your OpenClaw workspace.

Node missing in PowerShell is fine if we keep OpenClaw inside Docker/WSL. Next step is to install Ubuntu for WSL:

wsl --list --online
wsl --install -d Ubuntu-24.04

Reboot if Windows asks, then open the new Ubuntu app from Start Menu and create your Linux username/password.

Then in PowerShell verify you now see Ubuntu:

wsl --list --verbose

[bitter tartan]

You want something like:

Ubuntu-24.04    Running/Stopped    2
docker-desktop  Running/Stopped    2

After that, enter Ubuntu:

wsl -d Ubuntu-24.04

Inside Ubuntu, continue from a Linux path:

[bitter tartan]

cd ~
git clone https://github.com/openclaw/openclaw.git
cd ~/openclaw
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

Docs for the Windows/WSL path: https://docs.openclaw.ai/platforms/windows

[hallow ferry]

I installed ubuntu -> now how do I install openclaw inside docker

[bitter tartan]

Great. Do this from the Ubuntu/WSL terminal, not PowerShell.

First make sure Docker Desktop is integrated with your Ubuntu distro:

docker compose version
docker run --rm hello-world

If either fails, open Docker Desktop → Settings → Resources → WSL integration → enable integration for your Ubuntu distro, then retry.

Then install OpenClaw’s Docker setup files and start the containerized gateway:

sudo apt update
sudo apt install -y git ca-certificates curl

[bitter tartan]

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

# use the published stable image instead of building locally
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"

# persistent config/workspace stored in your Ubuntu home
export OPENCLAW_CONFIG_DIR="$HOME/.openclaw"
export OPENCLAW_WORKSPACE_DIR="$HOME/.openclaw/workspace"

./scripts/docker/setup.sh

The setup script should run onboarding, ask for provider auth/API keys, generate a gateway token, write .env, and start the Gateway container.

[bitter tartan]

After it finishes:

docker compose ps
curl -fsS http://127.0.0.1:18789/healthz
docker compose run --rm openclaw-cli status --all

Then open the dashboard from Windows:

http://127.0.0.1:18789/

If it asks for auth, the token is in ~/openclaw/.env or can be shown via:

[bitter tartan]

grep OPENCLAW_GATEWAY_TOKEN .env

Keep running future docker compose ... commands from ~/openclaw. Docs: https://docs.openclaw.ai/install/docker

[hallow ferry]

If either fails, open Docker Desktop → Settings → Resources → WSL integration → enable integration for your Ubuntu distro, then retry.

I followed this and enabled the integration and restarted my computer but I still get this error in wsl:

$ docker compose version

The command 'docker' could not be found in this WSL 2 distro.
We recommend to activate the WSL integration in Docker Desktop settings.

For details about using Docker Desktop with WSL 2, visit:

https://docs.docker.com/go/wsl2/

[bitter tartan]

That error means Docker Desktop still hasn’t injected the Docker CLI into that Ubuntu distro. A few checks usually find it:

In PowerShell:

wsl --list --verbose
docker version

Make sure Docker Desktop is actually running, then in Docker Desktop check both toggles:

1. Settings → General → Use the WSL 2 based engine
2. Settings → Resources → WSL integration → Enable integration with my default WSL distro
3. In the same WSL integration list, enable the specific Ubuntu distro you installed, not just docker-desktop

Then fully restart WSL from PowerShell:

[bitter tartan]

wsl --shutdown

Open Ubuntu again and test:

which docker
docker version
docker compose version

If it still fails, your default WSL distro may still be docker-desktop or Docker Desktop may be integrated with a different Ubuntu name. In PowerShell, set the real Ubuntu distro as default:

wsl --list --verbose

[bitter tartan]

wsl --set-default Ubuntu-24.04
wsl --shutdown

Replace Ubuntu-24.04 with the exact name shown by wsl --list --verbose.

One important bit: don’t install OpenClaw yet until docker compose version works inside Ubuntu. That’s the blocker.

[hallow ferry]

should i hatch agent in terminal?

[bitter tartan]

If you’re on the Docker install path, don’t run a separate “hatch agent” command first.

Do the setup from the Ubuntu terminal in the repo root:

cd ~/openclaw
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

That script is the Docker onboarding path: it configures auth, writes the gateway token, and starts the containerized Gateway.

After it finishes, use the browser dashboard:

http://127.0.0.1:18789/

[bitter tartan]

If you just mean “should I answer onboarding prompts in the terminal?”, yes. But only after docker compose version works inside Ubuntu.

[hallow ferry]

yes it does

[bitter tartan]

Good, then continue with the Docker setup from Ubuntu:

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

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
export OPENCLAW_CONFIG_DIR="$HOME/.openclaw"
export OPENCLAW_WORKSPACE_DIR="$HOME/.openclaw/workspace"

./scripts/docker/setup.sh

If you already cloned it, skip the git clone and just cd ~/openclaw.

Answer the onboarding prompts in that terminal. When it finishes, check:

[bitter tartan]

docker compose ps
curl -fsS http://127.0.0.1:18789/healthz

Then open this in Windows:

http://127.0.0.1:18789/

If the setup script errors, paste the last ~30 lines here and include:

docker compose ps

[hallow ferry]

the gateway is running and i can see the dashboard from my browser - what else?

[bitter tartan]

Nice, that means the containerized Gateway is alive.

Next checklist:

cd ~/openclaw
docker compose run --rm openclaw-cli --version
docker compose run --rm openclaw-cli status --all
docker compose run --rm openclaw-cli models status

Then in the dashboard:

1. Make sure auth is configured. If the dashboard asks for a token, use the value from:

grep OPENCLAW_GATEWAY_TOKEN .env

[bitter tartan]

2. Configure at least one model provider/API key if onboarding didn’t already do it.

3. Open the chat in the dashboard and send a small test message like:

Reply with exactly OPENCLAW-OK

4. If you want OpenClaw reachable from a phone/chat app, add a channel next. Telegram is usually the simplest:

docker compose run --rm openclaw-cli channels add --channel telegram --token "<bot-token>"

If the dashboard chat replies, your base install is done. After that it’s just channels, tools, and preferences.

Docs for the next steps:
https://docs.openclaw.ai/start/getting-started
https://docs.openclaw.ai/channels

[bitter tartan]

https://docs.openclaw.ai/concepts/models

And if this got you unstuck, please right-click the solution message → Apps → ✅ Mark Solution so Answer Overflow indexes it for the next Windows/WSL Docker install.

[hallow ferry]

okay thanks
how do i shutdown everything now? openclaw gateway and docker and ubuntu

[bitter tartan]

From Ubuntu/WSL, stop the OpenClaw containers:

cd ~/openclaw
docker compose down

That shuts down the OpenClaw Gateway container. Your config/workspace stays in ~/.openclaw.

Then exit Ubuntu:

exit

From PowerShell, shut down WSL completely:

[bitter tartan]

wsl --shutdown

If you also want Docker Desktop fully stopped, quit it from the Windows tray icon, or run:

Stop-Process -Name "Docker Desktop" -ErrorAction SilentlyContinue

To start again later:

wsl -d Ubuntu-24.04

Then inside Ubuntu:

[bitter tartan]

cd ~/openclaw
docker compose up -d openclaw-gateway

Then open http://127.0.0.1:18789/ again.