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

> 在 Linux 或 macOS 上使用 Crazyrouter 快速部署 OpenClaw，并完成 WebUI、Telegram 与日常运维配置

> 内容更新: 2026-06-09

通过一键脚本在 Linux 或 macOS 上部署 [OpenClaw](https://github.com/open-claw/open-claw) AI 网关，使用 Crazyrouter 作为默认后端。安装器会写入可直接运行的 `~/.openclaw/openclaw.json`、注册系统服务，并预配置一组适合聊天、编码和长上下文任务的模型。

## 概览

OpenClaw 适合把 Crazyrouter 变成一个你自己可控的本地 AI 入口：

* 本地 WebUI / 网关，默认监听 `18789`
* 可直接复用 Crazyrouter 的模型与额度
* 支持 Telegram，并预启用钉钉、企业微信、QQ Bot、Discord、Slack、飞书等插件入口
* 适合个人常驻机器人、团队内部助手、家庭服务器或轻量自托管场景

## 适合谁用

* 想用一条命令把 Crazyrouter 接到本地 AI 网关的人
* 想把 Telegram Bot 跑在自己的服务器上的人
* 想统一管理聊天、WebUI、IM 入口的人
* 想给开发机或家用小主机部署常驻助手的人

## 使用协议

推荐协议：`OpenAI-compatible API`

* 安装器默认把 `crazyrouter` provider 指向 `https://api.crazyrouter.com/v1`
* 同时会写入 `crazyrouter-claude`、`crazyrouter-minimax` provider，便于切换到 Anthropic Messages 兼容路径
* OpenClaw 自身对外暴露的是本地网关和 WebUI，认证依赖安装时生成的 `gateway.auth.token`

> [!NOTE]
>
> 如果你后续要手动调整 OpenClaw 的 provider 地址，先参考 [API Endpoint 说明](https://docs.crazyrouter.com/api-endpoint.md)，确认当前客户端应该填写根域名还是 `/v1`。

## 前置条件

| 项目 | 说明 |
| - | - |
| Crazyrouter 账号 | 先在 [crazyrouter.com](https://crazyrouter.com) 注册 |
| Crazyrouter API Key | 建议为 OpenClaw 单独创建一个 token，不要与 Cursor、Claude Code 共用 |
| 操作系统 | Linux 或 macOS，x64 / arm64 均可 |
| 网络 | 服务器需要能访问公网；如果你要从其他设备访问 WebUI，还要放行 `18789` 端口 |
| Node.js | 安装器会尽量自动安装 Node.js 22+ |
| Telegram Bot Token | 可选，仅在你要接 Telegram 时需要 |

> [!WARNING]
>
> OpenClaw 安装器默认把网关绑定到局域网地址（`bind: lan`）。如果你的主机直接暴露公网，请务必同时做好防火墙限制，并妥善保管网关登录 token。

## 5 分钟快速开始

**1. 创建专用 Crazyrouter token**

在 Crazyrouter 后台创建一个专门给 OpenClaw 使用的 `sk-...` token。建议先只放行你打算在网关里使用的模型，例如 `claude-opus-4-8`、`gpt-5.5`、`gemini-3.1-pro`。

**2. 运行安装脚本**

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-openclaw/main/install.sh | bash
```

如果你想跳过语言选择和 API Key 输入，也可以这样：

```bash theme={null}
CRAZYROUTER_API_KEY=sk-xxx INSTALLER_LANG=zh \
  curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-openclaw/main/install.sh | bash
```

**3. 记下安装器输出的 3 个值**

* WebUI 地址：`http://<服务器IP>:18789`
* 自动登录地址：`http://<服务器IP>:18789?token=<gateway_token>`
* 配置文件：`~/.openclaw/openclaw.json`

**4. 打开 WebUI 做第一次验证**

用浏览器访问自动登录地址，确认能够进入 OpenClaw 控制台，并用默认模型 `claude-opus-4-8` 发一条测试消息，例如“只回复 ok”。

**5. 按需完成 Telegram 配对**

安装器会询问是否立即设置 Telegram。若选择立即配置，填入 Bot Token 后，给你的机器人发送任意一条消息即可完成首个 owner 配对。

## 推荐模型配置

安装器默认主模型是 `claude-opus-4-8`。如果你想切换日常默认模型，直接修改 `~/.openclaw/openclaw.json` 里的 `agents.defaults.model.primary`。

| 场景 | 推荐模型 | 原因 |
| - | - | - |
| 默认日常聊天 | `claude-opus-4-8` | 当前默认主模型，适合作为高质量日常聊天与主控模型 |
| 编码 / Agent | `gpt-5.5` | 最新 OpenAI 兼容主力模型，适合作为编码与 Agent 主基线 |
| 高性价比备用 | `claude-opus-4-8` | 质量、稳定性和成本比较均衡 |
| Gemini 备用档 | `gemini-3.1-pro` | 适合作为第二条兼容性验证路径 |
| 深度推理 | `claude-opus-4-8` | 适合需要更强推理链的场景 |

示例：把默认模型改成 `gpt-5.5`

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "crazyrouter/gpt-5.5"
      }
    }
  }
}
```

如果你想显式走 Claude 兼容 provider，可以这样写：

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "crazyrouter-claude/claude-opus-4-8"
      }
    }
  }
}
```

## Token 设置最佳实践

| 设置 | 建议 | 说明 |
| - | - | - |
| 专用 token | 必须 | 不要把 OpenClaw 和其他 IDE / CLI 共用同一个 token |
| 模型白名单 | 建议开启 | 只保留 OpenClaw 会用到的模型，减少误用 |
| IP 限制 | 固定出口服务器建议开启 | 如果你的主机出口 IP 固定，可把 token 限制到这台服务器 |
| 配额上限 | 建议设置 | 给机器人场景单独设月度或日度预算 |
| 环境隔离 | 建议 | 生产机器人和测试机器人分开 token |
| 泄露处理 | 立即轮换 | 如果 `openclaw.json`、日志或分享链接暴露过 token，应立即重置 Crazyrouter token 和网关 token |

> [!TIP]
>
> OpenClaw 里至少有两类凭证：一类是 Crazyrouter 的 `sk-...` API Key，用来调用模型；另一类是 OpenClaw 本地网关登录 token，用来进入 WebUI。两者不要混用。

## 首次成功检查清单

* [ ] 浏览器能打开 `http://<服务器IP>:18789?token=<gateway_token>`
* [ ] OpenClaw WebUI 能正常进入，不会循环要求登录
* [ ] 默认模型可以成功返回第一条消息
* [ ] 修改模型后，重启服务仍能正常响应
* [ ] `journalctl --user -u openclaw -f` 或 `tail -f ~/.openclaw/openclaw.log` 能看到成功请求
* [ ] 如启用 Telegram，给机器人发消息后能够收到回复
* [ ] 已保存 `~/.openclaw/openclaw.json` 备份

## 关键文件与配置项

### 文件位置

| 路径 | 用途 |
| - | - |
| `~/.openclaw/openclaw.json` | 主配置文件 |
| `~/.openclaw/start-gateway.sh` | 启动脚本，系统服务实际调用它 |
| `~/.openclaw/crash-guard.cjs` | 安装器写入的稳定性补丁 |
| `~/.openclaw/credentials/.telegram-owner-paired` | Telegram 首个 owner 完成配对后的标记文件 |
| `~/.config/systemd/user/openclaw.service` | Linux 用户级 systemd 服务 |
| `~/Library/LaunchAgents/com.crazyrouter.openclaw.plist` | macOS launchd 服务 |
| `~/.openclaw/openclaw.log` | macOS 常规日志 |
| `~/.openclaw/openclaw.err` | macOS 错误日志 |

### 最常改的配置项

| JSON 路径 | 作用 | 常见修改 |
| - | - | - |
| `models.providers.crazyrouter.apiKey` | Crazyrouter OpenAI 兼容 key | 更换 API Key |
| `models.providers.crazyrouter.baseUrl` | OpenAI 兼容基址 | 通常保持 `https://api.crazyrouter.com/v1` |
| `agents.defaults.model.primary` | 默认主模型 | 切换到 `gpt-5.5`、`claude-opus-4-8` 等 |
| `gateway.port` | WebUI / 网关端口 | 改成你自己的端口 |
| `gateway.auth.token` | WebUI 登录 token | 泄露后立即更换 |
| `gateway.bind` | 监听范围 | 默认是 `lan` |
| `channels.telegram.botToken` | Telegram Bot Token | 启用 Telegram 时填写 |
| `plugins.entries.*.enabled` | 各 IM 插件是否启用 | 按需关闭未使用插件 |
| `env.vars.OPENAI_API_KEY` | 给某些内部能力复用的 API Key | 通常保持与主 key 一致 |

## IM 接入

### Telegram

这是安装器支持最完整的渠道，建议优先从 Telegram 开始：

1. 在 Telegram 搜索 `@BotFather`
2. 发送 `/newbot` 创建机器人，并拿到 Bot Token
3. 安装器询问 `Set up Telegram Bot now?` 时选择 `Y`
4. 粘贴 Bot Token，安装器会把它写入 `~/.openclaw/openclaw.json`
5. 安装器自动重启网关后，给机器人发送任意一条消息
6. 第一位发送消息的人会被自动配对为 owner
7. 如果自动配对失败，执行：

```bash theme={null}
openclaw pairing list
openclaw pairing approve <code>
```

手动补写 Telegram 配置时，可参考安装器写入的结构：

```json theme={null}
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456789:ABCdef...",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "streaming": "off"
    }
  },
  "plugins": {
    "entries": {
      "telegram": { "enabled": true }
    }
  }
}
```

### 其他 IM 平台

安装器会预启用以下插件入口：

* `dingtalk`
* `openclaw-wecom`
* `qqbot`
* `discord`
* `slack`
* `feishu`

但这些渠道通常还需要你自己补充平台凭证和对应的 `channels.<name>` 配置。推荐流程是：

1. 先在对应平台创建机器人或应用
2. 把平台凭证写入 `~/.openclaw/openclaw.json`
3. 确认对应 `plugins.entries.<name>.enabled` 为 `true`
4. 重启 OpenClaw 服务
5. 通过日志验证该渠道是否成功加载

| 平台 | 安装器状态 | 你还需要做什么 |
| - | - | - |
| Telegram | 支持交互式配置 | 填 Bot Token，完成 owner 配对 |
| 钉钉 | 插件会安装并启用 | 补充机器人凭证和对应 channel 配置 |
| 企业微信 | 插件会安装并启用 | 补充企业应用凭证和对应 channel 配置 |
| QQ Bot | 插件会安装并启用 | 补充机器人凭证和对应 channel 配置 |
| Discord / Slack / 飞书 | 插件入口已启用 | 按各自机器人配置要求补充 channel 凭证 |

> [!NOTE]
>
> 如果你准备把 OpenClaw 接入团队 IM，强烈建议为团队机器人单独创建 Crazyrouter token，并设置更严格的模型白名单和配额。

## 服务管理与日志

> [tab] Linux (systemd)
>
> ```bash theme={null}
> systemctl --user status openclaw
> systemctl --user start openclaw
> systemctl --user restart openclaw
> systemctl --user stop openclaw
> journalctl --user -u openclaw -f
> ```
>
> 说明：安装器会尝试执行 `loginctl enable-linger $(whoami)`，这样即使你退出 SSH，会话外的用户级服务也能继续运行。

> [tab] macOS (launchd)
>
> ```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
> ```
>
> 说明：macOS 下 `openclaw.log` 通常看运行日志，`openclaw.err` 更适合排查启动失败。

## 性能与成本建议

* 默认先用 `claude-opus-4-8`，确认整体流程跑通后再做模型分工
* 高频日常问答或机器人通知场景，可按成本回退到 `claude-opus-4-8` 或 `gemini-3.1-pro`
* 编码类工作流单独切到 `gpt-5.5`
* 团队场景把 Telegram / 企业 IM / WebUI 分成不同 token，便于成本核算和风险隔离
* 只保留必要插件和必要模型，减少误调用成本

## 升级指南

最稳妥的升级方式是重新运行安装器，因为它会一起处理 OpenClaw 包、补丁和服务脚本：

**1. 备份当前配置**

```bash theme={null}
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
```

**2. 重新执行安装脚本**

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/xujfcn/crazyrouter-openclaw/main/install.sh | bash
```

**3. 检查自定义配置是否需要回填**

如果你手动加过 Telegram 以外的 channel 或改过默认模型，重新对比 `openclaw.json`，确保这些自定义项仍然存在。

**4. 重启并验证**

重新打开 WebUI，确认模型、日志和已接入的 IM 渠道都正常。

如果你明确知道自己只想升级 OpenClaw npm 包，也可以先执行 `npm install -g openclaw@latest`，再重启服务；但这种方式不会帮你重新应用安装器里的补丁与脚本更新。

## 卸载指南

> [tab] Linux
>
> ```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
> ```

> [tab] macOS
>
> ```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
> ```

如果你当初是专门为了 OpenClaw 安装 Node.js，也可以在确认没有其他项目依赖后再手动移除 Node.js。

## 常见错误与修复

| 现象 | 常见原因 | 修复方式 |
| - | - | - |
| WebUI 打不开 | 服务未启动、端口被占用、主机防火墙未放行 | 先看服务状态，再检查 `18789` 端口和防火墙 |
| 页面能打开但一直要求登录 | `gateway.auth.token` 不对，或你访问的不是自动登录地址 | 重新读取安装器输出的 `?token=...` 链接，必要时检查 `openclaw.json` |
| 401 unauthorized | `models.providers.*.apiKey` 里的 Crazyrouter key 无效或已失效 | 更新 API Key 后重启服务 |
| 403 / model not allowed | OpenClaw 正在请求的模型不在 Crazyrouter token 白名单中 | 在 token 设置里放行对应模型 |
| 429 / 配额耗尽 | token 超额或速率限制触发 | 提高配额、换更便宜模型，或拆分 token |
| 修改模型后仍调用旧模型 | 服务未重启，或改错了 provider 路径 | 检查 `agents.defaults.model.primary`，然后重启 |
| Telegram Bot 不回复 | 未写入 `botToken`、未完成 owner 配对，或服务未重启 | 检查 `channels.telegram`、重启服务、重新发消息触发配对 |
| Linux 安装后提示服务可能未启动 | systemd 用户服务失败 | 运行 `journalctl --user -u openclaw -f` 看错误 |
| macOS 安装后提示服务可能未启动 | launchd 启动失败 | 查看 `~/.openclaw/openclaw.err` |

## FAQ

### 应该使用哪个地址作为 Crazyrouter 后端？

默认保持安装器写入的值即可：OpenAI 兼容 provider 用 `https://api.crazyrouter.com/v1`，Claude / MiniMax 原生兼容 provider 用 `https://api.crazyrouter.com`。

### 应该保留哪个默认模型？

大多数情况下先保留 `claude-opus-4-8`。如果你主要把 OpenClaw 当代码助手，再切到 `gpt-5.5`。

### 为什么模型列表里看不到我想用的模型？

通常是你的 Crazyrouter token 没放行该模型，或你改成了错误的 provider 前缀。

### 为什么 Telegram 私聊可以，群聊不行？

安装器默认把 Telegram 组策略设为 `allowlist`。你需要按自己的使用需求继续调整 Telegram channel 配置。

### 怎样最安全地对外开放 OpenClaw？

最少要做到三件事：限制来源访问、保护好 `gateway.auth.token`、为 OpenClaw 使用单独的 Crazyrouter token。若直接暴露公网，建议再加反向代理和额外访问控制。

> [card] [查看安装脚本仓库](https://github.com/xujfcn/crazyrouter-openclaw)
>
> 查看安装脚本、提交 Issue，或手动审查一键安装逻辑。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.