OpenClaw GitHub: Install Guide + First Agent in 12 Minutes (2026)

If you searched openclaw ai agent github, you’re probably one of three people: an engineer evaluating local-first agent frameworks, someone migrating from a hosted assistant, or a researcher cloning the repo for a side project. This is the install path I use on a fresh LXC, with the security caveats the README glosses over.

I run OpenClaw in production on my homelab as a personal assistant across WhatsApp, Telegram, and iMessage. The install is straightforward; the gotchas are around Node versions, sandbox backends, and channel credential security. Here’s the 12-minute path.

Prerequisites

Requirement	Version	How to check
Node.js	24 (recommended), 22.19+ supported	node -v
npm	10+	npm -v
Docker	24+	docker --version
Git	any modern	git --version
RAM	4GB+ free	free -h / Activity Monitor
Disk	2GB+ free	df -h

If node -v returns anything below 22.19, install Node 24 via nvm before anything else. This is the #1 install failure.

Step 1: Clone the repository

git clone https://github.com/openclaw/openclaw.git
cd openclaw

The repo is ~80MB. Cloning typically takes under 30 seconds.

Step 2: Install dependencies

npm install

This pulls ~600 npm packages. Takes 2-4 minutes on a typical broadband connection. If npm install fails with a Node version error, see prerequisites above.

Step 3: Configure environment

OpenClaw looks for config at ~/.openclaw/openclaw.json. Create it:

mkdir -p ~/.openclaw
cp config/openclaw.example.json ~/.openclaw/openclaw.json

Open the file and set at minimum:

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4",
    "apiKey": "sk-ant-..."
  },
  "sandbox": {
    "backend": "docker"
  },
  "channels": []
}

Provider options: openai, anthropic, openrouter, ollama. For local-only setups, point provider to ollama and add endpoint: "http://localhost:11434".

Step 4: Start the Docker sandbox

docker compose up -d openclaw-sandbox

This pulls the OpenClaw sandbox image (~400MB on first run) and starts the container. Verify it’s running:

docker ps | grep openclaw-sandbox

If you skip this step, OpenClaw will start but agents won’t have isolated execution.

Step 5: Start the Gateway

npm run gateway:start

You’ll see the CLI prompt appear. This is your first agent — talk to it directly:

> Hello, can you confirm you can read my config file?

If you get a coherent response naming the model and the location of openclaw.json, you’re live.

Step 6: Wire up your first channel

The CLI is the boring channel. The real value is adding messaging.

Telegram (easiest, 5 minutes)

1. Open Telegram, message @BotFather, run /newbot, name it, get the bot token
2. In OpenClaw CLI:

> /skill install telegram
> /skill configure telegram

3. Paste the bot token when prompted
4. Restart the gateway: Ctrl+C then npm run gateway:start
5. Message your bot on Telegram — it responds

WhatsApp (15 minutes — pairing dance)

1. /skill install whatsapp
2. /skill configure whatsapp
3. Scan the QR code with WhatsApp → Linked Devices
4. Send a pair DM from your authorized number (security default)
5. Now message normally

iMessage (Mac-only, 5 minutes)

Requires running OpenClaw on a Mac with iMessage signed in. Add the iMessage skill, grant Full Disk Access in System Settings, restart Gateway.

Common failures (what actually breaks)

After running this on 6 different machines, the failure modes are:

Failure	Cause	Fix
npm install fails with engines	Node < 22.19	nvm install 24 && nvm use 24
Docker sandbox won’t start	Docker daemon not running	sudo systemctl start docker / Docker Desktop
LLM calls return 401	API key not loaded from ~/.openclaw/openclaw.json	Restart gateway after editing config
Telegram bot doesn’t respond	Bot privacy mode on	@BotFather → /setprivacy → Disable
WhatsApp pair timeout	Authorized number mismatch	Set whatsapp.authorizedNumbers in config
iMessage skill blank replies	No Full Disk Access for Node binary	System Settings → Privacy → Full Disk Access
High RAM (8GB+)	Local Ollama model loaded	Switch to remote API or smaller model

Security caveats the README glosses over

These are real but easy to miss:

1. Channel credentials live in plaintext at ~/.openclaw/openclaw.json by default. Set restrictive perms: chmod 600 ~/.openclaw/openclaw.json.
2. Docker socket mount — the default sandbox mounts /var/run/docker.sock so the agent can spawn containers. This is a privilege escalation surface. For untrusted agents, use the openshell backend instead.
3. MCP server permissions — OpenClaw’s MCP support (added early 2026) inherits whatever permissions the MCP server has. A filesystem MCP server with read access to ~/ exposes everything there to the agent. Scope MCP server roots tightly.
4. WhatsApp/iMessage — message logs are mirrored to OpenClaw’s local DB. If you’re privacy-sensitive, this matters.

For more on MCP server scoping in production, see Claude MCP: 90-Day Production Review and /glossary/mcp/.

First useful agent: a daily research brief

{
  "name": "morning-brief",
  "schedule": "0 7 * * *",
  "channel": "telegram",
  "prompt": "Fetch top 5 stories from Hacker News front page, summarize each in 2 sentences, tag with priority for an AI engineer. Reply via Telegram to my account."
}

Saved to ~/.openclaw/workspace/agents/morning-brief.json. The cron daemon picks it up; the agent calls the browser tool, the LLM summarizes, the Telegram channel delivers. End-to-end: ~$0.02/day in API costs.

When OpenClaw isn’t the right pick

• You want a team product — OpenClaw is single-user. Look at Trinity, n8n, or OpenSwarm for multi-user.
• You want autonomous coding — OpenClaw is conversational/scheduled. Use Claude Code, Cursor, or Cline.
• You want self-improving persistent agent — that’s Hermes Agent. See Hermes vs OpenClaw for the full comparison.

---

Picking between local-first agent platforms? The AI Coding Stack Decision Guide ($49) covers the 12-criteria rubric I use to grade self-hosted agents (Hermes, OpenClaw, OpenSwarm, Trinity).

Catalog entries: /agents/openclaw/ · /agents/hermes-agent/ · /agents/openswarm/