OpenClaw 安装与飞书机器人配置实战指南
OpenClaw 是一个开源的 AI Agent 框架，核心功能在于构建私人 AI 助手，支持接入飞书、Telegram、WhatsApp 等多种聊天平台。其架构逻辑清晰：用户消息经由网关转发至 AI 模型处理，再将回复返回给用户。
选择该框架的主要优势包括数据自托管以保障隐私、支持多模型（Claude、GPT、Gemini 等）以及可扩展的 Skill 系统。以下将介绍从环境准备到飞书对接的全流程配置。
环境准备
系统要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux / macOS / Windows (WSL2) |
| Node.js | v22 或更高 |
| 网络 | 需能访问飞书开放平台及 AI API |
安装 Node.js
若未安装或版本过低，建议使用 nvm 管理：
# 检查当前版本
node --version
# 安装并切换到 v22
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
输入 node --version 显示 v22.x.x 即表示安装成功。
安装 OpenClaw
一键安装
macOS / Linux：
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (PowerShell)：
iwr -useb https://openclaw.ai/install.ps1 | iex
安装完成后验证版本号：
openclaw --version
手动安装
若脚本执行异常，可使用 npm 全局安装：
npm install -g openclaw
注意：遇到权限错误时，建议调整 npm 目录权限而非直接使用 sudo。
初始配置
运行引导向导完成基础设置：
openclaw onboard --install-daemon
此命令会引导配置 AI 模型密钥、Gateway 端口（默认 18789）等信息。--install-daemon 参数会将 Gateway 注册为系统服务，实现开机自启。
配置后检查状态：
openclaw gateway status
显示 running 即表示基础服务正常。此时可通过 Web UI 进行初步测试：
openclaw dashboard
浏览器将自动打开 http://127.0.0.1:18789。
飞书机器人配置
1. 安装插件
OpenClaw 通过插件支持飞书，先安装对应模块：
openclaw plugins install @openclaw/feishu
openclaw gateway restart
2. 飞书开放平台操作
登录 飞书开放平台，创建企业自建应用。
- 获取凭证：在「凭证与基础信息」页面复制 App ID 和 App Secret，务必妥善保管。
- 权限开通：进入「权限管理」批量开通以下权限：
{"scopes":{"tenant":["im:message","im:message.group_at_msg:readonly","im:message.p2p_msg:readonly","im:message:readonly","im:message:send_as_bot","im:resource","im:chat.access_event.bot_p2p_chat:read","im:chat.members:bot_access","contact:user.employee_id:readonly"],"user":["im:chat.access_event.bot_p2p_chat:read"]}} - 开启机器人能力：在「应用能力」中启用机器人并设置名称。
- 事件订阅：这是关键步骤。选择「使用长连接接收事件」（WebSocket），添加
im.message.receive_v1事件。注意：必须确保 OpenClaw Gateway 正在运行，否则飞书无法检测到 WebSocket 连接端点。 - 发布应用：提交审核并发布，未发布前权限不生效。
3. OpenClaw 侧配置
推荐通过交互式向导添加渠道：
openclaw channels add
选择 Feishu 并按提示输入 App ID 和 App Secret。也可手动编辑配置文件 ~/.openclaw/openclaw.json：
{"channels":{"feishu":{"enabled":true,"dmPolicy":"pairing","accounts":{"main":{"appId":"cli_xxxxxxxxx","appSecret":"你的 AppSecret"}}}}}
修改后重启 Gateway：
openclaw gateway restart
4. 联调测试
- 在飞书中向机器人发送消息（如'你好'）。
- 机器人会返回配对码。
- 终端执行确认：
openclaw pairing approve feishu <配对码> - 配对成功后即可正常对话。
常见问题与排查
- 事件订阅保存失败：通常因 Gateway 未启动导致。请先运行
openclaw gateway start确认状态后再配。 - 机器人无响应：检查应用是否已发布、事件订阅是否包含
im.message.receive_v1、是否选择了长连接模式。查看日志定位问题：openclaw logs --follow - 群聊不回复：默认需@机器人。若需免@回复，需在配置中关闭
requireMention，并确保机器人已加入群组。 - 权限报错：飞书权限粒度较细，缺权限会导致特定功能失效。如有文档或表格操作需求，需补充
docx:document或bitable:app等权限并重新发布。 - Node.js 版本过低：OpenClaw 依赖 Node.js 22+，旧版本可能导致启动异常，请通过 nvm 升级。
常用命令速查
| 命令 | 用途 |
|---|---|
openclaw gateway status | 查看 Gateway 状态 |
openclaw gateway restart | 重启 Gateway |
openclaw logs --follow | 实时查看日志 |
openclaw channels add | 添加聊天渠道 |
openclaw pairing list feishu | 查看配对请求 |
openclaw dashboard | 打开 Web 控制面板 |
openclaw doctor | 健康检查与修复 |
在飞书内可使用的指令包括 /status（状态）、/reset（重置对话）、/model（切换模型）。