跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客GitHub 精选镜像工具UI配色美学隐私政策关于联系
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
JavaScriptNode.jsAI

OpenClaw 全平台安装与 Telegram/飞书集成部署指南

综述由AI生成OpenClaw AI 智能体网关在 Windows 和 macOS 系统上的安装部署流程。内容包括环境准备（Node.js 版本检查）、多种安装方式（脚本、npm、WSL2）、新手引导配置以及 Telegram 和飞书渠道的集成步骤。文章还涵盖了常见问题排查（如网络访问、权限、端口占用）及调试建议，帮助用户快速搭建本地 AI 助手并实现多平台消息互通。

SparkGeek发布于 2026/3/23更新于 2026/5/291.4K 浏览
OpenClaw 全平台安装与 Telegram/飞书集成部署指南

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
# 安装 Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

运行新手引导

# 在 WSL2 终端中运行 openclaw onboard --install-daemon

新手引导会帮助你完成：

  • ✅ 配置模型和认证（推荐使用 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

# 安装 Node.js 22
brew install node@22
# 安装 OpenClaw
npm install -g openclaw@latest

方法三：使用 pnpm

pnpm add -g openclaw@latest

运行新手引导

# 安装并启动服务
openclaw onboard --install-daemon

新手引导步骤：

  1. 选择 Gateway 运行模式（Local 或 Remote）
  2. 配置 AI 模型提供商（Anthropic、OpenAI 等）
  3. 设置认证方式（OAuth 或 API Key）
  4. 配置聊天渠道（WhatsApp、Telegram、飞书等）
  5. 安装后台服务（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

方式一：通过向导配置（推荐）
openclaw channels add

选择 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

openclaw gateway restart

4. 测试使用

  1. 在 Telegram 中搜索你的机器人
  2. 发送第一条消息（会收到配对码）
  3. 批准配对：
openclaw pairing list telegram
openclaw pairing approve telegram <配对码>
  1. 批准后即可正常对话

⚠️ 网络问题：如果聊天没反应，需配置代理。

5. 在群组中使用

  1. 将机器人添加到群组
  2. 默认需要 @机器人名 提及才会响应
  3. 配置自动响应：requireMention: false

Telegram 常用命令

命令说明
/status查看机器人状态
/reset重置对话会话
/model查看/切换模型
/activation always群组中始终响应
/activation mention群组中仅响应提及

飞书集成使用

1. 安装飞书插件

方式一：使用 openclaw plugins 命令（推荐）
openclaw plugins install @openclaw/feishu
方式二：使用 npm 全局安装（Windows 兼容性好）
# macOS/Linux
npm install -g @openclaw/feishu
# Windows PowerShell
npm install -g @openclaw/feishu
方式三：使用 pnpm
pnpm add -g @openclaw/feishu
方式四：手动克隆源码
git clone https://github.com/openclaw/feishu.git ~/.openclaw/plugins/feishu

2. 创建飞书应用

步骤 1：创建应用
  1. 访问 飞书开放平台 并登录
  2. 点击 创建企业自建应用
  3. 填写应用名称和描述，选择应用图标
步骤 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：启用机器人能力

在 应用能力 > 机器人 页面：

  1. 开启机器人能力
  2. 配置机器人名称
步骤 5：配置事件订阅

⚠️ 重要：确保 OpenClaw Gateway 已启动

在 事件订阅 页面：

  1. 选择 使用长连接接收事件（WebSocket 模式）
  2. 添加事件：im.message.receive_v1
步骤 6：发布应用
  1. 在 版本管理与发布 页面创建版本
  2. 提交审核并发布
  3. 等待管理员审批（自己就是管理员则自动通过）

3. 配置 OpenClaw

方式一：通过向导配置
openclaw channels add

选择 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

openclaw gateway restart

5. 测试使用

  1. 在飞书中找到你的机器人并发送消息
  2. 首次会收到配对码，批准配对：
openclaw pairing list feishu
openclaw pairing approve feishu <配对码>
  1. 批准后即可正常对话

6. 在群组中使用

  1. 将机器人添加到群组
  2. 默认需要 @机器人 提及才会响应
  3. 配置示例：
{"channels":{"feishu":{"groups":{"oc_xxx":{"requireMention":false}}}}}

飞书常用命令

命令说明
/status查看机器人状态
/reset重置对话会话
/model查看/切换模型

常见坑和注意点

🔴 Windows 通用问题

1. WSL2 网络访问问题

现象：Gateway 无法从宿主机访问

解决方案：

  • 确保在 WSL2 中使用 0.0.0.0 或 lan 模式
  • 使用 Windows 防火墙规则允许端口 18789
  • 或使用 http://localhost:18789/ 在宿主机访问
2. Node.js 版本管理

现象：系统 Node.js 版本过低或版本混乱

解决方案：

  • 在 WSL2 中使用 NodeSource 官方包安装
  • 避免使用 nvm/fnm（服务不会加载 shell 初始化）
  • 运行 openclaw doctor 检查环境
3. 权限问题

现象：权限不足导致服务无法启动

# 确保服务正确安装
openclaw gateway install --force
# 检查日志
openclaw logs --follow
4. 端口占用

现象：端口 18789 已被占用

# 查看占用进程
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. 权限授予时应用崩溃

现象：点击隐私提示的"允许"时应用消失

# 重置 TCC 缓存
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
# 查看 launchd 日志
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/LinuxWindows
主配置~/.openclaw/openclaw.json%USERPROFILE%\.openclaw\openclaw.json
认证配置~/.openclaw/credentials/%USERPROFILE%\.openclaw\credentials\

建议：运行 openclaw doctor 检查配置

4. 渠道不响应

排查步骤：

# 1. 检查网关状态
openclaw gateway status
# 2. 检查渠道状态
openclaw channels status --probe
# 3. 查看实时日志
openclaw logs --follow
5. 配对码问题

现象：未批准配对，机器人不回复

# 查看待审批列表
openclaw pairing list <channel>
# 批准配对
openclaw pairing approve <channel><code>
6. 媒体文件大小限制
平台图片音视频文档
WhatsApp6MB16MB100MB
Telegram5MB--
飞书30MB--
7. 内存占用过高
{"session":{"historyLimit":100,"reset":{"mode":"daily","atHour":4}}}
8. 网络连接问题

现象：国内网络访问某些 API 困难

解决方案：

  • 配置代理
  • 检查防火墙规则

🛠️ 调试建议

当遇到问题时，按以下顺序排查：

# 1. 快速状态检查
openclaw status
# 2. 深度诊断
openclaw status --all
openclaw status --deep
# 3. 查看日志
openclaw logs --follow
# 4. 检查健康状态
openclaw health
# 5. 运行诊断工具
openclaw doctor

📞 获取帮助

  1. 查看日志：/tmp/openclaw/ 目录下的日志文件
  2. 官方文档：https://docs.openclaw.ai/zh-CN
  3. GitHub Issue：提交时包含：
    • OpenClaw 版本
    • 相关日志片段
    • 重现步骤
    • 配置文件（隐藏密钥）

附录：命令速查表

安装和配置

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 # 登录渠道（如 WhatsApp QR）
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\

目录

  1. OpenClaw 全平台安装与 Telegram/飞书集成部署指南
  2. 安装前准备
  3. 系统要求
  4. 检查 Node.js 版本
  5. Windows 安装流程
  6. 方法一：使用安装脚本（推荐）
  7. 方法二：使用 npm 安装
  8. 方法三：使用 WSL2（⭐强烈推荐）
  9. 1. 安装 WSL2 Ubuntu
  10. 2. 在 WSL2 中安装 OpenClaw
  11. 更新系统
  12. 安装 Node.js 22
  13. 安装 OpenClaw
  14. 运行新手引导
  15. 在 WSL2 终端中运行 openclaw onboard --install-daemon
  16. 启动 Gateway
  17. 查看服务状态
  18. 手动启动
  19. 重启服务
  20. 验证安装
  21. macOS 安装流程
  22. 方法一：使用安装脚本（推荐）
  23. 方法二：使用 Homebrew + npm
  24. 安装 Node.js 22
  25. 安装 OpenClaw
  26. 方法三：使用 pnpm
  27. 运行新手引导
  28. 安装并启动服务
  29. 启动 Gateway
  30. 查看服务状态
  31. 手动启动
  32. 重启服务
  33. 访问控制界面
  34. Telegram 集成使用
  35. 1. 创建 Telegram 机器人
  36. 2. 配置 OpenClaw
  37. 方式一：通过向导配置（推荐）
  38. 方式二：通过环境变量
  39. 方式三：通过配置文件
  40. 3. 重启 Gateway
  41. 4. 测试使用
  42. 5. 在群组中使用
  43. Telegram 常用命令
  44. 飞书集成使用
  45. 1. 安装飞书插件
  46. 方式一：使用 openclaw plugins 命令（推荐）
  47. 方式二：使用 npm 全局安装（Windows 兼容性好）
  48. macOS/Linux
  49. Windows PowerShell
  50. 方式三：使用 pnpm
  51. 方式四：手动克隆源码
  52. 2. 创建飞书应用
  53. 步骤 1：创建应用
  54. 步骤 2：获取应用凭证
  55. 步骤 3：配置应用权限
  56. 步骤 4：启用机器人能力
  57. 步骤 5：配置事件订阅
  58. 步骤 6：发布应用
  59. 3. 配置 OpenClaw
  60. 方式一：通过向导配置
  61. 方式二：通过环境变量
  62. 方式三：通过配置文件
  63. 4. 重启 Gateway
  64. 5. 测试使用
  65. 6. 在群组中使用
  66. 飞书常用命令
  67. 常见坑和注意点
  68. 🔴 Windows 通用问题
  69. 1. WSL2 网络访问问题
  70. 2. Node.js 版本管理
  71. 3. 权限问题
  72. 确保服务正确安装
  73. 检查日志
  74. 4. 端口占用
  75. 查看占用进程
  76. 或使用不同端口
  77. 5. spawn EINVAL 错误
  78. 🔵 macOS 通用问题
  79. 1. 权限授予时应用崩溃
  80. 重置 TCC 缓存
  81. 2. Gateway 卡在 "Starting…"
  82. 停止监管程序
  83. 检查端口占用
  84. 查看日志
  85. 3. LaunchAgent 服务异常
  86. 检查服务状态
  87. 查看 launchd 日志
  88. 重新安装服务
  89. 4. PATH 环境变量问题
  90. 🟢 跨平台共同问题
  91. 1. Node 版本要求
  92. 2. 认证配置问题
  93. 检查认证状态
  94. 为智能体设置认证
  95. 3. 配置文件位置混乱
  96. 4. 渠道不响应
  97. 1. 检查网关状态
  98. 2. 检查渠道状态
  99. 3. 查看实时日志
  100. 5. 配对码问题
  101. 查看待审批列表
  102. 批准配对
  103. 6. 媒体文件大小限制
  104. 7. 内存占用过高
  105. 8. 网络连接问题
  106. 🛠️ 调试建议
  107. 1. 快速状态检查
  108. 2. 深度诊断
  109. 3. 查看日志
  110. 4. 检查健康状态
  111. 5. 运行诊断工具
  112. 📞 获取帮助
  113. 附录：命令速查表
  114. 安装和配置
  115. Gateway 管理
  116. 渠道管理
  117. 配对管理
  118. 日志和诊断
  119. 模型管理
  120. 发送测试消息
  121. 配置文件位置对照表
  • 💰 8折买阿里云服务器限时8折了解详情
  • Magick API 一键接入全球大模型注册送1000万token查看
  • 🤖 一键搭建Deepseek满血版了解详情
  • 一键打造专属AI 智能体了解详情
极客日志微信公众号二维码

微信扫一扫，关注极客日志

微信公众号「极客日志V2」，在微信中扫描左侧二维码关注。展示文案：极客日志V2 zeeklog

更多推荐文章

查看全部
  • 基于 Spring Boot 和 Leaflet 的省级旅游口号 WebGIS 可视化实现
  • Midjourney 进阶：色相详解与色彩控制
  • QClaw 本地 AI 助手接入微信的使用指南
  • C++ 模板编程：typename 用法与分离编译问题解析
  • Spring Boot 实战：基于 WebSocket 的前后端实时匹配系统实现
  • OpenClaw 浏览器控制：利用 Chrome Debug 模式实现持久化登录与自动化
  • LoRA 训练助手：快速生成 Stable Diffusion 专业训练标签
  • VSCode 远程连接时 Copilot Chat 图标不显示修复方案
  • Ubuntu 22.04.5 安装后 SSH 远程连接失败的排查步骤
  • 论文笔记 DiT：基于 Transformer 的可扩展扩散模型
  • 10 款主流 AI 降重工具对比与选型建议
  • CRITIC 模型与脑机协同：程序员代码记忆决策与认知增强实践
  • Kotlin 语言核心特性与常见陷阱测试题解析
  • Linux 进程替换详解：从 fork 到 exec 的完整链路
  • Ubuntu 20.04 手动安装与配置 Ollama 本地服务
  • IntelliJ IDEA 集成 GitHub Copilot 实战指南
  • 华为 OD 机试双机位 C 卷 - 评委评分与选手排名
  • 数据结构核心：顺序表的原理与模拟实现
  • Python 自动化测试工具 Selenium 核心详解与实战
  • uniapp 通用价格组件开发与 DCloud 插件市场发布指南

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online

  • 随机西班牙地址生成器

    随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online

  • Keycode 信息

    查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online

  • Escape 与 Native 编解码

    JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online

  • JavaScript / HTML 格式化

    使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online