OpenClaw 接入chanels飞书（feishu）插件避坑指南

一、操作背景

目标：在 Windows 系统下通过 openclaw plugins install @m1heng-clawd/feishu 安装飞书插件，解决安装过程中出现的各类报错，最终提供可落地的解决方案及撤销操作方法。

现象：安装时提示 plugin already exists: C:\Users\Administrator.openclaw\extensions\feishu
原因：此前已安装过该插件，目录未清理干净导致冲突
避坑方案：
1. 安装前先删除旧目录：Remove-Item -Recurse -Force C:\Users\Administrator.openclaw\extensions\feishu
2. 避免重复执行安装命令，确认目录删除后再操作

现象：插件加载失败，提示 Cannot find module '@larksuiteoapi/node-sdk'
原因：插件核心依赖未预装，OpenClaw 自带的安装流程未自动处理
避坑方案：
1. 安装插件前手动装核心依赖：npm install -g @larksuiteoapi/node-sdk
2. 优先用国内 npm 源（npm config set registry https://registry.npmmirror.com）避免下载失败

现象：npm install 报错 git@github.com: Permission denied (publickey) / Failed to connect to github.com port 443
原因：
- 插件依赖 libsignal-node 需从 GitHub 通过 SSH 拉取代码，本地未配置 SSH 密钥；
- 国内网络无法直接访问 GitHub（443 端口连接超时）；
- Windows 下误执行 Linux/Mac 版 ssh-agent 命令（eval $(ssh-agent -s)）导致密钥配置失败。
避坑方案：
1. 优先绕开 SSH：配置 Git 强制用 HTTPS 镜像 git config --global url."https://github.com.cnpmjs.org/".insteadOf git@github.com:；
2. 放弃第三方插件包：直接基于飞书官方核心 SDK（@larksuiteoapi/node-sdk-core）手写插件，完全规避 GitHub 依赖；
3. 若非要配置 SSH：
  - Windows 下用 Start-Service ssh-agent 启动代理（而非 eval $(ssh-agent -s)）；
  - 生成密钥时直接按回车用默认路径，避免手动输入路径导致命名错误。

现象：Installing plugin dependencies... 卡住或提示 npm install failed
原因：
- 国外 npm 源访问慢，依赖包下载超时；
- 依赖树冲突，默认安装规则无法处理；
避坑方案：
1. 切换国内 npm 源（淘宝 / 阿里云镜像）；
2. 手动进入插件目录执行 npm install --force 强制安装；
3. 清理缓存后重试：npm cache clean --force。

现象：执行 Start-Service ssh-agent 提示「无法启动服务」
原因：Windows 系统未启用 OpenSSH Authentication Agent 服务
避坑方案：
1. 非必需操作：该服务仅用于缓存 SSH 密钥，不启动也可正常使用密钥；
2. 如需修复：以管理员身份执行 Set-Service -Name ssh-agent -StartupType Automatic && Start-Service ssh-agent。

无需安装第三方插件包，直接手写极简版飞书插件，完全规避 GitHub 依赖和网络问题：

初始化 package.json，仅依赖飞书核心 SDK：

json

perl 复制代码

{
  "name": "feishu",
  "version": "0.1.16",
  "main": "index.ts",
  "dependencies": { "@larksuiteoapi/node-sdk-core": "^1.0.0" }
}