How to Install OpenClaw (Step-by-step Guide with Safe Defaults)

If you are searching for "how to install OpenClaw" and keep finding partial setup notes, this guide is the complete path:

• choose the right install method for your environment
• get OpenClaw running
• verify the install end-to-end
• apply safe defaults before exposing anything

This is written for beginners, but it is strict about security because installation is where most long-term problems start.

TL;DR

If you only have 10 minutes:

1. Use the Docker Compose path if you want the fastest stable setup.
2. Keep OpenClaw private at first (no public exposure).
3. Confirm health + logs before connecting channels.
4. Add access controls and approval gates before any real workflows.

Choose your install path

Use this quick decision table:

Your situation	Recommended path	Why
You want the fastest "works today" install	Docker Compose	Simple startup, easy restarts/upgrades
You already use Nix	Nix install	Reproducible environment and clean upgrades
You are experimenting on a dev machine	Docker Compose first, then tune	Lowest setup friction

If you are not sure, pick Docker Compose first.

If your goal is "I need this running today without managing servers," use a hosted OpenClaw setup (like Clawbase) and skip straight to integrations/workflows.

Want the fastest setup? Use hosted OpenClaw

If you do not want to manage Docker, updates, or infra hardening yourself, hosted deployment is the quickest path:

1. Create a hosted instance.
2. Add your model/provider credentials.
3. Open the dashboard and run one smoke test.
4. Connect one channel (Telegram/Slack) with strict allowlists.

This is the fastest route for teams that want to focus on outcomes instead of operations.

Ready for your own?

🦞 Hire an AI employee that works 24/7

Plans from less than $1/day. Dedicated cloud host, top models, and messaging on Telegram, Slack, or Discord. No API keys to manage.

Get started with Google

See plans · Cancel anytime

Reference docs:

• https://github.com/openclaw/openclaw/blob/main/docker-compose.yml
• https://docs.openclaw.ai/install/nix

Prerequisites

Before installation, confirm:

• Docker and Docker Compose are installed
• You can run containers as your current user
• You have a .env file or secure environment variable workflow

Quick checks:

docker --version
docker compose version

If either command fails, fix that first. Most "OpenClaw failed to start" issues are actually Docker permission or version issues.

Step 1) Create a dedicated OpenClaw directory

mkdir -p ~/openclaw && cd ~/openclaw

Keeping OpenClaw in its own directory makes upgrades and rollback safer.

Step 2) Add a minimal docker-compose.yml

Use OpenClaw's official compose file as the base:

• https://github.com/openclaw/openclaw/blob/main/docker-compose.yml

If you want a minimal starting point, use this pattern:

services:
  gateway:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw-gateway
    env_file:
      - .env
    ports:
      - "127.0.0.1:3000:3000"
    restart: unless-stopped

Important details:

• Binding to 127.0.0.1 keeps it local-only by default.
• restart: unless-stopped helps after host reboots.
• Keep secrets in .env, not in YAML.

Step 3) Create .env with safe defaults

Example (illustrative only):

# Do not commit this file
OPENCLAW_ENV=production
OPENCLAW_LOG_LEVEL=info

# If you use dashboard/token auth, set it here
OPENCLAW_DASHBOARD_TOKEN=replace_with_long_random_value

Use a long random token for any dashboard or gateway auth setting. Never reuse passwords/tokens from other systems.

Step 4) Start OpenClaw

docker compose up -d

Then inspect status:

docker compose ps
docker compose logs --tail=100 gateway

You want to see the gateway in a healthy/running state with no crash loop.

Step 5) Verify the install end-to-end

Use this checklist before you connect Telegram/Slack/Discord:

• Container is running for at least 2-3 minutes without restart
• Gateway health endpoint/UI is reachable locally
• Logs show normal startup (no missing env var panics)
• You can authenticate to dashboard/gateway (if enabled)

If this fails, stop here and fix install quality first.

Step 6) Apply hardening basics (do this before integrations)

Many users skip this and regret it later. Start with four controls:

1. Network scope

   • Keep service bound to localhost or private network initially.
   • Do not expose directly to the public internet on day one.

2. Access control

   • Add allowlists for user IDs/chat IDs when enabling channels.
   • Start with only your own account.

3. Approval gates

   • Require explicit approval for write or side-effect actions.
   • Prefer plan -> approve -> execute patterns.

4. Secret hygiene

   • Keep tokens in env/secret manager.
   • Rotate tokens if they were ever pasted into chat or logs.

Security hardening perspective:

• https://habr.com/en/articles/992720/

Step 7) First-run workflow test

Before production usage, run one controlled task:

1) Ask the assistant to restate your request.
2) Ask for a 3-5 step plan.
3) Approve explicitly.
4) Execute only read-only actions first.
5) Review logs and summary.

This validates both functionality and guardrails.

Common install problems and fixes

"Container exits immediately"

Likely causes:

• Missing required environment variable
• Invalid image tag
• Port conflict

Fix flow:

docker compose logs gateway
docker compose down
docker compose up -d

Then re-check logs after restart.

"Permission denied" with Docker

Usually your user is not configured for Docker runtime access. Resolve Docker permissions for your OS, then retry.

"Dashboard opens but auth fails"

• Verify token value in .env
• Ensure service restarted after .env changes:

docker compose up -d --force-recreate

"Works locally but remote access is broken"

Do not debug remote access until local install is stable. First lock in local reliability, then add one remote method (reverse proxy, SSH tunnel, or Tailscale) with explicit auth.

What to do next

After installation is stable:

1. Connect one channel (Telegram or Slack).
2. Keep it limited to one user/chat.
3. Add one practical workflow (for example: daily summary or backlog triage).
4. Add scheduling only after manual runs are reliable.

If you want a connected next step, start with Telegram:

• https://deepwiki.com/openclaw/openclaw/4.2-telegram

Final checklist

Use this as your definition of done:

• OpenClaw is running and stable in Docker
• Secrets are not committed to git
• Dashboard/gateway auth is configured
• Channel access is allowlisted
• Write actions require explicit approval
• You completed one controlled test task successfully

Install is "done" only when both the system and guardrails are working.