之OpenClaw的飞书接入与skills技能的使用和解析)
1. 为什么要把 OpenClaw 接进飞书群聊
OpenClaw 自带的 Web UI 在浏览器里点几下还行，真到日常运维场景就有点别扭：服务器告警来了，你还得切浏览器、找标签页、敲指令；同事想让你帮忙看个日志，你只能截图发过去。飞书是大多数团队已经在用的沟通工具，把 OpenClaw 接进飞书群聊，等于给运维机器人开了一个随时能 @ 的入口。
我这次要做的链路是：飞书自建应用负责收消息，OpenClaw 负责理解意图并调用 skills 技能执行，结果再回到飞书。整条链路里有两个关键点，一个是飞书侧的事件订阅和权限配置，另一个是 OpenClaw 侧的 skills 技能目录加载。前者决定消息能不能进来，后者决定机器人能不能干活。
适合谁看：已经在服务器上装好 OpenClaw、想把它从 Web UI 搬到飞书群里的运维同学；或者想给团队做一个能查磁盘、看日志、跑巡检的聊天机器人，但不想从零写框架的人。下面我会按“飞书配置 → OpenClaw 接入 → skills 目录 → 验证 → 排障”的顺序走一遍，命令和配置都能直接复制。
先说清楚一个概念：OpenClaw 的 skills 不是插件市场里那种点一下安装就完事的东西，它更像一份写给 AI 看的作业指导书。SKILL.md 定义“你是谁、遇到什么情况该怎么做”，scripts 目录放实际执行的脚本，references 目录放大模型需要参考的背景知识。飞书只是入口，真正让机器人有运维能力的是 skills。
2. 飞书自建应用配置与 OpenClaw 接入前置
这一章解决“消息怎么从飞书进到 OpenClaw”。很多人卡在权限没开全或者事件订阅方式选错，导致机器人收不到消息。
2.1 创建企业自建应用并开启长连接
打开飞书开放平台，进开发者后台，创建一个企业自建应用，比如叫openclaw-robot。创建完先别急着发版本，去左侧菜单「事件与回调」→「事件配置」。
订阅方式这里要选「使用长连接接收事件」，然后保存。选长连接的好处是不用暴露公网回调地址，OpenClaw 所在服务器只要能出网就能收事件，省掉内网穿透那一堆事。
保存后添加事件im.message.receive_v1，这是接收消息的核心事件。添加时会提示你开通对应权限，点确认就行。
2.2 权限清单：少一个都收不到消息
在「权限管理」里搜索并开通下面这些权限。我把必须的和可选的列成表，方便你对照：
| 权限名称 | 作用 | 是否必须 |
|---|---|---|
| im:message | 接收与发送单聊消息 | 必须 |
| im:message:send_as_bot | 以机器人身份发送消息 | 必须 |
| im:chat | 读取群组信息、发送群聊消息 | 必须 |
| im:chat:readonly | 读取群聊信息 | 必须 |
| im:resource | 处理图片/文件 | 建议 |
| contact:user.base:readonly | 获取用户基本信息 | 建议 |
| im:message.p2p_msg:readonly | 读取用户发给机器人的单聊消息 | 发布后再加 |
注意im:message.p2p_msg:readonly这个权限，应用没发布前是勾不上的。可以先跳过，等 OpenClaw 配置好、应用发布之后再回来补。
2.3 发布版本让配置生效
权限和事件都加完后，去「版本管理与发布」创建版本，填个版本号，可用范围选全员或指定部门，确认发布。发布后飞书客户端里才能搜到这个机器人。
2.4 OpenClaw 侧接入飞书
OpenClaw 侧需要拿到飞书应用的 App ID 和 App Secret，在开发者后台「凭证与基础信息」里能看到。然后在 OpenClaw 服务器上执行配置命令，把飞书渠道打开：
# 进入 OpenClaw 配置向导，选择飞书渠道 openclaw config --section channel # 或者直接编辑配置文件 ~/.openclaw/openclaw.json # 在 channels 段加入飞书配置配置文件里飞书渠道大致长这样，App ID 和 Secret 换成你自己的：
{ "channels": { "feishu": { "enabled": true, "appId": "cli_xxxxxxxxxxxx", "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxx", "connectionMode": "websocket" } } }改完重启网关：
openclaw gateway restart重启后看日志有没有飞书连接成功的记录：
openclaw gateway logs | grep -i feishu看到feishu channel connected之类的字样，说明长连接建起来了。
2.5 私聊访问控制与配对码
第一次在飞书里给机器人发消息，大概率会收到一段提示，类似：
OpenClaw: access not configured. Your Feishu user id: ou_ccc5XXXXXX Pairing code: XHULMMAU Ask the bot owner to approve with: openclaw pairing approve feishu XHULMMAU这不是报错，是 OpenClaw 的 Pairing 机制在起作用。因为机器人有执行 Shell 命令和读文件的权限，默认不允许陌生人直接使唤它。每个新用户第一次对话都会生成一个配对码，需要管理员在服务器上批准。
在 OpenClaw 服务器上执行：
openclaw pairing approve feishu XHULMMAU批准后再回飞书发消息，就能正常回复了。这个机制在群聊场景里尤其重要，能防止机器人被拉进无关群聊后被人乱调戏、白烧 token。
3. skills 技能目录结构与 SKILL.md 配置实战
飞书通道打通后，机器人能聊天了，但还不会干运维的活。这一章讲 skills 技能怎么放、SKILL.md 怎么写、clawhub 怎么用。
3.1 三种技能来源与加载优先级
OpenClaw 的技能来源分三类，路径和用途不一样：
| 来源 | 路径 | 说明 |
|---|---|---|
| openclaw-bundled | /usr/lib/node_modules/openclaw/skills/ | 内置技能，随安装包来 |
| openclaw-extra | 通过 clawhub 安装 | 社区技能，需登录下载 |
| openclaw-workspace | ~/.openclaw/workspace/skills/ | 用户自定义，推荐 |
workspace 目录下的技能会被自动识别，放进去就能用，不用重启网关。执行openclaw skills list时，来源列会显示openclaw-workspace，一眼能看出哪些是自己写的。
3.2 用 clawhub 搜索和安装技能
clawhub 是技能分发平台，官网https://clawhub.ai，用 GitHub 账号授权登录后，在 Settings → API tokens 里创建一个 token。
在 OpenClaw 服务器上安装 clawhub 命令行工具：
# 卸载旧版本 npm uninstall -g clawdhub # 安装正式包 npm install -g clawhub@latest # 配置全局软链，路径按你实际的 node 安装位置改 ln -s /data/nodejs/current/bin/clawhub /usr/local/bin/clawhub # 查看版本 clawhub -V登录并搜索安装：
# 登录，token 从 clawhub.ai 获取 clawhub login --token xxxxxx # 搜索技能 clawhub search 'linux-kernel-crash-debug' # 安装技能，会在当前目录生成 skills 目录 clawhub install 'linux-kernel-crash-debug'国内下载速度可能不理想，如果在线装不动，可以去网站手动下载技能包，解压后放到~/.openclaw/workspace/skills/下，效果一样。
3.3 手写一个自定义技能：目录结构
推荐自己写技能，可控性高，也不用担心第三方技能里藏了什么。一个技能目录长这样：
linux-skills/ ├── SKILL.md # 必需，技能定义 ├── scripts/ │ └── checkdisk.sh # 可选，可执行脚本 ├── references/ │ └── linux-list.md # 可选，参考文档 └── assets/ └── template.pdf # 可选，资源文件创建目录：
mkdir -p ~/.openclaw/workspace/skills/linux-skills/{scripts,references,assets}3.4 SKILL.md 的 frontmatter 与正文写法
SKILL.md 是核心，它决定 AI 什么时候触发这个技能、按什么逻辑执行。文件开头是 YAML frontmatter，必须包含name和description，description里要写清楚触发词，比如“磁盘、空间、巡检、诊断”，这样 Agent 推理时才能精准命中。
--- name: "linux-disk-check" description: "Linux 磁盘空间巡检技能。当用户提到磁盘、空间不足、inode、df、挂载点、清理等关键词时触发。用于诊断磁盘占用并给出清理建议。" license: "MIT" allowed-tools: - "node-connect" metadata: skill_id: "linux_disk_check_v1" version: "1.0.0" author: "OpenClaw Ops" display_name: "磁盘空间巡检" --- # Skill Name: 磁盘空间巡检专家 ## Description 你是一名 Linux 存储运维专家，负责诊断磁盘空间和 inode 使用情况，输出结构化的巡检报告。 ## Execution Logic 当用户要求检查磁盘或排查空间不足时，请遵循以下步骤： 1. **数据采集**：执行 `df -h` 和 `df -i` 获取空间与 inode 使用率。 2. **逻辑判断**：如果使用率超过 85%，则判定为高风险；超过 95% 判定为紧急。 3. **安全红线**：严禁执行 `rm -rf` 等删除操作，只输出建议。 ## Output Format 请按以下格式汇报： - **诊断结论**：... - **占用 TOP5**：... - **修复方案**：...正文控制在 500 行以内，太长会拖慢推理。复杂规则放 references 目录，别全塞进 SKILL.md。
3.5 scripts 目录：可执行脚本示例
scripts 目录放实际干活的脚本，SKILL.md 告诉框架“有这个能力”，脚本负责“把活干好”。下面是一个检查磁盘空间的脚本：
#!/bin/bash # 参数1: 挂载点 (默认 /) # 参数2: 阈值 (默认 10) MOUNT_POINT=${1:-/} THRESHOLD=${2:-10} FREE_PERCENT=$(df "$MOUNT_POINT" | awk 'NR==2 {print 100 - $5}' | tr -d '%') if ! [[ "$FREE_PERCENT" =~ ^[0-9]+$ ]]; then echo "错误: 无法获取挂载点 $MOUNT_POINT 的空间信息。" exit 1 fi if [ "$FREE_PERCENT" -lt "$THRESHOLD" ]; then echo "【警告】磁盘空间不足！" echo "挂载点: $MOUNT_POINT" echo "当前剩余: $FREE_PERCENT%" echo "占用最高的前5个文件/目录:" du -ah "$MOUNT_POINT" 2>/dev/null | sort -rh | head -n 5 else echo "【正常】挂载点 $MOUNT_POINT 空间充足，剩余 $FREE_PERCENT%。" fi给执行权限：
chmod +x ~/.openclaw/workspace/skills/linux-skills/scripts/checkdisk.sh3.6 references 目录：给大模型补背景知识
references 目录放纯知识文档，相当于本地 RAG。当技能涉及大量业务规则，写进 SKILL.md 会让文件臃肿，就放这里。比如一份巡检清单：
# 服务器巡检清单 ## 基础信息 - [ ] 系统版本和内核 - [ ] 主机名和运行时间 - [ ] 时区和时间同步 ## 硬件资源 - [ ] CPU 使用率和负载 - [ ] 内存使用率 - [ ] 磁盘空间和 inode ## 网络 - [ ] 网络接口状态 - [ ] 路由表 - [ ] 监听端口大模型在执行任务时如果觉得信息不够，会主动去读这些文件。
4. 验证请求与技能触发结果
配置写完不验证，等于没配。这一章给出从飞书发消息到技能执行的完整验证动作。
4.1 验证技能是否被加载
在服务器上执行：
# 查看技能目录 ls -la ~/.openclaw/workspace/skills/ # 查看技能列表，来源应显示 openclaw-workspace openclaw skills list # 查看某个技能详情 openclaw skills info linux-disk-check如果skills list里没有你的技能，先检查目录名和 SKILL.md 的 frontmatter 格式，YAML 缩进错了会导致解析失败。
4.2 在飞书里触发技能
打开飞书，搜索openclaw-robot，进入对话。先发一个基础指令确认通道正常：
/model status应该返回当前模型状态。然后发一个能触发磁盘巡检技能的自然语言请求：
帮我检查一下 192.168.1.136 这台服务器的磁盘空间，看看有没有风险如果技能配置正确，OpenClaw 会识别到“磁盘、检查”这些触发词，加载linux-disk-check技能，调用checkdisk.sh，然后把结果按 SKILL.md 里定义的格式返回。
4.3 让 OpenClaw 自己生成技能
如果不想手写脚本，可以直接在飞书里让 OpenClaw 生成。比如：
帮我写个 skill 脚本，通过 coffeemilk 用户连接到 192.168.1.136 服务器， 对这个服务器做登录日志巡检，并给出一份巡检报告生成的技能默认放在~/.openclaw/skill-workshop目录下。生产环境里，正式应用前先检查生成的内容有没有问题，确认无误再移到 workspace 目录。
4.4 验证技能打包
OpenClaw 源码里有个package_skill.py，能把技能目录打包成符合 clawhub 分发标准的.skill文件。它通常在skill-creator技能下：
# 路径按实际安装位置改 ls /data/nodejs/current/lib/node_modules/openclaw/skills/skill-creator/scripts/ # 验证并打包 python3 package_skill.py ~/.openclaw/workspace/skills/linux-skills注意package_skill.py依赖quick_validate.py，两个脚本要放在一起。打包好的文件默认在当前目录，以.skill结尾。
5. 常见报错排查：401、local proxy failed 与技能不触发
这一章按真实报错来，遇到问题对着查。
5.1 飞书消息发出去没反应
先看 OpenClaw 网关日志：
openclaw gateway logs | tail -50如果日志里没有收到事件的记录，大概率是飞书侧事件订阅没配好。回开发者后台检查「事件配置」里im.message.receive_v1是否添加、订阅方式是否为长连接。权限没开全也会导致事件推不过来，对照第 2.2 节的表逐个核对。
5.2 401 报错
飞书渠道返回 401，通常是 App ID 或 App Secret 填错，或者应用没发布。检查~/.openclaw/openclaw.json里channels.feishu的凭证，确认和开发者后台「凭证与基础信息」里一致。改完记得openclaw gateway restart。
如果是模型侧返回 401，检查模型服务的 API Key 是否有效。用 TaoToken 的话，Base URL 填https://taotoken.net/api，Key 从控制台生成，Model ID 按你订阅的模型填。这三件套缺一个都会 401。
5.3 local proxy failed
这个报错一般出现在 OpenClaw 尝试连接外部服务时。先确认服务器能正常出网：
curl -I https://open.feishu.cn如果网络没问题，检查 OpenClaw 的代理配置有没有残留。有些环境变量比如HTTP_PROXY会干扰长连接，清掉再重启：
unset HTTP_PROXY HTTPS_PROXY openclaw gateway restart5.4 reading choices 报错
这个通常和模型返回格式有关。如果用的是兼容 OpenAI 接口的服务，确认 Base URL 结尾有没有多写/v1。TaoToken 的 API 地址是https://taotoken.net/api，不要自己拼/v1/chat/completions，让 OpenClaw 按渠道配置去拼。
5.5 OAuth 相关报错
clawhub 登录用的 token 过期会报 OAuth 错误。重新生成 token 再登录：
clawhub login --token 新的token飞书侧如果报 OAuth，检查应用是否开启了对应的 OAuth 权限，以及重定向 URL 有没有配错。
5.6 技能不触发
技能文件放对了但机器人不调用，先看openclaw skills list里有没有这个技能。有的话，检查 SKILL.md 的description里触发词够不够具体。描述太泛，Agent 推理时匹配不上。把用户可能说的词都写进去，比如“磁盘、空间、df、inode、挂载点、清理”。
另外确认技能目录名和 frontmatter 里的name一致，不一致也可能导致加载异常。
6. 把飞书运维机器人用起来
到这一步，飞书群聊里的 OpenClaw 已经能收消息、调技能、回结果了。日常用法上，我习惯把常用巡检做成技能，比如磁盘检查、登录日志巡检、服务状态检查，然后在飞书里直接 @ 机器人说需求。
模型切换可以在飞书对话里临时做，发/model qwen/qwen3.6-plus只对当前会话生效，不用重启网关。要全局切换就用openclaw models set然后openclaw gateway restart。
技能写多了之后，建议按业务分目录，比如linux-skills、db-skills、network-skills，每个目录下放对应的 SKILL.md 和脚本。workspace 目录会自动扫描，不用手动注册。
最后提醒一句：给 OpenClaw 的 SSH 权限按最小化原则来，别直接给 root。在目标服务器上给指定用户授权，比如只读/var/log/secure：
setfacl -m u:coffeemilk:r-- /var/log/secure getfacl /var/log/secure这样即使技能脚本被误触发，也造不成大破坏。飞书入口 + skills 技能这套组合，本质上是把你的运维经验固化成可复用的作业指导书，值班新人 @ 一下机器人，也能拿到专家级的诊断结论。
