> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crazyrouter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# OpenClaw Deployment Guide
> Deploy OpenClaw with Crazyrouter on Linux or macOS, then finish WebUI, Telegram, and day-two operations setup
> Дата обновления: 2026-06-23
Use the one-click installer to deploy [OpenClaw](https://github.com/open-claw/open-claw) on Linux or macOS with Crazyrouter as the default backend. The installer writes a ready-to-run `~/.openclaw/openclaw.json`, registers the system service, and preloads a practical model set for chat, coding, and long-context work.
## Overview
OpenClaw is a good fit when you want a self-controlled local AI entrypoint backed by Crazyrouter:
* local WebUI and gateway, default port `18789`
* reusable access to your Crazyrouter models and quota
* Telegram support out of the box, plus pre-enabled plugin entries for DingTalk, WeCom, QQ Bot, Discord, Slack, and Feishu
* a good match for persistent personal bots, internal team assistants, home servers, and light self-hosted deployments
## Best For
* connecting Crazyrouter to a local AI gateway with one command
* running a Telegram bot on your own server
* managing WebUI, chat, and IM entrypoints in one place
* keeping an always-on assistant on a dev box or home mini server
## Protocol Used
Recommended protocol: `OpenAI-compatible API`
* the installer points the default `crazyrouter` provider at `https://api.crazyrouter.com/v1`
* it also writes `crazyrouter-claude` and `crazyrouter-minimax` providers for native-compatible switching
* OpenClaw itself exposes a local gateway and WebUI, authenticated with the generated `gateway.auth.token`
## Prerequisites
| Item | Notes |
| ------------------- | ------------------------------------------------------------------------------------------------------- |
| Crazyrouter account | Create one at [crazyrouter.com](https://crazyrouter.com) |
| Crazyrouter API key | Create a dedicated `sk-...` token for OpenClaw instead of reusing your IDE or CLI tokens |
| OS | Linux or macOS, x64 / arm64 |
| Network | The host needs outbound internet access; if you want remote WebUI access, allow the chosen gateway port |
| Node.js | The installer tries to install Node.js 22+ for you |
| Telegram bot token | Optional, only needed if you want Telegram |
The installer binds the gateway to LAN scope by default (`bind: lan`). If the machine is reachable from the public internet, protect it with firewall rules and keep the gateway login token private.
## Quick Start In 5 Minutes
In Crazyrouter, create a dedicated `sk-...` token for OpenClaw. Start with a small model allowlist such as `claude-opus-4-8`, `gpt-5.5`, and `gemini-3.1-pro`.
```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-openclaw/main/install.sh | bash
```
To skip the language picker and API key prompt:
```bash theme={null}
CRAZYROUTER_API_KEY=sk-xxx INSTALLER_LANG=en \
curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-openclaw/main/install.sh | bash
```
* WebUI URL: `http://:18789`
* auto-login URL: `http://:18789?token=`
* config path: `~/.openclaw/openclaw.json`
Open the auto-login URL in a browser, confirm you can enter the OpenClaw control UI, and send a simple test prompt with the default model `claude-opus-4-8`, such as `Reply with ok`.
The installer can set up Telegram immediately. If you choose that path, paste your Bot Token and then send any message to the bot so the first owner pairing can complete.
## Recommended Model Setup
The installer sets `claude-opus-4-8` as the default primary model. To change the day-to-day default, edit `agents.defaults.model.primary` in `~/.openclaw/openclaw.json`.
| Use case | Recommended model | Why |
| ----------------------- | ----------------- | ---------------------------------------------------------------------------------- |
| Default daily assistant | `claude-opus-4-8` | Current default primary model for high-quality daily chat and controller workloads |
| Coding / agent work | `gpt-5.5` | Latest OpenAI-compatible baseline for coding and agent-heavy workflows |
| Cost-balanced fallback | `claude-opus-4-8` | Strong balance of quality, stability, and cost |
| Gemini fallback path | `gemini-3.1-pro` | Useful as a second compatibility-validation path |
| Heavy reasoning | `deepseek-v4-pro` | Useful when you want stronger reasoning behavior |
Example: switch the default model to `gpt-5.5`
```json theme={null}
{
"agents": {
"defaults": {
"model": {
"primary": "crazyrouter/gpt-5.5"
}
}
}
}
```
If you want to explicitly use the Claude-compatible provider instead:
```json theme={null}
{
"agents": {
"defaults": {
"model": {
"primary": "crazyrouter-claude/claude-opus-4-8"
}
}
}
}
```
## Token Setup Best Practices
| Setting | Recommendation | Notes |
| ----------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Dedicated token | Required | Do not reuse the same token across OpenClaw, Cursor, and CLI tools |
| Model allowlist | Recommended | Keep only the models OpenClaw should use |
| IP restriction | Recommended on fixed-egress servers | Restrict the token to the server IP when possible |
| Quota cap | Recommended | Give the bot its own daily or monthly budget |
| Environment split | Recommended | Use separate tokens for production bots and test bots |
| Leak response | Immediate rotation | If `openclaw.json`, logs, or shared links expose credentials, rotate both the Crazyrouter token and gateway token |
OpenClaw uses at least two credential types: the Crazyrouter `sk-...` API key for model calls, and the local gateway login token for WebUI access. Keep them separate.
## Verification Checklist
* [ ] `http://:18789?token=` opens successfully
* [ ] the WebUI signs in without looping back to login
* [ ] the default model returns the first response successfully
* [ ] after a model change, a service restart still works
* [ ] `journalctl --user -u openclaw -f` or `tail -f ~/.openclaw/openclaw.log` shows successful requests
* [ ] if Telegram is enabled, the bot can reply to a test message
* [ ] a backup of `~/.openclaw/openclaw.json` is saved
## Key Files And Config Fields
### File Locations
| Path | Purpose |
| ------------------------------------------------------- | ------------------------------------------------------------ |
| `~/.openclaw/openclaw.json` | main config file |
| `~/.openclaw/start-gateway.sh` | launcher script used by the service |
| `~/.openclaw/crash-guard.cjs` | stability patch written by the installer |
| `~/.openclaw/credentials/.telegram-owner-paired` | marker file created after the first Telegram owner is paired |
| `~/.config/systemd/user/openclaw.service` | Linux user-level systemd service |
| `~/Library/LaunchAgents/com.crazyrouter.openclaw.plist` | macOS launchd service |
| `~/.openclaw/openclaw.log` | macOS runtime log |
| `~/.openclaw/openclaw.err` | macOS error log |
### Most Common Config Fields
| JSON path | Purpose | Typical change |
| -------------------------------------- | -------------------------------------------- | ------------------------------------------------- |
| `models.providers.crazyrouter.apiKey` | Crazyrouter OpenAI-compatible key | rotate API key |
| `models.providers.crazyrouter.baseUrl` | OpenAI-compatible base URL | usually keep `https://api.crazyrouter.com/v1` |
| `agents.defaults.model.primary` | default primary model | switch to `gpt-5.5`, `claude-opus-4-8`, and so on |
| `gateway.port` | WebUI / gateway port | move to a different port |
| `gateway.auth.token` | WebUI login token | rotate immediately if exposed |
| `gateway.bind` | listener scope | default is `lan` |
| `channels.telegram.botToken` | Telegram Bot Token | fill this when enabling Telegram |
| `plugins.entries.*.enabled` | whether each IM plugin is enabled | disable unused plugins |
| `env.vars.OPENAI_API_KEY` | API key reused by some internal capabilities | usually keep it aligned with the main key |
## IM Integrations
### Telegram
Telegram is the most complete path supported by the installer and should be your first integration:
1. Open Telegram and search for `@BotFather`
2. Send `/newbot` and create your bot
3. When the installer asks `Set up Telegram Bot now?`, choose `Y`
4. Paste the Bot Token so the installer can write it into `~/.openclaw/openclaw.json`
5. After the installer restarts the gateway, send any message to the bot
6. The first sender is auto-paired as the owner
7. If auto-pairing fails, run:
```bash theme={null}
openclaw pairing list
openclaw pairing approve
```
If you need to add Telegram manually later, this is the structure the installer writes:
```json theme={null}
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456789:ABCdef...",
"dmPolicy": "pairing",
"groupPolicy": "allowlist",
"streaming": "off"
}
},
"plugins": {
"entries": {
"telegram": { "enabled": true }
}
}
}
```
### Other IM Platforms
The installer pre-enables plugin entries for:
* `dingtalk`
* `openclaw-wecom`
* `qqbot`
* `discord`
* `slack`
* `feishu`
Those channels usually still require you to add your own platform credentials and the matching `channels.` config. A safe rollout pattern is:
1. create the bot or app in the target platform
2. write the platform credentials into `~/.openclaw/openclaw.json`
3. confirm `plugins.entries..enabled` is `true`
4. restart the OpenClaw service
5. validate the channel by checking logs and sending a test message
| Platform | Installer state | What you still need to do |
| ------------------------ | ------------------------------ | ------------------------------------------------- |
| Telegram | interactive setup supported | provide Bot Token and complete owner pairing |
| DingTalk | plugin installs and is enabled | add robot credentials and channel config |
| WeCom | plugin installs and is enabled | add enterprise app credentials and channel config |
| QQ Bot | plugin installs and is enabled | add bot credentials and channel config |
| Discord / Slack / Feishu | plugin entry is enabled | add the platform-specific channel credentials |
If OpenClaw will be connected to a team IM workspace, create a separate Crazyrouter token for that bot and enforce a tighter model allowlist and quota cap.
## Service Management And Logs
```bash theme={null}
systemctl --user status openclaw
systemctl --user start openclaw
systemctl --user restart openclaw
systemctl --user stop openclaw
journalctl --user -u openclaw -f
```
The installer also attempts `loginctl enable-linger $(whoami)` so the user-level service can keep running after you disconnect your SSH session.
```bash theme={null}
launchctl list | grep openclaw
launchctl start com.crazyrouter.openclaw
launchctl stop com.crazyrouter.openclaw
launchctl stop com.crazyrouter.openclaw && launchctl start com.crazyrouter.openclaw
tail -f ~/.openclaw/openclaw.log
cat ~/.openclaw/openclaw.err
```
On macOS, `openclaw.log` is usually enough for runtime activity, while `openclaw.err` is the first place to look when startup fails.
## Performance And Cost Tips
* start with `claude-opus-4-8` until the whole flow is stable
* keep routine bot traffic on `claude-opus-4-8` or move selected tasks to `gemini-3.1-pro` when cost matters more
* use `gpt-5.5` for coding-heavy agent workflows
* split WebUI, Telegram, and team IM usage across different tokens for better cost tracking
* keep only the models and plugins you actually need
## Upgrade Guide
The safest upgrade path is to rerun the installer, because it refreshes the OpenClaw package, patches, and service script together:
```bash theme={null}
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
```
```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-openclaw/main/install.sh | bash
```
If you manually added non-Telegram channels or changed the default model, compare the updated `openclaw.json` with your backup and re-apply the custom sections if needed.
Open the WebUI again and confirm your models, logs, and IM channels still work.
If you intentionally want to upgrade only the OpenClaw npm package, you can run `npm install -g openclaw@latest` and then restart the service, but that path will not re-apply installer-managed patches and script updates.
## Uninstall Guide
```bash theme={null}
systemctl --user disable --now openclaw
rm -f ~/.config/systemd/user/openclaw.service
systemctl --user daemon-reload
rm -rf ~/.openclaw
npm uninstall -g openclaw
```
```bash theme={null}
launchctl stop com.crazyrouter.openclaw
launchctl unload ~/Library/LaunchAgents/com.crazyrouter.openclaw.plist
rm -f ~/Library/LaunchAgents/com.crazyrouter.openclaw.plist
rm -rf ~/.openclaw
npm uninstall -g openclaw
```
If Node.js was installed only for OpenClaw, you can remove Node.js afterward once you confirm nothing else on the machine depends on it.
## Common Errors And Fixes
| Symptom | Likely cause | Fix |
| --------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| WebUI does not open | service is down, port is busy, or firewall is blocking access | check service state first, then verify port `18789` and firewall rules |
| The page opens but keeps asking for login | wrong `gateway.auth.token` or not using the auto-login URL | re-check the `?token=...` link printed by the installer and confirm `openclaw.json` |
| `401 unauthorized` | invalid or expired Crazyrouter API key in `models.providers.*.apiKey` | update the API key and restart the service |
| `403` or `model not allowed` | the requested model is not allowed by the Crazyrouter token | add that model to the token allowlist |
| `429` or quota exhaustion | budget or rate limit reached | raise the budget, switch to a cheaper model, or split traffic across tokens |
| The old model is still used after editing config | service was not restarted or the provider path is wrong | check `agents.defaults.model.primary`, then restart |
| Telegram bot does not reply | missing `botToken`, owner pairing never completed, or service was not restarted | check `channels.telegram`, restart, and trigger pairing again |
| Linux install says the service may not have started | user-level systemd service failed | inspect `journalctl --user -u openclaw -f` |
| macOS install says the service may not have started | launchd startup failed | inspect `~/.openclaw/openclaw.err` |
## FAQ
### Which Crazyrouter base URL should I keep?
Leave the installer defaults unless you are intentionally changing provider modes: `https://api.crazyrouter.com/v1` for the OpenAI-compatible provider, and `https://api.crazyrouter.com` for Claude / MiniMax native-compatible providers.
### Which default model should I keep first?
For most users, keep `claude-opus-4-8` first. If OpenClaw is mainly a coding assistant, switch to `gpt-5.5`.
### Why is my expected model missing?
Usually the model is not allowed by the Crazyrouter token, or the config is pointing at the wrong provider prefix.
### Why does Telegram work in DM but not in groups?
The installer sets Telegram group policy to `allowlist` by default. Adjust the Telegram channel config if your rollout needs broader group behavior.
### What is the safest way to expose OpenClaw externally?
At minimum: restrict inbound access, protect `gateway.auth.token`, and use a dedicated Crazyrouter token for OpenClaw. If the host is public, add a reverse proxy and extra access control.
Review the installer source, file issues, or audit the one-click setup yourself.