Openclaw Setup

OpenClaw Setup Skill

Deploy and configure OpenClaw — the open-source personal AI assistant (145k+ GitHub stars) — safely and correctly. This skill handles the full lifecycle: installation, Anthropic model auth, channel wiring (Telegram + iMessage), security hardening, cost control, and deployment to either a local Mac mini or a Hostinger VPS.

• Source: https://github.com/openclaw/openclaw
• Docs: https://docs.openclaw.ai
• Created by: Peter Steinberger (founder of PSPDFKit)

What is OpenClaw?

OpenClaw is a self-hosted, conversation-first AI assistant built on LLMs. Originally launched as "Clawdbot" (November 2025), renamed to "Moltbot" (January 27, 2026) after Anthropic trademark concerns, then became "OpenClaw" (January 30, 2026). It runs a local Gateway (WebSocket control plane) on your machine or server and connects to messaging channels you already use — Telegram, iMessage, WhatsApp, Discord, Slack, and 50+ others. The assistant responds through those channels using models from Anthropic, OpenAI, or other providers.

Key facts:

• Runtime: Node.js ≥22.12.0, TypeScript, pnpm monorepo
• Architecture: Gateway (control plane) → Pi agent (RPC) → LLM provider
• Recommended model: Anthropic Claude Opus 4.5 via OAuth (Pro/Max subscription) for best prompt-injection resistance and long-context strength
• Install method: curl -fsSL https://openclaw.ai/install.sh | bash then openclaw onboard --install-daemon
• Config location: ~/.openclaw/openclaw.json (JSON5 format)
• Default port: 18789 (WebSocket + HTTP multiplexed)
• Minimum context window: 64K tokens
• License: MIT

⚠️ CRITICAL SECURITY PREREQUISITES

Before ANY installation, these four steps are non-negotiable:

1. Set API spending limits FIRST — Go to console.anthropic.com → Settings → Limits → set a monthly cap ($30-50/month is achievable with smart routing). A misconfigured cron job or heartbeat can cost $750+/month. Do this BEFORE pasting any API key anywhere.

2. Version must be 2026.1.29 or later — CVE-2026-25253 (CVSS 8.8) affects all earlier versions. It enabled 1-click remote code execution through the Control UI. After installation, verify with openclaw --version.

3. Gateway must bind to 127.0.0.1, NEVER 0.0.0.0 — Security researcher Maor Dayan found 42,665 publicly exposed OpenClaw instances via Shodan. 93.4% had critical auth bypasses. The root cause: Docker's default port publishing binds to 0.0.0.0 on VPS instances.

4. DM policy must be "pairing" or "allowlist" — Never use dmPolicy: "open" unless you fully understand the risk.

See references/security-defaults.md for the complete security guide.

When to Use This Skill

Use this skill when the user wants to:

• Install OpenClaw from scratch on macOS or Linux
• Deploy OpenClaw to a Hostinger VPS using Docker
• Configure Anthropic as the model provider
• Connect Telegram or iMessage as a messaging channel
• Apply safe security defaults to a new or existing OpenClaw installation
• Run post-setup health checks (openclaw doctor, openclaw security audit)
• Troubleshoot common OpenClaw setup issues
• Understand OpenClaw costs and optimize spending

When NOT to Use This Skill

Do not use this skill for:

• WhatsApp, Slack, Discord, Signal, or other channel setup (not covered here)
• Advanced multi-agent routing or Canvas/A2UI configuration
• iOS/Android node pairing or voice wake setup
• OpenClaw skills/plugins development
• Browser control configuration
• Ollama/local model setup

Setup Workflow

Follow this order. Each step links to its reference file.

Step 0: Set API Spending Limits

Before touching anything else, go to your LLM provider's console and set a monthly spending cap. See references/anthropic-auth.md for details.

Step 1: Choose a Deployment Path

If the user wants iMessage, they must use the Mac path (iMessage requires macOS with Messages signed in).

Step 2: Set Up Anthropic Auth

Configure Anthropic as the primary model provider during or after onboarding.

→ Read references/anthropic-auth.md

Step 3: Connect Channels

Step 4: Apply Security Defaults

Harden the installation with safe defaults before going live.

→ Read references/security-defaults.md

Step 5: Verify

openclaw --version              # Must be 2026.1.29+
openclaw doctor
openclaw security audit --deep
openclaw gateway status
openclaw channels status --probe
openclaw status --all

On VPS, verify the gateway is NOT bound to 0.0.0.0:

ss -tlnp | grep 18789
# Must show 127.0.0.1:18789, NOT 0.0.0.0:18789

Interactive Setup Mode

When running commands for the user, Claude Code should:

1. Set spending limits first — Walk the user through setting API caps at console.anthropic.com 2. Check prerequisites — Verify Node.js ≥22.12.0, Xcode CLI tools (macOS), and gather credentials 3. Run the install script — Execute the curl installer or npm global install 4. Verify version — Confirm openclaw --version shows 2026.1.29+ 5. Launch the onboarding wizard — Run openclaw onboard --install-daemon and guide the user through each interactive prompt 6. Generate secure config — Produce a ~/.openclaw/openclaw.json with safe defaults 7. Warn about skills — During the wizard's skills step, advise installing only bundled skills. ClawHub community skills should be treated with extreme caution (Cisco found 26% contain vulnerabilities; 341 malicious skills found including macOS malware installers) 8. Warn about heartbeat costs — If heartbeat is enabled, recommend switching it to Haiku model or disabling it. Default Opus heartbeat costs ~$54/month. 9. Configure channels — Set up Telegram bot token and/or iMessage 10. Run health checks — Execute openclaw doctor and openclaw security audit --deep 11. Verify binding — On VPS, run ss -tlnp | grep 18789 to confirm loopback binding 12. Test connectivity — Send a test message or open the dashboard

For each interactive prompt in the wizard, explain what the option means and recommend the safe choice. Non-technical users need plain-language explanations; developers can get the concise version.

Non-Interactive Setup (for scripting)

openclaw onboard --non-interactive \
  --mode local --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 --gateway-bind loopback \
  --install-daemon --daemon-runtime node --skip-skills

Key Config Structure

Minimal safe config (Anthropic + Telegram + secure defaults):

{
  agent: {
    model: "anthropic/claude-opus-4-5"
  },
  gateway: {
    bind: "loopback",
    port: 18789,
    auth: { mode: "token", token: "<auto-generated>" }
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "<from-botfather>",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } }
    }
  },
  discovery: {
    mdns: { mode: "minimal" }
  }
}

Troubleshooting Quick Reference

Reference Files

Anthropic Model Authentication & Cost Control

Configure Anthropic as the primary model provider for OpenClaw. This guide covers auth setup, model selection, smart routing to control costs, and spending safeguards.

⚠️ STEP ZERO: Set Spending Limits

Do this BEFORE pasting any API key into OpenClaw.

1. Go to console.anthropic.com → Settings → Limits 2. Set a monthly spending cap — $30-50/month is achievable with optimized routing 3. Set per-day limits if available

Why this matters: A single misconfigured heartbeat or cron job can cost $750/month. One user's leaked API key was exploited for 11 days before discovery. Unoptimized setups regularly hit $1,500+/month. Spending limits are your safety net.

Auth Methods

Option 1: Anthropic API Key (recommended for simplicity)

Direct pay-per-token. Most straightforward setup.

1. Go to console.anthropic.com → API Keys → Create key 2. Key format: sk-ant-... 3. During onboarding wizard, select "Anthropic API key" and paste the key 4. Or set via environment variable:

   export ANTHROPIC_API_KEY="sk-ant-your-key-here"

Cost model: Pay per token. No subscription required. Costs scale with usage — which is why spending limits are critical.

Option 2: Claude Pro/Max Subscription via Setup Token

Uses your Claude Pro ($20/mo) or Max ($100-200/mo) subscription credits instead of direct API billing. Natural spending ceiling — you can't exceed your subscription tier.

1. Install Claude Code CLI if not already installed 2. Generate a setup token:

   claude setup-token

3. During onboarding, select "Anthropic setup-token" and paste the token:

   openclaw onboard --auth-choice setup-token

Or configure after onboarding:

   openclaw models auth setup-token --provider anthropic

Trade-off: Subscription auth does NOT honor prompt cache settings. You get rate-limited usage with a natural spending ceiling, but miss the 90% cache discount on repeated system prompts.

Option 3: Anthropic OAuth via Claude Code CLI

Browser-based OAuth flow. Works well for local Mac setups.

1. During onboarding, select "Anthropic OAuth via Claude Code CLI" 2. Browser opens for authorization 3. Approve and return to terminal

For headless VPS: The browser won't open. Copy the redirect URL from the terminal output and complete auth on your local machine, then paste the callback URL back.

Recommended Model Configuration

Primary Model

{
  agent: {
    model: "anthropic/claude-opus-4-5"
  }
}

Claude Opus 4.5 is recommended as the primary model for:

• Strongest prompt-injection resistance
• Best reasoning and complex task handling
• Most capable tool use
• Longest effective context utilization

Model Selection by Use Case

⚠️ Avoid Haiku for security-sensitive or tool-enabled agents — smaller models are more susceptible to prompt injection.

Smart Model Routing (Cost Optimization)

The proven pattern that brings costs from $1,500+/month down to $30-50/month:

Add routing guidance to your SOUL.md:

## Model Usage Rules
Default: Always use Haiku for routine tasks.
Switch to Sonnet ONLY when: writing content, research, code generation, detailed analysis.
Switch to Opus ONLY when: architecture decisions, production code review, security analysis, complex debugging, critical reasoning.

Or use OpenRouter's auto model (openrouter/openrouter/auto) which automatically selects cost-effective models per prompt.

Model Switch Command

/model claude-haiku-4-5     # Switch to Haiku
/model claude-sonnet-4-5    # Switch to Sonnet
/model claude-opus-4-5      # Switch to Opus

Heartbeat Cost Warning

The heartbeat feature runs periodic agent turns in the main session. Default interval: 30 minutes (1 hour for subscription auth).

Cost reality:

• Opus heartbeat at 30-min intervals: ~$54/month ($5-30/day)
• Haiku heartbeat at 1-hour intervals: ~$0.30/month

Recommendation: Either disable heartbeat entirely, or switch to Haiku:

{
  heartbeat: {
    model: "anthropic/claude-haiku-4-5",
    interval: 3600,  // 1 hour in seconds
    activeHours: { start: "08:00", end: "24:00" }
  }
}

Prompt Caching

Anthropic auto-applies a 5-minute cache (cacheRetention: "short") for API key auth. The system prompt alone is 5,000-10,000 tokens resent with every call — caching gives a 90% discount on this repeated content.

Extended 1-hour cache is available:

{
  models: {
    cacheRetention: "long"  // Requires beta flag
  }
}

Note: Subscription (setup-token) auth does NOT benefit from prompt caching.

Model Failover

Configure fallback models so OpenClaw switches automatically if the primary is unavailable:

{
  models: {
    fallback: [
      "anthropic/claude-sonnet-4-5",
      "anthropic/claude-haiku-4-5"
    ]
  }
}

Priority order when multiple API keys are present: Anthropic → OpenAI → OpenRouter → Gemini.

Auth Storage and Security

Auth profiles are stored at:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Lock permissions:

chmod 600 ~/.openclaw/agents/*/agent/auth-profiles.json
chmod 700 ~/.openclaw/credentials/

Never store API keys in:

• SOUL.md or MEMORY.md (loaded into LLM context — could leak via prompt injection)
• Public git repositories
• Shared documents or chat messages
• Docker images (use environment variables or .env files with proper permissions)

Verification

openclaw models status        # Shows configured providers and auth status
openclaw models list          # Lists available models
openclaw status --all         # Includes model info in full status

Hostinger VPS Notes

For Hostinger Docker deployments, API keys are configured via:

1. During one-click deploy: Enter ANTHROPIC_API_KEY in the environment variables form 2. After deploy: Add to .env file and restart:

   docker compose exec openclaw-gateway bash
   echo 'ANTHROPIC_API_KEY=sk-ant-your-key' >> .env
   exit
   docker compose restart

3. Via web UI: Some Hostinger Docker configurations expose environment variable editing in hPanel

Monthly Cost Targets

Hostinger VPS Deployment

Deploy OpenClaw to a Hostinger VPS using Docker for 24/7 cloud availability. This guide covers both the one-click Docker template and manual deployment.

⚠️ VPS Security Warning

VPS deployments are the #1 source of exposed OpenClaw instances. Security researcher Maor Dayan found 42,665 publicly exposed instances via Shodan — 93.4% had critical auth bypasses. The root cause: Docker's default port publishing binds to 0.0.0.0 (all interfaces), making the gateway discoverable on the public internet.

You MUST actively harden a VPS deployment. Follow every security step in this guide and in security-defaults.md. If you're not comfortable with Linux server administration, use the Mac mini local deployment path instead — it's much safer by default.

Plan Selection

Realistic minimum requirements: 2 CPU cores, 4GB RAM, 40GB storage. Community consensus says the advertised $5/month floor is often insufficient. Plans renew at ~$12.99/month for 2-year terms.

Critical: Enable daily automatic backups in hPanel during purchase — this is essential for recovery.

Important Limitations

• No iMessage — iMessage requires macOS with Messages signed in. VPS runs Linux.
• No voice wake — Voice Wake requires the macOS companion app.
• If you need iMessage, use the Mac mini path and optionally pair the VPS as a remote device node.

Path A: One-Click Docker Template (recommended)

Hostinger provides a pre-configured OpenClaw Docker image in the hPanel Docker Manager Catalog.

For a new VPS purchase:

1. Go to hostinger.com → VPS Hosting → choose a plan (KVM 2 recommended) 2. During setup, select Docker as the OS template 3. In the Docker Catalog, find OpenClaw and select it 4. Configure environment variables:

• OPENCLAW_GATEWAY_TOKEN — auto-generated (save this immediately)
• ANTHROPIC_API_KEY — paste your API key (with spending limits already set!)
• Optional: OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY

5. Deploy — the container auto-starts

For an existing VPS:

1. In hPanel → VPS → OS & Panel → switch to Docker OS (⚠️ this wipes all existing data) 2. Once Docker OS is active, open Docker Manager → Catalog → deploy OpenClaw 3. Configure environment variables as above

Retrieve your gateway token:

The token is shown during deployment and saved in the Docker environment. To retrieve it later:

ssh root@YOUR_VPS_IP
docker compose exec openclaw-gateway printenv OPENCLAW_GATEWAY_TOKEN

Access the Control UI:

# Via SSH tunnel (recommended — no public port exposure)
ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
# Then open: http://127.0.0.1:18789/?token=YOUR_GATEWAY_TOKEN

Path B: Manual Docker Deployment

For full control over the setup, deploy manually.

1. SSH into your VPS

ssh root@YOUR_VPS_IP

2. Create a dedicated non-root user

useradd -r -m -d /opt/openclaw -s /bin/bash openclaw
passwd openclaw
usermod -aG docker openclaw
su - openclaw

3. Install Docker (if not pre-installed)

curl -fsSL https://get.docker.com | sh
sudo systemctl enable docker
sudo systemctl start docker

4. Clone and configure

git clone https://github.com/openclaw/openclaw.git
cd openclaw
cp .env.example .env

Edit .env:

OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
ANTHROPIC_API_KEY=sk-ant-your-key-here

5. Fix Docker port binding (CRITICAL)

Edit docker-compose.yml — change the port binding from the default:

# ❌ WRONG — binds to all interfaces, publicly accessible
ports:
  - "18789:18789"

# ✅ CORRECT — binds to localhost only
ports:
  - "127.0.0.1:18789:18789"

This single change prevents your gateway from being discoverable via Shodan.

6. Start the container

docker compose up -d

7. Verify binding

ss -tlnp | grep 18789
# Must show: 127.0.0.1:18789
# Must NOT show: 0.0.0.0:18789

If you see 0.0.0.0:18789, stop immediately and fix the docker-compose port binding.

CLI Commands in Docker

Prefix all openclaw commands with docker compose exec:

docker compose exec openclaw-gateway openclaw --version
docker compose exec openclaw-gateway openclaw doctor
docker compose exec openclaw-gateway openclaw security audit --deep
docker compose exec openclaw-gateway openclaw channels status --probe
docker compose exec openclaw-gateway openclaw gateway logs --follow
docker compose exec openclaw-gateway openclaw pairing list telegram
docker compose exec openclaw-gateway openclaw pairing approve telegram <CODE>

VPS Network Security (mandatory)

Tailscale (zero public ports — recommended)

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# Expose gateway only to your Tailnet devices
tailscale serve https / http://127.0.0.1:18789

UFW Firewall

sudo apt install ufw -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp        # SSH
sudo ufw enable

Do NOT add a UFW rule for port 18789. Access the gateway via SSH tunnel or Tailscale only.

fail2ban (SSH brute-force protection)

sudo apt install fail2ban unattended-upgrades -y
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Disable root SSH and password auth

Edit /etc/ssh/sshd_config:

PermitRootLogin no
PasswordAuthentication no

Then: sudo systemctl restart sshd

Disable mDNS broadcasting

export OPENCLAW_DISABLE_BONJOUR=1

Or in openclaw.json:

{ "discovery": { "mdns": { "mode": "off" } } }

VPS-Specific Security Checklist

After deployment, verify ALL of these:

• [ ] Gateway bound to 127.0.0.1, NOT 0.0.0.0 (ss -tlnp | grep 18789)
• [ ] OpenClaw version is 2026.1.29+ (openclaw --version)
• [ ] Gateway auth token is set and strong (32+ hex chars)
• [ ] UFW enabled with only SSH allowed
• [ ] fail2ban running
• [ ] Root SSH disabled
• [ ] Password auth disabled (key-only)
• [ ] API spending limits set at provider console
• [ ] DM policy set to "pairing" (not "open")
• [ ] Tailscale or SSH tunnel for gateway access (no public port)
• [ ] mDNS disabled
• [ ] File permissions locked: chmod 700 ~/.openclaw, chmod 600 ~/.openclaw/openclaw.json
• [ ] openclaw security audit --deep passes clean

Docker Network Isolation

For enhanced isolation, create a dedicated Docker network:

# docker-compose.yml
services:
  openclaw-gateway:
    # ... existing config
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge
    internal: false  # Needs outbound for API calls

Never mount `/var/run/docker.sock` into the OpenClaw container — a container escape would grant full Docker control.

Consider rootless Podman as an alternative to Docker — a container escape lands as an unprivileged user (UID 1000), not root.

Backup and Recovery

Hostinger Automatic Backups

Enable daily auto-backups in hPanel during VPS purchase or in VPS settings. Hostinger retains backups for the plan's retention period.

Manual Backup

# Backup OpenClaw config and state
docker compose exec openclaw-gateway tar -czvf /tmp/openclaw-backup.tar.gz -C /root .openclaw
docker cp openclaw-gateway:/tmp/openclaw-backup.tar.gz ./openclaw-backup-$(date +%F).tar.gz

Recovery

# Fresh deploy, then restore config
docker compose down
docker compose up -d
docker cp ./openclaw-backup-YYYY-MM-DD.tar.gz openclaw-gateway:/tmp/
docker compose exec openclaw-gateway tar -xzvf /tmp/openclaw-backup-YYYY-MM-DD.tar.gz -C /root
docker compose restart

Updating

docker compose pull
docker compose down
docker compose up -d
docker compose exec openclaw-gateway openclaw --version    # Verify
docker compose exec openclaw-gateway openclaw doctor       # Health check

Alternative VPS Providers

This skill focuses on Hostinger, but OpenClaw also has official deployment support for:

• DigitalOcean — 1-Click Marketplace image, $6-12/month, $200 free credit for new accounts
• Cloudflare Workers — Experimental via moltworker, $5/month Workers Paid plan + compute
• Emergent.sh — Fully managed, no infrastructure knowledge required, 50 credits/month per app

iMessage Channel Setup (macOS Only)

Connect OpenClaw to iMessage so you can message your AI assistant from any Apple device. Two methods are available: BlueBubbles (recommended) and the legacy imsg channel.

Requirements

• macOS only — iMessage is NOT available on Linux VPS deployments
• Messages app signed in with your Apple ID on the Mac running OpenClaw
• OpenClaw running locally on the same Mac
• macOS 14 (Sonoma) or later recommended

Method 1: BlueBubbles (Recommended)

BlueBubbles is the recommended iMessage integration. It's a bundled plugin that communicates with the BlueBubbles macOS server over HTTP, providing a richer feature set than the legacy method.

Features

• ✅ Typing indicators
• ✅ Read receipts
• ✅ Tapback reactions
• ✅ Attachments (images, files)
• ✅ Voice memo support
• ✅ Edit/unsend support
• ✅ Reliable message handling (no race conditions)

Setup

1. Install the BlueBubbles Server app on your Mac:

• Download from bluebubbles.app or via Homebrew
• Launch and complete initial setup
• BlueBubbles Server runs alongside Messages.app

2. Configure OpenClaw to connect to BlueBubbles:

{
  channels: {
    bluebubbles: {
      enabled: true,
      // BlueBubbles server URL (default localhost)
      serverUrl: "http://127.0.0.1:1234",
      password: "<bluebubbles-server-password>",
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

3. Restart OpenClaw: openclaw gateway restart 4. Verify: openclaw channels status --probe

BlueBubbles Permissions

BlueBubbles Server needs the same macOS permissions as the legacy method:

• Full Disk Access — to read Messages database
• Automation — to send messages via AppleScript

Method 2: Legacy imsg Channel

The legacy imsg channel directly accesses the Messages database. It works but has known limitations.

How It Works

1. Monitors ~/Library/Messages/chat.db (SQLite database) for new messages 2. Sends replies via AppleScript through Messages.app 3. Polls the database at regular intervals

Configuration

Minimal config — just enable it:

{
  channels: {
    imsg: {
      enabled: true,
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

macOS Permissions (required for both methods)

Grant these in System Settings → Privacy & Security:

1. Full Disk Access — Add Terminal (or your terminal app) AND the OpenClaw process

• System Settings → Privacy & Security → Full Disk Access → toggle on for Terminal
• This allows reading ~/Library/Messages/chat.db

2. Automation — Allow OpenClaw to control Messages.app

• System Settings → Privacy & Security → Automation → enable Messages access
• First-time use triggers a system permission dialog — click Allow

Legacy imsg Limitations

• ⚠️ Duplicate-message race conditions — The database polling approach can occasionally process the same message twice, especially under load
• macOS only (no Linux/Windows support)
• Single Apple ID account only
• Mac must be awake and Messages must be signed in
• No read receipt support
• No typing indicator support
• No tapback/reaction support
• Rate limited by Apple (sending too many messages too fast may trigger throttling)

Recommendation: Use BlueBubbles instead of legacy imsg for a more reliable experience.

DM Policy and Pairing

Same as Telegram — with dmPolicy: "pairing", unknown iMessage contacts receive a pairing code:

# List pending pairing requests
openclaw pairing list imsg        # For legacy
openclaw pairing list bluebubbles # For BlueBubbles

# Approve
openclaw pairing approve imsg ABC123
openclaw pairing approve bluebubbles ABC123

Group Chat Configuration

iMessage group chats work similarly to Telegram groups:

{
  channels: {
    imsg: {  // or bluebubbles
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

Note: iMessage group @mentions work differently than Telegram — the bot name must be typed as a mention in the group chat. The exact behavior depends on the group type (standard iMessage group vs. group chat with SMS participants).

Keep-Awake Configuration

For a Mac mini running as an always-on iMessage gateway, the Mac must never sleep:

System Settings

• System Settings → Energy → Enable "Prevent automatic sleeping when display is off"
• Enable "Wake for network access"
• Enable "Start up automatically after a power failure"

Amphetamine (recommended)

Install the free Amphetamine app from the Mac App Store for more reliable sleep prevention. See mac-local-setup.md for setup details.

Terminal (alternative)

sudo pmset -a disablesleep 1

HDMI Dummy Plug

A ~$10 HDMI dummy plug prevents macOS from entering a reduced GPU mode on headless Mac minis. Recommended for always-on setups.

Troubleshooting

Architecture Note

iMessage integration is fundamentally different from cloud channels like Telegram:

• Telegram: Bot connects to Telegram's cloud API. Works from any server with internet.
• iMessage: Requires physical access to the Messages database on a Mac. Must run on macOS with Messages signed in. This is why iMessage only works with the Mac mini deployment path, never on a Linux VPS.

Mac Mini Local Deployment

Complete guide for running OpenClaw as an always-on personal AI assistant on a Mac mini.

Hardware Recommendations

• Cloud API only (most users): Base Mac mini M4, 16GB RAM — $549-599. AI processing happens on cloud servers; the Mini just runs the gateway.
• Local LLM inference: M4 Pro with 64GB unified memory — ~$2,000. Runs 32B models at 10-15 tokens/second.
• Budget options: Refurbished M2 Mini (~$599) or used M1 Mini (~$450) work fine for cloud API usage.
• Running costs: Electricity $1-5/month (M4 idles at ~3-6W), Anthropic API $5-20/month light use, $50-100/month moderate.

Prerequisites

Credential Checklist (gather before starting)

Before installation, assemble:

• Apple ID details (for iMessage, App Store)
• Anthropic API key (primary — from console.anthropic.com) with spending limits already set
• OpenAI API key (optional fallback)
• Brave Search API key (optional — 2,000 free requests/month)
• Telegram bot token (if using Telegram — see telegram-channel.md)
• Password manager access for all of the above

Developer Prerequisites

# 1. Install Xcode Command Line Tools (required)
xcode-select --install

# 2. Install Homebrew (recommended)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

# 3. Install Node.js 22+ via Homebrew
brew install node@22
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 4. Verify
node --version    # Must show v22.x.x+
npm --version     # Should show 10.x.x+

Alternative: Use nvm if you need multiple Node versions:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc
nvm install 22
nvm use 22

System Requirements

• macOS 14 (Sonoma) or later for menu bar companion app and voice features
• Node.js 22.12.0+
• Xcode Command Line Tools
• 64K+ token context window on chosen LLM model

Installation

Option A: Official One-Liner (recommended)

curl -fsSL https://openclaw.ai/install.sh | bash

The script handles Node.js detection, installs OpenClaw globally, and prompts for onboarding.

Option B: Manual npm Install

npm install -g openclaw@latest

Option C: From Source

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build

Verify Installation

openclaw --version    # Must show 2026.1.29+ (critical — older versions have CVE-2026-25253)

⚠️ If version is below 2026.1.29, update immediately: openclaw update --channel stable. See security-defaults.md for details on the vulnerability.

Onboarding Wizard

Run the wizard with daemon installation:

openclaw onboard --install-daemon

Wizard Flow (step by step)

The wizard presents each step in order. Here's what each one means and the recommended choice:

1. Existing config check — If ~/.openclaw/openclaw.json already exists, choose Keep (preserve current), Modify (edit), or Reset (start fresh). Reset uses trash, never rm, so your old config is recoverable.

2. Risk acknowledgment — "I understand this is powerful and inherently risky" → Select Yes (required to proceed).

3. Mode selection — QuickStart (recommended) applies sensible defaults: loopback binding, port 18789, token auth. Advanced prompts for every option individually.

4. Gateway configuration — Choose Local (this machine) for Mac mini. Advanced mode additionally asks about bind address (choose Loopback), port (keep 18789 default).

5. Auth/LLM provider — Choose Anthropic API key (recommended) or Anthropic OAuth via Claude Code CLI (if you have a Pro/Max subscription). Other options: OpenAI, Google Gemini, OpenRouter, and more. See anthropic-auth.md for guidance.

6. Model selection — Pick default model. Recommended: claude-opus-4-5 for capability and security. Wizard validates model availability against your auth.

7. Channel setup — Select messaging channels to enable. See telegram-channel.md and imessage-channel.md.

8. Pairing defaults — Choose pairing (recommended). Unknown senders receive a code; you approve with openclaw pairing approve.

9. Skills setup — Choose node manager (npm or pnpm). Only install bundled skills. Do NOT install ClawHub community skills during onboarding — Cisco research found 26% contain vulnerabilities and 341 were actively malicious (including macOS malware installers).

10. API keys for services — Optional: Brave Search, Exa.ai, etc. Can be added later.

11. Hooks setup — Optional: boot hooks, command logger, session memory. Safe to enable boot-md and session-memory. Be cautious with heartbeat — on Opus it costs ~$54/month. Switch to Haiku with 1-hour intervals (~$0.30/month) or skip entirely.

12. Daemon installation — With --install-daemon, registers a macOS launchd service for auto-start on login.

13. Health check + summary — Wizard runs validation and shows your configuration.

Non-Interactive Mode (for scripting)

openclaw onboard --non-interactive \
  --mode local --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 --gateway-bind loopback \
  --install-daemon --daemon-runtime node --skip-skills

Post-Install Verification

openclaw --version              # Must be 2026.1.29+
openclaw gateway status         # Gateway should be running
openclaw channels status --probe # Channels should show connected
openclaw doctor                 # Health check
openclaw security audit --deep  # Security validation
openclaw status --all           # Full system overview

Directory Structure

~/.openclaw/
├── openclaw.json          # Main config (JSON5)
├── state/                 # Session data, message history
├── workspace/             # Skills, SOUL.md, MEMORY.md, HEARTBEAT.md
│   └── skills/            # Installed skills (highest precedence)
├── credentials/           # OAuth tokens, API keys (chmod 700)
├── logs/                  # Command logs (if command-logger hook enabled)
└── skills/                # Shared skills (lower precedence than workspace)

LaunchAgent (24/7 Daemon)

The --install-daemon flag creates a launchd plist at ~/Library/LaunchAgents/com.openclaw.gateway.plist (some versions use ai.openclaw.gateway.plist). This auto-starts the gateway on login.

Manual daemon control

# Load/start
launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist
launchctl start com.openclaw.gateway

# Check status
launchctl list | grep openclaw

# Stop/unload
launchctl stop com.openclaw.gateway
launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist

Other daemon commands

openclaw gateway start     # Start gateway
openclaw gateway stop      # Stop gateway
openclaw gateway restart   # Restart gateway
openclaw gateway logs --follow  # Tail live logs

Always-On Mac Mini Configuration

Energy Settings (System Settings → Energy)

• ✅ Prevent automatic sleeping when display is off
• ✅ Wake for network access
• ✅ Start up automatically after a power failure

Amphetamine (recommended)

The free Amphetamine app from the Mac App Store provides more reliable sleep prevention than system settings alone:

1. Install from Mac App Store 2. Launch → Enable Launch at login 3. Set Start session when Amphetamine launches → Indefinitely 4. Enable Start session after waking from sleep 5. A filled pill icon in the menu bar = active (preventing sleep)

HDMI Dummy Plug

A ~$10 HDMI dummy plug is critical for headless Mac mini operation. Without it, macOS runs in a reduced GPU mode that can cause display-related issues with some applications. The plug tricks macOS into thinking a display is connected, enabling full GPU acceleration.

Keep-Awake via Terminal (alternative)

sudo pmset -a disablesleep 1

To revert: sudo pmset -a disablesleep 0

Remote Access via Tailscale

Tailscale creates a secure private network between your devices without opening any public ports. This is the recommended way to access your Mac mini remotely.

Setup

1. Install Tailscale from the Mac App Store on the Mac mini 2. Install Tailscale on your daily-driver device 3. Sign both into the same Tailscale account (same Tailnet) 4. Enable SSH on Mac mini: System Settings → General → Sharing → Remote Login

Access the Gateway (SSH tunnel)

Since the gateway binds to loopback (127.0.0.1), use SSH port forwarding:

ssh -L 18789:127.0.0.1:18789 yourusername@100.x.x.x
# Then open: http://127.0.0.1:18789/?token=YOUR_GATEWAY_TOKEN

Tailscale Serve (expose to all Tailnet devices)

tailscale serve 18789

This exposes the gateway to all your Tailnet devices with automatic TLS. Tailscale works even with macOS "Block all incoming connections" enabled — it routes through its own virtual network interface.

Screen Sharing (VNC)

Enable in System Settings → General → Sharing → Screen Sharing, then connect from another device via vnc://mac-mini-tailscale-ip.

macOS Companion App

OpenClaw offers an optional macOS companion app providing:

• Menu bar control plane (start/stop gateway)
• Voice Wake (wake word activation)
• Talk Mode overlay (speech-to-text interaction)
• WebChat (local chat interface)

Install from openclaw.ai or via the onboarding wizard. Requires macOS 14+ (Sonoma).

File Locations

Updating

openclaw update --channel stable
openclaw --version    # Verify new version
openclaw gateway restart
openclaw doctor       # Validate health after update

Post-Setup: Web Search and Services

Brave Search (recommended — 2,000 free requests/month)

openclaw configure --section web
# Or set directly:
export BRAVE_API_KEY="your-key-here"

Note: Brave requires a credit card for anti-fraud even on the free tier.

Tavily (alternative — 1,000 free searches/month, no credit card)

openclaw mcp add --transport http tavily https://mcp.tavily.com/mcp/?tavilyApiKey=<key>

Key Slash Commands

Security Defaults & Hardening

OpenClaw is powerful but genuinely dangerous when misconfigured. This reference covers the critical vulnerability history, safe defaults, hardening steps, and incident response. Apply these before going live with any deployment.

⚠️ CVE-2026-25253 — Critical Remote Code Execution

All OpenClaw versions before 2026.1.29 are affected. CVSS score: 8.8 (High). CWE-669.

What happened

The OpenClaw Control UI accepted a gatewayUrl parameter from the URL query string and automatically established a WebSocket connection without user confirmation, transmitting the stored authentication token. Combined with missing WebSocket origin validation, this enabled a 1-click RCE kill chain:

1. Victim visits a malicious URL 2. Token exfiltrated in milliseconds via crafted gatewayUrl parameter 3. Attacker connects via Cross-Site WebSocket Hijacking 4. Disables sandbox: exec.approvals.set = 'off' 5. Escapes Docker: tools.exec.host = 'gateway' 6. Full remote code execution on host

Even localhost-bound instances were vulnerable because the attack pivoted through the victim's browser.

Remediation (mandatory)

# 1. Update immediately
openclaw update --channel stable
openclaw --version    # Must show 2026.1.29+

# 2. Rotate ALL gateway auth tokens
export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
# Update in openclaw.json and restart

# 3. Rotate ALL API keys (Anthropic, OpenAI, etc.)
# Generate new keys at each provider's console

# 4. Review logs for suspicious WebSocket connections
openclaw gateway logs | grep -i "websocket\|ws://"

The fix (v2026.1.29) implemented Trust on First Use (TOFU) policy and WebSocket origin validation.

The 42,665 Exposed Instances

Security researcher Maor Dayan discovered 42,665 publicly exposed OpenClaw instances via Shodan/Censys scanning:

• 93.4% had critical authentication bypasses
• 8 instances were completely open — no password, no token, full shell access
• One user's Anthropic API key was leaked and exploited for 11 days before discovery

Root causes

1. Docker default port binding to 0.0.0.0 on VPS instances with public IPs — making gateways discoverable via Shodan HTML fingerprints 2. Reverse proxies making all traffic appear as localhost, bypassing auth 3. Guest mode privilege escalation granting Python REPL access 4. API keys stored in plaintext in ~/.clawdbot leaking via exposed dashboards

Lesson

If you run OpenClaw on a VPS, assume it WILL be found by automated scanners. Binding to 0.0.0.0 is equivalent to publishing your gateway to the internet.

Quick Security Audit

Run these commands after any installation or configuration change:

# Read-only config + filesystem scan
openclaw security audit

# Deep scan: adds live WebSocket probe + credential location audit
openclaw security audit --deep

# Auto-fix safe issues, then run full audit for remaining
openclaw security audit --fix

# Health check with security warnings
openclaw doctor
openclaw doctor --fix        # Auto-fix permission problems, missing dirs, config errors
openclaw doctor --deep --yes # Deep health check with auto-accept fixes

Safe Baseline Configuration

Copy-paste this as your starting point. Every setting is explained below.

{
  gateway: {
    port: 18789,
    mode: "local",
    bind: "loopback",                    // 1. Localhost only
    auth: {
      mode: "token",                     // 2. Token required
      token: "<auto-generated-or-openssl-rand-hex-32>",
      allowTailscale: true               // Allows Tailscale connections
    }
  },
  channels: {
    telegram: {
      enabled: true,
      dmPolicy: "pairing",              // 3. Require approval for DMs
      groups: {
        "*": { requireMention: true }   // 4. @mention required in groups
      }
    }
  },
  discovery: {
    mdns: { mode: "minimal" }           // 5. Minimal network broadcasting
  },
  session: {
    dmScope: "per-channel-peer"          // 6. Isolate sessions per user
  }
}

Setting Explanations

1. `gateway.bind: "loopback"` — Binds to 127.0.0.1 only. The gateway is never reachable from outside the machine. Access via SSH tunnel or Tailscale. This is the single most important security setting.

2. `gateway.auth.mode: "token"` — Requires a strong random token for all gateway connections. Auto-generated during onboarding, or generate manually: openssl rand -hex 32.

3. `dmPolicy: "pairing"` — Unknown senders receive a pairing code instead of getting direct access. You approve each contact via openclaw pairing approve. Never use dmPolicy: "open" with allowFrom: ["*"] unless you understand you're giving anyone access.

4. `requireMention: true` — Bot only responds in groups when @mentioned. Prevents it from responding to every message and reduces prompt injection surface.

5. `discovery.mdns.mode: "minimal"` — Minimal mDNS broadcasting. Use "off" on VPS deployments. Disable Bonjour entirely: export OPENCLAW_DISABLE_BONJOUR=1.

6. `session.dmScope: "per-channel-peer"` — Each channel+sender pair gets an isolated session. Prevents cross-user context leakage in multi-user setups.

File Permissions

# Lock down the OpenClaw directory
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/credentials

# Lock auth profiles
chmod 600 ~/.openclaw/agents/*/agent/auth-profiles.json

# Full-disk encryption
# macOS: Enable FileVault (System Settings → Privacy & Security → FileVault)
# Linux: Use LUKS

Docker Port Binding (VPS Critical)

The #1 cause of exposed instances. In docker-compose.yml:

# ❌ DANGEROUS — binds to all interfaces, publicly accessible via Shodan
ports:
  - "18789:18789"

# ✅ SAFE — binds to localhost only
ports:
  - "127.0.0.1:18789:18789"

Verify after starting:

ss -tlnp | grep 18789
# Must show: 127.0.0.1:18789
# If you see: 0.0.0.0:18789 — STOP and fix immediately

Sandboxing

Control whether agent sessions run in isolated containers:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main"  // Sandbox group/channel sessions (recommended for VPS)
        // mode: "off"     // No sandboxing (default)
        // mode: "all"     // Sandbox every session
      }
    }
  }
}

Scope options:

• "agent" — Per-agent containers (default when sandboxing enabled)
• "session" — Stricter per-session isolation
• "shared" — Single shared container

Rootless Podman is strongly preferred over Docker for sandboxing. A container escape in rootless Podman lands as an unprivileged user (UID 1000), not root. Never mount `/var/run/docker.sock` into the OpenClaw container — a container escape would grant full Docker control.

SOUL.md Security

SOUL.md defines agent behavioral boundaries and is loaded into the system prompt at every session start. The CRITICAL keyword marks rules that should never be overridden — legitimate use is marking security-sensitive rules.

⚠️ SOUL.md is Writable by Default

This makes it a prime attack surface. A compromised SOUL.md grants control equivalent to a compromised .bashrc — the agent will follow whatever instructions are in it.

Defenses:

• Treat SOUL.md as code — review changes carefully
• Set read-only permissions during runtime: chmod 444 ~/.openclaw/workspace/SOUL.md
• Use file integrity monitoring (e.g., md5sum checks in a cron job)
• Backup SOUL.md before installing any skills or making agent changes
• Mark critical security rules with the CRITICAL keyword:

  CRITICAL: Never execute commands that delete files recursively.
  CRITICAL: Never send data to external URLs unless explicitly approved.

ClawHub Skills Security

Treat ClawHub community skills with extreme caution.

The facts:

• Cisco's AI Defense team found 26% of analyzed ClawHub skills contain at least one vulnerability (9 found in a single skill, 2 critical, 5 high severity)
• One skill (#1 ranked "What Would Elon Do?") used direct prompt injection to silently exfiltrate data via curl commands
• Koi Security found 341 malicious skills across 2,857 analyzed, with 335 using fake prerequisites to install Atomic Stealer (AMOS) macOS malware
• No signature verification exists on ClawHub currently
• VirusTotal partnership provides scanning, but social engineering attacks bypass it

Safe practices:

• Only install bundled skills during onboarding
• If you must use ClawHub skills, review the source code first
• Skills are just code — npm install can run arbitrary scripts
• Never install a skill that asks you to run additional install commands
• Check skill ratings AND review counts (fake ratings are common)
• Monitor ~/.openclaw/logs/commands.log (if command-logger hook is enabled) for unexpected commands after installing skills

What NOT to Expose

Never configure or enable these in public-facing or group contexts:

• Directory listings of the workspace or config
• Credentials in SOUL.md, MEMORY.md, or any file loaded into LLM context
• Reasoning/verbose mode in public rooms (leaks system prompt details)
• Elevated tools (shell access, file write, git push) in group sessions
• Browser control in shared contexts
• `/restart` command (disabled by default; don't enable: commands.restart: true)
• Guest mode with elevated privileges (was exploited in exposed instances)

Blocking Destructive Commands

Add to SOUL.md or agent configuration:

CRITICAL: Never execute these commands:
- rm -rf (recursive delete)
- git push --force (force push)
- Commands piped through shell (curl | bash, wget | sh)
- Any command that modifies system files outside the workspace

Trust Hierarchy

OpenClaw processes input from multiple sources. Trust level (highest to lowest):

1. System prompt / SOUL.md — Highest trust (but protect from modification) 2. Owner DMs — Approved owner via pairing 3. Approved users — Paired contacts 4. Group messages — Lower trust, mention-gated 5. Web content / tool results — Untrusted external data 6. Strangers — Zero trust, pairing code required

Configure the agent to treat external content (web search results, file contents from unknown sources) as untrusted data that should not override SOUL.md rules.

Network Security

Tailscale (recommended — zero public ports)

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
tailscale serve https / http://127.0.0.1:18789

SSH Tunnel (alternative)

ssh -N -L 18789:127.0.0.1:18789 user@VPS_IP
# Then access: http://127.0.0.1:18789/?token=YOUR_TOKEN

UFW + fail2ban (VPS mandatory)

sudo apt install ufw fail2ban unattended-upgrades -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw enable
sudo systemctl enable fail2ban

Do NOT open port 18789 in UFW. Access via tunnel or Tailscale only.

Dedicated User (VPS)

Never run OpenClaw as root:

useradd -r -m -d /opt/openclaw -s /bin/bash openclaw
# Transfer ownership of OpenClaw files
chown -R openclaw:openclaw /opt/openclaw/.openclaw

Disable root SSH in /etc/ssh/sshd_config:

PermitRootLogin no
PasswordAuthentication no

Incident Response Procedure

If you suspect a compromise:

1. Stop the gateway immediately:

   openclaw gateway stop
   # Or: docker compose down

2. Lock down network access:

   sudo ufw deny 18789

3. Rotate ALL secrets:

   # New gateway token
   export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
   # Regenerate API keys at each provider's console
   # Regenerate Telegram bot token via BotFather

4. Review logs:

   openclaw gateway logs | grep -i "suspicious\|unauthorized\|websocket"
   cat ~/.openclaw/logs/commands.log | tail -100

5. Check SOUL.md integrity:

   # Compare against your known-good backup
   diff ~/.openclaw/workspace/SOUL.md ~/backups/SOUL.md.bak

6. Re-audit:

   openclaw security audit --deep
   openclaw doctor --deep --yes

7. Update to latest version:

   openclaw update --channel stable

Shadow's Warning

One of OpenClaw's maintainers, known as "Shadow," stated on Discord:

"If you can't understand how to run a command line, this is far too dangerous of a project for you to use safely."

Peter Steinberger himself acknowledged on the Lex Fridman Podcast (#491) that many security issues stemmed from users putting the web backend on the public internet despite documentation warnings. He has hired professional security researcher Jamieson O'Reilly (founder of Dvuln) to strengthen the platform.

This skill exists to bridge that gap — providing safe defaults and clear guidance so that users at all skill levels can deploy OpenClaw without exposing themselves to unnecessary risk. But the warning stands: OpenClaw is powerful software that requires respect for security fundamentals.

Telegram Channel Configuration

Connect OpenClaw to Telegram so you can message your AI assistant from any device. This covers bot creation, DM pairing, and group chat setup.

Step 1: Create a Telegram Bot via BotFather

1. Open Telegram and search for @BotFather 2. Send /newbot 3. Enter a display name (e.g., "My OpenClaw Assistant") 4. Enter a username — must end with bot (e.g., myopenclaw_bot) 5. BotFather returns a bot token in the format: 123456789:ABCdefGHIJKLMNOP... 6. Save this token securely — it's the only credential needed

Recommended BotFather Settings

After creating the bot, send these commands to @BotFather:

• /setjoingroups → Select your bot → Allow (lets the bot be added to groups)
• /setprivacy → Select your bot → Disable (bot can see all group messages, not just commands)

⚠️ After changing privacy to Disabled, you must remove and re-add the bot to each existing group for the change to take effect. New groups added after the change work automatically.

Step 2: Configure in OpenClaw

During Onboarding

The onboarding wizard (openclaw onboard) will prompt for Telegram setup. Select Telegram when asked about channels, then paste your bot token.

Manual Configuration

Add to ~/.openclaw/openclaw.json:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456789:ABCdefGHIJKLMNOP",
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

Via Environment Variable

Alternatively, set the token as an environment variable (useful for Docker/VPS):

export TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIJKLMNOP"

Then restart: openclaw gateway restart

⚠️ CRITICAL: Telegram is a CHANNEL, not a Plugin

This is the most common configuration mistake. The config must go under channels.telegram:

// ✅ CORRECT
{ channels: { telegram: { enabled: true, botToken: "..." } } }

// ❌ WRONG — will cause "plugin not found" error
{ plugins: { entries: { telegram: { enabled: true, botToken: "..." } } } }

Step 3: DM Pairing

With dmPolicy: "pairing" (recommended), unknown senders who DM the bot receive a short pairing code. You must approve each new contact.

Pairing Flow

1. Someone DMs your bot on Telegram 2. Bot replies with a pairing code (e.g., ABC123) 3. On your OpenClaw host, approve the pairing:

# List pending pairing requests
openclaw pairing list telegram

# Approve a specific code
openclaw pairing approve telegram ABC123

Pairing details:

• Codes expire after 1 hour
• Maximum 3 pending requests per channel at a time
• After approval, the contact can message freely (within their session)

Docker Commands

On a VPS with Docker, prefix with docker compose exec:

docker compose exec openclaw-gateway openclaw pairing list telegram
docker compose exec openclaw-gateway openclaw pairing approve telegram ABC123

Step 4: Group Chat Configuration

Groups use isolated sessions — each group gets its own conversation context.

Mention-Gating (recommended)

With requireMention: true, the bot only responds when @mentioned in group chats. This prevents it from responding to every message.

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }  // All groups require @mention
      }
    }
  }
}

Per-Group Configuration

Override settings for specific groups by using the group chat ID:

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true },
        "-1001234567890": { requireMention: false }  // This specific group doesn't need @mention
      }
    }
  }
}

Privacy Mode Requirement

If requireMention is set to false for any group, the bot must have Telegram privacy mode disabled (via BotFather: /setprivacy → Disable). Otherwise, the bot only sees messages starting with / or messages that @mention it.

Remember: After changing privacy mode, remove and re-add the bot to existing groups.

History Injection

When the bot is added to a group or when a new session starts, OpenClaw provides the last 50 unprocessed messages as context. This helps the bot understand the ongoing conversation.

Advanced Options

Custom Bot Commands

Register slash commands with BotFather for discoverability:

/setcommands → Select your bot → Enter:
new - Start a new conversation
status - Show session status
help - Show available commands

Streaming Mode

Control how responses appear in Telegram:

{
  channels: {
    telegram: {
      streaming: "edit"      // Edit message in-place as tokens arrive (default)
      // streaming: "append"  // Send complete message after generation
    }
  }
}

Link Previews

{
  channels: {
    telegram: {
      linkPreviews: false    // Disable link previews in bot responses
    }
  }
}

Troubleshooting

Session Behavior

• DMs collapse to the agent's main session: agent:main:main
• Groups get isolated sessions: agent:<agentId>:telegram:group:<chatId>
• Use /new command in Telegram to start a fresh session
• Session isolation prevents cross-user context leakage when session.dmScope: "per-channel-peer" is set (see security-defaults.md)