OpenClaw

OpenClaw is an open-source multi-channel messaging bot. It connects to Telegram, Discord, WhatsApp Cloud API, and Slack, and replies using your choice of AI provider: Anthropic, OpenAI, Google, Mistral, Groq, OpenRouter, xAI, Moonshot, or any OpenAI-compatible endpoint (vLLM, Ollama, LM Studio, LiteLLM, and the like). This page covers running OpenClaw on Suji end-to-end. OpenClaw itself is maintained upstream; Suji provides the marketplace packaging.

Before you install

You’ll need:

An AI provider API key (optional, OpenClaw boots unconfigured, so you can also skip this and set it later from the Terminal with the openclaw CLI). For example:
- Anthropic, console.anthropic.com
- OpenAI, platform.openai.com
- Or any other supported provider / OpenAI-compatible endpoint.
At least one channel token for the platforms you want OpenClaw to respond on. You can start with one and add others later.

Channel	Where to get the token
Telegram	@BotFather
Discord	Discord developer portal
WhatsApp Cloud API	Meta Business
Slack	Your Slack app’s config page

Install

Dashboard → Apps → OpenClaw → Install, then pick the VM to install on.

Field	Required	Notes
AI provider	yes	Anthropic, OpenAI, Google, Mistral, Groq, OpenRouter, xAI, Moonshot, or OpenAI-compatible.
Custom endpoint base URL	only for OpenAI-compatible	e.g. `https://llm.example.com/v1`.
AI API key	for hosted providers	Encrypted at rest. Optional for OpenAI-compatible endpoints that need no auth. Use Test connection to verify the key and model.
Model	for OpenRouter / Moonshot / OpenAI-compatible	e.g. `gpt-5.5`, `claude-sonnet-4-6`. Test connection lists the provider’s models, or type any value.
Gateway access token	no	Unlocks the Control UI. Auto-generated if blank; reveal it later in the Variables tab.
Telegram bot token	no	Provide to enable Telegram; leave blank to skip.
Discord bot token	no	Provide to enable Discord; leave blank to skip.

OpenClaw boots with --allow-unconfigured, so the AI fields are optional. You can choose Skip & configure later, then set the provider, key, and model after install from the Terminal tab (pick OpenClaw) using the openclaw CLI. See Configure after a skip install below. Recommended VM size: Small or larger. (Small = 2 vCPU / 4 GB is the floor.) Click Deploy. The install reaches running in ~1 minute. You’ll see a public URL like https://<your-subdomain>.suji.fr: that’s the Control UI.

First connection (two one-time steps)

OpenClaw protects the Control UI with two layers. Both run automatically from localhost, but over the public tunnel you do them once:

Sign in with your gateway access token.
Approve this browser (a one-time device pairing).

The install’s Deployment tab also walks you through these steps with the token revealable inline. Click Open on the install page to load the Control UI. Its login screen asks for the gateway access token. That token is the Gateway access token from the install form (auto-generated if you left it blank). To get it:

Install detail page → Deployment tab → Getting started: reveal and copy it there, or
Install detail page → Variables tab → reveal OPENCLAW_GATEWAY_PASSWORD.

Paste it into the login screen. It’s the same value every time you need it again.

Step 2: approve this browser

The first time you sign in, OpenClaw asks you to approve this browser and shows a command like:

openclaw devices approve [id]

Run that exact command (with the real id it showed you) from the dashboard:

Instance page → Terminal tab → pick OpenClaw from the selector.
Paste and run the command.
Sign in again. The Control UI connects.

The approval request is short-lived, so approve it while the sign-in screen is still open. Pairing is per browser/device, so you’ll repeat this once for each new browser.

Configure after a skip install

If you chose Skip & configure later, OpenClaw is running but unconfigured: it has no AI provider yet. You set this up from the Terminal with the openclaw CLI, not from OpenClaw’s web UI. Instance page → Terminal tab → pick OpenClaw, then run the guided setup:

openclaw configure

It walks you through credentials (provider + API key), the default model, and channels, and applies them to the running gateway. To jump straight to one part, target a section:

openclaw configure --section model      # provider + model
openclaw configure --section channels   # Telegram / Discord / WhatsApp / Slack

Prefer non-interactive commands? They map one-to-one:

openclaw models set anthropic/claude-sonnet-4-6   # <provider>/<model>
openclaw channels add                             # add a messaging channel
openclaw config get <key>                         # inspect a setting
openclaw config set <key> <value>                 # change a setting

CLI changes write to OpenClaw’s persisted config and take effect immediately, so there’s no redeploy.

A Restart re-applies the install form, which re-seeds a default model for your provider. If you set the model from the CLI and later restart, re-run openclaw models set …, or pin it once in the Variables tab (AI_MODEL) so it survives restarts.

Connecting channels

You have two ways to add a channel:

Bot token (Telegram / Discord): set TELEGRAM_BOT_TOKEN or DISCORD_BOT_TOKEN in the install’s Variables tab and Restart. Presence of the token enables the channel at startup; there is no separate selector.
CLI (any channel): from the Terminal (pick OpenClaw), run openclaw channels add and follow the prompts. This is how you set up WhatsApp (scan the QR code with your phone) and Slack (needs both a bot and an app token), which don’t fit a single install-time field.

For webhook-based channels (WhatsApp Cloud API, Slack events), point the webhook URL in the provider’s console at https://<your-subdomain>.suji.fr/webhooks/<channel>. Confirm by sending a test message to your bot.

Day-to-day management

Want to…	Where
Change AI provider / model / channels	Terminal (pick OpenClaw) → `openclaw configure`
View live logs	Dashboard → Logs (pick OpenClaw)
Open a shell as `node` inside the container	Dashboard → Terminal (pick OpenClaw)
Browse data files	Dashboard → Files (pick the OpenClaw volume)
Edit `openclaw.json`	Files → open → `Cmd-S` to save → restart from install detail page
Restart	Install detail page → Restart
Upgrade to a newer version	Install detail page → Upgrade (when available)
Remove the install + its data	Install detail page → Uninstall

Troubleshooting

Signed in, but it asks to approve a device

The browser isn’t paired yet. Open the instance Terminal tab (pick OpenClaw), run the openclaw devices approve [id] command OpenClaw showed you, then sign in again. Pairing is per browser, so repeat on every new device.

Bad gateway (Cloudflare 502)

OpenClaw isn’t reachable through the tunnel. Most common causes:

Container still starting. Wait 30 s and retry, especially right after an upgrade.
Container crashing, Logs tab will show the reason. If it’s a permission error on /home/node/.openclaw, that’s a packaging issue, file a Suji support ticket.

Permission denied on /home/node/.openclaw/…

OpenClaw runs as the node user. If the data volume’s ownership has drifted, OpenClaw can’t write its config. Fix from the host terminal:

docker exec --user 0 $(docker ps -q -f label=com.docker.compose.project=<install-id>) \
  chown -R node:node /home/node/.openclaw
docker compose -f /etc/suji/installs/<install-id>/compose.yaml restart openclaw

Fresh installs handle this automatically via an init-permissions container.

Mail isn't sending

The underlying network blocks outbound SMTP on ports 25 and 465. Use port 587 with STARTTLS, or an HTTP-based provider (Resend / Postmark / Mailgun / SendGrid). A firewall rule won’t help, the block is upstream of the firewall.

Control UI works in one browser, fails 1008 in another

Expected. Pairing is per device, approve the new browser’s pairing request the same way as the first.

Where things live

What	Inside container	On host
sqlite, sessions, gateway config	`/home/node/.openclaw`	Named volume `<install-id>_openclaw-data`
Logs	stdout/stderr	—
Compose file (rendered)	—	`/etc/suji/installs/<install-id>/compose.yaml`
Env (rendered secrets)	injected as env vars	`/etc/suji/installs/<install-id>/.env` (`0600`)

Uninstalling deletes the volume by default. Choose keep data during uninstall to preserve it (you can reconnect to it later over SSH).

Recommended size

Small (2 vCPU / 4 GB) is the floor for stable operation.
The compose caps OpenClaw at 2048 MiB and 1 vCPU. AI work itself runs at the provider (Anthropic / OpenAI), local CPU is just message routing, channel adapters, and HTTP roundtrips, which is light. The 2 GB ceiling is what actually matters: sustained high message volume can push memory usage if sessions accumulate, which is when an OOM kill would happen.

If you run multiple apps on the same VM, factor those caps in, the VM’s total CPU/memory is still shared.

Reporting issues

Class	Where
OpenClaw bug (wrong AI reply, channel logic, etc.)	openclaw/openclaw issues
Marketplace packaging bug (compose / manifest / install form)	suji-hq/suji-templates issues
Suji platform bug (dashboard, billing, network)	Support ticket from the dashboard

Getting Started

Concepts

Managing your VM

Marketplace apps

Billing

FAQ

What's new

Before you install

Install

First connection (two one-time steps)

Step 2: approve this browser

Configure after a skip install

Connecting channels

Day-to-day management

Troubleshooting

Where things live

Recommended size

Reporting issues

​Before you install

​Install

​First connection (two one-time steps)

​Step 1: sign in with the access token

​Step 2: approve this browser

​Configure after a skip install

​Connecting channels

​Day-to-day management

​Troubleshooting

​Where things live

​Recommended size

​Reporting issues

Before you install

Install

First connection (two one-time steps)

Step 1: sign in with the access token

Step 2: approve this browser

Configure after a skip install

Connecting channels

Day-to-day management

Troubleshooting

Where things live

Recommended size

Reporting issues