10 KiB

Raw Permalink Blame History

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:

openclaw onboard

This will guide you through:

Selecting your preferred AI models
Entering API keys
Configuring messaging channels (optional)

Option 2: Web Interface

Open Firefox/Chromium in this desktop
Navigate to: http://localhost:18789
Click Settings in the Gateway UI
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:

{
  "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:

./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):

"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

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:

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.

In Telegram, open a chat with @BotFather, run /newbot, and copy the bot token.
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.
Add a channels.telegram block in ~/.openclaw/openclaw.json (merge with existing channels if present):

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

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

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

Discord

In the Discord Developer Portal, create an application, add a Bot, and copy the bot token.
Add to .env as DISCORD_BOT_TOKEN=... (Clawtainer passes it in), or set channels.discord.token in openclaw.json.
Add a channels.discord block:

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

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 uses the gateway’s web channel (Baileys). A linked session must exist before WhatsApp will start.

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

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

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.
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).

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

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

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 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:

Open http://localhost:18789
Open Settings (gear or settings panel)
Enter token: clawtainer (or whatever you set in OPENCLAW_GATEWAY_TOKEN)
Save / connect. Health should show online once the WebSocket connects with the token.

Gateway not responding?

# 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

10 KiB Raw Permalink Blame History Unescape Escape