clawtainer/OPENCLAW-SETUP.md

# OpenClaw Setup Guide

Welcome to Clawtainer! This desktop has OpenClaw Gateway pre-installed and running on port 18789.

## Container layout

- **Desktop (VNC):** http://localhost:6901 (via nginx proxy)
- **OpenClaw Gateway:** http://localhost:18789
- **Gateway token:** `clawtainer` (enter in Settings → token)
- **Config:** `~/.openclaw/openclaw.json` (inside the container; `/home/kasm-user/.openclaw/`)
- **Env vars:** Project `.env` is loaded by Docker Compose; `GROQ_API_KEY`, `TELEGRAM_BOT_TOKEN`, etc. are passed into the container.

## What is OpenClaw?

OpenClaw is an open-source AI agent orchestration platform that connects to AI provider APIs. The Gateway is already running in the background, but you need to configure it with your API keys.

## Quick Setup (Choose One)

### Option 1: Interactive Wizard (Recommended)

Open a terminal and run:

```bash
openclaw onboard
```

This will guide you through:
- Selecting your preferred AI models
- Entering API keys
- Configuring messaging channels (optional)

### Option 2: Web Interface

1. Open Firefox/Chromium in this desktop
2. Navigate to: `http://localhost:18789`
3. Click **Settings** in the Gateway UI
4. Add your API keys for desired providers

### Option 3: Manual Configuration

Create or edit `~/.openclaw/openclaw.json` inside the desktop (or merge config and `docker cp` it in). For **built-in providers** (Anthropic, OpenAI, Google, Groq), you can also use environment variables: add keys to the project `.env` and ensure they're in `docker-compose.yml` `environment` so they reach the container.

Example manual `models.providers`:

```json
{
  "models": {
    "providers": {
      "anthropic": { "apiKey": "sk-ant-your-key-here" },
      "openai": { "apiKey": "sk-your-key-here" },
      "google": { "apiKey": "AIza-your-key-here" }
    }
  }
}
```

## Get API Keys

You'll need API keys from at least one provider:

- **Anthropic (Claude)**: https://console.anthropic.com/
  - Best for: Coding, analysis, long conversations
  - Pricing: Pay-per-token, ~$3-15 per million tokens

- **OpenAI (GPT-4)**: https://platform.openai.com/api-keys
  - Best for: General purpose, creative writing
  - Pricing: Pay-per-token, varies by model

- **Google (Gemini)**: https://makersuite.google.com/app/apikey
  - Best for: Free tier available, multimodal
  - Pricing: Free tier + pay-per-token

- **OpenRouter**: https://openrouter.ai/keys
  - Best for: Access to multiple models through one API
  - Pricing: Varies by model selected

- **Groq**: https://console.groq.com/keys
  - Best for: Very fast inference (Llama 3.x, GPT-OSS). OpenAI-compatible API.
  - Pricing: Low cost per token, free tier available.

### Using Groq with Clawtainer

Put `GROQ_API_KEY` in the project `.env`. Docker Compose passes it into the container.

**Option A: Script (recommended)**

From the project root, after `docker compose up -d`:

```bash
./scripts/configure-groq.sh
docker exec clawtainer openclaw gateway restart
```

> **Note:** The script **overwrites** `~/.openclaw/openclaw.json` with a Groq-only config. If you have other providers or channels, run the script first, then add them manually to `openclaw.json`.

**Option B: Manual config**

Inside the desktop, edit `~/.openclaw/openclaw.json`. Add under `models.providers` (merge with existing providers if present):

```json
"groq": {
  "baseUrl": "https://api.groq.com/openai/v1",
  "api": "openai-completions",
  "apiKey": "your-groq-api-key",
  "models": [
    { "id": "llama-3.3-70b-versatile", "name": "Llama 3.3 70B", "contextWindow": 131072 },
    { "id": "llama-3.1-8b-instant", "name": "Llama 3.1 8B", "contextWindow": 131072 }
  ]
}
```

Use `"api": "openai-completions"` (not `"openai"`). Wrong API type can cause **Verification failed: status 404**.

**Groq model IDs**

| Model ID | Notes |
|----------|-------|
| `groq/llama-3.3-70b-versatile` | Best quality, 280 tok/s |
| `groq/llama-3.1-8b-instant` | Faster, cheaper |
| `groq/openai/gpt-oss-120b` | OpenAI OSS 120B |

Set default: add `"agents": { "defaults": { "model": { "primary": "groq/llama-3.3-70b-versatile" } } }` to `openclaw.json`.

**Verify your Groq key**

```bash
curl -s "https://api.groq.com/openai/v1/models" -H "Authorization: Bearer $GROQ_API_KEY" | head -20
```

If you get JSON back, the key works. If 401, the key is invalid. If 404, the URL is wrong.

## Verify Setup

After adding keys, test the connection:

```bash
openclaw gateway status
```

Or visit `http://localhost:18789` to see the Gateway control panel.

## Messaging Channels (WhatsApp, Telegram, Discord, Signal, …)

You can add WhatsApp, Telegram, Discord, **Signal**, and other channels so the agent is reachable from your phone or team chat. Config lives in `~/.openclaw/openclaw.json` under `channels`. Restart the gateway after changes: `openclaw gateway restart`.

**Install all channel plugins (no container rebuild):** Run `./scripts/install-channel-clients.sh` to add Mattermost, Teams, Matrix, Nostr, Zalo, and signal-cli into the running container via `docker exec`. Then restart: `docker exec clawtainer openclaw gateway restart`.

### Telegram

1. In Telegram, open a chat with **@BotFather**, run `/newbot`, and copy the bot token.
2. Add the token to `.env` as `TELEGRAM_BOT_TOKEN=...` (Clawtainer passes it into the container), or put it in `openclaw.json` under `channels.telegram.botToken`.
3. Add a `channels.telegram` block in `~/.openclaw/openclaw.json` (merge with existing `channels` if present):

```json
"channels": {
  "telegram": {
    "enabled": true,
    "dmPolicy": "pairing",
    "groups": { "*": { "requireMention": true } }
  }
}
```

4. Restart the gateway, then approve DMs: `openclaw pairing list telegram` and `openclaw pairing approve telegram <CODE>`.

- Docs: https://docs.openclaw.ai/channels/telegram

### Discord

1. In the [Discord Developer Portal](https://discord.com/developers/applications), create an application, add a Bot, and copy the bot token.
2. Add to `.env` as `DISCORD_BOT_TOKEN=...` (Clawtainer passes it in), or set `channels.discord.token` in `openclaw.json`.
3. Add a `channels.discord` block:

```json
"channels": {
  "discord": {
    "enabled": true,
    "dmPolicy": "pairing",
    "allowFrom": ["YOUR_DISCORD_USER_ID"]
  }
}
```

4. Invite the bot to your server (OAuth2 → URL Generator, scopes: bot; permissions as needed). Restart the gateway.

- Docs: https://docs.openclaw.ai/gateway/configuration-reference (Discord section)

### WhatsApp

WhatsApp uses the gateway’s web channel (Baileys). A linked session must exist before WhatsApp will start.

1. In `~/.openclaw/openclaw.json`, ensure the web channel and WhatsApp are enabled:

```json
"channels": {
  "whatsapp": {
    "dmPolicy": "pairing",
    "allowFrom": ["+15555550123"],
    "groups": { "*": { "requireMention": true } }
  }
},
"web": { "enabled": true }
```

2. **Link a session once** (from a terminal inside the Clawtainer desktop, or via the Control UI if it supports pairing):
   - Run `openclaw channels login` and complete the QR/linking flow for WhatsApp.
3. Restart the gateway. WhatsApp will start when the linked session exists.

- Docs: https://docs.openclaw.ai/gateway/configuration-reference (WhatsApp section)

### Signal

OpenClaw supports **Signal** (E2E encrypted) via the external CLI **signal-cli**. You get DMs, groups, reactions, read receipts, and media. Use a **dedicated bot number** (recommended) or link an existing account with QR.

**Requirements:** `signal-cli` must be installed where the gateway runs (inside the Clawtainer container if you use Docker). The native Linux build is preferred (no JVM).

1. **Path A (QR link)** – Link an existing Signal account: run `signal-cli link -n "OpenClaw"` and scan the QR in Signal.
2. **Path B (dedicated number)** – Register a new number: `signal-cli -a +1… register` (and `--captcha` if required; see [Signal captcha](https://signalcaptchas.org/registration/generate.html)), then `signal-cli -a +1… verify <CODE>`.
3. Add a `channels.signal` block in `~/.openclaw/openclaw.json`:

```json
"channels": {
  "signal": {
    "enabled": true,
    "account": "+15551234567",
    "cliPath": "signal-cli",
    "dmPolicy": "pairing",
    "allowFrom": ["+15557654321"]
  }
}
```

4. Restart the gateway. Approve DMs with `openclaw pairing list signal` and `openclaw pairing approve signal <CODE>`.

**Clawtainer note:** The stock image does not include `signal-cli`. Run `./scripts/install-channel-clients.sh` to install it in the running container, or add it in a custom Dockerfile.

- Docs: https://docs.openclaw.ai/channels/signal

### Other channels

OpenClaw also supports **iMessage** (macOS only; uses `imsg` and Messages DB), **Slack** (bot + app tokens), **Google Chat** (service account), and **Mattermost** (plugin: `openclaw plugins install @openclaw/mattermost`). See the [configuration reference](https://docs.openclaw.ai/gateway/configuration-reference) for each.

## Pre-installed Tools

This desktop includes:

- **OpenClaw** - AI agent orchestration (port 18789)
- **Cursor** - AI-powered code editor
- **VS Code** - Microsoft Visual Studio Code
- **Antigravity** - Google's AI IDE with Gemini
- **Anthropic SDK** - Python library for Claude (`import anthropic`)

All tools have desktop shortcuts for easy access.

## Gateway Token

The OpenClaw Gateway is configured with token: `clawtainer`

You can change this by setting the `OPENCLAW_GATEWAY_TOKEN` environment variable when launching the container.

## Troubleshooting

**"Health offline" in the Control UI?**  
The UI connects to the gateway over WebSocket. You must **enter the gateway token** so it can authenticate:
1. Open http://localhost:18789
2. Open **Settings** (gear or settings panel)
3. Enter token: **`clawtainer`** (or whatever you set in `OPENCLAW_GATEWAY_TOKEN`)
4. Save / connect. Health should show online once the WebSocket connects with the token.

**Gateway not responding?**
```bash
# Check if gateway is running
ps aux | grep openclaw

# Restart gateway
openclaw gateway restart
```

**API key not working?**
- Check that your API key has not expired
- Verify billing is enabled on the provider's platform
- Check for typos in the key

**Groq: "Verification failed: status 404"?**
- Ensure `baseUrl` is exactly `https://api.groq.com/openai/v1` (no trailing slash)
- Use `"api": "openai-completions"` (not `"openai"`)
- Re-run `./scripts/configure-groq.sh` and restart the gateway, or verify your manual config matches the template

**Need help?**
- OpenClaw Docs: https://docs.openclaw.ai/
- OpenClaw GitHub: https://github.com/openclaw/openclaw

---

**Clawtainer** - https://colinknapp.com
Licensed under CC Attribution 4.0