The quickest path from zero to a running clawq instance takes about five minutes. This guide covers building from source, configuring a provider, opening the streaming web UI, and optionally adding a chat channel such as Telegram.

Prerequisites

• opam — the OCaml package manager
• libsqlite3-dev (Debian/Ubuntu) or equivalent for your distribution
• An LLM API key from OpenRouter, OpenAI, or any OpenAI-compatible provider
• Optional channel credentials — Telegram bot token (from @BotFather), Discord bot token, Slack app token, or a GitHub PAT plus webhook secret if you want channel integrations beyond the browser UI

1. Bootstrap and Build

# Clone the repository
git clone <repo-url> clawq && cd clawq

# Create opam switch "clawq-5.1" and install all dependencies
make bootstrap

# Build the project
make build

# Run tests to verify the build
make test

2. Interactive Setup (Recommended)

The fastest way to configure clawq is with the onboarding wizard:

clawq onboard

The wizard walks through every section — provider, model, security, channels, gateway, and memory — and writes ~/.clawq/config.json at the end. You can re-run it any time.

Alternatively, use the config wizard directly:

clawq config wizard

Channel Setup Wizards

For individual channel configuration, use the dedicated setup wizards:

clawq setup telegram    # Telegram bot
clawq setup discord     # Discord bot
clawq setup slack       # Slack app
clawq setup github      # GitHub webhooks
clawq setup teams       # MS Teams bot

Each wizard loads existing config, presents an interactive dashboard, and writes changes back to ~/.clawq/config.json.

Additional setup wizards:

clawq setup tunnel      # Cloudflare / Tailscale / ngrok tunnel
clawq setup summarizer  # Autosummarizer settings

3. Manual Configuration

Using config set commands

Set individual values by dot-path:

clawq config set providers.openrouter.api_key "sk-or-v1-YOUR_KEY_HERE"
clawq config set providers.openrouter.base_url "https://openrouter.ai/api/v1"
clawq config set agent_defaults.primary_model "openrouter:gpt-4o"

# Optional Telegram channel
clawq config set channels.telegram.accounts.main.bot_token "7123456789:AAF1k_YOUR_TOKEN_HERE"
clawq config set channels.telegram.accounts.main.allow_from '["*"]'

Review the result:

clawq config show           # full config, secrets redacted
clawq config show channels  # one section
clawq config get providers.openrouter.default_model  # single value

Editing config.json directly

$EDITOR ~/.clawq/config.json

Minimal working configuration:

{
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-YOUR_KEY_HERE",
      "base_url": "https://openrouter.ai/api/v1",
      "default_model": "openai/gpt-4o"
    }
  },
  "channels": {
    "telegram": {
      "accounts": {
        "main": {
          "bot_token": "7123456789:AAF1k_YOUR_TOKEN_HERE",
          "allow_from": ["*"]
        }
      }
    }
  },
  "gateway": {
    "host": "127.0.0.1",
    "port": 13451,
    "require_pairing": true
  }
}

Configuration notes:

• allow_from: ["*"] allows all users. To restrict access, list specific chat IDs: ["123456789", "987654321"].
• base_url: Use https://api.openai.com/v1 for OpenAI directly, or any compatible endpoint.
• default_model: Default model for this provider. Can be overridden per-request.
• agent_defaults.primary_model: Sets the provider and model using provider:model format (e.g. "openrouter:gpt-4o").
• For GitHub webhook automation, add channels.github config plus a public webhook URL; see the Channels page for the full setup and hook file format.

4. Validate

Check your configuration for common issues:

clawq doctor

You should see doctor: all checks passed. If there are warnings, fix the noted issues.

Check the active workspace path:

clawq workspace

Check the full runtime status:

clawq status

5. Start the Daemon

clawq agent

You should see output like:

clawq: [INFO] clawq daemon starting (pid=12345)
clawq: [INFO] Starting Telegram polling for account 'main'
clawq: [INFO] Daemon ready. Gateway on 127.0.0.1:13451

The daemon runs in the foreground. Press Ctrl+C to stop it. To run in the background:

clawq agent &

6. Verify

Test the HTTP gateway:

curl http://127.0.0.1:13451/health
# {"status":"ok"}

If you configured Telegram, open Telegram and message your bot. Built-in commands:

Command	Action
/start	Welcome message
/help	Show available commands
/new	Reset conversation history

The bot maintains conversation history per chat, so follow-up questions work naturally.

Open the browser UI at http://127.0.0.1:13451/:

• The page streams assistant text live from /chat/stream.
• Thinking deltas and tool output render in separate panels while the turn is in progress.
• Slash command suggestions are loaded from /commands.
• When the gateway uses pairing mode, the page asks for the live 6-digit browser pairing code from clawq otp-show and stores the issued bearer token locally for later requests.

Troubleshooting

Bot does not respond:

• Check the daemon is running and showing Starting Telegram polling
• Verify your bot token with clawq doctor
• Check that allow_from includes your chat ID (or is ["*"])

“No providers configured” warning:

• Ensure providers is set in ~/.clawq/config.json with a valid API key

LLM API errors:

• Verify your API key is valid and has credits
• Try a different model (e.g., openai/gpt-3.5-turbo for lower cost)
• Check that base_url matches your provider

Permission denied / config not found:

• Run clawq onboard to create the config directory
• Check ~/.clawq/config.json exists and is readable

What’s Next

Now that clawq is running, here are some things to explore:

• Slash commands in chat: Type /help in any chat channel to see all available slash commands. /status shows a rich status report, /costs shows usage costs, and /model list shows available models.
• Interrupt a running turn: Prefix a message with ! to interrupt the current turn and send a new message. For example, !stop interrupts and sends “stop”.
• Background tasks: Use clawq delegate "implement feature X" to hand off coding work to a background agent running in a git worktree. See the output with clawq background logs.
• Shell completions: Run clawq completions install to set up tab completion for your shell.
• Configuration Reference — all config sections and fields
• CLI Reference — complete command reference with slash commands
• Channels — detailed setup guides for Discord, Slack, GitHub, Teams, and more