OpenClaw Setup Guide

A multi-platform AI coding agent with terminal TUI, Web Dashboard, and Telegram Bot support.

Overview

OpenClaw is a feature-rich AI coding agent that supports terminal TUI interaction, Web Dashboard management, and Telegram Bot remote access. It is suitable for developers who want to run AI coding assistants on servers.

Supported Environment

This guide is suitable for Linux cloud servers, macOS, and Windows users.

403 Your request was blocked

When using the Xiaomai API channel, you must add the headers field in provider configuration. Otherwise, requests may be blocked with 403:

json

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

Authorization must match apiKey, formatted as Bearer sk-your-key
User-Agent must keep the example format and should not be omitted or changed casually
Run openclaw gateway restart after modification

See full configuration example.

Links

Resource	URL
OpenClaw website	https://openclaw.ai
Installation docs	https://docs.openclaw.ai/zh-CN/install/installer

Features

Terminal TUI: command-line interaction for SSH environments
Web Dashboard: browser-based management panel
Telegram Bot: remote chat through Telegram
Multi-model support: Claude, GPT, Gemini, and more
Gateway: built-in gateway service with reverse proxy support
Skill extensions: install skills from the Dashboard

Installation and Initialization

Prerequisites

Node.js: Node 24 is required, or Node 22 LTS 22.16+. If the server has no Node.js, use install-cli.sh self-contained installation below
Git: required during installation
curl / bash: required on Linux/macOS

Step 1: Run the Installer

Choose the installation method for your system.

macOS / Linux / WSL standard installation:

bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

macOS / Linux / WSL self-contained installation without system Node.js:

bash

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

About install-cli.sh

install-cli.sh downloads a local Node.js runtime automatically and does not depend on system Node.js. It is suitable for servers without Node.js.

Windows PowerShell 5+:

powershell

iwr -useb https://openclaw.ai/install.ps1 | iex

Wait for installation to finish.

Step 2: Initialize Configuration

During installation, choose:

Step	Choice	Description
Startup mode	QuickStart	Fast setup mode
Provider setup	Skip for now	Skip and edit config manually later
Adapter	anthropic	Choose the Anthropic adapter
Model	opus-4.5	Or choose the model you need
Social adapter	As needed	Telegram is optional
Skill installation	Skip	Install later from Dashboard
Hook selection	Select all	Press Space to select all, then Enter
Open method	Skip	Skip for now
Shell completion	yes	Install shell completion

Channel and Model Configuration

Step 1: Edit Configuration File

Open the OpenClaw configuration file:

bash

vim ~/.openclaw/openclaw.json

Use the full configuration example below and fill in provider and model information.

Step 2: Enter API Key

In models.providers, replace apiKey and headers.Authorization with the API key created in the Xiaomai API console.

Step 3: Restart Gateway

bash

openclaw gateway restart

Step 4: Verify

Run this command to enter TUI and test the model:

bash

openclaw tui

After a successful test, type /quit to exit TUI.

Access Dashboard in Browser

Get Dashboard URL

Run the command in the console to get the Dashboard URL, then open it in a browser.

Remote Server Note

If OpenClaw runs on a remote server:

1. Configure reverse proxy

Use Nginx or another reverse proxy and set up an SSL certificate.

2. Modify configuration

Edit ~/.openclaw/openclaw.json and add this under gateway:

json

"controlUi": {
  "allowInsecureAuth": true
}

3. Restart gateway

bash

openclaw gateway restart

Open the tokenized Dashboard URL to enter the admin panel.

Configure Telegram Bot (Optional)

If you selected the Telegram adapter during installation:

Step 1: Chat with the Bot

Open Telegram and start a conversation with the bot you created through @BotFather.

Step 2: Get Pairing Code

After the first message, you receive a Pairing Code.

Step 3: Approve Pairing

Run this command:

bash

openclaw pairing approve telegram your_pairing_code

After pairing succeeds, you can chat with OpenClaw through Telegram Bot.

Full Configuration Example

This is a Windows example for connecting OpenClaw to Xiaomai API, with path ~/.openclaw/openclaw.json:

Note

sk-xxxx and xxxxx are placeholders. Replace them with your own API key and Bot Token.

json

{
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "xiaomai-claude/claude-opus-4-6"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "compaction": {
        "mode": "safeguard"
      },
      "workspace": "C:\\Users\\Administrator\\.openclaw\\workspace"
    }
  },
  "models": {
    "providers": {
      "xiaomai-claude": {
        "baseUrl": "https://xiaomai.win/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-6",
            "name": "claude-opus-4-6",
            "contextWindow": 200000,
            "maxTokens": 32000,
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            }
          }
        ]
      },
      "xiaomai-codex": {
        "baseUrl": "https://xiaomai.win/v1",
        "apiKey": "sk-xxxx",
        "api": "openai-completions",
        "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": "xxxx"
    },
    "port": 18789,
    "bind": "loopback",
    "tailscale": {
      "mode": "off",
      "resetOnExit": false
    }
  },
  "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, formatted as `provider/model-id`
`agents.defaults.maxConcurrent`	Max main-agent concurrency
`agents.defaults.subagents.maxConcurrent`	Max sub-agent concurrency
`agents.defaults.compaction.mode`	Context compaction mode. `safeguard` is the safer mode
`agents.defaults.workspace`	Workspace path. Adjust for your system
`models.providers`	Model provider configuration. Multiple providers can be configured
`models.providers.*.baseUrl`	API base URL. Xiaomai API uses `https://xiaomai.win/v1`
`models.providers.*.apiKey`	API key for the corresponding group
`models.providers.*.api`	API protocol. Use `openai-completions`
`models.providers.*.headers`	Request headers. Must include `User-Agent` and `Authorization`
`gateway.port`	Gateway port. Default is `18789`
`gateway.bind`	Binding mode. `loopback` allows local access only
`channels.telegram.botToken`	Telegram Bot Token from @BotFather
`logging.level`	Log level. Use `trace` when troubleshooting

Notes

headers.Authorization must match apiKey, formatted as Bearer sk-xxxx
Keep the User-Agent format close to the example to avoid blocked requests
For workspace, Windows uses escaped backslashes and Linux/macOS uses /, such as /root/.openclaw/workspace
cost can be set to 0 when using Xiaomai API as a gateway

FAQ

Installer failed

Confirm network access to openclaw.ai
Confirm curl and bash are installed
If the server is in mainland China, a proxy may be needed
If no Node.js environment exists, use install-cli.sh instead of install.sh

`openclaw` command not found

Check whether PATH includes the npm global directory
On Linux/macOS, run npm config get prefix and make sure it is in $PATH
On Windows, run npm config get prefix and add the output path to user PATH
Reopen the terminal or run source ~/.bashrc or source ~/.zshrc

npm EACCES permission error on Linux

npm global directory may point to a root-owned path
The installer tries to switch prefix to ~/.npm-global and update shell config
If it still fails, run:

bash

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

403 `Your request was blocked`

If the request returns 403 Your request was blocked, correct request headers are missing. Add headers in provider configuration:

json

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

Important

Authorization must match apiKey, formatted as Bearer sk-your-key
User-Agent must keep the example format
Run openclaw gateway restart after configuration

Model still unavailable after gateway restart

Check whether the API key is correct
Confirm the key group supports the selected model
Check OpenClaw logs for details

OpenClaw Setup Guide ​

Links ​

Features ​

Installation and Initialization ​

Step 1: Run the Installer ​

Step 2: Initialize Configuration ​

Channel and Model Configuration ​

Step 1: Edit Configuration File ​

Step 2: Enter API Key ​

Step 3: Restart Gateway ​

Step 4: Verify ​

Access Dashboard in Browser ​

Get Dashboard URL ​

Configure Telegram Bot (Optional) ​

Step 1: Chat with the Bot ​

Step 2: Get Pairing Code ​

Step 3: Approve Pairing ​

Full Configuration Example ​

Key Fields ​

FAQ ​

Installer failed ​

openclaw command not found ​

npm EACCES permission error on Linux ​

403 Your request was blocked ​

Model still unavailable after gateway restart ​

More Questions ​

OpenClaw Setup Guide

Links

Features

Installation and Initialization

Step 1: Run the Installer

Step 2: Initialize Configuration

Channel and Model Configuration

Step 1: Edit Configuration File

Step 2: Enter API Key

Step 3: Restart Gateway

Step 4: Verify

Access Dashboard in Browser

Get Dashboard URL

Configure Telegram Bot (Optional)

Step 1: Chat with the Bot

Step 2: Get Pairing Code

Step 3: Approve Pairing

Full Configuration Example

Key Fields

FAQ

Installer failed

`openclaw` command not found

npm EACCES permission error on Linux

403 `Your request was blocked`

Model still unavailable after gateway restart

More Questions