Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.suji.fr/llms.txt

Use this file to discover all available pages before exploring further.

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 Claude or OpenAI GPT). 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:
  • At least one channel token for the platforms you want OpenClaw to respond on. You can start with one and add others later.
ChannelWhere to get the token
Telegram@BotFather
DiscordDiscord developer portal
WhatsApp Cloud APIMeta Business
SlackYour Slack app’s config page

​
Install

Dashboard → Apps → OpenClaw → Install:
FieldRequiredNotes
AI provideryesAnthropic (Claude) or OpenAI (GPT).
AI API keyyesEncrypted at rest.
Gateway passwordnoAuto-generated if blank.
ChannelsyesPick one or more of Telegram / Discord / WhatsApp / Slack.
Per-channel tokensfor the channels you selectedSee table above.
Recommended VM size: Small or larger. Mini is borderline and will OOM under load. 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 extra steps)

OpenClaw uses two security layers in front of the Control UI. Both run automatically when you access from localhost but require explicit setup over the public tunnel:
  1. A token that authenticates your browser.
  2. A device pairing approval per browser.

​
Step 1 — open the tokenized URL

OpenClaw generates its own access token on first boot and stores it in openclaw.json under gateway.auth.token.
  1. Dashboard → instance → Files tab.
  2. Switch the root to the OpenClaw install’s volume.
  3. Open openclaw.json.
  4. Copy the value of gateway.auth.token.
Then open: 
https://<your-subdomain>.suji.fr/#token=<paste-the-token>
You’ll see the Control UI start to load, then drop with error 1008 — the next step.

​
Step 2 — approve the device pairing

The browser will show:
disconnected (1008): pairing required
That means OpenClaw created a pending pairing request for your browser and is waiting for you to approve it. Leave the browser tab open, then in the dashboard:
  1. Terminal tab → pick OpenClaw from the selector.
  2. List the pending request: 
    openclaw devices list
  3. Approve it (replace with the ID you saw): 
    openclaw devices approve <requestId>
  4. Refresh the browser tab. The Control UI connects.
Pairing requests are short-lived (~30 s) — approve while the tab is still showing the error. The pairing is per browser/device, so you’ll repeat this once for each new browser.

​
Connecting channels

After the Control UI is up, channels you selected at install time auto-connect using the tokens you provided. Confirm by sending a test message to your bot. For webhooks-based channels (WhatsApp Cloud API, Slack events), point the webhook URL in the provider’s console at https://<your-subdomain>.suji.fr/webhooks/<channel>. To add a channel after the initial install:
  1. Install detail page → Edit Install.
  2. Toggle the channel on.
  3. Paste its token.
  4. Save — Suji redeploys the container with the new env.

​
Day-to-day management

Want to…Where
View live logsDashboard → Logs (pick OpenClaw)
Open a shell as node inside the containerDashboard → Terminal (pick OpenClaw)
Browse data filesDashboard → Files (pick the OpenClaw volume)
Edit openclaw.jsonFiles → open → Cmd-S to save → restart from install detail page
RestartInstall detail page → Restart
Upgrade to a newer versionInstall detail page → Upgrade (when available)
Remove the install + its dataInstall detail page → Uninstall

​
Troubleshooting

You opened the Control UI without the #token=... fragment. Rebuild the URL using the token from openclaw.json (Files tab → gateway.auth.token).
The browser isn’t paired yet. Open the dashboard’s per-app Terminal, run openclaw devices list and openclaw devices approve <id> while the failing browser tab is still on screen. Pairing is per browser, so repeat on every new device.
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.
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.
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.
Expected. Pairing is per device — approve the new browser’s pairing request the same way as the first.

​
Where things live

WhatInside containerOn host
sqlite, sessions, gateway config/home/node/.openclawNamed volume <install-id>_openclaw-data
Logsstdout/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 the app deletes the volume.
  • 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

ClassWhere
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