OpenClawDocs
On this page

On this page

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

First steps

Getting started

Install OpenClaw, run onboarding, and chat with your AI assistant in about 5 minutes. By the end you will have a running Gateway, configured auth, and a working chat session.

What you need

  • Node.js 24.16.0+ on 24.x, or 26.1.0+ (Node 26 is recommended; use 24.22.1+/26.12.1+ for the security fixes)
  • An existing Claude Code or Codex CLI login, or a provider API key — onboarding can reuse it

Try it in one command

bash
npx openclaw@latest

On a fresh install, choose Quick start after a one-line pointer to the security guide. That is the only onboarding prompt when usable AI access is already available: OpenClaw finds an existing Claude Code or Codex CLI login or API key, verifies it with a real completion, saves the config, and opens the web dashboard.

Quick start then asks Keep OpenClaw running in the background? Yes installs a copy of the same OpenClaw version under ~/.openclaw and runs the Gateway as a background service from it, so clearing the npx cache does not stop it. No keeps the Gateway in this terminal until you press Ctrl+C; your config stays saved. If no detected route works, onboarding opens manual provider setup. Choose Custom setup to walk through all guided options instead.

To keep the Gateway running in the background later, install the CLI below and run openclaw gateway install, then openclaw gateway start to wait until it is ready. Run openclaw for the TUI or openclaw dashboard to reopen the web UI.

Quick setup

  • Install OpenClaw

    macOS / Linux

    bash
    curl -fsSL https://openclaw.ai/install.sh | bash

    Install Script Process

    Windows (PowerShell)

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

  • Complete onboarding

    The installer starts the guided onboarding wizard automatically. Choose Quick start to reuse detected AI access and open the dashboard, or Custom setup for the full guided flow. Provider sign-in and optional setup can take longer. Return later with openclaw configure for additional settings. openclaw onboard --classic opens the classic step-by-step wizard instead.

    See Onboarding (CLI) for the full reference.

  • Install the Gateway service

    Quick start asks Keep OpenClaw running in the background? and installs the service when you accept, so skip this step in that case. Otherwise, press Ctrl+C to stop the foreground Gateway, then install the service and wait for it to be ready:

    bash
    openclaw gateway installopenclaw gateway start

    This installs a LaunchAgent on macOS, a systemd user unit on Linux and WSL2, or a Scheduled Task on native Windows (with a per-user Startup-folder login item as the fallback if task creation is denied). Your config stays saved across the stop and the install.

    gateway install returns once the service is registered, while the Gateway may still be starting. gateway start waits until the Gateway passes its health and readiness checks; it does not restart a Gateway that is already running.

  • Verify the Gateway is running

    bash
    openclaw gateway status

    You should see the Gateway listening on port 18789.

  • Open the dashboard

    bash
    openclaw dashboard

    This opens the Control UI in your browser. If it loads, everything is working.

  • Send your first message

    Type a message in the Control UI chat and you should get an AI reply.

    Want to chat from your phone instead? The fastest channel to set up is Telegram (just a bot token). See Channels for all options.

    • Advanced: mount a custom Control UI build

    If you maintain a localized or customized dashboard build, point gateway.controlUi.root to a directory that contains your built static assets and index.html.

    bash
    mkdir -p "$HOME/.openclaw/control-ui-custom"# Copy your built static files into that directory.

    Then set:

    json
    {  "gateway": {    "controlUi": {      "enabled": true,      "root": "${HOME}/.openclaw/control-ui-custom"    }  }}

    Restart the gateway and reopen the dashboard:

    bash
    openclaw gateway restartopenclaw dashboard

    If setup does not work

    One command turns the current state of your install into a diagnosis you can act on:

    bash
    openclaw triage

    It runs read-only health checks, writes a sanitized prompt describing what it found, and then offers to hand that prompt to a coding agent it detects on your machine — Claude Code, Codex CLI, or the built-in OpenClaw agent — so the agent starts with the diagnosis already loaded. Pick "just print the commands" if you would rather run the handoff yourself.

    Nothing leaves your machine until you choose an agent, and secrets, tokens, raw chat payloads, and raw logs are excluded from the prompt.

    To read the findings yourself instead, run openclaw doctor. For symptom-first routes, see Troubleshooting.

    What to do next

    Connect a channel

    Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more.
    Pairing and safety

    Control who can message your agent.
    Configure the Gateway

    Models, tools, sandbox, and advanced settings.
    Browse tools

    Browser, exec, web search, skills, and plugins.
    Advanced: environment variables

    If you run OpenClaw as a service account or want custom paths:

    • OPENCLAW_HOME — home directory for internal path resolution
    • OPENCLAW_STATE_DIR — override the state directory
    • OPENCLAW_CONFIG_PATH — override the config file path

    Full reference: Environment variables.

    Was this useful?