OpenClaw Configuration Guide

Personal AI assistant: Terminal TUI, Web Dashboard, and 20+ chat platforms

📋 About OpenClaw

OpenClaw is a personal AI assistant that runs on your own devices. It supports Terminal TUI interaction, Web Dashboard management, and remote conversations through WhatsApp, Telegram, Slack, Discord, WeChat, and many more chat platforms.

Official website: https://openclaw.ai | Docs: https://docs.openclaw.ai

⚠️ Supported Environments

This guide is for Linux cloud servers, macOS, and Windows (via WSL2) users. Requires Node.js 22.16+ or 24 (recommended).

🚨 Getting 403/400 Errors or "client not supported"?

When using TokenSwitch as your API provider, you must add a headers field in the provider configuration, otherwise requests may return 403, 400 errors, or a client not supported message:

"headers": {
  "User-Agent": "claude-cli/2.0.76 (external, cli)",
  "Authorization": "Bearer sk-xxxx"
}

• Authorization must match your apiKey, in the format Bearer sk-your-key
• User-Agent must follow the example format — do not omit or modify it
• Claude and Codex use different User-Agent values — see the full config below
• After changes, run openclaw gateway restart to apply

See the Full Configuration Example below.

Links

Resource	URL
OpenClaw Website	https://openclaw.ai
Official Docs	https://docs.openclaw.ai
GitHub	https://github.com/openclaw/openclaw
Discord	https://discord.gg/clawd

Features

• Terminal TUI: Command-line interface, ideal for SSH environments
• Web Dashboard: Browser-based visual management panel
• Multi-platform chat: WhatsApp, Telegram, Slack, Discord, WeChat, QQ, and 20+ more
• Multi-model support: Claude, GPT, and more
• Gateway: Built-in gateway service with reverse proxy support
• Skill extensions: Install extensions via the Dashboard
• Canvas: Live controllable Canvas rendering

Installation & Setup

Step 1: Run the Install Script

Log in via SSH or open a macOS terminal and run:

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

Wait for the installation to complete.

Step 2: Initialize (Recommended: onboard)

Use openclaw onboard for a guided setup that walks you through Gateway, workspace, channels, and skills:

openclaw onboard

Or use openclaw init for a quick setup:

openclaw init

During the initialization wizard, follow these steps:

Step	Selection	Notes
Start mode	QuickStart	Quick start mode
Provider setup	Skip for now	We'll configure manually
Adapter	anthropic	Select Anthropic adapter
Model	opus-4.5	Or choose your preferred model
Social adapter	As needed	e.g., Telegram (optional)
Skill install	Skip	Can install later via Dashboard
Hook selection	Select all	Use spacebar to select all, then Enter
Open method	Skip	Skip for now
Shell completion	yes	Install command-line auto-completion

Provider & Model Configuration

Step 1: Edit the Configuration File

Open the OpenClaw config file:

vim ~/.openclaw/openclaw.json

Refer to the Full Configuration Example below for the complete structure.

Step 2: Enter Your API Key

In the models.providers section, configure the provider info. Replace apiKey and headers.Authorization with your API Key from the TokenSwitch console.

Step 3: Restart the Gateway

openclaw gateway restart

Step 4: Verify

Launch the TUI to test:

openclaw tui

Type /quit to exit after confirming it works.

Full Configuration Example

Below is a complete openclaw.json reference for connecting to TokenSwitch (path: ~/.openclaw/openclaw.json):

💡 Note

sk-xxxx and xxxxx are placeholders — replace them with your actual API Key and Bot Token.

{
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "tokenswitch-claude/claude-opus-4-5-20251101"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "compaction": {
        "mode": "safeguard"
      },
      "workspace": "/root/.openclaw/workspace"
    }
  },
  "models": {
    "providers": {
      "tokenswitch-claude": {
        "baseUrl": "https://tokenswitch.cc/v1",
        "apiKey": "sk-xxxx",
        "api": "openai-completions",
        "headers": {
          "User-Agent": "claude-cli/2.0.76 (external, cli)",
          "Authorization": "Bearer sk-xxxx"
        },
        "models": [
          {
            "id": "claude-opus-4-5-20251101",
            "name": "claude-opus-4-5-20251101",
            "contextWindow": 200000,
            "maxTokens": 32000,
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            }
          }
        ]
      },
      "tokenswitch-codex": {
        "baseUrl": "https://tokenswitch.cc/v1",
        "apiKey": "sk-xxxx",
        "api": "openai-responses",
        "headers": {
          "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal",
          "Authorization": "Bearer sk-xxxx"
        },
        "models": [
          {
            "id": "gpt-5.4",
            "name": "gpt-5.4",
            "contextWindow": 200000,
            "maxTokens": 32000,
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            }
          }
        ]
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "xxxxx"
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "auth": {
    "profiles": {}
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "xxxxx"
    }
  },
  "logging": {
    "level": "trace",
    "consoleLevel": "debug",
    "consoleStyle": "pretty"
  },
  "commands": {
    "restart": true
  },
  "skills": {
    "install": {
      "nodeManager": "npm"
    }
  }
}

Key Fields

Field	Description
agents.defaults.model.primary	Default model, format: provider-name/model-id
agents.defaults.maxConcurrent	Max concurrent main agents
agents.defaults.subagents.maxConcurrent	Max concurrent sub-agents
agents.defaults.compaction.mode	Context compaction mode, safeguard is the safe option
agents.defaults.workspace	Workspace directory path, adjust for your system
models.providers	Model provider configs, supports multiple providers
models.providers.*.baseUrl	API base URL, use https://tokenswitch.cc/v1
models.providers.*.apiKey	Your TokenSwitch API Key
models.providers.*.api	API protocol: openai-completions for Claude, openai-responses recommended for Codex
models.providers.*.headers	Request headers, must include User-Agent and Authorization
gateway.port	Gateway listen port, default 18789
gateway.bind	Bind mode, loopback for local access only
channels.telegram.botToken	Telegram Bot Token from @BotFather
logging.level	Log level, set to trace for debugging

⚠️ Important Notes

• Authorization in headers must match apiKey, format: Bearer sk-xxxx
• Claude and Codex use different User-Agent values: Claude uses claude-cli/..., Codex uses codex_cli_rs/...
• Codex is recommended to use openai-responses mode
• Workspace path: Windows users use \\ double backslashes, Linux/macOS users use / (e.g., /root/.openclaw/workspace)
• Cost set to 0: No local billing needed when using TokenSwitch as a proxy

Browser Dashboard Access

Getting the Dashboard URL

Run the dashboard command in your console to get the URL, then open it in your browser.

⚠️ Remote Server Users

If running OpenClaw on a remote server, you need to:

1. Set up a reverse proxy

Use Nginx or another reverse proxy to forward traffic to the OpenClaw service, with SSL configured.

2. Edit the config file

In ~/.openclaw/openclaw.json, add under the gateway field:

"controlUi": {
  "allowInsecureAuth": true
}

3. Restart the gateway

openclaw gateway restart

Access the Dashboard URL with your token to enter the management panel.

Telegram Bot Setup (Optional)

OpenClaw supports 20+ chat platforms including WhatsApp, Telegram, Slack, Discord, WeChat, QQ, and more. Here's an example using Telegram:

If you selected the Telegram adapter during installation:

1. Create a Bot via @BotFather on Telegram and get the Bot Token
2. Add the token to channels.telegram.botToken in openclaw.json
3. Restart the gateway: openclaw gateway restart
4. Chat with your Bot on Telegram to get a Pairing Code
5. Authorize in the console:

openclaw pairing approve telegram your-pairing-code

Once paired, you can interact with OpenClaw remotely via Telegram.

Troubleshooting

Install script fails?

• Confirm network connectivity to openclaw.ai
• Ensure curl and bash are installed
• If on a server in China, you may need to configure a proxy

Getting 403/400 Errors or "client not supported"?

Missing request headers. You must add the headers field in your provider config:

"headers": {
  "User-Agent": "claude-cli/2.0.76 (external, cli)",
  "Authorization": "Bearer sk-xxxx"
}

🚨 Important

• Authorization must match apiKey, format: Bearer sk-your-key
• User-Agent must follow the example format, or requests will be blocked
• Claude and Codex use different User-Agent values — refer to the full config example
• Run openclaw gateway restart after making changes

Gateway restart but model still unavailable?

• Verify the API Key is entered correctly
• Confirm the key's token group supports your chosen model
• Check OpenClaw logs: openclaw gateway logs

More questions?

See the FAQ.