OpenClaw Getting Started: Self-Hosted AI Gateway Across Chat Apps

OpenClaw is easy to misread as "yet another chat UI for an API key." It isn't. It is a self-hosted multi-channel gateway that sits between the messaging apps you already use and an agent that can run tools, keep sessions, and talk back from your pocket — on your machine, under your rules.

1. What you're actually buying​

From the OpenClaw docs home and Getting started:

Mental model:

Who it is for: developers and power users who want a personal AI assistant reachable from anywhere, without surrendering data to a hosted chat product.

What makes it different:

• Self-hosted — your hardware, your config, your credentials
• Multi-channel — one Gateway, many chat apps at once
• Agent-native — tools, sessions, memory, sub-agents, automation — not a thin wrapper around chat completions
• Open source — MIT licensed; developed in the open by the OpenClaw Foundation

You need a supported Node runtime, a model-provider API key (Anthropic, OpenAI, Google, OpenRouter, local Ollama/LM Studio, and many others), and roughly five minutes for the happy path.

2. Prerequisites and platform paths​

Runtime​

• Node.js 22.22.3+, 24.15+, or 25.9+ — Node 26 is the recommended default
• Check with node --version
• Fresh installs via the installer script can provision Node when it is missing (Install, Node setup)

Windows choices (Windows)​

Privacy-sensitive node commands (screen.record, camera.snap, camera.clip) need explicit Gateway allowlists — they are not on by default.

Linux always-on note (Setup)​

Linux installs use a systemd user service. User services can die on logout unless lingering is enabled:

sudo loginctl enable-linger $USER

For always-on multi-user servers, prefer a system unit over a user unit.

3. Quick setup (the five-minute path)​

Follow the official Getting started sequence.

Step 1 — Install​

macOS / Linux:

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

Windows (PowerShell):

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

Skip onboarding in the installer if you want install-only:

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

Step 2 — Onboard and install the daemon​

openclaw onboard --install-daemon

The wizard picks a model provider, collects an API key (or reuses detected local AI access), and configures the Gateway. QuickStart is usually short; full runs take longer if you add channel pairing, skills, plugins, or daemon install in one sitting. Skip optional steps and return later with openclaw configure.

Full wizard behaviour: Onboarding (CLI).

Step 3 — Verify the Gateway​

openclaw gateway status

You should see the Gateway listening on port 18789 (default WebSocket / Control UI host: http://127.0.0.1:18789/).

Step 4 — Open the dashboard​

openclaw dashboard

If the Control UI loads, the install is healthy. Type a message in the chat panel and expect a model reply.

Step 5 — Optional: chat from your phone​

Fastest channel is usually Telegram (bot token only, included in core). See Telegram and the broader Channels catalogue.

Sanity commands after any install​

openclaw --version
openclaw doctor
openclaw gateway status
openclaw health

4. Install methods beyond the script​

From Install:

Managed startup after install:

• macOS: LaunchAgent via onboard or openclaw gateway install
• Linux / WSL2: systemd user service
• Native Windows: Scheduled Task (with Startup-folder fallback if task creation is denied)

If openclaw is "not found," it is almost always a PATH problem for npm's global bin directory — see Node troubleshooting.

5. Onboarding in depth: guided vs classic​

From Onboarding (CLI):

Guided default (openclaw onboard)​

1. Accept the security notice.
2. Detect existing model access (API-key env vars, supported local CLIs, Ollama / LM Studio on the Gateway host). Detection is read-only — it never downloads a model.
3. Verify with a real completion. Failures show a reason and try the next candidate.
4. If nothing works, pick OpenAI, Anthropic, xAI, Google, OpenRouter, or More…. Skip for now exits without starting OpenClaw.
5. Persist only the verified model route (and required credential/plugin state).
6. Start OpenClaw so it can finish workspace, Gateway, channels, agents, plugins, and optional setup.

Re-running onboard on a configured machine re-verifies the current default model first. A failing check does not silently replace your model — you choose how to continue. Provider/auth changes: run openclaw onboard again. Non-inference additions: openclaw channels add or openclaw configure.

Locale for fixed onboarding copy: OPENCLAW_LOCALE → LC_ALL → LC_MESSAGES → LANG (supported: en, zh-CN, zh-TW). Product names and config keys stay English.

Classic wizard (openclaw onboard --classic)​

Choose QuickStart or Advanced (--flow quickstart / --flow advanced).

QuickStart defaults (local):

• Loopback Gateway, port 18789, token auth (auto-generated even on loopback)
• Default workspace (or existing)
• Tool profile tools.profile: "coding" for new setups
• DM sessions share the agent's rolling main session across channels (personal-agent default); multi-user inboxes should use session.dmScope: "per-channel-peer"
• Tailscale off
• Telegram / WhatsApp DMs default toward allowlist prompts

Advanced exposes every step: mode, workspace, gateway, channels, daemon, skills.

Remote mode (--mode remote) only configures this machine as a client of a Gateway elsewhere — it never installs or mutates the remote host.

Classic steps in order: Model/Auth → Workspace (~/.openclaw/workspace) → Gateway (port, bind, auth, Tailscale; optional SecretRef for tokens) → Channels → Daemon → Health check → Skills.

Security note from the docs: if the agent will run tools or process webhook/hook content, prefer the strongest latest-generation model and keep tool policy strict — weaker tiers are easier to prompt-inject.

Reset is opt-in (Reset in UI or --reset; --reset-scope full also removes the workspace). Invalid/legacy config → run openclaw doctor first.

Extra agents​

openclaw agents add <name>

Creates a separate agent with its own workspace, sessions, and auth profiles (default workspace ~/.openclaw/workspace-<name>). Bindings route inbound messages; this is not a full re-onboard.

6. Channels: where the assistant lives​

From Chat channels:

Text works everywhere; media and reactions vary. iMessage, Telegram, and WebChat ship in core. Many others are official plugins (openclaw plugins install @openclaw/<name> or on-demand during onboard / channels add, then Gateway restart). Some are external plugins.

Representative catalogue: Discord, Feishu, Google Chat, iMessage, IRC, LINE, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, QQ Bot, Signal, Slack, SMS (Twilio), Synology Chat, Telegram, Twitch, Voice Call, WebChat, WhatsApp, Zalo, plus others (Buzz, Reef, Raft, WeChat, Yuanbao, …).

Practical defaults:

• Fastest first remote channel: Telegram (token; no plugin install)
• WhatsApp: QR pairing via Baileys; more on-disk state; popular but heavier
• Multiple channels can run simultaneously; routing is per chat
• DM pairing and allowlists are the safety net — see Pairing and Security

Telegram walkthrough (recommended first channel)​

From Telegram:

1. Create a bot with @BotFather (/newbot) and copy the token.
2. Configure:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

Env fallback for the default account: TELEGRAM_BOT_TOKEN. Telegram does not use openclaw channels login telegram — set the token, start the Gateway, then pair.

3. Approve yourself:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Codes expire after 1 hour. Default DM policy is pairing.

4. Groups: disable Privacy Mode or make the bot an admin if it must see all messages; put numeric user IDs in allowlists and group chat IDs under channels.telegram.groups. DM pairing does not grant group command rights.

For one-owner bots, prefer dmPolicy: "allowlist" with explicit numeric allowFrom over relying only on historical pairing approvals. dmPolicy: "open" with allowFrom: ["*"] is intentionally public — only for tightly tool-restricted bots.

7. Pairing and access control​

From Pairing:

OpenClaw uses pairing in two places:

1. DM pairing — who may talk to the bot
2. Node / device pairing — which phones, Windows Hub nodes, or browsers may join the Gateway network

DM pairing​

With dmPolicy: "pairing", unknown senders get an 8-character code (uppercase, no ambiguous 0O1I). Messages are not processed until you approve. Pending requests cap at 3 per channel account.

Approve in Control UI (Settings → Channels → DM access requests) or:

openclaw pairing list <channel>
openclaw pairing approve <channel> <CODE>

First CLI approval can bootstrap commands.ownerAllowFrom when no owner exists yet (privileged commands / exec approvals). Later approvals grant DM access only.

Reusable sender sets across channels: top-level accessGroups with accessGroup: references in allowlists (Access groups).

State lives in SQLite: ~/.openclaw/state/openclaw.sqlite (legacy JSON allowlists migrate via startup / openclaw doctor --fix). Treat that DB as sensitive — it gates access to your assistant.

Node pairing (mobile / Windows / Control UI)​

Devices connect with role: node and must be approved (official iOS/Android apps can auto-approve when setup-code metadata matches). Prefer Control UI Settings → Devices → Pair mobile device, or Telegram /pair with the device-pair plugin.

Setup codes encode Gateway URL(s) plus a single-use bootstrap token (≈10 minutes). Treat them like passwords. Prefer wss:// or Tailscale Serve for full access; plaintext LAN ws:// tends to get limited operator scopes.

openclaw devices list
openclaw devices approve <requestId>

Already-paired devices that ask for broader scopes get a new pending upgrade — approvals never silently widen.

8. Tools, skills, and plugins​

From Tools overview:

Built-in tool categories (representative):

• Runtime: exec, process, terminal, code_execution
• Files: read, write, edit, apply_patch
• Web: web_search, x_search, web_fetch
• Browser: browser
• Messaging: message
• Sessions / agents: sessions_*, subagents, goals, swarm orchestration
• Automation: cron, heartbeat responders
• Media: image, image_generate, tts, video/music generation
• Experimental: Code Mode, Tool Search for large catalogs without stuffing every schema into the prompt

Tool visibility is filtered by profile, allow/deny lists, provider restrictions, sandbox state, channel permissions, and plugin availability — if policy removes a tool, the model never sees its schema for that turn.

New setups often default to tools.profile: "coding". Tighten before exposing the Gateway beyond loopback. Deep reference: Tools and custom providers, Exec approvals, Sandbox vs tool policy vs elevated.

Web search providers (classic wizard / configure web search): Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG, Tavily — some need keys, some do not (Web tools).

9. Configuration and environment​

Config file​

From Gateway configuration:

• Path: ~/.openclaw/openclaw.json (JSON5)
• Missing file → safe defaults
• Strict schema validation — unknown keys or bad types refuse Gateway start; use openclaw doctor / openclaw doctor --fix
• Edit via openclaw onboard, openclaw configure, openclaw config get|set|unset, Control UI Config tab, or direct file edit (hot reload when valid)

Minimal example:

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Shared DM policy pattern:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // allowlist / open
    },
  },
}

Model primary + fallbacks use provider/model refs, e.g. anthropic/claude-sonnet-4-6 with optional openai/gpt-5.4 fallback.

Custom Control UI build (Getting started)​

Point gateway.controlUi.root at a directory with built static assets + index.html, then:

openclaw gateway restart
openclaw dashboard

Environment variables (Environment)​

Precedence (never overrides existing values): process env → CWD .env (credentials/runtime controls ignored) → ~/.openclaw/.env → config env block → optional login-shell import.

Operator path overrides:

Put provider API keys in process env, ~/.openclaw/.env, config env, or SecretRefs — not only in a workspace .env (workspace dotenv is lower-trust and strips provider credentials).

Legacy CLAWDBOT_* / MOLTBOT_* prefixes are ignored; rename to OPENCLAW_*.

Where state lives (Setup)​

Keep personalisation outside the git repo:

• Config: ~/.openclaw/openclaw.json
• Workspace / skills / memories: ~/.openclaw/workspace (good private git repo candidate)
• Credentials: ~/.openclaw/credentials/
• Auth profiles: ~/.openclaw/agents/<id>/agent/auth-profiles.json
• Sessions: SQLite under each agent dir
• Pairing / devices: ~/.openclaw/state/openclaw.sqlite

Bootstrap folders without full wizard:

openclaw setup --baseline

(Bare openclaw setup aliases to full onboard.)

10. Security model you must not skip​

From Security:

• Personal-assistant trust model: one trusted operator boundary per Gateway — not a hostile multi-tenant product.
• Mutually untrusted users ⇒ separate Gateways (ideally separate OS users/hosts), not one shared agent with tools.
• Anyone who can modify ~/.openclaw is a trusted operator.
• Before opening remote access, reverse proxies, or public DMs, run the exposure checklist and:

openclaw security audit
openclaw security audit --deep
openclaw security audit --fix

If openclaw security audit recommends DM isolation for multi-user traffic, treat that as a product warning, not a style note — shared inboxes plus tool-enabled agents share delegated authority.

11. Day-2 operations​

Automation beyond chat: cron, heartbeat, hooks, Task Flow — see Automation. Multi-agent coordination: Sub-agents, Swarm, ACP agents.

12. Traps and gotchas​

Trap 1 — Treating OpenClaw as a hosted chatbot. It is a local/server Gateway with real tool authority. Pairing defaults and loopback binds exist for a reason.

Trap 2 — dmPolicy: "open" on a tool-enabled bot. That is public command of whatever tools the agent can see. Prefer pairing or numeric allowlists.

Trap 3 — Assuming DM pairing authorises groups. Pairing is DM-only; group allowlists and mention rules are separate.

Trap 4 — Putting API keys only in workspace .env. Those credentials are ignored for providers; use ~/.openclaw/.env, process env, or SecretRefs.

Trap 5 — Editing openclaw.json with unknown keys. Strict validation refuses start; use doctor --fix and the schema (openclaw config schema).

Trap 6 — Wrong port / dual Gateways. Default is 18789; keep app, CLI, and nodes aligned. Avoid accidental second Gateway fighting the supervised service.

Trap 7 — Linux Gateway dies after logout. Enable lingering or use a system service.

Trap 8 — Weak models + tools. Docs explicitly warn that older/weaker tiers are easier to prompt-inject when tools and webhooks are enabled.

Trap 9 — Symlinked openclaw.json. Atomic writes replace the symlink target layout — point OPENCLAW_CONFIG_PATH at a real file.

Trap 10 — npm 12 global install without --allow-scripts. Lifecycle scripts are blocked and the install may look "fine" while incomplete.

Quick decision checklist​

Before calling the setup "production-ready":

• openclaw gateway status shows a healthy listener on the expected port.
• Control UI chat works with a verified model completion.
• DM policy is pairing or an explicit allowlist — not accidental public open.
• First owner is set (commands.ownerAllowFrom) if you use privileged commands / exec approvals.
• Tool profile matches exposure (coding tools on loopback ≠ coding tools on a public Telegram bot).
• openclaw security audit has been run after config changes.
• Credentials live in trusted env/config paths, not workspace-only dotenv.
• Remote access uses authenticated Gateway + wss:// / Tailscale rather than raw public ws://.
• Personal config/workspace are outside the OpenClaw source tree so updates do not clobber them.

Reading order​

1. Getting started — install → onboard → dashboard
2. Onboarding (CLI) — guided vs classic, remote mode, agents add
3. Install — npm/pnpm/source/Docker/VPS
4. Channels + Telegram — first remote surface
5. Pairing + Security — who may talk and who may join
6. Tools overview — tools vs skills vs plugins
7. Gateway configuration + Environment variables
8. Setup — stable vs bleeding-edge workflows
9. Windows — if that is your desktop

Verdict​

OpenClaw is the right default when you want a self-hosted, multi-channel, tool-capable personal agent and are willing to own Gateway ops, pairing, and tool policy. The five-minute path (installer → onboard --install-daemon → dashboard) is real; the long-term value is one Gateway that already speaks Telegram today and Discord/Slack/WhatsApp tomorrow without rewriting your assistant. Treat security as part of onboarding — not an afterthought once the bot is in a group chat.