OpenClaw setup: install, onboarding, channels and MCP

Updated 9 min read

To set up OpenClaw, run curl -fsSL https://openclaw.ai/install.sh | bash (it adds Node if you do not have 24.16+ or 26.1+) and pick Quick start in onboarding. Quick start reuses a Claude Code or Codex CLI login or an API key, checks it with a real reply, and opens the web dashboard. Then run openclaw gateway install so the Gateway keeps running in the background, and add a chat channel such as Telegram.

We have not installed OpenClaw for this guide. Every command and path below comes from docs.openclaw.ai as of October 2026. We run Hermes Agent ourselves, so there is a short note near the end on where setting up the two differs.

What do you need before you set up OpenClaw?

  • Node.js 24.16+ or 26.1+. Node 26 is the recommended runtime. The docs list Node 22, 23 and 25, Node 24 before 24.16.0 and Node 26 before 26.1.0 as unsupported. Check with node --version. If Node is missing, the installer script provisions it (Node 26 on macOS, Node 24 LTS on Linux).
  • macOS, Linux or Windows. On Windows you can use the native Windows Hub app, the PowerShell installer, or a Gateway in WSL2.
  • AI access. An existing Claude Code or Codex CLI login, or an API key for a model provider. Onboarding can also find tool-capable models already installed in Ollama or LM Studio on the same machine.
  • pnpm only if you build from source.

How do I install OpenClaw?

The installer script detects your OS, installs Node if needed, installs OpenClaw and starts onboarding:

# macOS, Linux, WSL2
curl -fsSL https://openclaw.ai/install.sh | bash

# Windows (PowerShell)
iwr -useb https://openclaw.ai/install.ps1 | iex

To install without starting onboarding, add --no-onboard:

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

If you manage Node yourself, install the npm package and run onboarding with the background service in one go. On npm 12 or 11.16+ the --allow-scripts flag lets OpenClaw’s install scripts run; on npm 11.15 and earlier, drop it:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

To try it before installing anything, npx openclaw@latest runs onboarding directly. The docs also cover desktop apps (a macOS menu bar app and the Windows Hub), Docker, Podman, Nix, a local-prefix installer (install-cli.sh) that keeps Node under ~/.openclaw, and guides for VPS hosts such as Hetzner, DigitalOcean and Oracle Cloud.

What happens during OpenClaw onboarding?

openclaw onboard (which the installer runs for you) offers two lanes after a one-line pointer to the security guide:

  • Quick start detects configured models, API key environment variables, local AI CLIs and local Ollama or LM Studio models. You choose one, and only that one is tested with a real completion. If the test fails, you retry, pick another provider or skip. It never switches provider on its own.
  • Custom setup walks through every option: agent name, access mode, telemetry and the optional steps.

Quick start uses the agent name main and full access by default. If you want a tighter access mode from the first run, choose Custom setup.

When onboarding creates the first agent you choose One agent (the default) or A small team: a chief of staff plus a researcher, writer and reviewer, each with its own workspace. Start with one agent unless you already know you want the team.

When Quick start finishes, the Gateway runs in your terminal until you press Ctrl+C, and your config stays saved. A few commands for later:

openclaw configure          # change non-model settings
openclaw onboard            # change the model provider or its sign-in
openclaw onboard --classic  # the older step-by-step wizard (remote Gateway, pairing, daemon, skills)
openclaw agents add <name>  # add another agent

Coming from Hermes Agent? On a fresh install, openclaw onboard --import-from hermes --import-source ~/.hermes brings over your model settings, MCP servers, SOUL.md, AGENTS.md and memory files, and openclaw migrate hermes --dry-run previews the import first.

How do I keep the OpenClaw gateway running?

The Gateway is the one process that holds your sessions, tools and channels. Quick start runs it in the foreground; to make it a background service, stop it with Ctrl+C and run:

openclaw gateway install
openclaw gateway status
openclaw dashboard

gateway install creates a LaunchAgent on macOS, a systemd user unit on Linux and WSL2, or a Scheduled Task on Windows. gateway status should show it listening on port 18789. openclaw dashboard opens the Control UI in your browser; send a message there and you should get a reply. Run openclaw on its own for the terminal UI.

On a normal host install the Gateway binds to loopback only, so nothing outside your machine can reach it. Container images are the exception: they default to an exposed bind, which the docs say to pair with auth. Read the exposure runbook before you open it to a network.

How do I connect Telegram or another channel?

The docs call Telegram the fastest channel to set up, because it needs only a bot token. Create a bot with /newbot in @BotFather, then:

openclaw channels add --channel telegram --token <bot-token>
openclaw channels status --probe

Telegram does not use openclaw channels login; the token goes in config (channels.telegram.botToken) or the TELEGRAM_BOT_TOKEN environment variable. With dmPolicy: "pairing", as in the setup page’s example, an unknown sender gets an 8-character code instead of a reply. Message your bot, then approve yourself:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Codes expire after one hour, and approval covers direct messages only, not groups. You can also approve from the Control UI under Settings, then Channels, then DM access requests. The security docs say most channels answer unknown senders with a pairing code the same way; each channel’s page states its own defaults.

How do I choose or change the model?

OpenClaw refers to models as provider/model. The default agent uses agents.defaults.model.primary, then tries agents.defaults.model.fallbacks in order. From the terminal:

openclaw models status
openclaw models list
openclaw models set <model-or-alias>

In chat, /model switches the model for the current session by default. To change the provider itself or its sign-in, exit and run openclaw onboard again; on an existing install it offers your current model first and runs a verification pass.

What goes in the OpenClaw workspace?

The workspace is the agent’s home and working directory, ~/.openclaw/workspace by default (OPENCLAW_WORKSPACE_DIR overrides it). Onboarding seeds these files, and you can edit them under Settings, then Agents, then Files in the Control UI:

File What it holds
AGENTS.md Operating instructions and how to use memory; loaded every session
SOUL.md Persona, tone and boundaries; loaded every session
USER.md Your preferences, with a separate 4,000-character budget (optional)
IDENTITY.md The agent’s name, vibe and emoji
BOOTSTRAP.md One-time first-run ritual; delete it once done
BOOT.md Startup checklist, if the boot-md hook is on (optional)
MEMORY.md, memory/YYYY-MM-DD.md Long-term memory and daily notes
skills/ Workspace skills, highest precedence

Config, credentials and sessions live outside the workspace, in ~/.openclaw/ (openclaw.json and SQLite databases). Do not commit those if you keep the workspace in Git. One warning from the docs: the workspace is the default working directory, not a sandbox. Absolute paths still reach the rest of the machine unless you turn on agents.defaults.sandbox.

How memory in these files works is in the OpenClaw memory guide, and the AGENTS.md guide compares how OpenClaw and other agents read AGENTS.md.

How do I add skills and MCP servers?

Skills are folders with a SKILL.md. openclaw skills search and openclaw skills install pull them from ClawHub. Read a third-party skill and its ClawHub audit before enabling it; the OpenClaw skills guide covers load order, safety and writing your own.

MCP servers give the agent tools from other programs. Add one in the Control UI under Settings, then MCP, then Add server, or from the CLI:

openclaw mcp add docs \
  --url https://mcp.example.com/mcp \
  --transport streamable-http
openclaw mcp doctor docs --probe

Saved servers go under mcp.servers in openclaw.json. The docs make a point worth repeating: saving a definition proves nothing about reachability, the probe does. openclaw mcp status --verbose lists saved servers without starting them, and openclaw mcp login <name> handles servers that use OAuth. Keep API keys out of config literals; the memory guide shows the ${VAR} pattern with ~/.openclaw/.env.

How do I check that OpenClaw works?

openclaw status          # gateway, channels, sessions, recent activity
openclaw status --all    # full read-only diagnosis, safe to paste
openclaw status --deep   # live probe, including channels
openclaw health          # the running gateway's health snapshot
openclaw doctor          # checks and guided repairs (--fix applies them)
openclaw security audit  # review exposure and access settings
openclaw logs --follow

If setup does not work at all, openclaw triage runs read-only checks and writes a sanitized prompt you can hand to Claude Code, Codex or the built-in agent. The docs say secrets, tokens, raw chat and raw logs are left out of it, and nothing leaves your machine until you choose an agent.

How is this different from setting up Hermes Agent?

We run Hermes Agent, several profiles on one Mac, so this is the part we can speak to from use. Both install with a one-line script and both have a gateway for chat apps. The differences you notice during setup:

  • Runtime. OpenClaw needs Node 24.16+ or 26.1+, which its installer adds if missing. Hermes Agent is a Python app that installs into its own directory with its own virtual environment.
  • Several agents. OpenClaw runs several agents inside one Gateway, each with its own workspace. Hermes gives each agent its own profile, with its own config, memory, skills and gateway.
  • First run. OpenClaw’s Quick start tests the model with a live reply before it saves anything, and the first agent gets full access unless you pick Custom setup.

The Hermes Agent setup guide walks through Hermes from scratch, and Hermes Agent vs OpenClaw compares memory, skills, MCP and scheduling in detail.

Share what OpenClaw learns with your other agents

Each OpenClaw agent keeps its memory in its own workspace, on one machine. If you also run Claude Code, Codex, Cursor or Hermes, none of them see it.

Dexio is a hosted wiki those agents read and write over MCP, so what one agent finds, the others can read, and you see what they know as a page graph at https://app.dexio.wiki. It is open source (AGPL-3.0) and free for one person. Once OpenClaw is running, send it this:

Connect yourself to my Dexio wiki. The steps are at https://dexio.wiki/agents.md: read the whole file, not a summary, and follow them.

OpenClaw gives you a sign-in link and code, then adds Dexio as a Streamable HTTP server; the OpenClaw memory guide has the manual config and the check. To look at the markdown already in a folder, such as your workspace, the free wiki graph viewer shows its pages and links in the browser.

FAQ

Where is the OpenClaw config file? ~/.openclaw/openclaw.json. For service accounts or custom layouts, OPENCLAW_CONFIG_PATH points to another config file and OPENCLAW_STATE_DIR moves the state directory.

Which port does OpenClaw use? The Gateway listens on 18789 by default, bound to loopback on a regular host install.

Can I run OpenClaw on a VPS? Yes. The install docs have guides for Docker, Hetzner, DigitalOcean, Oracle Cloud, Fly.io, Railway, Render, Kubernetes and a Raspberry Pi, among others. Read the exposure runbook first, since container images bind beyond loopback by default.

How do I re-run setup? openclaw onboard for the model and its sign-in, openclaw configure for everything else, and openclaw channels add for a new channel.

Sources

Ask a question

Ask anything about Dexio.

About
We reply by email.