跳到主要内容 OpenClaw 全平台安装与 Telegram/飞书集成部署指南 | 极客日志
JavaScript Node.js AI
OpenClaw 全平台安装与 Telegram/飞书集成部署指南 OpenClaw AI 智能体网关在 Windows 和 macOS 系统上的安装部署流程。内容包括环境准备（Node.js 版本检查）、多种安装方式（脚本、npm、WSL2）、新手引导配置以及 Telegram 和飞书渠道的集成步骤。文章还涵盖了常见问题排查（如网络访问、权限、端口占用）及调试建议，帮助用户快速搭建本地 AI 助手并实现多平台消息互通。
SparkGeek 发布于 2026/3/23 更新于 2026/4/17 OpenClaw 全平台安装与 Telegram/飞书集成部署指南
OpenClaw 是一个适用于任何操作系统的 AI 智能体 Gateway 网关，支持 WhatsApp、Telegram、Discord、飞书等多种聊天应用。
安装前准备
系统要求
依赖项 版本要求 说明 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（⭐强烈推荐）
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
微信扫一扫，关注极客日志 微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
相关免费在线工具 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
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.jsonWindows : %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\
