跳到主要内容OpenClaw 跨平台部署与 Telegram/飞书集成实战指南 | 极客日志JavaScriptNode.jsAI
OpenClaw 跨平台部署与 Telegram/飞书集成实战指南
OpenClaw 是一款支持多平台的 AI 智能体网关,兼容 Telegram、飞书等渠道。本文详解 Windows 与 macOS 下的安装部署流程,涵盖 Node.js 环境检查、WSL2 推荐方案及原生安装步骤。重点梳理了 Telegram 机器人创建、飞书应用权限配置及双向集成方法,并总结了常见网络、权限、端口占用等问题的排查思路与调试命令,帮助开发者快速搭建本地 AI 服务。
OpenClaw 跨平台部署与 Telegram/飞书集成实战指南
OpenClaw 是一个适用于任何操作系统的 AI 智能体 Gateway 网关,支持 WhatsApp、Telegram、Discord、飞书等多种聊天应用。
在 Windows 和 macOS 环境下部署 OpenClaw 时,环境配置和渠道对接往往是最大的难点。本文将完整记录从 Node.js 环境准备到多平台集成的全流程,重点分享 WSL2 推荐方案及常见坑的避坑经验。
安装前准备
系统要求
| 依赖项 | 版本要求 | 说明 |
|---|
| Node.js | ≥ 22 | 核心运行环境 |
| 操作系统 | Windows/macOS/Linux | 推荐 WSL2 (Ubuntu) / 原生 macOS |
检查 Node.js 版本
node --version
⚠️ 注意:如果版本低于 22,请先升级 Node.js,否则后续会出现兼容性问题。
Windows 安装流程
方法一:使用安装脚本(推荐)
在 PowerShell 中运行:
iwr -useb https://openclaw.ai/install.ps1 | iex
方法二:使用 npm 安装
npm install -g openclaw@latest
方法三:使用 WSL2(⭐强烈推荐)
Windows 下直接运行有时会遇到权限或路径问题,WSL2 是更稳定的选择。
1. 安装 WSL2 Ubuntu
打开 PowerShell(管理员) 运行:
wsl --install
重启电脑并完成 Ubuntu 初始设置。
2. 在 WSL2 中安装 OpenClaw
sudo apt update && sudo apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
curl -fsSL https://openclaw.ai/install.sh | bash
运行新手引导
新手引导会帮助你完成:
✅ 配置模型和认证(推荐使用 Anthropic API Key)✅ 设置 Gateway 运行模式✅ 配置聊天渠道✅ 安装后台服务(systemd)启动 Gateway
openclaw gateway status
openclaw gateway --port 18789
openclaw gateway restart
验证安装
openclaw status
openclaw health
macOS 安装流程
方法一:使用安装脚本(推荐)
curl -fsSL https://openclaw.ai/install.sh | bash
方法二:使用 Homebrew + npm
brew install node@22
npm install -g openclaw@latest
方法三:使用 pnpm
pnpm add -g openclaw@latest
运行新手引导
openclaw onboard --install-daemon
- 选择 Gateway 运行模式(Local 或 Remote)
- 配置 AI 模型提供商(Anthropic、OpenAI 等)
- 设置认证方式(OAuth 或 API Key)
- 配置聊天渠道(WhatsApp、Telegram、飞书等)
- 安装后台服务(launchd)
启动 Gateway
openclaw gateway status
openclaw gateway --port 18789
openclaw gateway restart
访问控制界面
在浏览器中打开:http://127.0.0.1:18789/
Telegram 集成使用
1. 创建 Telegram 机器人
| 步骤 | 操作 | 说明 |
|---|
| 1 | 搜索 @BotFather | ⚠️ 认准蓝标认证账号 |
| 2 | 发送 /newbot | 创建新机器人 |
| 3 | 设置名称和用户名 | 用户名必须以 bot 结尾 |
| 4 | 复制 Token | 格式:123456:ABC-DEF1234ghIkl-zyx57W2vxxu123ew11 |
2. 配置 OpenClaw
方式一:通过向导配置(推荐)
选择 telegram 并粘贴 Bot Token。
方式二:通过环境变量
export TELEGRAM_BOT_TOKEN="你的机器人 Token"
方式三:通过配置文件
- macOS/Linux:
~/.openclaw/openclaw.json
- Windows:
%USERPROFILE%\.openclaw\openclaw.json
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "你的机器人 Token",
"dmPolicy": "pairing",
"groups": {
"*": {
"requireMention": true
}
}
}
}
}
3. 重启 Gateway
4. 测试使用
- 在 Telegram 中搜索你的机器人
- 发送第一条消息(会收到配对码)
- 批准配对:
openclaw pairing list telegram
openclaw pairing approve telegram <配对码>
5. 在群组中使用
- 将机器人添加到群组
- 默认需要
@机器人名 提及才会响应
- 配置自动响应:
requireMention: false
Telegram 常用命令
| 命令 | 说明 |
|---|
/status | 查看机器人状态 |
/reset | 重置对话会话 |
/model | 查看/切换模型 |
/activation always | 群组中始终响应 |
/activation mention | 群组中仅响应提及 |
飞书集成使用
1. 安装飞书插件
方式一:使用 openclaw plugins 命令(推荐)
openclaw plugins install @openclaw/feishu
方式二:使用 npm 全局安装(Windows 兼容性好)
npm install -g @openclaw/feishu
npm install -g @openclaw/feishu
方式三:使用 pnpm
pnpm add -g @openclaw/feishu
方式四:手动克隆源码
git clone https://github.com/openclaw/feishu.git ~/.openclaw/plugins/feishu
2. 创建飞书应用
步骤 1:创建应用
- 访问 飞书开放平台 并登录
- 点击 创建企业自建应用
- 填写应用名称和描述,选择应用图标
步骤 2:获取应用凭证
- App ID(格式如
cli_xxx)
- App Secret
步骤 3:配置应用权限
在 权限管理 页面,点击 批量导入,粘贴以下 JSON:
{
"scopes": {
"tenant": [
"aily:file:read",
"aily:file:write",
"application:application.app_message_stats.overview:readonly",
"application:application.self_manage",
"application:bot.menu:write",
"cardkit:card:write",
"contact:user.employee_id:readonly",
"corehr:file:download",
"docs:document.content:read",
"event:ip_list",
"im:chat",
"im:chat.access_event.bot_p2p_chat:read",
"im:chat.members:bot_access",
"im:message",
"im:message.group_at_msg:readonly",
"im:message.group_msg",
"im:message.p2p_msg:readonly",
"im:message:readonly",
"im:message:send_as_bot",
"im:resource",
"sheets:spreadsheet",
"wiki:wiki:readonly"
],
"user": [
"aily:file:read",
"aily:file:write",
"im:chat.access_event.bot_p2p_chat:read"
]
}
}
步骤 4:启用机器人能力
步骤 5:配置事件订阅
⚠️ 重要:确保 OpenClaw Gateway 已启动
- 选择 使用长连接接收事件(WebSocket 模式)
- 添加事件:
im.message.receive_v1
步骤 6:发布应用
- 在 版本管理与发布 页面创建版本
- 提交审核并发布
- 等待管理员审批(自己就是管理员则自动通过)
3. 配置 OpenClaw
方式一:通过向导配置
选择 feishu 并输入 App ID 和 App Secret。
方式二:通过环境变量
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
方式三:通过配置文件
{
"channels": {
"feishu": {
"enabled": true,
"dmPolicy": "pairing",
"accounts": {
"main": {
"appId": "cli_xxx",
"appSecret": "xxx",
"botName": "我的 AI 助手"
}
}
}
}
}
4. 重启 Gateway
5. 测试使用
- 在飞书中找到你的机器人并发送消息
- 首次会收到配对码,批准配对:
openclaw pairing list feishu
openclaw pairing approve feishu <配对码>
6. 在群组中使用
- 将机器人添加到群组
- 默认需要
@机器人 提及才会响应
- 配置示例:
{
"channels": {
"feishu": {
"groups": {
"oc_xxx": {
"requireMention": false
}
}
}
}
}
飞书常用命令
| 命令 | 说明 |
|---|
/status | 查看机器人状态 |
/reset | 重置对话会话 |
/model | 查看/切换模型 |
常见坑和注意点
🔴 Windows 通用问题
1. WSL2 网络访问问题
- 确保在 WSL2 中使用
0.0.0.0 或 lan 模式
- 使用 Windows 防火墙规则允许端口 18789
- 或使用
http://localhost:18789/ 在宿主机访问
2. Node.js 版本管理
- 在 WSL2 中使用 NodeSource 官方包安装
- 避免使用 nvm/fnm(服务不会加载 shell 初始化)
- 运行
openclaw doctor 检查环境
3. 权限问题
openclaw gateway install --force
openclaw logs --follow
4. 端口占用
netstat -ano | findstr :18789
openclaw gateway --port 19001
5. spawn EINVAL 错误
现象:运行 openclaw plugins install @openclaw/feishu 时报错:
Failed to start CLI: Error: spawn EINVAL
原因:Windows PowerShell 与 Node.js 的 spawn 调用存在兼容性问题
| 方案 | 命令 |
|---|
| 方案一(推荐) | npm install -g @openclaw/feishu |
| 方案二:使用 CMD | 在 CMD 中运行(非 PowerShell) |
| 方案三:使用 WSL2 | 在 WSL2 Ubuntu 中运行 |
| 方案四:手动克隆 | git clone https://github.com/openclaw/feishu.git "$HOME\.openclaw\plugins\feishu" |
🔵 macOS 通用问题
1. 权限授予时应用崩溃
tccutil reset All bot.molt.mac.debug
2. Gateway 卡在 'Starting…'
openclaw gateway stop
lsof -nP -iTCP:18789 -sTCP:LISTEN
openclaw logs --follow
3. LaunchAgent 服务异常
openclaw gateway status
tail -f ~/.openclaw/logs/gateway.log
tail -f ~/.openclaw/logs/gateway.err.log
openclaw gateway install --force
4. PATH 环境变量问题
- macOS 服务最小 PATH:
/opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
- 将依赖工具路径放入
~/.openclaw/.env
- 或设置
tools.exec.pathPrepend 配置
🟢 跨平台共同问题
1. Node 版本要求
| 问题 | 解决方案 |
|---|
| Node 版本低于 22 | 安装 Node 22+,使用官方安装包 |
| Bun 运行时不兼容 | 使用 Node.js 运行 Gateway(推荐) |
2. 认证配置问题
openclaw models status
openclaw models auth setup-token --provider anthropic
3. 配置文件位置混乱
| 配置文件 | macOS/Linux | Windows |
|---|
| 主配置 | ~/.openclaw/openclaw.json | %USERPROFILE%\.openclaw\openclaw.json |
| 认证配置 | ~/.openclaw/credentials/ | %USERPROFILE%\.openclaw\credentials\ |
建议:运行 openclaw doctor 检查配置
4. 渠道不响应
openclaw gateway status
openclaw channels status --probe
openclaw logs --follow
5. 配对码问题
openclaw pairing list <channel>
openclaw pairing approve <channel> <code>
6. 媒体文件大小限制
| 平台 | 图片 | 音视频 | 文档 |
|---|
| WhatsApp | 6MB | 16MB | 100MB |
| Telegram | 5MB | - | - |
| 飞书 | 30MB | - | - |
7. 内存占用过高
{
"session": {
"historyLimit": 100,
"reset": {
"mode": "daily",
"atHour": 4
}
}
}
8. 网络连接问题
🛠️ 调试建议
openclaw status
openclaw status --all
openclaw status --deep
openclaw logs --follow
openclaw health
openclaw doctor
📞 获取帮助
附录:命令速查表
安装和配置
openclaw onboard
openclaw channels add
openclaw configure
openclaw config set <key> <value>
Gateway 管理
openclaw gateway status
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway install
openclaw gateway uninstall
渠道管理
openclaw channels login
openclaw channels logout
openclaw channels status
openclaw channels status --probe
配对管理
openclaw pairing list <channel>
openclaw pairing approve <channel> <code>
日志和诊断
openclaw logs --follow
openclaw logs --limit 100
openclaw status --all
openclaw doctor
openclaw doctor --fix
模型管理
openclaw models list
openclaw models status
openclaw models auth setup-token
发送测试消息
openclaw message send --target <number> --message "Hello"
配置文件位置对照表
| 配置文件 | macOS/Linux 位置 | Windows 位置 |
|---|
| 主配置文件 | ~/.openclaw/openclaw.json | %USERPROFILE%\.openclaw\openclaw.json |
| 认证配置 | ~/.openclaw/credentials/ | %USERPROFILE%\.openclaw\credentials\ |
| 会话文件 | ~/.openclaw/agents/<agentId>/sessions/ | %USERPROFILE%\.openclaw\agents\<agentId>\sessions\ |
| 媒体缓存 | ~/.openclaw/media/ | %USERPROFILE%\.openclaw\media\ |
| 日志文件 | /tmp/openclaw/openclaw-YYYY-MM-DD.log | %USERPROFILE%\.openclaw\logs\ |
相关免费在线工具
- RSA密钥对生成器
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
- Mermaid 预览与可视化编辑
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
- Keycode 信息
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具,Keycode 信息在线工具,online
- Escape 与 Native 编解码
JavaScript 字符串转义/反转义;Java 风格 \uXXXX(Native2Ascii)编码与解码。 在线工具,Escape 与 Native 编解码在线工具,online
- JavaScript / HTML 格式化
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具,JavaScript / HTML 格式化在线工具,online
- JavaScript 压缩与混淆
Terser 压缩、变量名混淆,或 javascript-obfuscator 高强度混淆(体积会增大)。 在线工具,JavaScript 压缩与混淆在线工具,online