You just heard about OpenClaw, typed “how do I install this thing?” into a search bar, and landed here. Good news: this is the definitive from zero to first message guide. We’ll walk through prerequisites, the npm install, the Gateway onboarding wizard, spinning up your first agent, wiring it to Telegram, and a handful of experiments to run in your first hour. No prior Node.js or AI-agent experience assumed.

What OpenClaw Is (And What It Isn’t)

OpenClaw is an open-source AI agent framework written in Node 22+. Think of it as a programmable chatbot skeleton that can:

  • Live on the channels where people already hang out — WhatsApp, Slack, Telegram, Discord, Signal, iMessage, or the web UI.
  • Call out to 800+ third-party tools through the Composio integration layer (GitHub, Gmail, Notion, Calendar, etc.).
  • Browse the web headlessly, run shell commands in a jailed sandbox, remember context between sessions, and schedule cron-like tasks.

What it isn’t: a hosted black box or a general LLM. You bring your own OpenAI, Anthropic, or local model key; OpenClaw just orchestrates conversations and tool usage. You can self-host or click “Create Agent” on ClawCloud and be live in a minute. This article sticks to local install so you see what’s under the hood.

Prerequisites Checklist

Save yourself future face-palms by checking these off first:

  • OS: macOS 12+, Ubuntu 20.04+, or Windows 11 with WSL2. Anything that runs Node 22 works.
  • Node.js 22+: node -v should print at least 22. If not: nvm install 22 && nvm use 22.
  • npm 10+: ships with Node 22. Verify with npm -v.
  • Git: v2.30+. You’ll clone example recipes.
  • OpenAI or Anthropic API key: optional but you’ll hit a wall without one. Export it: export OPENAI_API_KEY="sk-…".
  • Port 3040 free: Gateway’s default HTTP port. Changeable later.

Step 1 – Install OpenClaw Locally

OpenClaw lives on npm as @claw/openclaw. Global install keeps commands in $PATH.

npm install -g @claw/openclaw@latest

The package drops two binaries:

  • claw-gateway — the web UI and inbound webhook server.
  • claw-daemon — background supervisor that restarts the agent if it crashes.

Verify:

claw-gateway --version # prints something like 1.7.3 claw-daemon --version # same version

Step 2 – Fire Up the Gateway & Onboarding Wizard

The Gateway bundles an onboarding flow that scaffolds your first agent. Start it:

claw-gateway start --port 3040 --open

This does four things:

  1. Loads config from ~/.claw/config.json (creates it if missing).
  2. Generates an agent-id and local SQLite memory store.
  3. Boots an Express server on http://localhost:3040.
  4. Opens your browser to the onboarding wizard.

Wizard Walkthrough (screenshots in repo README)

  • Step 0: Name your agent — avoid spaces; “alfred”, “support-bot”, etc.
  • Step 1: LLM provider — paste your OpenAI key; choose gpt-4o if you have access, else gpt-3.5-turbo.
  • Step 2: Capabilities — checkboxes for Browser, Shell, Composio. You can add or remove later.
  • Step 3: Storage — default sqlite://./memory.db. For prod you’d point at Postgres.
  • Step 4: Review & launch — the wizard writes agent.json under ~/.claw/agents/<agent-id>/, then starts the runtime.

After launch you land on the Gateway chat UI. Time to talk.

Step 3 – Your First Conversation

Type “hello”. You should see a streaming response like:

Hello! I'm alfred. How can I help today?

Two commands worth testing immediately:

  • /memory list — shows persistent memories (should be empty).
  • /tools — lists enabled tools and docs each exposes.

If you get a red error banner, check the gateway logs in the terminal. The usual culprit: missing or invalid LLM API key.

Step 4 – Connect a Messaging App (Telegram Example)

Chatting in the browser is fine for testing, but the real fun is when friends can ping the agent. Telegram is the fastest on-ramp because it doesn’t require complicated webhooks if you use polling.

Create the bot in Telegram

  1. Open @BotFather and run /newbot.
  2. Name it and grab the HTTP API token. It looks like 654321:ABC-DEF1234ghIkl-zyx57W2v1u123ew11.

Add the integration in OpenClaw

Back in the Gateway UI:

  1. Settings → Integrations → Telegram → “Enable”.
  2. Paste the token. Choose long polling for local dev (no public URL needed).
  3. Click “Connect”.

The gateway log prints:

[telegram] connected, polling interval 1000ms

Now DM your bot “ping”. The message should surface in both Telegram and the Gateway UI, and the agent replies “pong” (or a witty GPT-generated response).

Five Things to Try in Your First Hour

  1. Web scraping with the browser tool
    Ask: “Visit https://news.ycombinator.com and give me the titles of the top 3 posts.” The browser tool spins up Puppeteer and returns structured data.
  2. GitHub issue triage via Composio
    Enable the GitHub tool, auth via OAuth, then: “List open issues on pspdfkit-labs/openclaw with the label ‘bug’.” Useful if you dog-food your own repo.
  3. Shell command (sandboxed)
    Prompt: “Run ls -1 /usr/bin | head -n 5 and show me the output.” The shell tool executes in /tmp/claw-<agent> jail, returns stdout/stderr.
  4. Memory write & recall
    Say: “Remember that my bike lock code is 9124.” Then: “What’s my bike lock code?” Verifies persistence.
  5. Cron-style scheduled task
    Command: “Every day at 9 AM send me a motivating quote on Telegram.” The task scheduler stores a cron expression and uses the same integration token.

Troubleshooting Install Blips

node-gyp fails on arm64 macOS

Xcode CLI tools might be missing. Fix:

xcode-select --install

Port 3040 already in use

Run:

lsof -i :3040 kill <pid> # or start on a different port claw-gateway start --port 4040 --open

“Invalid API key provided”

Double-check env var export. The daemon inherits env when you launch it. You can also paste the key in Settings → Providers.

Where to Go Next

If the basics worked, you have three common next steps:

  • Deploy the same agent on ClawCloud to avoid exposing your laptop to the internet. The free tier gets you one always-on agent.
  • Fork the example-recipe-github-triage template from GitHub and tweak the prompt logic. Community PRs welcome.
  • Join #openclaw on Discord and share what broke; maintainers (including Peter) lurk there daily.

Happy clawing.