OpenClaw First Start: What It Is, What It’s For, and How to Install It Step by Step
Introduction
If you want an assistant you can message from anywhere (WhatsApp, Telegram, Discord, Slack, and more) while keeping the “brains” running on your own machine, OpenClaw is built for that workflow. Instead of living only in a website tab, OpenClaw runs a local Gateway that connects your chat apps to your assistant and a browser-based Control UI you can open anytime.
This post is a full OpenClaw first start guide: what it is, what people use it for, how to install it on macOS/Linux/Windows (WSL2 recommended), how to get your first working chat, how to connect channels safely, and what to do if something breaks.
What is OpenClaw?
OpenClaw is a self-hosted Gateway that bridges messaging apps (like WhatsApp and Telegram) with an assistant you control. You run one Gateway process on your machine or server, and it provides:
- A Control UI (dashboard) you can open in your browser
- A single place to connect multiple chat channels
- A local control plane for sessions and tool-enabled workflows
In simple terms: you message your assistant in the apps you already use, while OpenClaw runs the infrastructure on your hardware.
Why people use OpenClaw (use cases)
Here are realistic ways OpenClaw gets used once it’s up:
1) Chat-first productivity
- Ask for summaries, rewrite drafts, generate checklists, and plan your day from a chat thread
- Keep a “single inbox” conversation where you drop tasks and turn them into actions
2) Multi-channel access, one assistant
- Message from WhatsApp when you’re away from your desk
- Use Telegram in groups for shared team reminders
- Use Discord or Slack for community or internal automation
3) Local-first control and privacy
- Keep your Gateway and configuration on your own machine
- Decide what channels are connected and who is allowed to message it
- Avoid exposing a public endpoint when you don’t need one
4) Automation-style workflows (optional)
Once you’re comfortable, you can add more capabilities gradually: approvals, pairing rules, tool execution, and other “do things” workflows—without changing where you chat.
How OpenClaw works (quick mental model)
Understanding this makes installation and troubleshooting much easier:
- OpenClaw CLI: the command-line tool you install (“openclaw …” commands)
- Gateway: the local server process (HTTP + WebSocket) that runs the Control UI and handles channels
- Control UI: the browser dashboard that talks to the Gateway
- Channels: connectors for WhatsApp, Telegram, Discord, Slack, etc.
- Config: your settings file (commonly in your home folder)
The Gateway usually runs on port 18789, so your Control UI is typically available at:
http://127.0.0.1:18789/
Prerequisites (before you install)
Do these checks first so the install goes smoothly:
1) Have Node.js ready (Node 22+)
OpenClaw requires Node.js 22 or newer. Check:
node --version
If you don’t have it (or you’re on an old version), the recommended OpenClaw installer can handle Node detection and setup for you.
2) Windows users: use WSL2 if possible
OpenClaw supports Windows, but many users get the smoothest experience using WSL2 for the Linux-style install flow.
3) Make sure port 18789 is free
If another app already uses that port, your Gateway/Control UI won’t start. You can change the port later, but it’s easiest to start with the default.
Installation method 1 (recommended): the official installer script
This is the easiest OpenClaw first start path because it handles Node detection, CLI installation, and onboarding in one flow.
macOS / Linux / WSL2
Open Terminal and run:
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (PowerShell)
Open PowerShell and run:
iwr -useb https://openclaw.ai/install.ps1 | iex
When it finishes, you should have the openclaw command available.
Installation method 2 (manual): npm or pnpm
If you prefer manual installs (for example, you already manage Node yourself), you can install the CLI globally.
npm
npm install -g openclaw@latest
pnpm
pnpm add -g openclaw@latest
After that, continue to onboarding.
Step-by-step: onboarding and first working chat
This section is the “OpenClaw first start” flow you want to follow in order.
Step 1: Run the onboarding wizard
This configures Gateway settings, auth, and optional channels. It can also install a background service/daemon so the Gateway stays running.
openclaw onboard --install-daemon
What to choose in onboarding (practical guidance):
- Gateway location: Local (for a first start)
- Auth: Token (recommended for safety)
- Channels: Skip for now if you want the fastest first chat (you can add channels later)
Step 2: Confirm the Gateway is running
openclaw gateway status
If it’s running, you’re ready for the Control UI.
Step 3: Open the Control UI (dashboard)
This is the fastest way to confirm everything works because you can chat right away without configuring any messaging channel.
openclaw dashboard
Or open it directly in your browser on the Gateway machine:
http://127.0.0.1:18789/
Step 4 (optional): Run the Gateway in the foreground for debugging
If you want to see logs live while testing:
openclaw gateway --port 18789
Connecting chat channels (WhatsApp, Telegram, Discord, Slack)
Once the Control UI works, you can connect a channel so you can message your assistant from your phone or favorite app.
Step 1: Start channel login
openclaw channels login
OpenClaw supports multiple channels (WhatsApp, Telegram, Discord, IRC, Slack, Feishu/Lark via plugin, Google Chat, and more). The exact setup varies by channel.
WhatsApp basics (first-time friendly)
WhatsApp is popular for OpenClaw, and it typically uses a QR pairing flow. A few best practices:
- Consider using a dedicated WhatsApp number for the assistant when possible
- Don’t open access to everyone by default—add an allowlist rule
A minimal example config that only allows messages from one number looks like this:
{
"channels": {
"whatsapp": {
"allowFrom": ["+15555550123"]
}
}
}
Save your config, then restart the Gateway if needed.
Telegram basics (first-time friendly)
Telegram usually uses a bot token flow (you create a bot and paste the token during setup). Once connected:
- Test in a private chat first
- Then add it to a group only after you confirm your allowlist or pairing rules
Discord and Slack basics
Discord and Slack use bot/app setups where you create an app in their developer portals and provide credentials during setup. Start with a single test server/workspace before rolling out broadly.
Security settings you should not skip
OpenClaw is powerful because it’s always-on when the Gateway runs as a service. That also means you should treat it like any self-hosted service.
1) Keep the Gateway private (bind to localhost)
For personal use, do not expose the Gateway directly to the public internet. Keep it on localhost (127.0.0.1) unless you truly know what you’re doing.
2) Use authentication (token)
During onboarding, token auth is a strong default. If your machine is shared or you plan to access the UI remotely through a tunnel, auth becomes even more important.
3) Be careful with “canvas” and untrusted content
The Gateway serves web content (the Control UI and other hosted surfaces). Treat any arbitrary or unknown content as untrusted, and avoid installing random add-ons from places you don’t trust.
If you need remote access, use a private tunnel (instead of opening the Gateway port publicly).
Helpful environment variables (advanced but useful)
If you run OpenClaw under a service account or want to control where it stores state/config, these environment variables can help:
- OPENCLAW_HOME
- OPENCLAW_STATE_DIR
- OPENCLAW_CONFIG_PATH
You can set these in your shell profile or service configuration depending on your OS.
Troubleshooting (common first-start problems)
Problem: “openclaw: command not found”
This usually means the global npm bin directory isn’t on your PATH.
Try:
npm prefix -g
echo "$PATH"
A common fix on macOS/Linux is adding npm’s global bin to PATH:
export PATH="$(npm prefix -g)/bin:$PATH"
Then open a new terminal and retry:
openclaw --help
Problem: The dashboard won’t load
Check the Gateway:
openclaw gateway status
If it’s not running, start it:
openclaw gateway --port 18789
If the port is busy, pick a different one:
openclaw gateway --port 18889
Then open:
http://127.0.0.1:18889/
Problem: Messages from chat apps don’t reach OpenClaw
- Confirm the channel is logged in and connected
- Confirm your allowlist/pairing rules permit your number/user
- Restart the Gateway after changing config
Problem: You want a quick end-to-end test
If you already configured a channel, you can send a test message from CLI (example format):
openclaw message send --target +15555550123 --message "Hello from OpenClaw"
Next steps after your first chat
Once you’ve completed the OpenClaw first start successfully, the best next step is to expand slowly:
- Keep using the Control UI until things feel stable
- Add one channel (WhatsApp or Telegram) and lock it down with allowlists
- Only then explore more automation features and integrations
Conclusion
OpenClaw is at its best when you keep the setup simple: install the CLI, run onboarding, confirm the Gateway, open the dashboard, then add channels one at a time with clear access rules. If you follow that order, you’ll get a clean first start and a setup you can trust long-term.
References
https://openclaw.ai/
https://docs.openclaw.ai/
https://docs.openclaw.ai/install
https://docs.openclaw.ai/start/getting-started
https://docs.openclaw.ai/channels
https://docs.openclaw.ai/channels/whatsapp
https://docs.openclaw.ai/gateway/security