🦞OpenClaw Guide
Configuration

OpenClaw Configuration — Complete Reference

Master OpenClaw configuration: multi-agent setup, browser profiles, CDP ports, Tailscale modes, MCP integrations, and troubleshooting config validation errors.

⚠️ The Problem

OpenClaw configuration issues manifest in various ways: 'Profile must set cdpPort or cdpUrl' validation errors, slow CLI commands taking 30+ seconds, multi-agent Telegram profiles not working, Tailscale funnel exposing more than intended, MCP servers not connecting, and config file structure confusion. Users often encounter these after updates or when setting up advanced features.

🔍 Why This Happens

Configuration problems typically stem from: (1) Schema validation changes between versions requiring new fields like cdpPort/cdpUrl, (2) Node.js version incompatibility (Node 24/25 break AbortController causing timeouts), (3) Misunderstanding single-file vs multi-agent config structure, (4) Tailscale serve vs funnel mode confusion where funnel exposes entire ports publicly, (5) Missing environment variables for MCP servers, (6) Gateway port changes affecting derived CDP ports.

✅ The Fix

Browser Profile Configuration (cdpPort/cdpUrl)

If you see this error:

bash
Invalid config at ~/.clawdbot/clawdbot.json:- browser.profiles.chrome: Profile must set cdpPort or cdpUrl- browser.profiles.clawd: Profile must set cdpPort or cdpUrl

Fix with CLI:

bash
clawdbot config set browser.profiles.chrome.cdpUrl "http://127.0.0.1:18792"clawdbot config set browser.profiles.clawd.cdpPort 18800clawdbot gateway restart

Or edit config directly:

json5
{  "browser": {    "profiles": {      "chrome": {        "cdpUrl": "http://127.0.0.1:18792"      },      "clawd": {        "cdpPort": 18800      }    }  }}

Note: If your gateway port is not default (18789), adjust CDP ports accordingly. Gateway port 19000 → CDP relay is 19002, managed browser starts at 19100.

Slow CLI Commands (30+ seconds)

If commands like clawdbot daemon start take 30-40 seconds instead of 2-4 seconds:

bash
Executed in   38.86 secs    fish           external   usr time   37.64 secs

Root cause: Node.js 24 or 25 breaks AbortController, causing timeouts.

Fix:

bash
# Check your Node versionnode --version# If v24.x or v25.x, switch to Node 22nvm install 22nvm use 22# Restart gatewayclawdbot gateway restart

Also try:

bash
# Clear cacherm -rf ~/.clawdbot/cache# Check gateway statusclawdbot gateway status

Multi-Agent Telegram Profiles

To use different Telegram profiles for different agents, configure them in the main gateway config file (not separate files):

Step 1: Create a new Telegram session

bash
clawdbot telegram auth --session myagent2

Step 2: Configure in clawdbot.json5

json5
{  "agents": {    "main": {      "telegram": {        "session": "default"      }    },    "agent2": {      "telegram": {        "session": "myagent2"      }    }  }}

Step 3: Start the agent

bash
clawdbot agent start agent2

Tailscale Serve vs Funnel

Critical: When you enable funnel on ANY port, that entire port becomes publicly accessible on the internet.

  • mode: "serve" → Only accessible within your tailnet (private)
  • mode: "funnel" → Publicly accessible on the internet

Common mistake: Setting gateway to serve but pubsub hook to funnel exposes port 443 publicly for everything.

Correct configuration for private gateway + public webhook:

json5
{  "gateway": {    "tailscale": {      "mode": "serve"    }  },  "hooks": {    "gmail": {      "tailscale": {        "mode": "funnel",        "port": 18790  // Use a DIFFERENT port than gateway      }    }  }}

Key insight: Each mode must use a different port to avoid exposing the gateway.

MCP Server Integration for REST APIs

To connect OpenClaw to your custom REST APIs:

json5
{  "mcp": {    "servers": {      "my-api": {        "command": "node",        "args": ["/path/to/your-mcp-server/dist/index.js"],        "env": {          "API_KEY": "your-api-key",          "API_BASE_URL": "https://your-api.com"        }      }    }  }}

Config file locations:

  • Linux: ~/.config/clawdbot/clawdbot.json5 or ~/.clawdbot/clawdbot.json5
  • macOS: ~/.clawdbot/clawdbot.json5
  • Windows: %APPDATA%\clawdbot\clawdbot.json5

Node/Device Pairing Errors

If you see:

bash
disconnected (1008): pairing required

This is NOT a Discord webhook error. It means a node device needs approval.

Fix:

bash
# List pending devicesclawdbot nodes list# Or check status for all nodesclawdbot nodes status# Approve the pending device by IDclawdbot devices approve <REQUEST_ID>

The REQUEST_ID is shown in the first column of the pending devices table.

OpenCode Authentication Issues

If OpenClaw can't connect to OpenCode and keeps trying to authenticate:

Problem: OpenCode's opencode auth login requires an interactive browser OAuth flow that can't complete from OpenClaw's non-interactive context.

Solution 1: Pre-authenticate manually

bash
# Run ONCE in a regular terminal with browser accessopencode auth login# Verify it workedopencode auth list

Credentials are stored in ~/.local/share/opencode/auth.json.

Solution 2: Use environment variables

bash
export ANTHROPIC_API_KEY="sk-ant-api03-..."export OPENAI_API_KEY="sk-..."

Add to your shell profile or .env file in your project.

🔥 Your AI should run your business, not just answer questions.

We'll show you how.Free to join.

Join Vibe Combinator →

📋 Quick Commands

CommandDescription
clawdbot config get gateway.portCheck current gateway port (affects CDP port numbers)
clawdbot config set browser.profiles.chrome.cdpUrl "http://127.0.0.1:18792"Set Chrome extension relay CDP URL
clawdbot config set browser.profiles.clawd.cdpPort 18800Set managed browser CDP port
clawdbot gateway restartRestart gateway to apply config changes
clawdbot telegram auth --session <name>Create a new Telegram session for multi-agent setup
clawdbot agent start <agent-name>Start a specific agent by name
clawdbot nodes listList all nodes including pending approval requests
clawdbot nodes statusShow detailed status of all nodes
clawdbot devices approve <id>Approve a pending device pairing request
node --versionCheck Node.js version (use v22, avoid v24/v25)
rm -rf ~/.clawdbot/cacheClear cache to fix slow CLI issues
cat ~/.clawdbot/clawdbot.json5View current configuration file

Related Issues

📚 You Might Also Like

Blog

OpenClaw Discord: AI Bot for Your Server

Add an AI assistant to your Discord server. Setup guide, features, and configuration options.

Integration

Discord

Add your AI assistant to Discord servers and DMs. Get help, manage tasks, and run automations directly from your Discord channels.

Feature

AI Assistant with Memory That Remembers Everything

Stop re-explaining yourself to AI. OpenClaw remembers every conversation, preference, and detail forever. The only AI assistant with true persistent memory.

Blog

OpenClaw Backup Strategy: Never Rebuild Your Agent From Scratch Again

Your OpenClaw server dies. Hardware failure, VPS provider goes down, a botched update bricks the config, someone nukes the server by mistake. Pick any scenario.

🐙 Your AI should run your business.

Weekly live builds + template vault. We'll show you how to make AI actually work.Free to join.

Join Vibe Combinator →