OpenClaw Setup Guide: Install, Harden, and Connect Your First Agent
OpenClaw is the MIT-licensed personal agent runtime that runs on your own box, talks to any LLM you want, and routes messages through WhatsApp, Telegram, Slack, Discord, and 50+ messaging channels. This guide is for practitioners who want it running cleanly in under an hour with security defaults that will not get you fired. We will cover prerequisites, the three install paths, the seven workspace files that define your agent's behavior, the 13-item hardening checklist you cannot skip, and the ClawHub skill vetting rules that keep info-stealers off your machine.
Quick Verdict
Self-hosting OpenClaw takes 30-60 minutes end to end. Node 22.14+, 500 MB+ base RAM, and a hardening checklist are non-negotiable. The default Gateway bind is 0.0.0.0:18789 — that is a direct path to remote code execution if you leave it exposed. OpenClaw Cloud at $39/mo skips the infra work entirely if you would rather outsource the sysadmin piece and just author SOUL.md and a few skills.
Prerequisites Checklist
Click items as you confirm them. State persists in localStorage, so you can close the tab and come back. If any of these are missing, stop and fix them before you run a single command — skipping prereqs is where most broken installs originate.
Installation Paths
Three ways to get OpenClaw running. Pick based on how much infrastructure work you want to own. If you have never administered a Linux box before, start with the managed cloud option — you can migrate to self-hosted later once you understand the configuration surface.
The rest of this guide is written for self-hosted. If you pick Cloud or Lighthouse, skip ahead to Step 2 (workspace files) and Step 4 (messaging connection) — the managed platforms handle Steps 1 and 3 for you.
Step 1 — Install Node and OpenClaw
Verify Node first. OpenClaw's install will bail if you are on anything below 22.14. On a fresh Ubuntu VPS, the distro repo usually ships an older version — use nvm or the NodeSource binaries to get 22 or 24.
Install OpenClaw per the official docs. The exact package name and install verb can shift between releases — treat the block below as illustrative and confirm the current command against docs.openclaw.ai before running it. The repo at github.com/openclaw/openclaw is the canonical source.
Why this guide stays vague on the exact npm incantation: the package name has changed twice already (Clawdbot → Moltbot → OpenClaw, November 2025 to January 2026) and the install path has moved during each rename. Always pull the current command from docs.openclaw.ai rather than copying a command from a stale blog post.
The workspace init creates an openclaw.config.yaml at the root of your workspace directory. Here is a minimal shape you will edit in Step 3 — treat this as illustrative and verify key names against the official docs for your version:
Once the CLI is on your PATH and the workspace is initialized, OpenClaw drops a default directory layout: ~/.openclaw/ for credentials and state, and your workspace folder for the Markdown files we author in Step 2. Do not skip to launching the Gateway yet — the default bind is wide open, and Step 3 closes that hole.
Step 2 — Configure Workspace Files
OpenClaw's behavior is defined by seven Markdown files in your workspace. Think of them as layered context that gets injected into every agent turn. Getting this right is half the battle — a sloppy SOUL.md produces a sloppy agent.
- SOUL.md — Agent personality, values, hard limits. First file injected every session. If it is not here, it is not reliable behavior.
- IDENTITY.md — Name, vibe, emoji, avatar. Cosmetic but helps humans track which agent they are talking to when you run several.
- USER.md — User context (pronouns, timezone, role). Never commit this to a public repo — it is a PII magnet.
- TOOLS.md — Which tools to use when. Does NOT grant permissions — the config file does. This file is guidance, not access control.
- AGENTS.md — Multi-agent workflow instructions. Required if you are wiring more than one agent together; skip on first single-agent pass.
- HEARTBEAT.md — Cron-style scheduled tasks. Runs every 30 minutes by default. Morning briefings, Git digest posts, health checks.
- MEMORY.md — Curated long-term memory, layered with memory/YYYY-MM-DD.md daily logs.
Here is a sample SOUL.md you can drop in and edit:
Do not commit USER.md to Git. Add it to .gitignore on day one. Timezone and role leak context; pronouns and health notes leak more. Keep it local or in a private vault.
Pick a tool profile in your config: full (everything, default), coding (file I/O, runtime, sessions, memory, image), messaging (messaging + session list/history/send/status), or minimal (session_status only). Start at minimal if you are evaluating, then widen.
Step 3 — Security Hardening (DO NOT SKIP)
The default OpenClaw install is hostile to strangers, not to attackers on the same LAN or a compromised browser tab. The Gateway binds to 0.0.0.0:18789 by default, which means every interface on the box answers agent API calls. Plaintext credentials in ~/.openclaw/ are an info-stealer magnet. Work through every item below before you route a real message.
The 13-item hardening checklist
One more patch note: the localhost trust flaw fixed in v2026.2.25 (February 26, 2026) closed a hole where JavaScript in any open browser tab could hit the Gateway and brute-force the password. If you are on an older build, upgrade before Step 4 — an attacker does not need to be on your network, they just need a malicious ad to load.
Step 4 — Connect Your First Messaging Platform
Telegram and Slack are the two easiest starting points. Telegram wins on pure setup simplicity: BotFather gives you a bot token in under two minutes, no workspace admin required. Slack is close behind if you already have workspace owner rights.
Telegram (recommended first)
- Open @BotFather in Telegram, run /newbot, follow the prompts, copy the HTTP API token.
- Add the token to your workspace config under the Telegram channel section (see docs.openclaw.ai for the exact key name in your version).
- Send a DM to your new bot from your own account. Watch the Gateway logs — you should see a paired-session message.
- Reply with "hello" and confirm the agent responds using whatever LLM you configured in Step 1.
Slack
- Create a Slack app at api.slack.com/apps, install it to your workspace, grab the Bot User OAuth Token.
- Enable Socket Mode if you do not want to run a public webhook endpoint — this keeps the Gateway behind loopback bind (Step 3, item 1).
- Subscribe to message.im and app_mention events. DM pairing uses the im event; channel interaction uses app_mention.
- Add the bot to one test channel. Mention it. Confirm reply.
The other 50+ channels
WhatsApp requires Meta Business verification and is heavier to set up; start with a Meta developer sandbox. Discord uses a bot token flow similar to Telegram (Developer Portal → New Application → Bot → token). Signal integration needs a dedicated phone number — painful but doable. iMessage works via the Beeper bridge or a macOS-hosted instance; not headless-friendly. Enterprise channels (Microsoft Teams, Matrix, WeCom, Feishu/Lark, DingTalk) all need admin approvals and were added across various 2026 releases — WeCom Agent mode in v2026.2.6-3 (February 9), Feishu/Lark native in v2026.2.2, WeChat consumer via Tencent on March 22, 2026.
Get one channel working first. Do not try to onboard three platforms in parallel on day one. One channel paired, one clean round-trip, then add another. Most failed installs come from stacked auth problems across multiple channels that are hard to untangle.
Step 5 — Add Your First Skill (Carefully)
Skills are guidance files (SKILL.md injected into the system prompt) paired with the tools they describe. ClawHub is the community registry. It is also the biggest attack surface in the OpenClaw ecosystem. Read this section twice before you install anything.
MANDATORY WARNING — the ClawHub malicious skill rate. Three independent security firms audited ClawHub and found wildly different rates depending on methodology: Koi Security flagged 12% of 2,857 audited skills as malicious (341 skills, including the "ClawHavoc" campaign distributing AMOS stealer via fake packages like "solana-wallet-tracker" and "youtube-summarize-pro"). Bitdefender estimated ~20% (~900 malicious, including a fake Polymarket bot that opened a reverse shell). Snyk's ToxicSkills audit found 36% with security flaws (1,467 vulnerable, 76 confirmed malicious payloads). Pick your threshold — none of these numbers are "safe." A single publisher, "hightower6eu," uploaded 314+ malicious skills alone.
Skill vetting checklist
- Review the source. Open the skill repo on GitHub. Read the SKILL.md, the tool implementation, and any install hooks. If it is obfuscated or minified, reject.
- Pin versions. Never install "latest" — pin to a specific commit or tagged release. Auto-updates are how a clean skill becomes a malicious skill three weeks after you install it.
- Scan with VirusTotal. ClawHub added VirusTotal integration for new submissions in February 2026, but it only covers new uploads, not the existing corpus. Run your own scan.
- Check publisher age. The only mandatory publisher requirement is a GitHub account one week old. That is not a filter — that is a formality. Look for skills from publishers you recognize or whose track record you can verify.
- Avoid curl|bash prerequisites. This is item 6 on the hardening checklist but bears repeating: if SKILL.md's install section says to pipe a URL into a shell, do not.
- Prefer official skills. As of late March 2026, ClaudeFast reported roughly 5,700+ community-built skills on ClawHub, versus 53 official ones — Clarifai counted ~10,700 total on March 6, 2026, and Skywork reported 3,000 community plus 53 official on March 24. The exact count depends on what you count, but the ratio is clear: the official 53 are orders of magnitude safer than the community long tail.
Install flow: pick one official skill (a weather lookup or a calendar reader, something boring) for your first install. Confirm it runs without errors, check logs for outbound connections, then move on. Resist the urge to install ten skills at once — you will lose the ability to attribute weird behavior to any particular one.
Verification and Testing
Before you call it done, run three checks:
- Gateway status. Hit the Gateway health endpoint through your SSH tunnel or local loopback. It should report listening on 127.0.0.1:18789, not 0.0.0.0. If you see 0.0.0.0, go back to Step 3, item 1.
- Round-trip message. Send a DM from your paired messaging account, get a coherent response, confirm the logs show the expected tool calls and no unexpected outbound requests.
- Log review. Tail the log for five minutes of idle time. Watch for any WebSocket connections you did not initiate. If something is dialing out on its own, one of your skills is misbehaving — isolate by disabling skills one at a time.
Run openclaw secrets audit (from the v2026.2.26+ external secrets feature) to confirm no plaintext credentials are sitting in ~/.openclaw/credentials/. If it reports any, move them into the secrets manager before you route real traffic.
Troubleshooting
Nine issues that catch most people on the first install. Click any question to expand.
If you hardened correctly, the Gateway is bound to loopback and will not answer external requests. That is the point. Access it through an SSH tunnel: ssh -L 18789:localhost:18789 user@vps, then hit http://localhost:18789 from your laptop.
If you expect it to answer publicly (which you should not — see Step 3), check your firewall rules (ufw status on Ubuntu) and cloud provider security groups. But really, do not expose it.
OpenClaw requires Node 22.14+. Ubuntu 22.04's default repo ships 18.x; Debian 12 ships 20.x. Both will fail.
Use nvm: nvm install 24 && nvm use 24 && nvm alias default 24. Confirm with node --version before reinstalling OpenClaw.
Restart the Gateway process. OpenClaw reads credentials at boot; hot-reload is not guaranteed.
Double-check the YAML indentation — a single mismatched space turns a credential entry into a sibling of the wrong key and it silently gets ignored. Run your config through a YAML linter if you are stuck.
Check the skill's SKILL.md for its Node version requirement — some skills need 24+. Check whether the skill lists native dependencies (build-essential, python3, libssl-dev). Missing native deps cause cryptic node-gyp errors.
If the skill tries to run a curl|bash step to fetch a binary, stop. That is the hardening checklist item 6 violation and you should find a different skill.
Your client (UI or messaging bridge) cannot reach 18789. If Gateway is bound to loopback (correct) and your client is off-box, you need an SSH tunnel or Tailscale Serve.
If your client is on-box and still fails, check lsof -i :18789 to confirm the Gateway is actually listening, and check your local firewall (macOS Application Firewall or Linux ufw) for a block.
Telegram: confirm the bot token is pasted without leading/trailing whitespace. BotFather tokens have the format 123456:AAA-... and are case-sensitive.
Slack: make sure Socket Mode is enabled if you bound to loopback. Otherwise Slack cannot deliver events without a public webhook URL, and the auth handshake will never complete.
Discord: the bot needs the Message Content Intent enabled in the Developer Portal — Discord disabled this by default in 2022 and many guides predate that change.
500 MB is the base runtime. A browser tool adds Chromium (300-500 MB), a local model via Ollama adds model-size (7B params ~4 GB quantized), and heavy MEMORY.md payloads balloon context.
Disable the browser tool if you are not using it. Swap a local model for a hosted API. Trim MEMORY.md — it gets injected every turn, so bloat there is expensive on tokens and memory.
Workspace files load at Gateway boot and are keyed on exact filenames. If SOUL.md is not being honored or HEARTBEAT.md cron tasks never fire, work through this order:
- Verify YAML frontmatter parses. If your SOUL.md or HEARTBEAT.md starts with a frontmatter block, a single malformed colon or unquoted string will make OpenClaw skip the file silently. Run the file through a YAML linter.
- Check filenames are exact-case. Soul.md or soul.md will not load — it must be SOUL.md. Same for IDENTITY.md, USER.md, TOOLS.md, AGENTS.md, HEARTBEAT.md, MEMORY.md. Case-insensitive filesystems (macOS default, Windows) hide this bug locally; Linux VPS will fail.
- Confirm agent.profile in config matches. If you set a non-default profile in openclaw.config.yaml, the Gateway looks for the workspace under that profile's directory — an orphaned workspace at the default path will be ignored.
- Check daemon logs for "workspace loaded" line. Tail the Gateway log during restart. You should see a confirmation that each Markdown file was read, with line/token counts. If the line is missing for a file, that file is not being injected.
Baseline cold boot is ~2,500 ms on OpenClaw. Anything beyond 5 seconds usually means: slow disk (spinning rust, not SSD), too many skills loaded at startup, or a heavy plugin bundling its own runtime.
If you need sub-second boot, evaluate ZeroClaw (Rust reimplementation, ~10 ms boot, ~5 MB RAM) or NanoClaw (~500 ms, ~10 MB RAM) for edge/IoT use cases. OpenClaw itself is tuned for developer desktops and VPS boxes, not cold-start-sensitive workloads.