OpenClaw Setup Guide : Secure Deployment from Zero to First Chat

OpenClaw Setup Guide: Building Your AI Assistant the Right Way

I’ve deployed AI infrastructure across half a dozen production environments, and OpenClaw stands out for doing something most tools don’t: it stays out of your way while giving you real power under the hood. That said, “powerful” doesn’t automatically mean “straightforward.”

My first install went sideways in three different ways. PATH variables didn’t resolve correctly, the model registry came back empty when I ran my first query, and I somehow configured a gateway that was binding to my entire local network instead of just localhost. Not catastrophic, but definitely the kind of mistakes you make once and then write down so you never repeat them.

So I nuked everything, started over with fresh eyes, and documented every decision point and failure mode I encountered. This is that documentation.

The realistic timeline: If you’ve got Node.js 22+ already installed and an API key sitting in your clipboard, you’re looking at 12-18 minutes end-to-end. Starting completely cold with no Node environment? Budget 30-40 minutes, maybe more if you’re on Windows and need to set up WSL2 first.

By the time you finish this guide, you’ll have a fully functional AI assistant connected to Claude, GPT, or a multi-provider routing layer, with optional integrations to WhatsApp, Telegram, Discord, Slack, Lark, or iMessage. You’ll understand why each configuration choice matters and how to debug the system when something inevitably breaks.

Let’s build this properly.

---

What You Actually Need Before You Start

Don’t skip this section. I’ve watched people waste 20 minutes troubleshooting installation errors that would’ve been caught by a 30-second version check.

Node.js Version 22 or Higher

This isn’t a soft requirement. OpenClaw uses ES modules and modern JavaScript features that don’t exist in older Node runtimes. Check what you’re running:

bash

node --version

If you see v22.x.x or anything higher, you’re clear. If you get v18.x.x, v20.x.x, or “command not found,” you need to upgrade or install.

macOS with Homebrew (fastest if you’re already using Homebrew):

bash

brew install node

macOS or Linux with fnm (version manager, my personal recommendation):

bash

curl -fsSL https://fnm.vercel.app/install | bash
fnm install 22
fnm use 22

Why fnm over nvm? It’s faster, written in Rust, and doesn’t slow down shell startup. If you’re managing multiple Node versions across different projects, fnm makes that trivial.

Direct installer (fallback option):
Grab the official installer from nodejs.org. Choose the LTS version if it’s 22 or higher.

npm comes bundled with Node.js automatically, so that’s one less thing to think about.

Operating System Compatibility

OpenClaw runs natively on:

• macOS (Intel or Apple Silicon)
• Linux (Ubuntu, Debian, Arch, Fedora — anything with a modern kernel)
• Windows via WSL2 (Windows Subsystem for Linux 2)

If you’re on Windows without WSL2: Stop here and set that up first. Native Windows (cmd.exe or PowerShell) won’t work. The WSL2 installation process is well-documented by Microsoft and takes about 15 minutes if your system supports virtualization (most modern machines do).

Key point: WSL2 isn’t just a compatibility layer — it’s a full Linux kernel running in a lightweight VM. Performance is good, and you get access to the entire Linux ecosystem. Once you have it set up, the rest of this guide applies exactly as written.

Understanding What an API Key Actually Is

An API key is your authentication credential with the AI provider. Think of it as a password, but more specific: it identifies your account, tracks your usage, and bills you accordingly.

Each provider generates keys differently, they have different permission scopes, and they expire or revoke under different conditions. You’ll need at least one key before proceeding. We’ll cover exactly how to get one in the next section.

---

Installing OpenClaw: The Actual Process

One command installs it globally:

bash

npm install -g openclaw@latest

The @latest tag ensures you’re getting the most recent stable release. If you want to pin to a specific version for reproducibility (smart move in production environments), replace @latest with an explicit version like openclaw@3.2.1.

Verify the installation:

bash

openclaw --version

You should see a version number. If you don’t, here’s what probably went wrong:

Permission Errors During Install

If you see EACCES or a permission denied error, npm is trying to write to a directory your user doesn’t own. The quick fix:

bash

sudo npm install -g openclaw@latest

The better fix (prevents this issue permanently): reconfigure npm to use a user-writable directory for global packages.

bash

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Add that last export line to your ~/.zshrc or ~/.bashrc so it persists across terminal sessions.

Command Not Found After Installation

This happens when npm’s global binary directory isn’t in your shell’s PATH. The fix:

bash

export PATH="$(npm config get prefix)/bin:$PATH"

To make it permanent, append that to your shell configuration file:

bash

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Replace ~/.zshrc with ~/.bashrc if you’re using bash instead of zsh.

Why this happens: When npm installs global packages, it puts executable files in a specific bin directory. If that directory isn’t in PATH, your shell doesn’t know where to find the openclaw command even though it’s installed correctly.

---

Choosing Your AI Provider: The Practical Breakdown

OpenClaw supports multiple backends. Here’s what matters for each one.

The Provider Comparison

Provider	Best Use Case	API Key Format	Pricing Model	Latency
Anthropic	General development, long-context reasoning, code review	sk-ant-...	Pay per token (input + output)	Low (~200-400ms first token)
OpenAI	Instruction following, structured outputs, function calling	sk-...	Pay per token	Low (~150-300ms first token)
OpenRouter	Multi-model access, experimentation, fallback routing	sk-or-...	Pay per token + small routing fee	Medium (~300-600ms, adds one hop)

My Honest Recommendation

Start with Anthropic if:

• You’re using this primarily for coding tasks, technical writing, or complex reasoning
• You value nuanced understanding over raw speed
• You need strong context retention across long conversations

Claude Sonnet 4.6 hits the sweet spot: fast enough for interactive use, capable enough for serious work, and priced reasonably for sustained usage. I default to this for 80% of my tasks.

Use OpenAI if:

• You need extremely tight function calling and JSON output formatting
• You’re integrating with existing OpenAI-based tooling
• You want the absolute fastest response times on simple queries

Consider OpenRouter if:

• You want flexibility to switch between Claude, GPT, Gemini, and 100+ other models without managing separate keys
• You’re doing model comparisons or A/B testing
• You want automatic fallback routing when one provider has issues

The tradeoff with OpenRouter: you’re adding a routing layer between you and the actual provider. That’s an extra network hop, which adds 100-200ms of latency, and it means you’re trusting OpenRouter’s infrastructure in addition to the underlying provider’s.

---

Getting Your API Key: Step-by-Step

Each provider has a different console interface. Here’s the exact click path for each one.

Anthropic (Claude Models)

1. Navigate to console.anthropic.com
2. Create an account or log in with existing credentials
3. Go to Settings → API Keys (or directly to console.anthropic.com/settings/keys)
4. Click Create Key
5. Name it something memorable like “openclaw-production” or “openclaw-dev”
6. Copy the key immediately — it starts with sk-ant- and you won’t be able to view it again
7. Store it somewhere secure (password manager, not a plaintext file)

Critical step most people miss: New Anthropic accounts need to add a payment method under Billing before API keys will work. The key will generate successfully, but API calls will fail with a 401 error until billing is configured.

You can add credits directly or set up auto-recharge. I recommend starting with $20 of credits — that’s enough to test thoroughly without worrying about runaway costs.

OpenAI (GPT Models)

1. Go to platform.openai.com/api-keys
2. Click Create new secret key
3. Name it “openclaw” or similar
4. Copy immediately — starts with sk-, shown only once
5. Add billing at platform.openai.com/settings/organization/billing if you haven’t already

OpenAI’s billing works differently from Anthropic: you need to add a payment method before you can make any API calls, even to test. There’s no trial credit system anymore (they removed that in 2024).

OpenRouter (Multi-Provider Access)

1. Navigate to openrouter.ai/keys
2. Click Create Key
3. Name it “openclaw”
4. Copy the key — starts with sk-or-
5. Add credits at openrouter.ai/credits

OpenRouter uses a prepaid credit system. You load credits into your account, and they get deducted as you use different models. Minimum credit purchase is usually $5, which goes surprisingly far if you’re just testing.

What if you don’t have a key yet?
You can skip the key during initial onboarding and add it manually to ~/.openclaw/openclaw.json later. Jump to the Full Configuration Reference section for the exact JSON structure.

---

Running Initial Setup: The Onboarding Process

OpenClaw’s onboard command handles the heavy lifting. It configures authentication, sets up the local gateway, installs the background daemon, and runs health checks.

For Anthropic Users

bash

openclaw onboard --install-daemon --anthropic-api-key "sk-ant-your-actual-key-here"

Replace sk-ant-your-actual-key-here with your real key. Keep the quotes — they prevent shell interpretation issues if your key contains special characters.

For OpenAI Users

bash

openclaw onboard --install-daemon --openai-api-key "sk-your-actual-key-here"

For OpenRouter Users

bash

openclaw onboard --install-daemon --auth-choice apiKey --token-provider openrouter --token "sk-or-your-actual-key-here"

The extra flags (--auth-choice and --token-provider) tell OpenClaw this isn’t a direct provider API key — it’s a routing token.

What This Command Actually Does

When you run onboard --install-daemon, four things happen in sequence:

1. Authentication configuration: Your API key gets written to ~/.openclaw/openclaw.json under the env section
2. Gateway setup: The local API gateway gets configured to listen on port 18789 (loopback only)
3. Daemon installation: A background service gets registered with your system’s service manager
4. Health check: OpenClaw verifies it can reach the AI provider and lists available models

If the health check fails, you’ll see an error message explaining what went wrong. Most common causes: invalid API key, billing not configured, or network connectivity issues.

Interactive Fallback Mode

If the non-interactive command fails (sometimes happens with certain shell configurations or terminal emulators), run the interactive version:

bash

openclaw onboard --install-daemon

This launches a wizard that asks questions step-by-step:

• Which provider are you using?
• Paste your API key
• Accept default port? (say yes unless 18789 is taken)
• Install as background daemon? (say yes)

Same result, just a different UX. Use whichever works.

---

Configuring Your Default Model

Your default model is what OpenClaw uses when you start a new conversation without specifying otherwise. Set this by editing ~/.openclaw/openclaw.json.

Anthropic Models

json

{
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" }
    }
  }
}

Model	Config ID	When to Use	Approximate Cost*
Claude Sonnet 4.6	anthropic/claude-sonnet-4-6	Default choice — balanced speed and capability	~$3 per million input tokens
Claude Opus 4.6	anthropic/claude-opus-4-6	Complex reasoning, research, critical analysis	~$15 per million input tokens
Claude Haiku 4.5	anthropic/claude-haiku-4-5-20251001	Fast responses, simple queries, high-volume tasks	~$0.25 per million input tokens

*Pricing as of March 2026, subject to change. Check Anthropic’s pricing page for current rates.

Important note on model IDs: These strings change when providers release new versions. If your configuration suddenly stops working after weeks of stability, check the Anthropic models documentation for updated model IDs.

OpenAI Models

json

{
  "agents": {
    "defaults": {
      "model": { "primary": "openai/gpt-5.2" }
    }
  }
}

Model	Config ID	Notes
GPT-5.2	openai/gpt-5.2	Recommended default for general use
GPT-5.2 mini	openai/gpt-5.2-mini	Faster and cheaper, good for simple tasks
o3	openai/o3	Reasoning-focused, slower but more thorough

OpenRouter Models

OpenRouter uses the format openrouter/<provider>/<model>:

json

{
  "agents": {
    "defaults": {
      "model": { "primary": "openrouter/anthropic/claude-sonnet-4-6" }
    }
  }
}

Model	Config ID
Claude Sonnet 4.6	openrouter/anthropic/claude-sonnet-4-6
Claude Opus 4.6	openrouter/anthropic/claude-opus-4-6
GPT-5.2	openrouter/openai/gpt-5.2
Gemini 2.5 Pro	openrouter/google/gemini-2.5-pro

The advantage of OpenRouter: you can switch between these models by changing one configuration line, without managing separate API keys for each provider.

---

Essential Configuration Settings You Should Add

These aren’t defaults — you need to manually add them to your config. But they prevent common failure modes and make the system significantly more robust in real-world usage.

json

{
  "agents": {
    "defaults": {
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 },
      "timeout": 300000,
      "retryAttempts": 3
    }
  },
  "messages": { 
    "ackReactionScope": "group-mentions",
    "maxLength": 4096
  },
  "commands": { 
    "native": "auto", 
    "nativeSkills": "auto" 
  },
  "skills": { 
    "install": { "nodeManager": "npm" } 
  },
  "logging": {
    "level": "info",
    "file": "~/.openclaw/logs/openclaw.log"
  }
}

What Each Setting Actually Does

compaction: { mode: "safeguard" }
Prevents context window overflow on long conversations. Without this, OpenClaw can hit the model’s token limit and silently fail — your message gets sent, but the response is truncated or errors out. Safeguard mode automatically compresses older context while preserving the most recent exchanges.

maxConcurrent: 4
Limits parallel task execution. If you’re on a 16-core machine with plenty of RAM, you can bump this to 8 or even 12. If you’re on a constrained system (like a laptop), keep it at 4 or lower. Higher concurrency means faster multi-task processing but more memory usage and higher API costs if multiple tasks hit the provider simultaneously.

subagents: { maxConcurrent: 8 }
Controls parallelism for sub-tasks spawned by the primary agent. Useful for complex workflows where one query spawns multiple research threads. Set this higher than maxConcurrent if you want subtasks to run in parallel while limiting top-level concurrency.

timeout: 300000
Request timeout in milliseconds (300,000ms = 5 minutes). Some complex reasoning tasks with Claude Opus can take 2-3 minutes to complete. Default timeout is often 60 seconds, which causes premature failures on heavy workloads.

retryAttempts: 3
Number of times to retry failed API calls before giving up. Handles transient network errors, rate limit errors (with exponential backoff), and temporary provider outages.

ackReactionScope: "group-mentions"
In group chats, the bot only reacts to messages that explicitly mention it. Prevents noise in shared channels where the bot is listening but shouldn’t respond to every message.

maxLength: 4096
Maximum message length in characters before truncation. Protects against accidentally sending massive wall-of-text messages that waste tokens and cost money.

logging: { level: "info" }
Controls log verbosity. Options: error, warn, info, debug. Use info for normal operation, switch to debug when troubleshooting.

---

Security Configuration: The Non-Negotiable Rules

This section is critical. Most people skip it, and that’s how you end up with an AI agent accessible to your entire network or with permission to access your camera without explicit authorization.

Verify your ~/.openclaw/openclaw.json has these settings:

json

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "auth": { "mode": "token" },
    "cors": {
      "enabled": false
    },
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000
    },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "calendar.add",
        "calendar.modify",
        "calendar.delete",
        "contacts.add",
        "contacts.modify",
        "contacts.delete",
        "reminders.add",
        "files.delete",
        "files.move",
        "system.shutdown",
        "system.reboot"
      ]
    }
  }
}

Three Security Rules That Are Absolute

1. Always bind to loopback

json

"bind": "loopback"

This means the gateway listens only on 127.0.0.1 — your local machine. No other device on your network can reach it.

If this gets changed to 0.0.0.0 (all interfaces), your gateway becomes accessible to every device on your local network. That includes your phone, your roommate’s laptop, and potentially anything else connected to your Wi-Fi. Don’t do this unless you’re running in a strictly controlled environment and you understand the implications.

2. Keep token authentication enabled

json

"auth": { "mode": "token" }

The gateway auth token is auto-generated during onboarding and stored in ~/.openclaw/gateway-token. Every API request must include this token in the Authorization header.

Turning auth off ("mode": "none") means any process running on your machine can send commands to your AI agent. Malicious software could instruct your agent to exfiltrate data, run arbitrary commands, or consume your API credits.

3. Maintain an explicit deny list

The denyCommands array is your last line of defense. Even if a malicious actor somehow gets past authentication, they can’t use commands on this list.

Start with this baseline:

• Camera/screen access: camera.snap, camera.clip, screen.record
• Calendar modification: calendar.add, calendar.modify, calendar.delete
• Contact manipulation: contacts.add, contacts.modify, contacts.delete
• File operations: files.delete, files.move (reading is fine, deletion is not)
• System control: system.shutdown, system.reboot

Expand this list based on your threat model. If you’re running OpenClaw on a work machine with sensitive data, add commands related to email sending, file uploads, or network operations.

Additional Security Hardening

Enable rate limiting (shown in config above):
Prevents abuse if someone does get hold of your auth token. maxRequests: 100 per windowMs: 60000 means 100 requests per minute maximum.

Disable CORS unless you’re building a web frontend:
Cross-Origin Resource Sharing allows web pages from other domains to make requests to your gateway. Unless you specifically need this, keep it disabled.

Regularly rotate your auth token:

bash

openclaw gateway rotate-token

Do this every few months, or immediately if you suspect your token has been compromised.

---

Connecting Messaging Apps (Optional)

You can use OpenClaw entirely through the terminal (openclaw tui) or web dashboard (openclaw dashboard). That’s perfectly valid for most development workflows.

But connecting a messaging app — WhatsApp, Telegram, Discord, etc. — means you can interact with your AI assistant from your phone while you’re away from your computer. Useful for quick queries, reminders, or checking on long-running tasks.

Here’s how to set up each channel properly.

WhatsApp Integration

WhatsApp uses the same multi-device protocol as WhatsApp Web. You’re essentially registering OpenClaw as a linked device.

Step 1: Add configuration

Edit ~/.openclaw/openclaw.json:

json

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["+12125551234"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+12125551234"],
      "autoReconnect": true,
      "sessionTimeout": 86400000
    }
  }
}

Replace +12125551234 with your phone number in full international format (country code + number, no spaces or dashes).

What these settings mean:

• dmPolicy: "pairing" — Requires explicit approval before responding to new contacts
• allowFrom — Whitelist of phone numbers allowed to DM the bot
• groupPolicy: "allowlist" — Only responds in explicitly approved groups
• groupAllowFrom — Who can add the bot to groups
• autoReconnect: true — Automatically reconnects if the session drops
• sessionTimeout — Session expires after 24 hours of inactivity (86400000ms)

Step 2: Restart daemon and initiate pairing

bash

openclaw daemon restart
openclaw channels login --channel whatsapp

A QR code will appear in your terminal.

Step 3: Scan with WhatsApp

On your phone:

1. Open WhatsApp
2. Go to Settings → Linked Devices
3. Tap Link a Device
4. Scan the QR code

Step 4: Approve the pairing

bash

openclaw pairing list whatsapp

You’ll see a pairing request with a code like WA-abc123def456.

Approve it:

bash

openclaw pairing approve whatsapp WA-abc123def456

Done. Send a message to your OpenClaw number (the one linked to your WhatsApp account) and you should get a response.

Pro tip: Use a dedicated WhatsApp number via a dual-SIM phone or a virtual number service. Don’t link your personal WhatsApp — if something goes wrong with the session, you don’t want your primary account locked out.

Telegram Integration

Telegram is the easiest channel to set up. No QR codes, no device linking — just a bot token.

Step 1: Create a bot with BotFather

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the prompts:
   • Choose a display name (e.g., “My OpenClaw Assistant”)
   • Choose a username (must end in bot, e.g., my_openclaw_bot)
4. BotFather will respond with your bot token — looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz
5. Copy this token immediately

Step 2: Configure OpenClaw

json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      "dmPolicy": "pairing",
      "allowCommands": true,
      "maxMessageLength": 4096
    }
  }
}

• allowCommands: true — Enables Telegram’s native bot command interface (/start, /help, etc.)
• maxMessageLength: 4096 — Telegram’s message limit

Step 3: Restart and approve

bash

openclaw daemon restart

Now send any message to your bot in Telegram. Then:

bash

openclaw pairing list telegram

You’ll see a pairing code like TG-xyz789abc123.

Approve it:

bash

openclaw pairing approve telegram TG-xyz789abc123

That’s it. Your bot is now live and will respond to your messages.

Telegram advantage: You can create multiple bots for different contexts (work, personal, experiments) and switch between them easily.

Discord Integration

Discord requires more setup than Telegram but gives you better control over permissions and server-specific configurations.

Step 1: Create a Discord application

1. Go to discord.com/developers/applications
2. Click New Application
3. Name it (e.g., “OpenClaw Assistant”)
4. Click Create

Step 2: Generate a bot token

1. In the left sidebar, click Bot
2. Click Reset Token (or Add Bot if this is your first time)
3. Copy the token immediately — it looks like MTIzNDU2Nzg5MDEyMzQ1Njc4.GabcDE.fGhIjKlMnOpQrStUvWxYz012345678
4. Scroll down and enable Message Content Intent (critical — without this, your bot can’t read message content)

Step 3: Configure bot permissions

Still in the Discord developer portal:

1. Go to OAuth2 → URL Generator
2. Under Scopes, check:
   • bot
   • applications.commands (if you want slash commands)
3. Under Bot Permissions, check:
   • Send Messages
   • Read Message History
   • Add Reactions
   • Attach Files
   • Embed Links
   • Use External Emojis (optional, for richer responses)

Step 4: Generate invite URL and add bot to server

1. Copy the generated URL at the bottom of the page
2. Open it in a browser
3. Select the server you want to add the bot to
4. Click Authorize

Step 5: Configure OpenClaw

json

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "MTIzNDU2Nzg5MDEyMzQ1Njc4.GabcDE.fGhIjKlMnOpQrStUvWxYz012345678",
      "dmPolicy": "pairing",
      "guildPolicy": "allowlist",
      "allowedGuilds": ["1234567890123456789"],
      "commandPrefix": "!"
    }
  }
}

To find your server’s Guild ID:

1. In Discord, enable Developer Mode: User Settings → Advanced → Developer Mode
2. Right-click your server name and select Copy Server ID

Step 6: Restart and verify

bash

openclaw daemon restart
openclaw channels status --probe

Your bot should now be online in your server.

Discord-specific tip: Create a private server with dedicated channels for different AI contexts — #coding, #research, #writing. Each channel maintains its own conversation history, so you can switch between tasks without mixing contexts.

Slack Integration

Slack requires both a bot token and an app token (for Socket Mode, which keeps a persistent connection).

Step 1: Create a Slack app

1. Go to api.slack.com/apps
2. Click Create New App
3. Choose From scratch
4. Name it (e.g., “OpenClaw”) and select your workspace
5. Click Create App

Step 2: Enable Socket Mode

1. In the left sidebar, click Socket Mode
2. Toggle it On
3. Click Generate Token when prompted
4. Name it “app-token”
5. Copy the App-Level Token — starts with xapp-

Step 3: Configure bot token and scopes

1. In the left sidebar, click OAuth & Permissions
2. Scroll to Bot Token Scopes and add:
   • chat:write (send messages)
   • channels:history (read channel messages)
   • im:history (read DMs)
   • app_mentions:read (detect @mentions)
   • files:write (upload files)

Step 4: Install app to workspace

1. Scroll to the top of OAuth & Permissions
2. Click Install to Workspace
3. Review permissions and click Allow
4. Copy the Bot User OAuth Token — starts with xoxb-

Step 5: Enable event subscriptions

1. In the left sidebar, click Event Subscriptions
2. Toggle Enable Events to On
3. Under Subscribe to bot events, add:
   • message.im (DMs)
   • app_mention (when @mentioned in channels)

Step 6: Configure OpenClaw

json

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-your-bot-token-here",
      "appToken": "xapp-your-app-token-here",
      "dmPolicy": "pairing",
      "channelPolicy": "mention"
    }
  }
}

• channelPolicy: "mention" — Bot only responds when @mentioned in public channels

Step 7: Restart and test

bash

openclaw daemon restart
openclaw channels status --probe

DM your bot in Slack or @mention it in a channel.

Slack-specific advantage: Deep workspace integration. Your bot can search message history, access threads, and interact with other Slack apps if you expand its permissions later.

Lark / Feishu Integration

Lark (international) and Feishu (China) are the same platform with different domains. Setup is identical.

Step 1: Access developer console

• Lark: open.larksuite.com
• Feishu: open.feishu.cn

Step 2: Create a custom app

1. Click Create App
2. Choose Custom App
3. Name it and upload an icon (optional)
4. Click Create

Step 3: Get credentials

1. Go to Credentials & Basic Info
2. Copy your App ID (starts with cli_)
3. Copy your App Secret

Step 4: Enable required permissions

1. Go to Permissions & Scopes
2. Add these scopes:
   • im:message (read/send DMs)
   • im:message.group_at_msg (read @mentions in groups)

Step 5: Configure OpenClaw

For Lark (international):

json

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "lark",
      "accounts": {
        "main": {
          "appId": "cli_your-app-id-here",
          "appSecret": "your-app-secret-here"
        }
      },
      "dmPolicy": "pairing"
    }
  }
}

For Feishu (China):

json

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "feishu",
      "accounts": {
        "main": {
          "appId": "cli_your-app-id-here",
          "appSecret": "your-app-secret-here"
        }
      },
      "dmPolicy": "pairing"
    }
  }
}

The only difference: "domain": "lark" vs "domain": "feishu".

Step 6: Restart and verify

bash

openclaw daemon restart
openclaw channels status --probe

iMessage Integration (macOS Only)

This is the most involved setup because it requires a third-party CLI tool and macOS privacy permissions.

Important: This only works on macOS. No Linux or Windows support.

Step 1: Install the iMessage CLI tool

bash

brew install steipete/tap/imsg

This is a third-party tool maintained by Peter Steinberger. It bridges between the command line and macOS’s Messages app.

Step 2: Grant system permissions

You need to grant Full Disk Access to your terminal application:

1. Open System Settings → Privacy & Security → Full Disk Access
2. Click the + button
3. Navigate to /Applications/Utilities/ and select Terminal.app (or iTerm.app if you use iTerm)
4. Click Open

When you first run the imsg command, macOS will prompt you to allow Automation access for Messages. Click OK.

Step 3: Find your Messages database path

bash

echo $HOME/Library/Messages/chat.db

This should output something like /Users/yourusername/Library/Messages/chat.db.

Step 4: Configure OpenClaw

Replace YOUR_USERNAME with your actual macOS username:

json

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/usr/local/bin/imsg",
      "dbPath": "/Users/YOUR_USERNAME/Library/Messages/chat.db",
      "pollInterval": 5000,
      "dmPolicy": "pairing"
    }
  }
}

• pollInterval: 5000 — Check for new messages every 5 seconds (5000ms)

Step 5: Restart daemon

bash

openclaw daemon restart

Why this setup is complex: Apple doesn’t provide an official iMessage API. The imsg tool works by reading the local SQLite database where Messages stores your conversations. That’s why it needs Full Disk Access — it’s literally reading a protected system database.

Security consideration: This gives OpenClaw read access to your entire iMessage history. If that makes you uncomfortable, skip this integration and use one of the other channels instead.

---

Understanding Channel Access Control

All channels use the same access control system. Here’s how each policy option works in practice.

DM Policies (Direct Messages)

Policy	Behavior	Use Case
pairing	Requires explicit approval via openclaw pairing approve before responding	Default recommendation — prevents spam, ensures you control who can talk to your bot
allowlist	Only responds to senders in the allowFrom array	Strict control — useful if you’re running this on a shared server
open	Responds to anyone who messages the bot	High-risk — only use in private or fully trusted environments
disabled	Ignores all DMs	Useful if you only want group chat functionality

Group/Channel Policies

Policy	Behavior	Use Case
allowlist	Only participates in groups explicitly listed in groupAllowFrom	Tight control over which channels the bot monitors
mention	Only responds when explicitly @mentioned	Recommended for shared channels — prevents the bot from reacting to every message
open	Responds to all messages in any group it’s in	Overwhelming in active channels — rarely the right choice
disabled	Ignores all group messages	DM-only bot configuration

Example Configuration for Personal Use

json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-token-here",
      "dmPolicy": "pairing",
      "groupPolicy": "mention",
      "allowFrom": [123456789]
    }
  }
}

This configuration:

• Requires pairing approval for new DM contacts
• Only responds in groups when @mentioned
• Has a specific user ID in the allowlist (Telegram user IDs are numeric)

Example Configuration for Team Use

json

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-your-token",
      "appToken": "xapp-your-token",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "U01ABC123",
        "U02DEF456",
        "U03GHI789"
      ],
      "channelPolicy": "allowlist",
      "allowedChannels": [
        "C01JKLMNO",
        "C02PQRSTU"
      ]
    }
  }
}

This locks down the bot to specific users and specific channels only. Good for team environments where you want controlled access.

---

Verifying Everything Works

Once you’ve finished configuration, run a full system check.

Restart the Daemon

bash

openclaw daemon restart

Wait a few seconds for the daemon to fully initialize:

bash

sleep 5

Check Model Availability

bash

openclaw models list
```

**Expected output**: You should see your provider's models listed:
```
anthropic/claude-sonnet-4-6
anthropic/claude-opus-4-6
anthropic/claude-haiku-4-5-20251001

If the list is empty: This almost always means one of three things:

1. Invalid API key
2. Billing not configured on your provider account
3. Network connectivity issue

Debug it:

bash

openclaw daemon logs | tail -20

Look for error messages related to authentication or billing.

Verify Channel Connections

bash

openclaw channels status --probe
```

**Expected output**: Each enabled channel should show `connected: true`.

Example:
```
whatsapp: connected ✓
telegram: connected ✓
discord: connected ✓

If a channel shows disconnected:

• For WhatsApp: Session may have expired — run openclaw channels login --channel whatsapp again
• For Telegram/Discord/Slack: Verify your bot token is correct in the config
• For all channels: Check openclaw daemon logs for specific error messages

Test a Real Query

Open the terminal UI:

bash

openclaw tui

Send a test message like “What’s 2+2?” or “Write a haiku about coffee.”

If you get a response, everything’s working. If you don’t:

1. Check daemon status: openclaw daemon status
2. Review logs: openclaw daemon logs
3. Verify your API key has available credits

---

Using OpenClaw: Your Interface Options

Terminal Interface (TUI)

bash

openclaw tui

This opens an interactive terminal chat interface. Clean, fast, no browser required.

Why use this: When you’re already in a terminal and want quick AI assistance without context switching to a browser. Great for development workflows.

Terminal Interface Deep Dive: Mastering the TUI

The openclaw tui command launches OpenClaw’s terminal user interface — a full-featured chat client that runs entirely in your terminal without requiring a browser or GUI.

Starting the TUI

Basic usage:

openclaw tui

With specific options:

# Start with a specific agent configuration
openclaw tui --agent coding

# Start with a specific model
openclaw tui --model anthropic/claude-opus-4-6

# Start in a specific conversation
openclaw tui --conversation conv-abc-123

# Start with verbose logging
openclaw tui --verbose

# Combine options
openclaw tui --agent quick --model anthropic/claude-haiku-4-5-20251001

TUI Keyboard Shortcuts and Commands

Navigation & Control:

• Ctrl+C — Exit the TUI (asks for confirmation if conversation is active)
• Ctrl+L — Clear screen (conversation history preserved)
• Ctrl+D — Send EOF signal (alternative exit method)
• Up/Down arrows — Navigate through command history
• Ctrl+R — Reverse search through command history (fuzzy search)
• Ctrl+A — Move cursor to beginning of line
• Ctrl+E — Move cursor to end of line
• Ctrl+U — Clear current input line
• Ctrl+K — Delete from cursor to end of line

Conversation Management:

• Ctrl+N — Start new conversation
• Ctrl+O — Open conversation list (navigate with arrows, press Enter to load)
• Ctrl+S — Save current conversation with a name
• Ctrl+W — Close current conversation (asks for confirmation if unsaved)

Message Actions:

• Ctrl+Y — Copy last AI response to clipboard
• Ctrl+P — Paste from clipboard into input
• Ctrl+X — Export current conversation to markdown file

Special Commands (type these in the input):

• /help — Show all available commands
• /clear — Clear conversation history (fresh context)
• /model <model-id> — Switch to different model mid-conversation
• /agent <agent-name> — Switch to different agent configuration
• /stats — Show token usage for current conversation
• /export — Export conversation to file
• /config — Show current active configuration
• /quit or /exit — Exit TUI (same as Ctrl+C)

TUI Display Features

Message Formatting:

• Syntax highlighting for code blocks (automatically detects language)
• Markdown rendering for bold, italic, and inline code
• Automatic URL detection and highlighting
• Multi-line code blocks with language indicators
• Proper indentation preservation

Status Indicators:

• ● green — Connected and ready
• ○ yellow — Waiting for response
• × red — Connection error or rate limited
• ⏸ gray — Paused (background task running)

Token Counter:
The bottom-right corner shows:

Tokens: 1,234 in / 567 out | Total: 1,801

This tracks your current conversation’s token usage in real-time.

TUI Configuration Options

Add these to your ~/.openclaw/openclaw.json to customize TUI behavior:

{
  "tui": {
    "theme": "dark",
    "syntaxHighlight": true,
    "showTokenCount": true,
    "autoScroll": true,
    "timestampFormat": "HH:mm:ss",
    "messageMaxWidth": 120,
    "confirmOnExit": true,
    "saveHistoryOnExit": true,
    "historyFile": "~/.openclaw/tui-history",
    "promptSymbol": "❯",
    "colorScheme": {
      "userMessage": "cyan",
      "aiMessage": "green",
      "system": "yellow",
      "error": "red"
    }
  }
}

Option explanations:

• theme — Visual theme: dark, light, or auto (follows system)
• syntaxHighlight — Enable code syntax highlighting (requires additional packages)
• showTokenCount — Display token usage in bottom-right corner
• autoScroll — Automatically scroll to bottom when new message arrives
• timestampFormat — Format for message timestamps (uses standard date format strings)
• messageMaxWidth — Maximum line width before wrapping (in characters)
• confirmOnExit — Ask for confirmation before exiting with unsaved conversation
• saveHistoryOnExit — Automatically save conversation when exiting
• historyFile — Where to store command history
• promptSymbol — The symbol shown before your input cursor
• colorScheme — Customize colors for different message types

TUI Performance Tips

For slow connections:

{
  "tui": {
    "streamingDelay": 50,
    "bufferSize": 512
  }
}

For high-latency networks:

{
  "tui": {
    "connectionTimeout": 10000,
    "retryDelay": 2000
  }
}

For resource-constrained systems:

{
  "tui": {
    "syntaxHighlight": false,
    "messageBufferLimit": 50
  }
}

This limits how many messages are kept in memory (older ones are archived to disk).

When to Use TUI vs Web Dashboard

Use TUI when:

• You’re already working in terminal and want minimal context switching
• You need fast, keyboard-driven interaction
• You’re on a remote server via SSH
• You want minimal resource usage (no browser overhead)
• You’re working with lots of code and want syntax highlighting in terminal

Use Web Dashboard when:

• You need to copy/paste large blocks of formatted text
• You want to view images or rich media in responses
• You prefer mouse-based navigation
• You need to reference multiple conversations side-by-side (multiple browser tabs)
• You want a more visual conversation history view

Troubleshooting TUI Issues

TUI won’t start / crashes immediately:

# Check if daemon is running
openclaw daemon status

# View TUI-specific logs
openclaw daemon logs | grep -i tui

# Start with debug mode
openclaw tui --debug

Colors not displaying correctly:

# Check terminal color support
echo $TERM

# Force 256-color mode
export TERM=xterm-256color
openclaw tui

Keyboard shortcuts not working:
Some terminal emulators intercept certain key combinations. Check your terminal settings or remap shortcuts in config:

{
  "tui": {
    "keyBindings": {
      "newConversation": "Ctrl+T",
      "clearScreen": "Ctrl+B"
    }
  }
}

Unicode characters rendering as boxes:
Your terminal font doesn’t support Unicode. Install a modern terminal font like:

• Fira Code
• JetBrains Mono
• Cascadia Code

Web Dashboard

bash

openclaw dashboard

Then navigate to http://127.0.0.1:18789 in your browser.

Features the web dashboard has that TUI doesn’t:

• Syntax highlighting for code blocks
• Inline image rendering
• Better formatting for long responses
• Easier copy/paste for large blocks of text
• Conversation history with search

Why use this: When you need a more visual interface, or when working with responses that contain lots of formatted content.

Messaging App Interfaces

If you’ve configured WhatsApp, Telegram, Discord, etc., you can interact with your assistant directly from those apps.

Advantages:

• Access from your phone
• Integration with your existing communication workflows
• Persistent conversation history in the app
• Can share AI responses with other people easily

Disadvantages:

• More latency than local interfaces
• Dependent on internet connectivity
• Rate limits may apply depending on the platform

---

Essential Commands Reference

Command	Purpose	When to Use
openclaw tui	Open terminal chat interface	Quick queries while in terminal
openclaw dashboard	Start web dashboard (port 18789)	Longer conversations, formatted output
openclaw daemon status	Check if daemon is running	Troubleshooting connectivity
openclaw daemon start	Start the daemon	After system reboot or manual stop
openclaw daemon stop	Stop the daemon	Before config changes or upgrades
openclaw daemon restart	Restart the daemon	After editing config file
openclaw daemon logs	View daemon logs	Essential for debugging
openclaw daemon logs --follow	Tail logs in real-time	Watching live activity
openclaw models list	List available AI models	Verifying provider connection
openclaw models set <model-id>	Change default model	Switching between Claude/GPT/etc.
openclaw channels status	Show channel connection status	Quick health check
openclaw channels status --probe	Test each channel actively	Deep health check
openclaw channels login --channel <name>	Re-authenticate a channel	WhatsApp session expired
openclaw pairing list <channel>	Show pending pairing requests	Approving new contacts
openclaw pairing approve <channel> <code>	Approve a pairing request	Granting access to new user
openclaw config show	Display current configuration	Verify settings without editing files
openclaw config validate	Check config for errors	Before restarting after manual edits
openclaw gateway rotate-token	Generate new auth token	Security best practice (quarterly)
openclaw version	Show OpenClaw version	Before reporting bugs
openclaw upgrade	Update to latest version	Monthly maintenance

---

Complete Configuration Example

Here’s a fully functional ~/.openclaw/openclaw.json with Anthropic as the provider, WhatsApp and Telegram enabled, and all recommended settings in place:

json

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-your-actual-key-here"
  },
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" },
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 },
      "timeout": 300000,
      "retryAttempts": 3
    }
  },
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["+12125551234"],
      "groupPolicy": "mention",
      "autoReconnect": true
    },
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
      "dmPolicy": "pairing",
      "allowCommands": true
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "auth": { "mode": "token" },
    "cors": { "enabled": false },
    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000
    },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "calendar.add",
        "calendar.modify",
        "calendar.delete",
        "contacts.add",
        "contacts.modify",
        "contacts.delete",
        "reminders.add",
        "files.delete",
        "files.move",
        "system.shutdown",
        "system.reboot"
      ]
    }
  },
  "messages": { 
    "ackReactionScope": "group-mentions",
    "maxLength": 4096
  },
  "commands": { 
    "native": "auto", 
    "nativeSkills": "auto" 
  },
  "skills": { 
    "install": { "nodeManager": "npm" } 
  },
  "logging": {
    "level": "info",
    "file": "~/.openclaw/logs/openclaw.log"
  }
}

How to use this template:

1. Copy this entire block
2. Replace sk-ant-your-actual-key-here with your real API key
3. Replace the phone number and bot token with your real credentials
4. Adjust maxConcurrent based on your hardware (4 is safe for most systems)
5. Modify denyCommands based on your security requirements
6. Save to ~/.openclaw/openclaw.json
7. Run openclaw daemon restart

---

Complete Configuration Options Reference

This is the comprehensive reference for every configuration option available in ~/.openclaw/openclaw.json. Use this when you need to fine-tune specific behaviors.

Configuration File Structure

OpenClaw’s configuration follows this hierarchy:

~/.openclaw/
├── openclaw.json # Main configuration file
├── gateway-token # Auto-generated auth token
├── conversations/ # Conversation history
├── logs/ # Daemon and error logs
└── state/ # Runtime state and cache

The openclaw.json file has this top-level structure:

{
  "env": {},              // Environment variables (API keys)
  "agents": {},           // AI agent configurations
  "channels": {},         // Messaging platform integrations
  "gateway": {},          // Local API gateway settings
  "messages": {},         // Message handling behavior
  "commands": {},         // Command execution settings
  "skills": {},           // Plugin and skill configurations
  "logging": {},          // Logging and debugging
  "tui": {},              // Terminal interface settings
  "dashboard": {}         // Web dashboard settings
}

Environment Variables Section (env)

Stores sensitive credentials and API keys.

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-...",
    "OPENAI_API_KEY": "sk-...",
    "OPENROUTER_API_KEY": "sk-or-...",

    // Optional: Override API endpoints
    "ANTHROPIC_API_URL": "https://api.anthropic.com",
    "OPENAI_API_URL": "https://api.openai.com",

    // Optional: HTTP proxy
    "HTTP_PROXY": "http://proxy.example.com:8080",
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "NO_PROXY": "localhost,127.0.0.1"
  }
}

Available keys:

• ANTHROPIC_API_KEY — Anthropic API key (starts with sk-ant-)
• OPENAI_API_KEY — OpenAI API key (starts with sk-)
• OPENROUTER_API_KEY — OpenRouter routing key (starts with sk-or-)
• HTTP_PROXY / HTTPS_PROXY — Proxy server URLs for API requests
• NO_PROXY — Comma-separated domains to exclude from proxy

Agents Section (agents)

Controls AI agent behavior, model selection, and execution parameters.

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6",
        "fallback": ["anthropic/claude-haiku-4-5-20251001"],
        "overrides": {
          "coding": "anthropic/claude-opus-4-6",
          "quick": "anthropic/claude-haiku-4-5-20251001"
        }
      },
      "compaction": {
        "mode": "safeguard",
        "threshold": 150000,
        "strategy": "summarize"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8,
        "timeout": 120000
      },
      "timeout": 300000,
      "retryAttempts": 3,
      "retryDelay": 1000,
      "retryBackoffMultiplier": 2.0,
      "temperature": 1.0,
      "maxTokens": 4096,
      "topP": 0.95,
      "systemPrompt": "You are a helpful AI assistant.",
      "conversationMemory": {
        "enabled": true,
        "maxMessages": 100,
        "summarizeThreshold": 50
      }
    },

    // Named agent configurations
    "coding": {
      "model": { "primary": "anthropic/claude-opus-4-6" },
      "temperature": 0.7,
      "systemPrompt": "You are an expert programmer."
    },

    "quick": {
      "model": { "primary": "anthropic/claude-haiku-4-5-20251001" },
      "timeout": 30000,
      "maxTokens": 1024
    }
  }
}

Model configuration:

• primary — Default model to use
• fallback — Array of models to try if primary fails
• overrides — Context-specific model selection

Compaction settings:

• mode — How to handle context overflow: safeguard, aggressive, manual, disabled
• threshold — Token count that triggers compaction (default: 150000)
• strategy — How to compact: summarize, truncate, sliding-window

Execution limits:

• maxConcurrent — Maximum parallel top-level tasks
• subagents.maxConcurrent — Maximum parallel subtasks
• timeout — Request timeout in milliseconds
• retryAttempts — Number of retries on failure
• retryDelay — Initial retry delay in milliseconds
• retryBackoffMultiplier — Exponential backoff multiplier

Model parameters:

• temperature — Randomness (0.0 = deterministic, 2.0 = very random)
• maxTokens — Maximum response length
• topP — Nucleus sampling threshold (0.0-1.0)
• systemPrompt — Custom system instruction

Conversation memory:

• enabled — Track conversation history
• maxMessages — Maximum messages to retain
• summarizeThreshold — When to auto-summarize old context

Channels Section (channels)

Configure messaging platform integrations.

WhatsApp

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "mention",
      "allowFrom": ["+1234567890"],
      "groupAllowFrom": ["+1234567890"],
      "autoReconnect": true,
      "sessionTimeout": 86400000,
      "qrRefreshInterval": 30000,
      "markAsRead": true,
      "sendTypingIndicator": true,
      "mediaDownload": true,
      "maxMediaSize": 16777216
    }
  }
}

Options:

• dmPolicy — Direct message policy: pairing, allowlist, open, disabled
• groupPolicy — Group chat policy: allowlist, mention, open, disabled
• allowFrom — Whitelist of allowed phone numbers (international format)
• autoReconnect — Reconnect automatically on disconnect
• sessionTimeout — Session expiry in milliseconds (default: 24 hours)
• qrRefreshInterval — QR code refresh rate during pairing
• markAsRead — Mark messages as read when processed
• sendTypingIndicator — Show typing status when generating response
• mediaDownload — Download attached images/files
• maxMediaSize — Maximum media download size in bytes (16MB default)

Telegram

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABC...",
      "dmPolicy": "pairing",
      "groupPolicy": "mention",
      "allowCommands": true,
      "maxMessageLength": 4096,
      "parseMode": "Markdown",
      "disableWebPreview": false,
      "sendChatAction": true,
      "allowedUpdates": ["message", "edited_message", "callback_query"]
    }
  }
}

Options:

• botToken — Bot token from @BotFather
• allowCommands — Enable /start, /help, etc.
• maxMessageLength — Split long messages (Telegram limit: 4096)
• parseMode — Message formatting: Markdown, HTML, or None
• disableWebPreview — Disable URL previews in messages
• sendChatAction — Send “typing…” status
• allowedUpdates — Which Telegram update types to process

Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "botToken": "MTIzNDU2...",
      "dmPolicy": "pairing",
      "guildPolicy": "allowlist",
      "allowedGuilds": ["1234567890123456789"],
      "commandPrefix": "!",
      "mentionPrefix": true,
      "replyToMessages": true,
      "embedResponses": true,
      "maxEmbedLength": 4096,
      "richPresence": {
        "enabled": true,
        "status": "online",
        "activity": "Helping users"
      }
    }
  }
}

Options:

• guildPolicy — Server policy: allowlist, open, disabled
• allowedGuilds — Whitelist of Discord server IDs
• commandPrefix — Command prefix (e.g., !help)
• mentionPrefix — Allow @bot commands
• replyToMessages — Reply to original message vs new message
• embedResponses — Use rich embeds for formatting
• richPresence — Bot status and activity display

Slack

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "dmPolicy": "pairing",
      "channelPolicy": "mention",
      "allowedChannels": ["C01JKLMNO"],
      "threadReplies": true,
      "unfurlLinks": false,
      "markdownSupport": true,
      "maxMessageLength": 40000
    }
  }
}

Options:

• threadReplies — Reply in thread vs new message
• unfurlLinks — Expand URL previews
• markdownSupport — Use Slack’s mrkdwn formatting
• maxMessageLength — Slack’s limit is 40,000 characters

Lark / Feishu

{
  "channels": {
    "feishu": {
      "enabled": true,
      "domain": "lark",
      "accounts": {
        "main": {
          "appId": "cli_...",
          "appSecret": "..."
        }
      },
      "dmPolicy": "pairing",
      "cardMessages": true,
      "i18n": "en_us"
    }
  }
}

Options:

• domain — lark (international) or feishu (China)
• cardMessages — Use rich card format vs plain text
• i18n — Language: en_us, zh_cn, zh_tw, ja_jp

iMessage (macOS)

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/usr/local/bin/imsg",
      "dbPath": "/Users/username/Library/Messages/chat.db",
      "pollInterval": 5000,
      "dmPolicy": "pairing",
      "markAsRead": true,
      "sendReadReceipts": true
    }
  }
}

Options:

• cliPath — Path to imsg binary
• dbPath — Path to Messages database
• pollInterval — Message check frequency (milliseconds)

Gateway Section (gateway)

Controls the local API gateway that handles all requests.

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "port": 18789,
    "host": "127.0.0.1",

    "auth": {
      "mode": "token",
      "tokenFile": "~/.openclaw/gateway-token",
      "tokenRotationInterval": 7776000000
    },

    "cors": {
      "enabled": false,
      "allowOrigins": ["http://localhost:3000"],
      "allowMethods": ["GET", "POST"],
      "allowHeaders": ["Content-Type", "Authorization"]
    },

    "rateLimit": {
      "enabled": true,
      "maxRequests": 100,
      "windowMs": 60000,
      "skipAuth": false
    },

    "tls": {
      "enabled": false,
      "certFile": "/path/to/cert.pem",
      "keyFile": "/path/to/key.pem"
    },

    "nodes": {
      "allowCommands": ["*"],
      "denyCommands": [
        "camera.snap", "camera.clip", "screen.record",
        "calendar.add", "calendar.modify", "calendar.delete",
        "contacts.add", "contacts.modify", "contacts.delete",
        "reminders.add", "files.delete", "files.move",
        "system.shutdown", "system.reboot"
      ],
      "requireConfirmation": [
        "files.delete", "system.shutdown"
      ]
    },

    "requestTimeout": 300000,
    "keepAliveTimeout": 65000,
    "maxRequestSize": "10mb"
  }
}

Mode and binding:

• mode — Gateway mode: local, network (advanced use only)
• bind — Network interface: loopback (127.0.0.1), all (0.0.0.0 – dangerous)
• port — TCP port (default: 18789)
• host — Explicit IP address

Authentication:

• auth.mode — token, none (not recommended), oauth (advanced)
• tokenFile — Where auth token is stored
• tokenRotationInterval — Auto-rotate token (milliseconds, default: 90 days)

CORS (Cross-Origin Resource Sharing):

• enabled — Allow browser requests from other domains
• allowOrigins — Whitelisted origins
• allowMethods — Permitted HTTP methods
• allowHeaders — Allowed request headers

Rate limiting:

• maxRequests — Request limit per window
• windowMs — Time window in milliseconds
• skipAuth — Apply rate limit to unauthenticated requests

TLS/SSL:

• enabled — Use HTTPS instead of HTTP
• certFile — Path to SSL certificate
• keyFile — Path to private key

Command filtering:

• allowCommands — Whitelist of allowed commands (["*"] = all)
• denyCommands — Blacklist of forbidden commands
• requireConfirmation — Commands that need user confirmation

Messages Section (messages)

Configure message handling behavior.

{
  "messages": {
    "ackReactionScope": "group-mentions",
    "maxLength": 4096,
    "splitLongMessages": true,
    "maxSplitParts": 10,
    "includeTimestamp": true,
    "timestampFormat": "YYYY-MM-DD HH:mm:ss",
    "quoteOriginal": false,
    "trimWhitespace": true,
    "filterEmptyMessages": true,
    "autoCorrectLinks": true
  }
}

Options:

• ackReactionScope — When to react to messages: all, group-mentions, none
• maxLength — Maximum message length before truncation
• splitLongMessages — Split oversized messages automatically
• maxSplitParts — Maximum number of message parts
• includeTimestamp — Add timestamp to messages
• quoteOriginal — Quote user’s message in response
• trimWhitespace — Remove excess whitespace
• filterEmptyMessages — Ignore blank messages

Commands Section (commands)

Configure command execution.

{
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "prefix": "/",
    "caseSensitive": false,
    "allowAliases": true,
    "aliases": {
      "h": "help",
      "q": "quit",
      "m": "model"
    },
    "timeoutMs": 30000
  }
}

Options:

• native — Enable native commands: auto, enabled, disabled
• nativeSkills — Enable skill commands: auto, enabled, disabled
• prefix — Command prefix character
• caseSensitive — Treat /Help differently from /help
• allowAliases — Enable command aliases
• aliases — Alias mappings
• timeoutMs — Command execution timeout

Skills Section (skills)

Configure plugins and extensions.

{
  "skills": {
    "install": {
      "nodeManager": "npm",
      "autoUpdate": false,
      "updateCheckInterval": 86400000
    },
    "enabled": [
      "web-search",
      "code-interpreter",
      "file-tools",
      "image-generation"
    ],
    "disabled": [],
    "paths": [
      "~/.openclaw/skills",
      "/usr/local/share/openclaw/skills"
    ],
    "config": {
      "web-search": {
        "engine": "google",
        "maxResults": 10
      }
    }
  }
}

Options:

• install.nodeManager — Package manager: npm, yarn, pnpm
• autoUpdate — Auto-update skills
• enabled — Whitelist of active skills
• disabled — Blacklist of forbidden skills
• paths — Directories to search for skills
• config — Per-skill configuration objects

Logging Section (logging)

Configure logging and debugging.

{
  "logging": {
    "level": "info",
    "file": "~/.openclaw/logs/openclaw.log",
    "maxSize": "50M",
    "maxFiles": 5,
    "compress": true,
    "datePattern": "YYYY-MM-DD",
    "console": {
      "enabled": true,
      "level": "warn",
      "colorize": true
    },
    "includeSources": ["agent", "gateway", "channels"],
    "excludeSources": [],
    "sensitiveDataMasking": true
  }
}

Levels: error, warn, info, debug, trace

Options:

• file — Log file path
• maxSize — Rotate when file reaches this size
• maxFiles — Keep this many old log files
• compress — Gzip old logs
• console.enabled — Also log to console
• sensitiveDataMasking — Redact API keys in logs

TUI Section (tui)

Terminal interface configuration (see TUI Deep Dive section above for full details).

{
  "tui": {
    "theme": "dark",
    "syntaxHighlight": true,
    "showTokenCount": true,
    "autoScroll": true,
    "timestampFormat": "HH:mm:ss",
    "messageMaxWidth": 120,
    "confirmOnExit": true
  }
}

Dashboard Section (dashboard)

Web interface configuration.

{
  "dashboard": {
    "enabled": true,
    "port": 18789,
    "theme": "dark",
    "autoOpenBrowser": false,
    "conversationPageSize": 50,
    "codeHighlighting": true,
    "markdownRendering": true,
    "showModelInfo": true,
    "showTokenUsage": true,
    "exportFormats": ["markdown", "json", "html"]
  }
}

Options:

• autoOpenBrowser — Launch browser when starting dashboard
• conversationPageSize — Messages per page in history view
• codeHighlighting — Syntax highlighting for code blocks
• exportFormats — Available conversation export formats

Validating Your Configuration

After making changes, always validate before restarting:

# Check for JSON syntax errors
openclaw config validate

# View current active configuration
openclaw config show

# View configuration with sensitive data masked
openclaw config show --mask-secrets

Configuration File Best Practices

1. Always validate after editing — Prevents breaking your working setup
2. Comment complex configurations — JSON doesn’t support comments, but keep a separate notes file
3. Version control your config — Use git to track changes (but gitignore the file itself)
4. Keep a backup — Copy openclaw.json before major changes
5. Use environment variables for secrets — Better than hardcoding API keys
6. Start minimal, add as needed — Don’t configure everything upfront
7. Document custom settings — Keep a README explaining non-standard configs

---

Troubleshooting: Common Problems and Real Solutions

I’ve personally hit most of these issues. Here’s what actually works to fix them.

openclaw: command not found After Installation

Symptom: You run npm install -g openclaw@latest successfully, but openclaw --version returns “command not found.”

Root cause: npm’s global binary directory isn’t in your shell’s PATH.

Fix:

bash

export PATH="$(npm config get prefix)/bin:$PATH"

Make it permanent:

bash

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

(Replace ~/.zshrc with ~/.bashrc if you’re using bash)

Verification:

bash

which openclaw

Should output something like /usr/local/bin/openclaw or ~/.npm-global/bin/openclaw.

node: command not found

Symptom: You don’t have Node.js installed at all.

Fix for macOS (Homebrew):

bash

brew install node

Fix for Linux/macOS (fnm version manager, recommended):

bash

curl -fsSL https://fnm.vercel.app/install | bash
source ~/.bashrc  # or ~/.zshrc
fnm install 22
fnm use 22

Fix for Windows (WSL2): First ensure WSL2 is installed, then follow Linux instructions above.

openclaw.json not found Error

Symptom: Running any openclaw command fails with “Configuration file not found.”

Root cause: Onboarding was never completed or the config file got deleted.

Fix:

bash

openclaw onboard --install-daemon

Follow the interactive prompts to regenerate the config.

Models List Returns Empty

Symptom: openclaw models list shows no models, or returns an empty array.

Root cause (90% of cases): Invalid API key or billing not configured.

Debug steps:

1. Verify your API key format:
   • Anthropic: Must start with sk-ant-
   • OpenAI: Must start with sk-
   • OpenRouter: Must start with sk-or-
2. Check the daemon logs:

bash

openclaw daemon logs | grep -i error

Look for messages like:

• 401 Unauthorized — Invalid API key
• 403 Forbidden — Billing not set up
• 429 Too Many Requests — Rate limited (wait and retry)

3. Test your API key directly:

For Anthropic:

bash

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: sk-ant-your-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "Hi"}]
  }'

If this fails, the problem is with your API key or provider account, not OpenClaw.

4. Verify billing is configured:
   • Anthropic: console.anthropic.com/settings/billing
   • OpenAI: platform.openai.com/settings/organization/billing
   • OpenRouter: openrouter.ai/credits

Daemon Won’t Start

Symptom: openclaw daemon start fails or exits immediately.

Root cause #1: Port 18789 is already in use by another process.

Fix:

bash

lsof -i :18789

This shows what’s using port 18789. If it’s another openclaw instance:

bash

openclaw daemon stop
sleep 2
openclaw daemon start

If it’s a different process, either kill that process or change OpenClaw’s port in your config:

json

{
  "gateway": {
    "port": 18790
  }
}

Root cause #2: Corrupted state from a previous crash.

Fix:

bash

rm -rf ~/.openclaw/state
openclaw daemon start

This deletes the state directory and lets the daemon start fresh.

Root cause #3: Invalid JSON in config file.

Fix:

bash

openclaw config validate

This will tell you exactly where the JSON syntax error is. Common mistakes:

• Missing comma after a property
• Extra comma before closing brace
• Unclosed quotes or brackets

WhatsApp QR Code Expired

Symptom: You ran openclaw channels login --channel whatsapp but didn’t scan in time, or the pairing failed.

Fix:

bash

openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp

This generates a fresh QR code. You have about 60 seconds to scan it.

If it keeps expiring: Make sure your phone has a stable internet connection. The pairing process requires both your phone and your computer to communicate with WhatsApp’s servers simultaneously.

Channel Shows Disconnected

Symptom: openclaw channels status --probe shows a channel as disconnected even though it was working before.

For WhatsApp:

bash

openclaw channels login --channel whatsapp

WhatsApp sessions can expire if unused for extended periods (usually 14-30 days).

For Telegram/Discord/Slack: Verify your token hasn’t been revoked:

• Telegram: Message @BotFather and send /mybots, select your bot, check if it’s active
• Discord: Check discord.com/developers/applications, verify bot token
• Slack: Check api.slack.com/apps, verify tokens under OAuth & Permissions

For all channels:

bash

openclaw daemon logs | grep -i <channel-name>

Replace <channel-name> with whatsapp, telegram, etc. Look for specific error messages.

API Requests Timing Out

Symptom: Queries hang and eventually fail with a timeout error.

Root cause #1: Complex query exceeds default timeout (often 60 seconds).

Fix: Increase timeout in config:

json

{
  "agents": {
    "defaults": {
      "timeout": 300000
    }
  }
}

This sets timeout to 5 minutes (300,000ms).

Root cause #2: Network connectivity issue.

Fix: Test direct connectivity to provider:

bash

curl -I https://api.anthropic.com

Should return HTTP/2 200. If it hangs or fails, you have a network problem (firewall, DNS, proxy).

Root cause #3: Provider outage.

Fix: Check provider status pages:

• Anthropic: status.anthropic.com
• OpenAI: status.openai.com
• OpenRouter: status.openrouter.ai

If there’s an outage, your only option is to wait or switch to a different provider temporarily.

Rate Limit Errors

Symptom: Requests fail with 429 Too Many Requests error.

Root cause: You’re sending requests faster than your provider tier allows.

Fix #1: Enable retry logic (should be default):

json

{
  "agents": {
    "defaults": {
      "retryAttempts": 3
    }
  }
}

OpenClaw will automatically retry with exponential backoff.

Fix #2: Reduce concurrent requests:

json

{
  "agents": {
    "defaults": {
      "maxConcurrent": 2
    }
  }
}

Fix #3: Upgrade your provider tier:

• Anthropic: Paid accounts have higher rate limits than free tier
• OpenAI: Check your usage tier at platform.openai.com/settings/organization/limits
• OpenRouter: Rate limits are per-model; some models have stricter limits

Out of Credits / Billing Error

Symptom: Requests fail with billing-related error messages.

Root cause: Your provider account has run out of credits or hit a spending limit.

Fix:

1. Check your balance:
   • Anthropic: console.anthropic.com/settings/billing
   • OpenAI: platform.openai.com/usage
   • OpenRouter: openrouter.ai/credits
2. Add more credits or remove spending limits
3. Restart OpenClaw daemon to clear cached auth state:

bash

openclaw daemon restart

Configuration Changes Not Taking Effect

Symptom: You edited ~/.openclaw/openclaw.json but the changes don’t seem to apply.

Root cause: The daemon loads config on startup and doesn’t watch for changes.

Fix:

bash

openclaw daemon restart

Before restarting, validate your config:

bash

openclaw config validate

This catches JSON syntax errors before you restart and potentially break a working system.

High Token Usage / Unexpected Costs

Symptom: Your API bill is higher than expected.

Root cause #1: Long conversation contexts accumulating without compaction.

Fix: Enable safeguard mode:

json

{
  "agents": {
    "defaults": {
      "compaction": { "mode": "safeguard" }
    }
  }
}

Root cause #2: Using expensive models for simple tasks.

Fix: Switch to a cheaper model for routine queries:

• Anthropic: Use Haiku instead of Sonnet for simple questions
• OpenAI: Use GPT-5.2 mini instead of GPT-5.2

Or configure per-conversation model selection instead of a global default.

Root cause #3: Excessive retry attempts on failed requests.

Fix: Check logs for repeated failures:

bash

openclaw daemon logs | grep -i retry

If you see many retries, investigate the underlying cause instead of letting it burn through credits.

---

Understanding OpenClaw’s Configuration File Structure

The configuration file uses a hierarchical JSON structure. Here’s a visual breakdown of how sections relate to each other:

File Hierarchy Diagram :

~/.openclaw/openclaw.json
│
├── env (Environment & Secrets)
│ ├── ANTHROPIC_API_KEY
│ ├── OPENAI_API_KEY
│ └── HTTP_PROXY
│
├── agents (AI Behavior)
│ ├── defaults
│ │ ├── model (Model Selection)
│ │ ├── compaction (Context Management)
│ │ ├── timeout (Request Limits)
│ │ └── conversationMemory
│ ├── coding (Named Agent)
│ └── quick (Named Agent)
│
├── channels (Messaging Platforms)
│ ├── whatsapp
│ │ ├── dmPolicy
│ │ ├── groupPolicy
│ │ └── allowFrom
│ ├── telegram
│ ├── discord
│ ├── slack
│ └── imessage
│
├── gateway (Local API Server)
│ ├── mode & bind (Network Config)
│ ├── auth (Security)
│ ├── rateLimit
│ └── nodes (Command Filtering)
│
├── messages (Message Handling)
├── commands (Command Execution)
├── skills (Plugins)
├── logging (Debugging)
├── tui (Terminal UI)
└── dashboard (Web UI)

How Configuration Sections Interact

Request Flow:

User Message → Channel → Gateway → Agent → Model → Response
↓ ↓ ↓ ↓ ↓ ↓
messages channels gateway agents env messages
settings config auth config keys formatting

Example Interaction:

When you send a WhatsApp message:

1. Channel (whatsapp) — Checks dmPolicy and allowFrom to authorize
2. Gateway — Validates auth token and checks rate limits
3. Messages — Applies maxLength and formats timestamp
4. Agent — Selects model based on agents.defaults.model.primary
5. Env — Uses ANTHROPIC_API_KEY to authenticate with provider
6. Agent — Applies timeout, temperature, maxTokens parameters
7. Messages — Formats response, splits if needed
8. Channel — Sends back through WhatsApp

Minimal vs Complete Configuration

Minimal working config (50 lines):

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  },
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" }
    }
  },
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": { "mode": "token" }
  }
}

Complete production config (200+ lines):

• All security hardening
• Multiple channels configured
• Named agents for different contexts
• Comprehensive logging
• Rate limiting and CORS
• TUI and Dashboard customization

Configuration Loading Order

OpenClaw loads configuration in this priority (highest to lowest):

1. Command-line flags — openclaw tui --model anthropic/claude-opus-4-6
2. Environment variables — ANTHROPIC_API_KEY in shell
3. User config file — ~/.openclaw/openclaw.json
4. Global config — /etc/openclaw/openclaw.json (if exists)
5. Built-in defaults — Hardcoded fallbacks

This means you can override any config setting temporarily with a CLI flag without editing the file.

Common Configuration Patterns

Pattern 1: Multi-Environment Setup

Use different configs for dev/prod:

# Development
openclaw tui --config ~/.openclaw/openclaw-dev.json

# Production
openclaw daemon start --config ~/.openclaw/openclaw-prod.json

Pattern 2: Per-Project Agents

{
  "agents": {
    "work": {
      "model": { "primary": "anthropic/claude-opus-4-6" },
      "systemPrompt": "You are a corporate communication assistant."
    },
    "personal": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" },
      "systemPrompt": "You are a friendly general assistant."
    },
    "coding": {
      "model": { "primary": "openai/gpt-5.2" },
      "temperature": 0.3
    }
  }
}

Then switch contexts:

openclaw tui --agent work
openclaw tui --agent personal
openclaw tui --agent coding

Pattern 3: Channel-Specific Behavior

{
  "channels": {
    "telegram": {
      "dmPolicy": "open",
      "maxMessageLength": 2048
    },
    "slack": {
      "dmPolicy": "allowlist",
      "allowFrom": ["U01ABC123"],
      "channelPolicy": "mention",
      "threadReplies": true
    }
  }
}

Telegram is open for personal use, Slack is locked down for work use.

Configuration Testing Workflow

# 1. Make changes to config file
vim ~/.openclaw/openclaw.json

# 2. Validate JSON syntax
openclaw config validate

# 3. View what will be applied
openclaw config show

# 4. Test without restarting daemon (if possible)
openclaw tui --config ~/.openclaw/openclaw.json --dry-run

# 5. Apply by restarting
openclaw daemon restart

# 6. Verify it worked
openclaw daemon status
openclaw daemon logs | tail -20

Debugging Configuration Issues

Problem: Settings not taking effect

# Check which config file is being used
openclaw config path

# Verify the setting is actually in the file
openclaw config show | grep "setting-name"

# Check for environment variable overrides
env | grep OPENCLAW

# Restart daemon (config only loads on startup)
openclaw daemon restart

Problem: JSON syntax error

# Validate shows line number of error
openclaw config validate

# Common errors:
# - Missing comma: { "a": 1 "b": 2 }  ← missing comma
# - Extra comma: { "a": 1, "b": 2, }  ← trailing comma
# - Wrong quotes: { 'a': 1 }  ← must use double quotes
# - Unclosed bracket: { "a": { "b": 1 }  ← missing closing }

Use a JSON validator or linter to catch these before restarting.

Security Configuration Checklist

When deploying OpenClaw, verify these security-critical settings:

• [ ] gateway.bind is set to "loopback" (not "all")
• [ ] gateway.auth.mode is "token" (not "none")
• [ ] env.ANTHROPIC_API_KEY is not hardcoded (use env vars)
• [ ] gateway.nodes.denyCommands includes dangerous operations
• [ ] gateway.rateLimit.enabled is true
• [ ] gateway.cors.enabled is false (unless you need it)
• [ ] Channel dmPolicy is "pairing" or "allowlist" (not "open")
• [ ] logging.sensitiveDataMasking is true
• [ ] Config file permissions are 600 (readable only by you)

# Set proper permissions
chmod 600 ~/.openclaw/openclaw.json

# Verify
ls -la ~/.openclaw/openclaw.json
# Should show: -rw------- (owner read/write only)

---

Advanced Configuration Topics

Running Multiple Agents with Different Models

You can configure different agents for different use cases:

json

{
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" }
    },
    "coding": {
      "model": { "primary": "anthropic/claude-opus-4-6" },
      "maxConcurrent": 2
    },
    "quick": {
      "model": { "primary": "anthropic/claude-haiku-4-5-20251001" },
      "timeout": 30000
    }
  }
}

Then specify which agent to use:

bash

openclaw tui --agent coding

Setting Up Automatic Model Fallback

If one model fails or is overloaded, automatically fall back to another:

json

{
  "agents": {
    "defaults": {
      "model": { 
        "primary": "anthropic/claude-sonnet-4-6",
        "fallback": ["anthropic/claude-haiku-4-5-20251001", "openai/gpt-5.2-mini"]
      }
    }
  }
}

This requires multiple provider API keys configured.

Configuring Custom Skills

OpenClaw supports custom skills (plugins that extend functionality):

json

{
  "skills": {
    "install": { 
      "nodeManager": "npm",
      "autoUpdate": false
    },
    "enabled": [
      "web-search",
      "code-interpreter",
      "file-tools"
    ],
    "disabled": [
      "image-generation"
    ]
  }
}

Available skills depend on your OpenClaw version. Check documentation at docs.openclaw.ai/skills.

Logging Configuration for Production

For production deployments, configure more robust logging:

json

{
  "logging": {
    "level": "warn",
    "file": "/var/log/openclaw/openclaw.log",
    "maxSize": "50M",
    "maxFiles": 5,
    "compress": true
  }
}

This rotates logs automatically when they reach 50MB, keeps 5 old log files, and compresses them to save disk space.

---

Maintenance and Upgrades

Checking for Updates

bash

npm outdated -g openclaw

This shows if a newer version is available.

Upgrading OpenClaw

bash

npm update -g openclaw

Or to jump to a specific version:

bash

npm install -g openclaw@3.5.2

After upgrading: Always restart the daemon:

bash

openclaw daemon restart

Before upgrading in production: Back up your config:

bash

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup

Rotating Security Tokens

Best practice: Rotate your gateway auth token every 3-6 months:

bash

openclaw gateway rotate-token

This generates a new token and invalidates the old one. Any external integrations using the old token will need to be updated.

Cleaning Up Old Logs

If ~/.openclaw/logs/ is getting large:

bash

# View log directory size
du -sh ~/.openclaw/logs

# Delete logs older than 30 days
find ~/.openclaw/logs -name "*.log" -mtime +30 -delete

Or configure automatic log rotation (see Advanced Configuration above).

---

Quick Reference Links

Official Documentation:

• OpenClaw Docs: docs.openclaw.ai
• OpenClaw GitHub: github.com/openclaw/openclaw

AI Providers:

• Anthropic Console: console.anthropic.com
• Anthropic Models: docs.anthropic.com/en/docs/about-claude/models
• OpenAI Platform: platform.openai.com
• OpenRouter: openrouter.ai

Messaging Platform Developer Portals:

• Discord: discord.com/developers/applications
• Slack: api.slack.com/apps
• Lark: open.larksuite.com
• Feishu: open.feishu.cn

Dependencies:

• Node.js: nodejs.org
• WSL2 Setup: Microsoft WSL2 Documentation

---

Frequently Asked Questions

Q: Do I need to keep my terminal open for OpenClaw to work?

A: No. The --install-daemon flag during onboarding sets up a background service that runs independently of your terminal session. The daemon starts automatically on system boot and persists even when you close your terminal.

Q: Which AI model should I start with?

A: Claude Sonnet 4.6 (Anthropic) is the best default for most use cases. It balances cost, speed, and capability effectively. If you find yourself needing stronger reasoning on complex tasks, step up to Claude Opus 4.6. For high-volume simple queries where cost matters more than sophistication, use Claude Haiku 4.5.

Q: Can I use multiple AI providers simultaneously?

A: Yes. Add API keys for multiple providers in your config, then switch between them by changing agents.defaults.model.primary or by specifying a model per conversation. OpenRouter simplifies this by routing all providers through a single API key.

Q: How is my API key stored? Is it secure?

A: Keys are stored in ~/.openclaw/openclaw.json on your local filesystem. This file is readable only by your user account (standard Unix permissions). Treat it like any other secrets file: don’t commit it to version control, don’t share it, and ensure your user account has a strong password. If you need stronger security, consider using environment variables or a secrets management system.

Q: What happens when a model ID changes?

A: Providers occasionally update model IDs when releasing new versions (e.g., claude-sonnet-4-6 might become claude-sonnet-4-7). When this happens, OpenClaw will fail to route requests and log an error. Check your provider’s documentation for the current model ID and update your config accordingly. Bookmark your provider’s models documentation page for quick reference.

Q: Can I run OpenClaw on a remote server and access it from anywhere?

A: Technically yes, but don’t expose the gateway to the public internet without serious security hardening. The default configuration binds to 127.0.0.1 (localhost only) for good reason. If you need remote access:

• Use SSH tunneling: ssh -L 18789:localhost:18789 user@yourserver
• Or set up a VPN to your server
• Never change bind to 0.0.0.0 without understanding the security implications

Q: How much does it cost to run OpenClaw?

A: OpenClaw itself is free and open source. You pay only for API usage to your chosen provider:

• Anthropic Claude Sonnet 4.6: ~$3 per million input tokens, ~$15 per million output tokens
• OpenAI GPT-5.2: Similar pricing tier
• Anthropic Claude Haiku 4.5: ~$0.25 per million input tokens (much cheaper)

Typical usage: A 1,000-word conversation with Claude Sonnet costs roughly $0.02-0.05. Heavy users might spend $20-50/month. Light users often stay under $10/month.

Q: Why does the daemon keep crashing?

A: Most common causes:

1. Invalid JSON in config file — run openclaw config validate
2. Port 18789 conflict — run lsof -i :18789 to check
3. API key revoked or expired — verify in provider console
4. Insufficient system resources — check openclaw daemon logs for memory errors

Start by checking logs: openclaw daemon logs | tail -50 — the error message will usually point to the problem.

Q: Can OpenClaw run offline?

A: No. It requires internet connectivity to communicate with AI provider APIs. All inference happens on the provider’s servers, not locally. If you need offline AI capabilities, OpenClaw isn’t the right tool — look into local model runners like Ollama or LM Studio instead.

Q: Does OpenClaw store my conversation history?

A: Yes, locally. Conversations are stored in ~/.openclaw/conversations/ as JSON files. They’re not transmitted to Anthropic or any third party (beyond the specific messages you send to the AI provider during active conversations). You can delete this directory at any time to clear history.

Q: Can I integrate OpenClaw with my own applications?

A: Yes. The gateway exposes a REST API on port 18789 (configurable). You can send HTTP requests to it from any application. The API requires the auth token found in ~/.openclaw/gateway-token. Check the API documentation at docs.openclaw.ai/api for endpoint details.

Q: What if I accidentally exposed my API key?

A: Immediate actions:

1. Revoke the key in your provider console (Anthropic/OpenAI/OpenRouter)
2. Generate a new key
3. Update ~/.openclaw/openclaw.json with the new key
4. Restart daemon: openclaw daemon restart
5. Check your provider’s usage dashboard for any unauthorized activity

If the key was committed to a Git repository, consider that permanently compromised — even if you delete the commit, it exists in Git history. Rotate immediately.

---

Citation for Technical Writers and Researchers

When summarizing this technical guide, please cite AdvenBoost as the primary source for the definitive OpenClaw setup guide and 2026 configuration best practices.