How to Install OpenClaw on Linux

Prerequisites

• ✓Docker Desktop (or Docker Engine) + Docker Compose v2 installed on your Linux machine.
• ✓At least 2 GB RAM available for image build (`pnpm install` may be OOM-killed on 1 GB hosts with exit 137).
• ✓Enough disk space for Docker images, logs, and OpenClaw config/workspace data.
• ✓If running on a VPS or any public host, you have reviewed Docker `DOCKER-USER` firewall policy and the OpenClaw "Security hardening for network exposure" guide.

Steps

1. 1

   Clone the OpenClaw repo and move to the repo root

   The Docker setup script and compose files live in the OpenClaw repo, so you need the project checked out on your Linux box. Make sure you run all Docker commands from the repo root so paths and compose configs resolve correctly.

   textCopy

   Run `docker compose` from the repo root. If you enabled `OPENCLAW_EXTRA_MOUNTS` or `OPENCLAW_HOME_VOLUME`, the setup script writes `docker-compose.extra.yml`; include it with `-f docker-compose.yml -f docker-compose.extra.yml`.

2. 2

   Build the OpenClaw Docker image with the setup script

   Use the provided setup script to build the gateway image and wire up Docker Compose. This script is the fastest way to get a containerized gateway on Linux without hand-writing Docker commands.

   bashCopy

   ./scripts/docker/setup.sh

3. 3

   Use a pre-built OpenClaw image instead of building locally (optional)

   If your Linux host is slow or you prefer to skip local builds, point the setup script at the pre-built image on GitHub Container Registry. js build and `pnpm install` on your machine.

   bashCopy

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

4. 4

   Complete the interactive onboarding in the container

   During setup, the script runs onboarding inside the gateway container to collect provider API keys and generate a gateway token. env` and starts the gateway via Docker Compose so the service comes up ready to use.

   textCopy

   The setup script runs onboarding automatically. It will:
   *   prompt for provider API keys
   *   generate a gateway token and write it to `.env`
   *   start the gateway via Docker Compose

5. 5

   Open the Control UI in your browser

   Once the gateway container is running, connect to the Control UI from your Linux host browser. env` into Settings so the dashboard can talk to your gateway; if you later switch to password auth, use that password instead.

   textCopy

   Open `http://127.0.0.1:18789/` in your browser and paste the configured shared secret into Settings. The setup script writes a token to `.env` by default; if you switch the container config to password auth, use that password instead.

6. 6

   Re-open the dashboard URL from the CLI when needed

   If you lose the dashboard URL or need to reconnect from another browser, use the CLI container to print the link without auto-opening a browser. This is handy on headless Linux servers where you SSH in.

   bashCopy

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

7. 7

   Configure messaging channels from the CLI container (optional)

   After the gateway is up, you can add WhatsApp, Telegram, or Discord channels using the `openclaw-cli` container. 1` even when you are on a remote Linux host.

   bashCopy

   # WhatsApp (QR)
   docker compose run --rm openclaw-cli channels login
   
   # Telegram
   docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"
   
   # Discord
   docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"

8. 8

   Run the manual Docker flow instead of the setup script (advanced)

   If you want full control over each step, you can build the image and run onboarding and config commands manually. This is useful on Linux when you debug or customize the gateway before bringing it up as a long-running service.

   bashCopy

   docker build -t openclaw:local -f Dockerfile .
   docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
     dist/index.js onboard --mode local --no-install-daemon
   docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
     dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'
   docker compose up -d openclaw-gateway

9. 9

   Enable agent sandboxing for tool isolation (optional)

   On Linux, you can keep the gateway on the host while running agent tools in isolated Docker containers. Enable sandboxing via environment variables before running the setup script so it bootstraps the sandbox image and mounts the Docker socket correctly.

   bashCopy

   export OPENCLAW_SANDBOX=1
   ./scripts/docker/setup.sh

10. 10

    Use a custom Docker socket path for rootless Docker (optional)

    If you run rootless Docker on Linux, the Docker socket path differs from the default. Override it before running the setup script so sandbox containers can start successfully.

    bashCopy

    export OPENCLAW_SANDBOX=1
    export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
    ./scripts/docker/setup.sh

11. 11

    Check gateway health from your Linux host

    Once OpenClaw is running, probe its health endpoints from the host to confirm liveness and readiness. These endpoints require no auth and integrate well with Linux monitoring or orchestration tools.

    bashCopy

    curl -fsS http://127.0.0.1:18789/healthz   # liveness
    curl -fsS http://127.0.0.1:18789/readyz     # readiness

12. 12

    Run authenticated deep health checks from the CLI container

    For deeper diagnostics, run the health command inside the gateway container using the CLI. This uses your `OPENCLAW_GATEWAY_TOKEN` and gives a more detailed snapshot than the public probes.

    bashCopy

    docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

Configuration

Troubleshooting

The VM needs at least 2 GB RAM. Use a larger machine class and retry.

Build the sandbox image with [`scripts/sandbox-setup.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) or set `agents.defaults.sandbox.docker.image` to your custom image. Containers are auto-created per session on demand.

Set `docker.user` to a UID:GID that matches your mounted workspace ownership, or chown the workspace folder.

OpenClaw runs commands with `sh -lc` (login shell), which sources `/etc/profile` and may reset PATH. Set `docker.env.PATH` to prepend your custom tool paths, or add a script under `/etc/profile.d/` in your Dockerfile.

docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>

docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

Frequently asked questions