OpenClaw下载安装配置|Windows安装流程|macOS 安装流程|Telegram 集成使用|飞书集成使用|常见坑和注意事项保姆级教程

Ne0inhk

— 14 min read
OpenClaw下载安装配置|Windows安装流程|macOS 安装流程|Telegram 集成使用|飞书集成使用|常见坑和注意事项保姆级教程

🦞 OpenClaw 保姆级部署教程：Windows/macOS 全平台安装 + Telegram/飞书双端集成实战

作者：猫头虎AI | 阅读时间：约 25 分钟 | 难度：⭐⭐⭐☆☆

因为🦞实在太火了，加上看多了AI相关的东西搞得人很焦虑，所以还是打算自己部署一下找点自我安慰吧🤷。先不说我能用来干啥，就想探一探它这么火的原因😮‍💨

在Windows中折腾了一天，终于算是初步跑通了，并配置了 Telegram 和 飞书 两个 channel。本文将完整记录从环境准备到多平台集成的全流程，帮你避开我踩过的所有坑。

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
# 更新系统sudoapt update &&sudoapt upgrade -y# 安装 Node.js 22curl-fsSL https://deb.nodesource.com/setup_22.x |sudo-Ebash - sudoapt-getinstall-y nodejs # 安装 OpenClawcurl-fsSL https://openclaw.ai/install.sh |bash

运行新手引导

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

新手引导会帮助你完成：

  • ✅ 配置模型和认证（推荐使用 Anthropic API Key）
  • ✅ 设置 Gateway 运行模式
  • ✅ 配置聊天渠道
  • ✅ 安装后台服务（systemd）

启动 Gateway

# 查看服务状态 openclaw gateway status # 手动启动 openclaw gateway --port18789# 重启服务 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 # 安装 OpenClawnpminstall-g openclaw@latest

方法三：使用 pnpm

pnpmadd-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 --port18789# 重启服务 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。

方式二：通过环境变量
exportTELEGRAM_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/Linuxnpminstall-g @openclaw/feishu # Windows PowerShellnpminstall-g @openclaw/feishu
方式三：使用 pnpm
pnpmadd-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。

方式二：通过环境变量
exportFEISHU_APP_ID="cli_xxx"exportFEISHU_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 --port19001
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 --limit100# 查看最近日志 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\

💬 写在最后

部署 OpenClaw 的过程确实需要一些耐心，特别是在 Windows 环境下。但一旦跑通，拥有一个属于自己的 AI 智能体网关还是非常值得的。

如果你在部署过程中遇到其他问题，欢迎在评论区留言交流！

如果觉得本文对你有帮助，不妨点个赞👍、收藏⭐，让更多人看到！

Read more

Flutter 组件 pos 适配鸿蒙 HarmonyOS 实战：ESC/POS 硬件协议通信，构建高性能零售收银与物联网打印架构

Flutter 组件 pos 适配鸿蒙 HarmonyOS 实战：ESC/POS 硬件协议通信，构建高性能零售收银与物联网打印架构

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net Flutter 组件 pos 适配鸿蒙 HarmonyOS 实战：ESC/POS 硬件协议通信，构建高性能零售收银与物联网打印架构 前言 在鸿蒙（OpenHarmony）生态迈向专业收银终端、涉及智慧零售设备、数字化仓储标签打印及餐饮自助化服务的背景下，如何实现与热敏打印机（Thermal Printer）等硬件设备的底噪、高可靠通讯，已成为决定商业应用“交易闭环效率”的关键。在鸿蒙设备这类强调硬件直控能力（Raw IO）与实时系统响应的环境下，如果应用依然依赖图形化的截屏打印或低效的中间件转发，由于由于图像编解码的巨大算力消耗，极易由于由于“内存瞬时溢出”导致收银终端在高峰期发生严重卡顿。 我们需要一种能够直接生成热敏指令流（Hex Commands）、支持多种传输通道（蓝牙/Wi-Fi/USB）且符合行业标准（ESC/POS）的高性能控制方案。 pos

By Ne0inhk
时序数据库 Apache IoTDB：从边缘到云端Apache IoTDB 全链路数据管理能力、部署流程与安全特性解读

时序数据库 Apache IoTDB：从边缘到云端Apache IoTDB 全链路数据管理能力、部署流程与安全特性解读

时序数据库 Apache IoTDB：从边缘到云端Apache IoTDB 全链路数据管理能力、部署流程与安全特性解读 前言 大数据与物联网技术飞速发展的今天，时序数据呈现出爆发式增长的态势，从工业传感器的实时监控数据到智能设备的运行日志，从金融交易的时序记录到新能源汽车的工况数据，时序数据已成为企业数字化转型的核心资产，选择一款合适的时序数据库，直接关系到数据存储效率、分析能力与业务价值挖掘。 本文将从时序数据库的核心需求出发，结合大数据场景特点，通过与国外主流产品的对比分析，重点阐述 Apache IoTDB 在选型中的核心优势。 Apache IoTDB 介绍 Apache IoTDB 是由中科院软件所主导研发的开源时序数据库，专为物联网与工业大数据场景设计，以高性能、轻量级、易扩展为核心特点，通过三层数据模型与多级存储引擎，实现对海量时序数据的高效存储、快速查询与全生命周期管理，已成为国产化时序数据管理的标杆产品 ✅极致的性能表现：采用 TsFile 存储结构与多维索引体系，单节点每秒可处理数百万数据点写入，复杂聚合查询响应达毫秒级，结合差值编码等压缩算法，数据压缩

By Ne0inhk
程序员必看！VSCode Remote+cpolar让Mac和Linux无缝协作，代码随身走

程序员必看！VSCode Remote+cpolar让Mac和Linux无缝协作，代码随身走

文章目录 * 前言 * 1.WSL 环境下网络诊断 * 2.安装cpolar实现随时随地开发 * 3.配置公网地址 * 4.VsCode 远程连接开发环境 * 5.保留固定TCP公网地址 * 总结 前言 作为全栈开发者，你是否受够了在公司MacBook和家里Windows PC间同步开发环境的痛苦？VSCode Remote-SSH插件彻底终结了这种折腾——只需一次配置，就能让本地编辑器直接访问远程服务器的文件系统和终端，无论是修改Node.js后端还是调试Python脚本，都像在本地操作般流畅。我司前端团队通过这种方式，成功实现设计师用MacBook编辑React组件，后端工程师用Linux工作站调试API，代码实时同步且环境完全一致。 最让我惊喜的是VSCode Remote的端口转发功能。上次开发微信小程序时，后端服务运行在阿里云服务器，通过Remote-SSH转发3000端口后，本地IDE直接访问localhost就能调试接口，省去了配置Nginx反向代理的麻烦。而WSL2环境下的Docker容器，更是可以通过这种方式暴露给局域网其他设备，实现"Wi

By Ne0inhk
Linux《进度条》

Linux《进度条》

在之前的Linux基础开发工具当中我们已经了解了vim、gcc、makefile等基本的开发工具，那么有了这些开发工具我们就可以来实现我们Linux旅程当中的第一个程序——进度条。相信通过该项目的实现能让你对vim等开发工具更加的熟悉。一起加油吧！！！ 1.补充知识回车与换行  在实现进度条的项目之前我们先要来了解关于回车和换行的基础补充知识，在了解之后才能让接下来的项目的编写更加的顺畅。 首先我们要了解的是回车和换行有什么区别，此时你可能就会疑惑这两个实现的效果不是一样的吗？我们在点击回车的时候不就是实现了换行了吗？ 其实这两个实现的效果是不同的，只不过在现代的计算机当中基本将这两个概念不进行区分了，但在上个实际使用的老式打字机上换行自是将对应的纸向下移动，而要将实现回车还需要将指针移动回起始位置。 那通过以上的示例就可以理解在现代的计算机当中回车其实是 换行+回车 的，通过以下的老式键盘就可以看出这一特点 其实在之前在C语言当中使用的\n就是本质上就是实现了换行+回车的功能，\r实现的就是回车的功能。  2.练手小程序——倒计时 以上我

By Ne0inhk