OpenClaw Installation and Configuration

This guide is organized in a "get it running first, then refine" order. The goal is simple: install OpenClaw, get your server running, then understand openclaw.json.

Which Installation Path Should You Choose?

Your environment	Recommended approach	Why this is useful
macOS	Install script + wizard	Highest support level, best overall experience
Windows	WSL2 + install script	Officially recommended, usually more stable
Linux	Install script + systemd	Good for long-running services
Docker	docker-setup.sh	Isolated environment, easier migration

Before You Start (4 checks)

1. Make sure your environment has internet access (needed on first install).
2. Confirm terminal access (macOS Terminal, Windows PowerShell, or Linux shell).
3. Do not over-customize at first; get the default path working first.
4. Remember the config location: ~/.openclaw/openclaw.json (for Docker, use the container path as needed).

1. macOS Installation (Easiest)

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

If you get openclaw: command not found, run:

npm prefix -g
echo "$PATH"

Then add your npm global bin directory to PATH, reopen terminal, and retry.

2. Windows Installation (WSL2 Recommended)

Option A (Recommended): WSL2 + Ubuntu

In PowerShell (as Administrator), run:

wsl --install

After installation, open Ubuntu and run:

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

If gateway install fails inside WSL, systemd is usually not enabled. In WSL, run:

sudo tee /etc/wsl.conf >/dev/null <<'EOF2'
[boot]
systemd=true
EOF2

Then run wsl --shutdown in PowerShell and reopen Ubuntu.

Option B: Direct PowerShell Installation

iwr -useb https://openclaw.ai/install.ps1 | iex

Option A (WSL2) is generally more stable.

3. Linux Installation

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

If this runs on a remote host (VPS), forward the local port from your machine:

ssh -N -L 18789:127.0.0.1:18789 <user>@<host>

Then open http://127.0.0.1:18789/ in your local browser.

4. Docker Installation

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

After setup, open http://127.0.0.1:18789/ in your browser. If you need to print the dashboard link again:

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

5. openclaw onboard --install-daemon Step-by-Step (Important)

This command starts the interactive onboarding wizard and installs the daemon at the end, so Gateway can run in the background. If this is your first time, run:

openclaw onboard --install-daemon

Below is what you will typically see.

Step 0: Existing Config Detection (Keep / Modify / Reset)

The wizard may detect an existing ~/.openclaw/openclaw.json and ask you to:

• Keep: continue with current config
• Modify: adjust current config
• Reset: clear and re-create from scratch

Practical advice: If you are unsure, pick Modify first instead of Reset.

Step 1: Wizard Mode (Quick Start / Advanced)

You will see two options:

• Quick Start: uses defaults automatically
• Advanced: prompts each decision

Practical advice: For first-time setup, choose Quick Start.

Step 2: Model and Authentication (Most Critical)

The wizard asks which provider and auth method you want, for example:

• Anthropic API Key
• OpenAI API Key / OpenAI subscription
• Other providers (custom compatible endpoints)
• Skip (not recommended)

This step answers two core questions:

1. Which model provider will OpenClaw use?
2. What credential will it use?

Practical advice:

1. If you already have a valid API key, pick that provider and configure it first.
2. Do not configure many keys at once. Get one provider working first.
3. You can add more later with openclaw configure.

Recommended options for users in Mainland China (important)

As of 2026-02-22, the following onboarding auth options are usually more practical for Mainland China users:

Priority	Auth option	Best for	Why
1	volcengine-api-key	You already use Volcengine	Official support added in v2026.2.21, available directly in wizard
2	minimax-api-key-cn	MiniMax in Mainland China	Dedicated CN endpoint option
3	zai-api-key (or zai-cn / zai-coding-cn)	GLM family usage	Wizard supports Z.AI endpoint selection
4	moonshot-api-key-cn	Kimi usage	.cn option available in wizard
5	byteplus-api-key	BytePlus ecosystem	Official support added in v2026.2.21

A practical sequence:

1. Pick one provider you already have credentials for.
2. Configure only one provider first.
3. Add a fallback provider only after the first one works.

Non-interactive examples:

# Volcengine
openclaw onboard --non-interactive --accept-risk \
  --auth-choice volcengine-api-key \
  --volcengine-api-key "$VOLCANO_ENGINE_API_KEY"

# MiniMax (China endpoint)
openclaw onboard --non-interactive --accept-risk \
  --auth-choice minimax-api-key-cn \
  --minimax-api-key "$MINIMAX_API_KEY"

# Z.AI (CN)
openclaw onboard --non-interactive --accept-risk \
  --auth-choice zai-cn \
  --zai-api-key "$ZAI_API_KEY"

# Moonshot (.cn)
openclaw onboard --non-interactive --accept-risk \
  --auth-choice moonshot-api-key-cn \
  --moonshot-api-key "$MOONSHOT_API_KEY"

Notes:

• In interactive mode, you can choose from menus without memorizing flags.
• minimax-api and minimax-api-key-cn are different options.
• Z.AI can auto-detect endpoints, or you can force zai-cn / zai-coding-cn.
• Volcengine and BytePlus were major additions in v2026.2.21.

Step 3: Workspace Selection

The wizard asks where your workspace should be. Default is typically:

~/.openclaw/workspace

This directory stores runtime files and task artifacts.

Practical advice: Use the default path for your first setup.

Step 4: Gateway Parameters (Port / Bind / Auth)

You will configure:

• gateway.port (commonly 18789)
• gateway.bind (for example loopback)
• gateway.auth (for example token)
• Whether to enable Tailscale-related exposure

What is Tailscale?

Tailscale creates a private network among your devices (Tailnet), so you can access services remotely without directly exposing ports to the public internet.

For OpenClaw, this usually means:

1. You can access your Gateway remotely.
2. You reduce direct public port exposure risk.
3. Multi-device remote setup is easier.

Common wizard options:

• off: disable Tailscale mode
• serve: private Tailnet access (usually preferred)
• funnel: public internet exposure (higher risk)

Practical sequence:

1. Start with bind = loopback.
2. Keep auth enabled (token).
3. Start with tailscale.mode = off, then enable remote mode only when needed.
4. Avoid starting with funnel unless you fully understand the risk.

Step 5: Channel Configuration (Optional)

The wizard may ask whether to configure channels, such as:

• Telegram
• WhatsApp
• Discord
• Others

Each channel then asks for its own token/key/account info.

Practical advice:

1. Skip most channels in your first run.
2. At most, configure one channel first.
3. You can already test via openclaw dashboard without channels.

Step 6: Daemon Installation

Because you used --install-daemon, the wizard installs background service setup automatically:

• macOS: LaunchAgent
• Linux / WSL2: systemd user service

Why this matters: Gateway can keep running after terminal exits.

Practical advice:

1. Approve permission prompts when asked.
2. If systemd errors appear on Linux/WSL2, fix systemd first, then rerun.

Step 7: Health Check

The wizard tries to start Gateway and run checks, usually via:

• openclaw health
• or equivalent checks

Practical advice: Do not move on to advanced config until this step passes.

Step 8: Skills Installation (Recommended but Optional)

The wizard scans available Skills and may suggest optional dependencies. It usually asks package manager preference (for example npm / pnpm).

Practical advice: Install recommended items first and keep the core path stable.

Step 9: Finish and Next Steps

The wizard usually suggests:

openclaw gateway status
openclaw dashboard

If dashboard opens and chat works, your baseline setup is successful.

--install-daemon in one sentence

• Without it: onboarding may complete without background service installation.
• With it: onboarding also attempts daemon installation for stable long-running usage.

What Files Does Onboarding Usually Change?

Common outputs include:

• ~/.openclaw/openclaw.json (main config)
• ~/.openclaw/.env (some secrets/env values)
• ~/.openclaw/credentials/... (OAuth/channel credentials)
• ~/.openclaw/workspace/... (workspace initialization)

Common Setup Blockers

Blocker	Typical reason	Fix
Wizard stops and asks to fix config	Invalid legacy fields	Run openclaw doctor, then rerun
Daemon install fails	systemd or permission issue	Fix environment, rerun openclaw onboard --install-daemon
Model check fails	Invalid key or model name	Re-select provider and validate key
Channel cannot connect	Token/config incomplete	Disable that channel first, fix core path, then add it back

6. Baseline Server Setup in 10 Minutes

1) Locate the config file

• Default: ~/.openclaw/openclaw.json
• Custom path: OPENCLAW_CONFIG_PATH=/your/path/openclaw.json
• Format: JSON5 (supports comments and trailing commas)

2) Start from a minimal runnable config

{
  gateway: {
    mode: "local",
    bind: "lan",
  },
  agents: {
    defaults: {
      model: {
        primary: "openai/gpt-4.1-mini",
      },
    },
  },
}

3) Quick validation

openclaw gateway status
openclaw doctor
openclaw dashboard

If doctor reports field errors, fix typos or field types in openclaw.json and retry.

If you need the complete field dictionary (including full gateway keys) and high-frequency field lookup, see: OpenClaw Detailed Configuration Guide.

---

7. Practical Configuration Advice for Beginners

1. Keep gateway.mode = local first; get local setup stable before remote access.
2. Start with gateway.bind = loopback; do not begin with lan.
3. Enable minimal channels first (for example only telegram or discord).
4. Prefer environment variables for API keys instead of copying secrets around.
5. Run openclaw doctor after each config change.

8. Common Errors and Fixes

Symptom	Cause	Fix
Gateway start is rejected	gateway.mode is not local (without allowing unconfigured startup)	Set gateway.mode to local
401 on access	Auth mode mismatch or wrong token	Check gateway.auth.* and client credentials
Repeated pairing required	Device pairing not approved or token mismatch	Re-pair and verify device status
Docker EACCES error	Host mounted directory permission issue	Fix directory ownership and permissions

9. References (Official Sources)

• Getting Started
• Install
• Platforms
• Windows (WSL2)
• Linux
• macOS
• Docker
• Onboarding Wizard (CLI)
• CLI Onboarding Reference
• Gateway Configuration
• Configuration Reference
• MiniMax Provider
• Moonshot Provider
• Z.AI Provider
• OpenClaw GitHub Repository
• OpenClaw Releases
• v2026.2.21 Release

Checked on: 2026-02-23