Getting Started with QuantClaw

Welcome to QuantClaw! This guide will help you get up and running in just a few minutes.

What is QuantClaw?

QuantClaw is a high-performance C++17 implementation of OpenClaw, an AI agent framework designed to run locally on your machine. It can execute commands, control browsers, manage files, and integrate with various chat platforms — with minimal memory footprint and no runtime dependencies.

Prerequisites

Before you start, make sure you have:

• Linux (Ubuntu 20.04+), Windows 10+ (native or WSL2), or macOS 13+ on Apple Silicon
• C++17 compatible compiler (GCC 7+, Clang 5+)
• CMake 3.15+
• Node.js 16+ (for plugin support)
• An LLM API key (OpenAI, Anthropic, or any compatible provider)

Installation Methods

Method 1: Quick Docker Setup

The fastest way to get started:

docker run -d \
  --name quantclaw \
  -p 18800:18800 \
  -p 18801:18801 \
  -e OPENAI_API_KEY=sk-... \
  -v quantclaw_data:/home/quantclaw/.quantclaw \
  quantclaw:latest

Method 2: Build from Source

Clone and build QuantClaw:

# Clone the repository
git clone https://github.com/QuantClaw/QuantClaw.git
cd QuantClaw

# Install system dependencies (Ubuntu/Debian)
sudo apt install build-essential cmake libssl-dev \
  libcurl4-openssl-dev nlohmann-json3-dev libspdlog-dev zlib1g-dev

# Create build directory
mkdir build && cd build

# Configure and build
cmake ..
cmake --build . --parallel

# Verify the build
./quantclaw_tests

# Install (optional)
sudo cmake --install .

Method 3: Install Script

# macOS / per-user install
bash scripts/install.sh --user

# Linux / system-wide install
sudo bash scripts/install.sh --system

The install script auto-detects your OS, installs dependencies, builds from source, runs onboarding, and installs the background service definition. On macOS, the default install target is ~/.quantclaw/bin.

Initial Setup

Once installed, run the onboarding wizard:

# Interactive setup wizard (recommended)
quantclaw onboard

# Or quick setup with defaults (no prompts)
quantclaw onboard --quick

The wizard will:

• Create ~/.quantclaw/quantclaw.json (configuration)
• Create ~/.quantclaw/agents/main/workspace/ with all 8 workspace files
• Generate a gateway auth token and default configuration
• Optionally install as a background service (systemd --user on Linux, launchd on macOS)

Your First Session

Start the Gateway

# Run in foreground
quantclaw gateway run

# Or install and start the background service
quantclaw gateway install
quantclaw gateway start

Send a Message

quantclaw agent "Hello! Introduce yourself."

Open the Web Dashboard

quantclaw dashboard

This opens http://127.0.0.1:18801 in your browser — a full web interface for chatting, managing sessions, and viewing configuration.

Dashboard Authentication

The dashboard requires a token to access. The token is defined in your configuration file:

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "YOUR_SECRET_TOKEN"
    }
  }
}

First-time access:

1. Open http://127.0.0.1:18801 in your browser
2. Enter the token you configured in ~/.quantclaw/quantclaw.json
3. The token is stored in your browser's localStorage for future visits

To disable authentication (not recommended for production):

{
  "gateway": {
    "auth": {
      "mode": "none"
    }
  }
}

To change your token:

1. Edit ~/.quantclaw/quantclaw.json and update gateway.auth.token
2. Run quantclaw config reload (or restart the gateway)
3. Clear your browser's localStorage for 127.0.0.1:18801 and enter the new token

Command Line Usage

# Send a message (creates a new session automatically)
quantclaw agent "What is the weather today?"

# Use a specific session
quantclaw agent --session my:project "Continue our discussion"

# One-shot query without session history
quantclaw eval "What is 2 + 2?"

# Check gateway status
quantclaw health
quantclaw status

Configuration

The main configuration file is ~/.quantclaw/quantclaw.json:

{
  "llm": {
    "model": "openai/qwen-max",
    "maxIterations": 15,
    "maxTokens": 4096
  },
  "providers": {
    "openai": {
      "apiKey": "YOUR_API_KEY",
      "baseUrl": "https://api.openai.com/v1"
    }
  },
  "gateway": {
    "port": 18800,
    "controlUi": { "port": 18801 }
  }
}

See the Configuration Guide for all options.

Next Steps

• 📖 Configuration Guide
• 🏗️ Architecture Overview
• 🔌 Plugin Development
• 🛠️ CLI Reference

Getting Help

• Documentation: Full docs
• GitHub Issues: Report bugs
• Discussions: Community support

Troubleshooting

Build Errors

# Check system dependencies
sudo apt install build-essential cmake libssl-dev \
  libcurl4-openssl-dev nlohmann-json3-dev libspdlog-dev

# Rebuild with verbose output
cd build
cmake .. -DCMAKE_VERBOSE_MAKEFILE=ON
cmake --build . --parallel

Gateway Won't Start

quantclaw config get gateway.port   # Check configured port
quantclaw doctor                    # Run full diagnostics

API Key Problems

quantclaw health                    # Check gateway connectivity
quantclaw config get llm.model      # Verify model/provider config

---

🎉 You're ready! Check out the feature guide to explore more capabilities.