OpenClaw 🦞

OpenClaw 🦞 (formerly Clawdbot, Moltbot) is a personal AI assistant that runs locally and connects to multiple messaging platforms via a WebSocket-based Gateway architecture.

⚠️ This template uses ghcr.io/openclaw/openclaw:2026.2.26. OpenClaw 🦞 is in rapid development, so there may be undiscovered bugs. Changing versions may also cause stability issues.

⚠️ If you encounter any issues, feel free to check the GitHub issues for solutions or to report new ones. For Zeabur platform-related issues, please contact Zeabur support.

⚠️ macOS-specific software and packages (e.g. Homebrew) are not supported in this container environment. Please look for alternative solutions.

⚠️ This template requires a Dedicated Server on Zeabur. It cannot run on shared clusters.

⚠️ This template is pre-configured and ready to use - no need to run openclaw onboard. If you want to reconfigure, open Command in Zeabur dashboard and run:

openclaw onboard --gateway-bind lan

See the Wizard Reference for all available flags.

Recommended Resources

Minimum: 2 vCPU / 4 GB RAM
Recommended: 4 vCPU / 8 GB RAM

Feature Extensions

Browser: If you need browser features (web browsing, screenshots, etc.), deploy the Browser Template
Devbox: If you need multi-language code execution (Python, Go, Rust, C/C++), deploy the Devbox Template to the same project

Usage

After deployment, copy "Web UI (with token)" URL from the Instructions tab and paste it into your browser
Configure AI model (choose one):
- Zeabur AI Hub (default model: glm-4.7-flash): If you entered the API Key during deployment, go directly to step 3. You can also add ZEABUR_AI_HUB_API_KEY later via Variables tab in Zeabur dashboard (restart service after adding).
- Other providers (Anthropic, OpenAI, etc.): If you did not enter a Zeabur AI Hub API Key, the default model is anthropic/claude-opus-4-6. Go to Web UI Settings or add API key via environment variables. See: https://docs.openclaw.ai/providers/anthropic
Go to the Chat page to test if your AI model is working
(Optional) Set up messaging platforms like Telegram, WhatsApp, etc.

For AI model configuration, see the official documentation.

Model Switching & Failover

This template includes failover models that automatically switch when the primary model is unavailable. Default chain: glm-4.7-flash → grok-4-fast-non-reasoning → minimax-m2.5 → kimi-k2.5 → qwen-3-32 → gpt-5-mini.

You can manage models from Web UI Chat or Command in the Zeabur dashboard.

Via Web UI Chat — type slash commands directly in the chat box:

/model zeabur-ai/glm-4.7-flash — change primary model
/model — view current model
/models — list model providers
/models <provider> — list models for a specific provider (e.g. /models zeabur-ai)

Via Command (Zeabur dashboard) — same commands in the terminal:

openclaw models set zeabur-ai/glm-4.7-flash
openclaw models status
openclaw models list --all
openclaw models fallbacks list
openclaw models fallbacks add zeabur-ai/gpt-5-mini
openclaw models fallbacks remove zeabur-ai/gpt-5-mini
openclaw models fallbacks clear

Or edit the config file directly (~/.openclaw/config.json5):

"agents": {
  "defaults": {
    "model": {
      "primary": "zeabur-ai/glm-4.7-flash",
      "fallbacks": ["zeabur-ai/grok-4-fast-non-reasoning", "zeabur-ai/minimax-m2.5"]
    }
  }
}

After editing the config file, restart the service.

Adding External Model Providers

Besides Zeabur AI Hub, you can add external providers like Anthropic, OpenAI, Google, etc.

Method 1: Environment variables — add API keys via Variables tab in Zeabur dashboard:

ANTHROPIC_API_KEY — for Claude models
OPENAI_API_KEY — for GPT models
GOOGLE_API_KEY — for Gemini models

After adding, restart the service, then switch model:

Web UI Chat: /model anthropic/claude-opus-4-6
Command: openclaw models set anthropic/claude-opus-4-6

Method 2: Auth token — open Command in Zeabur dashboard:

# Paste an API key for a provider
openclaw models auth paste-token --provider anthropic

# Or use interactive auth helper
openclaw models auth add

Method 3: Config file — edit ~/.openclaw/config.json5:

"models": {
  "providers": {
    "anthropic": { "apiKey": "sk-ant-..." },
    "openai": { "apiKey": "sk-..." }
  }
}

For all supported providers, see the official documentation.

Telegram Bot Setup

Getting your bot token from BotFather:

Open Telegram and search for @BotFather
Send /newbot to create a new bot
Follow the prompts to set a name and username for your bot
BotFather will send you a token (e.g., 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)

Adding the token to Zeabur:

Go to your service's Environment Variables tab in Zeabur dashboard
Add TELEGRAM_BOT_TOKEN with your bot token
Restart the service
The Telegram plugin will be auto-enabled on restart. If the bot does not start, go to Settings → Config and verify the plugin is enabled: "plugins": { "entries": { "telegram": { "enabled": true } } }. To disable, set enabled to false.

Pairing your Telegram account:

Send /start to your bot in Telegram
The bot will reply with a pairing code (e.g., JN4MSY23)
Approve the pairing using one of these methods:
- Web Chat: In the OpenClaw web interface chat box, type openclaw pairing approve telegram <code>
- Terminal: Open Command in Zeabur dashboard, run openclaw pairing approve telegram <code>
You'll see: Approved telegram sender <user-id>.
Now you can chat with the bot!

WhatsApp Setup

Step 1: Configure WhatsApp channel Add the following configuration via OpenClaw Web UI (Settings → Config) or paste it to chat:

"channels": {
  "whatsapp": {
    "selfChatMode": true,
    "dmPolicy": "allowlist",
    "allowFrom": ["+15551234567"]
  }
}

Replace +15551234567 with your WhatsApp phone number (with country code). Restart the service after saving.

Step 2: Link WhatsApp

Open Command in Zeabur dashboard to access the container terminal
Run: openclaw channels login
A QR code will appear - scan it with WhatsApp on your phone
Connection complete! You can now message yourself on WhatsApp to chat with OpenClaw

LINE Bot Setup

Creating a LINE Messaging API channel:

Create a LINE Official Account if you don't have one
Go to LINE Developers Console
Create or select a Provider
Create a new Messaging API channel and link it to your LINE Official Account
In the Messaging API tab, issue a Channel access token (long-lived)
In the Basic settings tab, copy the Channel secret

Adding credentials to Zeabur:

Go to your service's Environment Variables tab in Zeabur dashboard
Add LINE_CHANNEL_ACCESS_TOKEN with your channel access token
Add LINE_CHANNEL_SECRET with your channel secret
Restart the service
The LINE plugin will be auto-enabled on restart. If the bot does not start, go to Settings → Config and verify the plugin is enabled: "plugins": { "entries": { "line": { "enabled": true } } }

Setting up the webhook:

After restarting, your webhook URL is: https://<your-domain>/line/webhook
In LINE Developers Console, go to your channel's Messaging API tab
Set Webhook URL to https://<your-domain>/line/webhook
Enable Use webhook
(Recommended) Disable Auto-reply messages and Greeting messages in the LINE Official Account Manager

Pairing your LINE account:

Add your bot as a friend on LINE and send any message
The bot will reply with a pairing code (e.g., JN4MSY23)
Approve the pairing using one of these methods:
- Web Chat: In the OpenClaw web interface chat box, type openclaw pairing approve line <code>
- Terminal: Open Command in Zeabur dashboard, run openclaw pairing approve line <code>
You'll see: Approved line sender <user-id>.
Now you can chat with the bot on LINE!

For other messaging platforms (Discord, Slack, etc.), see the Channels documentation.

AI Model Configuration

Verify your setup:

Your default model depends on deployment:
- With Zeabur AI Hub API Key → default model: zeabur-ai/glm-4.7-flash
- Without → default model: anthropic/claude-opus-4-6 (requires API key)
Open Chat page and send a test message
If you get a response → model is working
If you get an error → check that your API key is configured correctly

Switch model for current conversation (via chat commands):

/models - View available models
/model <model-id> - Switch model for this conversation only (does not affect other conversations)

Change default model for all new conversations (via Web UI Settings):

Go to Settings → Agents → Default model
Tip: Set a low-cost model as default (e.g., gemini-2.5-flash-lite, gpt-5-nano). If a model becomes unavailable, use /new to start a new conversation with the default model.

Add AI providers (via Web UI Settings or environment variables):

Add API keys for other AI providers (e.g., Anthropic, OpenAI)
See: https://docs.openclaw.ai/providers

Modify Zeabur AI Hub models (via Zeabur dashboard):

Go to Settings → Configs → Edit /opt/openclaw/providers/zeabur-ai-hub.json5
Older versions (without commands): Edit /home/node/.openclaw/openclaw.json via Files tab or Web UI Settings. Add the following to models.providers.zeabur-ai.models array:

{ "id": "gpt-5.2", "name": "GPT-5.2", "reasoning": false, "input": ["text", "image"], "cost": { "input": 1.5, "output": 12, "cacheRead": 0.15, "cacheWrite": 0 }, "contextWindow": 400000, "maxTokens": 8192 },
{ "id": "gpt-5.1", "name": "GPT-5.1", "reasoning": false, "input": ["text", "image"], "cost": { "input": 1.35, "output": 11, "cacheRead": 0.14, "cacheWrite": 0 }, "contextWindow": 400000, "maxTokens": 8192 },
{ "id": "gpt-5-nano", "name": "GPT-5 Nano", "reasoning": false, "input": ["text", "image"], "cost": { "input": 0.1, "output": 0.8, "cacheRead": 0.01, "cacheWrite": 0 }, "contextWindow": 400000, "maxTokens": 8192 },
{ "id": "glm-4.7", "name": "GLM-4.7", "reasoning": false, "input": ["text", "image"], "cost": { "input": 0.5, "output": 2, "cacheRead": 0.12, "cacheWrite": 0 }, "contextWindow": 204800, "maxTokens": 8192 },
{ "id": "glm-4.7-flash", "name": "GLM-4.7 Flash", "reasoning": false, "input": ["text", "image"], "cost": { "input": 0.25, "output": 1, "cacheRead": 0.06, "cacheWrite": 0 }, "contextWindow": 204800, "maxTokens": 8192 },
{ "id": "kimi-k2.5", "name": "Kimi K2.5", "reasoning": false, "input": ["text"], "cost": { "input": 0.45, "output": 2, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 131072, "maxTokens": 8192 }

Data Persistence

All data is stored under /home/node:

/home/node/.openclaw - Configuration, sessions, devices, and credentials
/home/node/.openclaw/workspace - Workspace and memory files

Backup & Restore

💡 Tip: We recommend creating a backup after completing your initial setup or making significant configuration changes.

Backup:

Method 1: Zeabur Backup Service (Recommended) - Use Zeabur's built-in backup feature. See Zeabur Backup Documentation.
Method 2: Manual Backup - Open Command → Run backup → Download from /home/node in Files tab (e.g. backup-1430.tar.gz)
- Older versions (without commands): cd /home/node && tar -czvf backup.tar.gz .openclaw

Restore:

Upload backup file to /home/node folder in Files tab
Open Command and run:
- From Zeabur Backup Service: restore <backup-file> --strip 2 (e.g. restore data-2026-02-27.zip --strip 2)
- From Manual Backup: restore <backup-file> (e.g. restore backup-1430.tar.gz)
- Older versions (without commands): cd /home/node && tar -xzvf <backup-file>
Delete the uploaded backup file from /home/node in Files tab to free up disk space
Restart service

⚠️ Restore will overwrite existing configuration and data on the new service. Remember to also restore related environment variables (e.g. TELEGRAM_BOT_TOKEN). Channel backup/restore has only been tested with Telegram and WhatsApp.

Troubleshooting

Default startup command: /opt/openclaw/startup.sh && /opt/openclaw/start_gateway.sh

New deployments (with helper page)

When the gateway stops, a helper page appears at the service URL with error details and steps to fix it:

Check the error logs — the helper page shows recent logs inline; for complete logs, open the Logs tab in Zeabur Dashboard
Fix the configuration — open the Files tab in Zeabur Dashboard, navigate to the config file (/home/node/.openclaw/openclaw.json), and correct the issue
Click Restart in Zeabur Dashboard to apply the fix

Existing deployments (without helper page)

If your deployment does not have the helper page, follow these steps:

Check the Logs tab in Zeabur Dashboard to find the error
Go to Settings → Command, change the startup command to sleep 3600, then click Restart — this keeps the container running so you can edit files
Fix the configuration — open the Files tab, navigate to the config file (/home/node/.openclaw/openclaw.json), and correct the issue
Change the startup command back to /opt/openclaw/startup.sh && /opt/openclaw/start_gateway.sh and click Restart

💡 To enable the helper page, redeploy from this template.

Updating OpenClaw Version

Check the latest version at OpenClaw releases
In Zeabur Dashboard, go to Settings → Service Image Source
Image: ghcr.io/openclaw/openclaw, Tag: change from the current version (e.g. 2026.2.19) to the new version (e.g. 2026.2.26)
Click Restart to apply

⚠️ Avoid using latest as the tag — it always pulls the newest release, which may introduce breaking changes or unexpected errors. Pin to a specific version for stability.

Check the Logs tab to confirm the gateway started successfully

💡 The startup script automatically migrates your config on each boot — new settings (like trustedProxies, dangerouslyDisableDeviceAuth) are added if missing. Your existing settings are preserved.

"device identity required"

This means the Web UI has not been paired with a Gateway Token yet. Fix:

Option 1: In Zeabur Dashboard Instructions tab, copy the Web UI (with Token) URL and open it in your browser
Option 2: Open the Web UI Overview page and enter the Gateway Token there

You can find the Gateway Token in the Zeabur Dashboard Instructions tab or Environment Variables (OPENCLAW_GATEWAY_TOKEN).

"non-loopback Control UI requires gateway.controlUi.allowedOrigins"

This error occurs after upgrading to image 2026.2.23 or later without updating the config. Fix: edit /home/node/.openclaw/openclaw.json and add "dangerouslyAllowHostHeaderOriginFallback": true under gateway.controlUi:

{
  "gateway": {
    "controlUi": {
      "dangerouslyAllowHostHeaderOriginFallback": true
    }
  }
}

Then restart the service. New deployments from this template already include this setting.

Tailscale Private Network Access (Optional)

⚠️ This feature requires a fresh deployment from this template. Existing deployments do not have the Tailscale startup scripts — please redeploy to use this feature.

Instead of a public domain, you can use Tailscale to make OpenClaw accessible only within your private network (tailnet), without exposing it to the public internet.

Prerequisites:

A Tailscale account (free plan works)
An Auth Key from Tailscale Admin Console (recommended: Reusable + Ephemeral)

Step 1: Set environment variables In the Zeabur dashboard Environment Variables tab, add:

TS_AUTHKEY (required): Your Tailscale Auth Key (tskey-auth-xxx). Get one at Tailscale Admin Console → Keys. Without this, Tailscale setup is skipped entirely.
TS_HOSTNAME (optional): The machine name on your tailnet, which determines your access URL (https://<TS_HOSTNAME>.<tailnet>.ts.net). Defaults to openclaw if not set.

Step 2: Switch startup command Go to Settings → Command, change to:

/opt/openclaw/startup.sh && /opt/openclaw/start_gateway_tailscale.sh

Restart the service.

Step 3: Install Tailscale on your device Install Tailscale on the device you want to access OpenClaw from (macOS, Windows, iOS, Android, Linux), and log in with the same Tailscale account used to create the Auth Key.

Step 4: First login to Web UI Once started, open in your browser (must be on the same tailnet):

https://<TS_HOSTNAME>.<your-tailnet>.ts.net

You can find your tailnet DNS name at Tailscale Admin Console → DNS, or check the full URL in the service Logs on Zeabur dashboard.

Append token to URL: https://<TS_HOSTNAME>.<your-tailnet>.ts.net?token=<GATEWAY_TOKEN>
Or enter the Gateway Token on the Web UI Overview page

You can find the Gateway Token in the Zeabur dashboard Instructions tab or Environment Variables (OPENCLAW_GATEWAY_TOKEN).

Step 5: Connect OpenClaw app (Optional, macOS example)

Install OpenClaw for macOS and Tailscale on the same device
Open OpenClaw app → Settings → General → select Remote mode
Set Transport to Direct (ws/wss)
Set Gateway URL to wss://<TS_HOSTNAME>.<your-tailnet>.ts.net
First connection requires pairing approval — go to the Web UI Nodes page and click approve

For iOS and Android setup, see the official documentation.

Switch back to public domain mode: Change the startup command back to /opt/openclaw/startup.sh && /opt/openclaw/start_gateway.sh and restart.

Zeabur-Specific Configuration

This template pre-configures the following settings for Zeabur's cloud environment:

gateway.trustedProxies: Set to ["10.0.0.0/8", "172.16.0.0/12"] so the gateway correctly identifies client IPs behind Zeabur's reverse proxy. Without this, the Web UI may show "device identity required" errors.
dangerouslyDisableDeviceAuth: Disables Web UI device pairing (device pairing is designed for local networks; cloud deployments use Gateway Token authentication instead).
/usr/local/bin symlinks: The openclaw, backup, and restore commands are symlinked to /usr/local/bin so they work in Zeabur's Command terminal.
OPENCLAW_DISABLE_BONJOUR=1: Disables mDNS/Bonjour because Zeabur container hostnames can exceed the 63-byte DNS label limit. mDNS is only used for local network discovery and is not needed in cloud environments.
OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=true: Fixes Telegram connection issues in containerized environments (required for image versions 2026.2.17 and later).

Documentation

Documentation: https://docs.openclaw.ai
GitHub: https://github.com/openclaw/openclaw

Changelog

2026/2/27

Add dangerouslyDisableDeviceAuth — replace device pairing with Gateway Token authentication for cloud deployment
Default model: zeabur-ai/glm-4.7-flash with failover chain (grok-4-fast-non-reasoning → minimax-m2.5 → kimi-k2.5 → qwen-3-32 → gpt-5-mini)
Add model switching, failover, and external provider documentation
Clean up environment variables (move defaults to startup script)
Auto-migrate existing configs (trustedProxies, auth settings)
Upgrade image to 2026.2.26 — Telegram DM allowlist inheritance fix, temp dir permissions fix for containers, CLI gateway --force in non-root Docker, Gemini model ID normalization, and additional security hardening

2026/2/26

Upgrade image to 2026.2.25 — 100+ security fixes across 2026.2.23→2026.2.25, new providers (Kilo Gateway, Mistral, Volcano Engine), heartbeat directPolicy config, gateway WebSocket auth hardening, cross-channel routing isolation, Discord voice DAVE reliability, Telegram webhook hang fix, and numerous stability improvements

2026/2/24

Upgrade image to 2026.2.23 — includes 30+ security fixes, new providers (Kilo Gateway, Mistral, Volcano Engine), unified channel streaming config, multilingual stop phrases, reasoning/thinking suppression across all channels, and numerous stability improvements
Add dangerouslyAllowHostHeaderOriginFallback to Control UI config — required for non-loopback deployments since 2026.2.23

2026/2/22

Replace health check with auto-restart wrapper: gateway now restarts automatically on crash with a helper page showing error details and fix steps, with 5-second service recovery detection
Remove rescue mode (rescue.sh) — replaced by the helper page

2026/2/20

Pin image tag to 2026.2.19 — add OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=true env var to fix Telegram connection issues (required for image versions 2026.2.17 and later)

2026/2/16

Switch image tag to latest to keep up with rapid security fixes

2026/2/15

Add Tailscale private network access: users can switch to start_gateway_tailscale.sh for private HTTPS access via tailnet without exposing to public internet
Bump image to 2026.2.14

2026/2/10

Fix image gen skill: switch from /v1/images/generations to /v1/chat/completions API, default model to gemini-2.5-flash-image
Fix gpt-oss-120b, llama-3.3-70b, qwen-3-32 HTTP 500: add supportsStore: false compat flag
Fix gpt-oss-120b reasoning flag (set to true)
Restore script now supports .zip format (Zeabur backup service)
Sync channel env vars (TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN, SLACK_APP_TOKEN, LINE_CHANNEL_ACCESS_TOKEN, LINE_CHANNEL_SECRET) into config at startup

2026/2/7

Fix cron proactive notifications not delivered: auto-detect heartbeat target from configured channels at startup
Initialize HEARTBEAT.md with actionable content for new deployments (prevents heartbeat skip on empty file)

2026/2/4

Use Zeabur configs for startup scripts (easier to maintain)
Add backup and restore global commands
Add auto-restart wrapper with fallback page for gateway crash recovery
Add 6 new Zeabur AI Hub models: gpt-5.2, gpt-5.1, gpt-5-nano, glm-4.7, glm-4.7-flash, kimi-k2.5
Add store compatibility setting for Zeabur AI Hub Claude models

2026/2/2

Add AI model configuration section (global vs conversation settings)
Add backup & restore section with Zeabur backup service
Add tip to backup after initial setup
Remove Google Gemini CLI patch (fixed upstream)
Remove ANTHROPIC_API_KEY and OPENAI_API_KEY from deployment variables to prevent OpenClaw from detecting empty API keys and failing (can be configured later via Web UI or environment variables)

quickActions

Features

Resources

Community

OpenClaw 🦞

OpenClaw 🦞 (formerly Clawdbot, Moltbot) is a personal AI assistant that runs locally and connects to multiple messaging platforms (WhatsApp, Telegram, Slack, Discord, etc.) via a WebSocket-based Gateway architecture.

OpenClaw 🦞

Recommended Resources

Feature Extensions

Usage

Model Switching & Failover

Adding External Model Providers

Telegram Bot Setup

WhatsApp Setup

LINE Bot Setup

AI Model Configuration

Data Persistence

Backup & Restore

Troubleshooting

New deployments (with helper page)

Existing deployments (without helper page)

Updating OpenClaw Version

"device identity required"

"non-loopback Control UI requires gateway.controlUi.allowedOrigins"

Tailscale Private Network Access (Optional)

Zeabur-Specific Configuration

Documentation

Changelog

Services

OpenClaw