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

Prerequisites

  • Node.js and npm — for the @clawq/clawq package
  • A model provider — either an LLM API key from OpenRouter, OpenAI, or another OpenAI-compatible provider, or a ChatGPT/Codex subscription using the built-in openai-codex 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. Install

npm install -g @clawq/clawq
clawq version

The current npm release artifact is built on Linux. If you are on another platform, use the Development Guide source build path for now.

You can also try the package without a global install:

npx @clawq/clawq version

If you want to build or contribute from source instead, use the Development Guide. Source builds need opam, OCaml 5.1, and system SQLite headers.

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:openai/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"
    }
  },
  "agent_defaults": {
    "primary_model": "openrouter: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
  }
}

For ChatGPT/Codex subscription auth instead of an API key, add an openai-codex provider and then run the OAuth login command:

{
  "providers": {
    "openai-codex": {
      "kind": "openai-codex",
      "base_url": "https://chatgpt.com/backend-api/codex",
      "default_model": "openai-codex:gpt-5.4"
    }
  },
  "agent_defaults": {
    "primary_model": "openai-codex:gpt-5.4"
  }
}
clawq auth codex-login openai-codex

The login opens a browser and waits for the OAuth callback on http://localhost:1455/auth/callback. If the browser cannot reach the local callback, paste the full redirect URL back into the terminal when prompted.

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. OpenRouter model IDs can contain slashes, so the full selector looks like "openrouter:openai/gpt-4o".
  • agent_defaults.subagent_default_model: Optional provider:model default for native/local subagents when no task or template model is set.
  • 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:

CommandAction
/startWelcome message
/helpShow command help
/newReset conversation history

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

Interrupt a stuck turn

If a response is still running and you want to interrupt it, send a message starting with !. For example, !stop interrupts the current turn for that session and then sends stop as the next normal message. This works in the browser UI and in chat channels such as Telegram.

Admins can also send a bare stop or /stop while a session is busy to terminate the active turn cleanly with Stopped by admin. and without enqueueing a follow-up message. Use !stop when you want the older interrupt-plus-follow-up behavior.

In Telegram, Discord, and Slack, a salute reaction means Clawq acknowledged the interrupt while the session was busy.

To send a non-interrupting note after the current turn finishes, use /followup MESSAGE. Use /followup-append MESSAGE to extend the latest queued follow-up.

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 or a configured subscription provider such as openai-codex

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 core command help. Use /help skills for skills and /help agents for agents. /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”. Admins can send bare stop or /stop during a busy turn to stop it cleanly with Stopped by admin. instead of enqueueing a follow-up.
  • 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

Clawq -- The Formal AI Assistant

OCaml 5.1 . Coq 8.19