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

一、操作背景

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

二、核心问题与避坑点

问题 1：插件目录重复 / 已存在

• 现象：安装时提示 plugin already exists: C:UsersAdministrator.openclawextensionsfeishu

• 原因：此前已安装过该插件，目录未清理干净导致冲突

• 避坑方案：

  1. 安装前先删除旧目录：Remove-Item -Recurse -Force C:UsersAdministrator.openclawextensionsfeishu
  2. 避免重复执行安装命令，确认目录删除后再操作

问题 2：依赖包缺失（@larksuiteoapi/node-sdk）

• 现象：插件加载失败，提示 Cannot find module '@larksuiteoapi/node-sdk'

• 原因：插件核心依赖未预装，OpenClaw 自带的安装流程未自动处理

• 避坑方案：

  1. 安装插件前手动装核心依赖：npm install -g @larksuiteoapi/node-sdk
  2. 优先用国内 npm 源（npm config set registry ）避免下载失败

问题 3：Git SSH 权限 / 访问失败（核心坑）

• 现象：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)）；
     • 生成密钥时直接按回车用默认路径，避免手动输入路径导致命名错误。

问题 4：npm 依赖安装超时 / 失败

• 现象：Installing plugin dependencies… 卡住或提示 npm install failed

• 原因：

  • 国外 npm 源访问慢，依赖包下载超时；
  • 依赖树冲突，默认安装规则无法处理；

• 避坑方案：

  1. 切换国内 npm 源（淘宝 / 阿里云镜像）；
  2. 手动进入插件目录执行 npm install --force 强制安装；
  3. 清理缓存后重试：npm cache clean --force。

问题 5：ssh-agent 服务启动失败（错误 1058）

• 现象：执行 Start-Service ssh-agent 提示「无法启动服务」

• 原因：Windows 系统未启用 OpenSSH Authentication Agent 服务

• 避坑方案：

  1. 非必需操作：该服务仅用于缓存 SSH 密钥，不启动也可正常使用密钥；
  2. 如需修复：以管理员身份执行 Set-Service -Name ssh-agent -StartupType Automatic && Start-Service ssh-agent。

三、最优解决方案（绕开所有坑）

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

1. 创建插件目录：mkdir -p C:UsersAdministrator.openclawextensionsfeishu && cd $_；

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

   json

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

3. 安装核心 SDK：npm install @larksuiteoapi/node-sdk-core；

4. 编写 index.ts 插件入口（符合 OpenClaw 规范，包含初始化、发消息等核心功能）；

5. 验证：openclaw plugins list 能看到 feishu 插件即为成功。

四、核心避坑原则

1. 优先绕开 GitHub 依赖：国内网络访问 GitHub 不稳定，尽量使用官方核心包而非第三方封装包；
2. 全程用国内源：npm/Git 均切换为国内镜像（npm 用淘宝源，Git 用 GitHub 镜像）；
3. Windows 适配：区分 Windows/Linux 命令（如 ssh-agent 启动方式），避免跨系统命令混用；
4. 手动替代自动：OpenClaw 自带的插件安装流程封装性强，出错时手动创建目录 / 安装依赖更可控。