Openclaw Setup

OpenClaw Setup & Best Practices

Docs: https://docs.openclaw.ai Repo: https://github.com/openclaw/openclaw (329K stars, MIT) Version: 2026.3.x | Runtime: Node.js 24 (or 22.16+ LTS)

Quick Reference

# Install
curl -fsSL https://openclaw.ai/install.sh | bash
# Or: npm install -g openclaw@latest && openclaw onboard --install-daemon

# Daily operations
openclaw gateway status          # Check health
openclaw gateway restart         # Apply config changes
openclaw skills list             # Show loaded skills
openclaw channels list           # Show connected channels
openclaw agent --message "..."   # Test agent locally
openclaw security audit --deep   # Security check
openclaw doctor                  # Health + fixes
openclaw logs --follow           # Tail gateway logs

Architecture (Single Gateway)

Channels (WhatsApp/Telegram/Discord/...)
    |
    v
OpenClaw Gateway (single daemon, port 18789, loopback-only)
    |
    +-- Agent Runtime (loads AGENTS.md + skills)
    +-- Tool Execution (exec, browser, web_search, cron)
    +-- Model Provider (openai-codex/gpt-5.4, google/gemini, etc.)
    |
    v
External APIs (Supabase EFs, REST, any HTTP endpoint)

Key facts:

• One Gateway per host (single Baileys WhatsApp session)
• WebSocket + HTTP on same port (18789)
• JSON wire protocol: {type:"req", id, method, params}
• Side-effecting methods need idempotency keys
• Config at ~/.openclaw/openclaw.json (chmod 600)
• State at ~/.openclaw/ (chmod 700)

Installation

Prerequisites

• Node.js 24 (recommended) or 22.16+ LTS
• macOS, Linux, or Windows (WSL2)

Methods (pick one)

# 1. Automated installer (recommended)
curl -fsSL https://openclaw.ai/install.sh | bash

# 2. npm global
npm install -g openclaw@latest
openclaw onboard --install-daemon

# 3. From source
git clone https://github.com/openclaw/openclaw.git
cd openclaw && pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon

Post-install verification

openclaw --version
openclaw doctor
openclaw gateway status

Linux systemd (user service)

# Enable lingering so service survives logout
sudo loginctl enable-linger $(whoami)

# Service file at: ~/.config/systemd/user/openclaw-gateway.service
systemctl --user enable --now openclaw-gateway.service
systemctl --user status openclaw-gateway.service

Configuration (~/.openclaw/openclaw.json)

Essential settings

{
  "agents": {
    "defaults": {
      "model": { "primary": "openai-codex/gpt-5.4" },
      "workspace": "/home/USER/.openclaw/workspace"
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token", "token": "<long-random-token>" }
  },
  "session": { "dmScope": "per-channel-peer" },
  "tools": {
    "profile": "coding",
    "web": { "search": { "enabled": true, "provider": "gemini" } }
  }
}

Environment variables

openclaw config set env.MY_KEY "value"     # Set env var
openclaw config get env                     # List all env vars

Env vars are available to skills and tools at runtime.

Config reload modes

• hot — apply safe changes without restart
• restart — restart gateway for breaking changes
• hybrid (default) — auto-detect which is needed

Providers (AI Models)

Authentication methods

Key model IDs

Multiple keys + rotation

Configure multiple API keys per provider. On 429 rate limit, OpenClaw auto-rotates to next key.

Channels

Fastest setup: Telegram

openclaw channels add telegram
# Paste your bot token from @BotFather

WhatsApp (QR pairing)

openclaw channels add whatsapp
# Scan QR code with WhatsApp -> Linked Devices -> Link a Device

Channel config

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "allowlist",       // pairing | allowlist | open | disabled
      "allowFrom": ["+1234567890"],   // E.164 phone numbers
      "selfChatMode": true,           // Chat with yourself
      "groupPolicy": "allowlist",
      "debounceMs": 0,
      "mediaMaxMb": 50
    },
    "telegram": {
      "enabled": true,
      "dmPolicy": "allowlist",
      "groups": { "*": { "requireMention": true } }
    }
  }
}

DM policies:

• pairing (default) — unknown senders get 1-hour pairing codes (max 3 pending)
• allowlist — only pre-approved senders (safest)
• open — anyone can DM (requires "*" in allowlist)
• disabled — ignore all DMs

Group policy: Always set requireMention: true to prevent always-on bot.

Skills

Directory precedence (highest first)

1. <workspace>/skills/ — per-agent, workspace-specific
2. ~/.openclaw/skills/ — shared across all agents
3. Bundled skills — shipped with OpenClaw
4. skills.load.extraDirs — additional directories

Creating a skill

~/.openclaw/workspace/skills/my-skill/
  SKILL.md

SKILL.md format

---
name: my_skill
description: One-line description shown to the agent.
version: 1.0.0
metadata: {"openclaw":{"requires":{"env":["MY_API_KEY"]}}}
---

# My Skill

Instructions for the agent. Use markdown with code blocks for tool calls.
The agent reads this file when the skill triggers.

Required metadata fields

• name (snake_case)
• description (one-line, used for skill matching)

Optional metadata

• metadata.openclaw.requires.env — required env vars (skill shows "missing" if not set)
• metadata.openclaw.requires.bins — required binaries on PATH
• metadata.openclaw.requires.config — required config keys
• metadata.openclaw.os — platform filter (darwin, linux, win32)

Skill injection

Skills are injected as compact references in the system prompt. The agent uses the read tool to load the full SKILL.md when a skill triggers. Skills must be loaded in a new session — old sessions don't pick up new skills.

# After adding/modifying a skill:
openclaw gateway restart
# Then start a new session (old sessions have cached skill lists)

Skills config

{
  "skills": {
    "load": {
      "extraDirs": ["~/my-skills"],  // Additional skill directories
      "watch": true,                  // Auto-reload on file change
      "watchDebounceMs": 250
    },
    "entries": {
      "my-skill": {
        "enabled": true,              // Toggle individual skills
        "env": { "API_KEY": "..." }   // Per-skill env vars
      }
    }
  }
}

Tools

Built-in tool groups

Tool profiles (presets)

• full — everything enabled
• coding — fs + runtime + web (default for dev)
• messaging — messaging + web (safe for chat bots)
• minimal — read-only + web search

Cron (scheduling)

# Add a recurring job
openclaw cron add \
  --name "daily-check" \
  --schedule "0 8 * * *" \
  --timezone "America/Toronto" \
  --session isolated \
  --message "Run daily health check" \
  --announce whatsapp

# One-shot
openclaw cron add --name "reminder" --at "2026-03-23T14:00:00Z" --message "Meeting in 5 min"

# List / remove
openclaw cron list
openclaw cron remove --name "daily-check"

Jobs persist at ~/.openclaw/cron/jobs.json. Isolated sessions get dedicated context per run.

Security Best Practices

Hardened baseline

{
  "gateway": {
    "bind": "loopback",
    "auth": { "mode": "token", "token": "<long-random-secret>" }
  },
  "session": { "dmScope": "per-channel-peer" },
  "tools": {
    "profile": "messaging",
    "deny": ["group:automation", "group:runtime", "group:fs", "sessions_spawn"]
  },
  "channels": {
    "whatsapp": { "dmPolicy": "pairing", "groups": { "*": { "requireMention": true } } }
  }
}

Security checklist

• gateway.bind: "loopback" (never expose unauthenticated on 0.0.0.0)
• Gateway auth token set (fail-closed — rejects connections without token)
• ~/.openclaw/openclaw.json is chmod 600
• ~/.openclaw/ directory is chmod 700
• DM policy is pairing or allowlist (never open without good reason)
• Groups require @mention (requireMention: true)
• Dangerous tools denied: gateway, cron, sessions_spawn, exec
• Run openclaw security audit --deep regularly
• Use dedicated browser profile (not personal)
• Enable logging.redactSensitive: "tools" for log safety

Security audit

openclaw security audit --deep    # Full check
openclaw security audit --fix     # Auto-fix what it can
openclaw security audit --json    # Machine-readable output

Critical audit findings

Workspace Files

Bootstrap budget

• bootstrapMaxChars: 20,000 per file (default)
• bootstrapTotalMaxChars: 150,000 total (default)
• Files exceeding limits are truncated with warning

Troubleshooting

openclaw doctor              # Health checks + quick fixes
openclaw gateway status      # Service status + probe
openclaw channels status     # Channel connection status
openclaw logs --follow       # Tail gateway logs
openclaw skills check        # Which skills are ready vs missing

Common issues

References

• references/install-guide.md — Full installation instructions
• references/architecture.md — Gateway architecture deep dive
• references/channels.md — Channel configuration details
• references/providers.md — AI model provider setup
• references/security.md — Security hardening guide
• references/tools-and-cron.md — Tools, cron, and automation
• references/skills-system.md — Creating and managing skills

Official docs: https://docs.openclaw.ai