How to Install and Configure OpenClaw: A Self‑Hosted AI Assistant Gateway

Overview

OpenClaw is a self‑hosted personal AI assistant gateway that provides a unified control plane for connecting chat applications (WhatsApp, Telegram, Discord, Slack, etc.) to AI programming agents while keeping all data on the local device.

System Requirements

Node.js ≥ 22 – verify with node --version Operating System: macOS or Linux (Windows is unstable; WSL2 is recommended)

AI provider API key – Anthropic (recommended), OpenAI, or a custom provider

Estimated installation time: 15 minutes

Installation

Homebrew (macOS only)

Skip this step on non‑macOS systems.

Check Homebrew: brew --version If not installed, run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install OpenClaw

The official script detects, installs, and initializes Node.js and runs the onboarding wizard:

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

During the interactive setup you will be prompted to confirm actions (use the left arrow, select Yes, and press Enter). If the interface differs, abort with Ctrl+C and rerun the script.

After the script finishes you will be asked to create a gateway token, set permissions for ~/.openclaw (700), and create a session directory.

Custom Model Provider Configuration

Run the onboarding wizard to add a custom provider: openclaw onboard Select yes for personal use, choose QuickStart, then Use existing values. When prompted for a provider, choose Custom Provider and supply:

Base URL of the provider

API key generated by the provider

Endpoint compatibility: OpenAI‑compatible Model ID (e.g., gpt-5.3-codex)

Endpoint ID (auto‑generated, e.g., custom-claude-chiddns-com)

Skip optional channel and skill configuration, then restart the gateway.

Increase Context Window and Max Tokens

Default limits are often too low for large models. Adjust them with:

# Set context window
openclaw config set 'models.providers.custom-claude-chiddns-com.models[0].contextWindow' 400000
# Set max tokens
openclaw config set 'models.providers.custom-claude-chiddns-com.models[0].maxTokens' 128000
# Verify configuration
openclaw config get 'models.providers.custom-claude-chiddns-com.models[0]'

Verification

Check Service Status

# Gateway status
openclaw gateway status
# Full diagnostic
openclaw doctor
# Overall status
openclaw status

Access Control Interface

Terminal (recommended for servers): openclaw tui Desktop environment – launch the web dashboard: openclaw dashboard Or open http://127.0.0.1:18789/ in a browser.

Front‑end Debugging

openclaw gateway --port 18789

Core Files and Directories

~/.openclaw/openclaw.json

– main configuration file (JSON5 format) ~/.openclaw/workspace – agent workspace directory ~/.openclaw/.env – environment file storing API keys and other secrets

Environment Variables

OPENCLAW_HOME

– OpenClaw home directory OPENCLAW_STATE_DIR – state data storage directory OPENCLAW_CONFIG_PATH – path to the configuration file

Basic Configuration

The file ~/.openclaw/openclaw.json uses JSON5 and provides safe defaults. Manage it via the wizard:

# Launch configuration wizard
openclaw configure
# View current configuration
openclaw config get

Minimal Configuration Example

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  }
}

Hot‑Reload Modes

Safe changes (e.g., channel settings) are applied instantly without restarting.

Infrastructure changes (e.g., port or authentication) require a gateway restart.

Common Commands Cheat Sheet

openclaw onboard

– run the onboarding wizard openclaw gateway – start the gateway openclaw gateway status – check gateway status openclaw dashboard – open the web console openclaw doctor – run diagnostic checks openclaw status – show overall system status openclaw logs --follow – tail logs in real time openclaw channels login – log in to chat channels openclaw configure – modify configuration openclaw config get – display current configuration openclaw agents add – add additional agent instances

FAQ

Q1: "EADDRINUSE" error on start?

Another gateway instance is using the port. Stop the other process or start on a different port, e.g.:

openclaw gateway --port 18790

Q2: Dashboard not reachable?

Confirm the gateway is running: openclaw gateway status If you see "device identity required", complete the device authentication flow.

When binding to a non‑loopback address, configure authentication first.

Q3: Features break after upgrade?

Upgrades may change defaults. Review the configuration and force reinstall of metadata:

openclaw config get
openclaw gateway install --force

Q4: How to update OpenClaw?

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