OpenClaw Configuration — Complete Reference

## Browser Profile Configuration (cdpPort/cdpUrl)

If you see this error:

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:

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:

{  "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:

Executed in   38.86 secs    fish           external   usr time   37.64 secs

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

Fix:

# 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:

# 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

clawdbot telegram auth --session myagent2

Step 2: Configure in clawdbot.json5

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

Step 3: Start the agent

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:

{  "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:

{  "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:

disconnected (1008): pairing required

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

Fix:

# 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

# 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

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

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