feishu

openclaw-feishu

一个可直接替换 OpenClaw 内置 feishu 插件的公开版本，包含正规飞书 @mention、bot-to-bot webhook 转发、旧 session 续写，以及“同 session 保序 / 不同 session 并行”的稳定化能力。

快速开始

方式一：一键安装

curl -fsSL https://raw.githubusercontent.com/zhangshihai1232/openclaw-feishu/main/scripts/install.sh | bash

安装脚本会自动：

• 备份现有 ~/.openclaw/extensions/feishu
• 拉取本仓库到 ~/.openclaw/extensions/feishu
• 安装运行依赖（npm install --omit=dev）
• 非破坏式更新 ~/.openclaw/openclaw.json
• 确保 plugins.allow 含有 feishu
• 确保 plugins.load.paths 含有 ~/.openclaw/extensions/feishu
• 确保 plugins.entries.feishu.enabled = true
• 确保 hooks.allowedSessionKeyPrefixes 含有 agent:

安装完成后，重启：

openclaw gateway

方式二：手动安装

git clone https://github.com/zhangshihai1232/openclaw-feishu.git ~/.openclaw/extensions/feishu
cd ~/.openclaw/extensions/feishu
npm install --omit=dev

然后把下面这段合并进 ~/.openclaw/openclaw.json：

{
  "plugins": {
    "allow": ["feishu"],
    "load": {
      "paths": ["~/.openclaw/extensions/feishu"]
    },
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  },
  "hooks": {
    "allowedSessionKeyPrefixes": ["agent:"]
  }
}

核心能力

• 正规飞书 @mention：把 @m-2 重写为飞书可识别的 <at ...> 结构
• bot-to-bot mention 转发：机器人发 @m-x 后，可自动触发目标 bot
• 旧 session 续写：优先走 sessions.send，不再默认分裂成新 transcript
• 保序调度：同一逻辑 session 串行，避免多条消息乱序
• 跨 lane 并行：不同 accountId + chatId + targetAgentId 可并行处理

配置说明

最小插件加载配置

这一段只负责让 OpenClaw 使用这个仓库里的插件：

{
  "plugins": {
    "allow": ["feishu"],
    "load": {
      "paths": ["~/.openclaw/extensions/feishu"]
    },
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  },
  "hooks": {
    "allowedSessionKeyPrefixes": ["agent:"]
  }
}

bot mention 配置

如果你要启用“机器人 A 在群里 @机器人 B，自动唤起 B”的链路，最少需要配置：

{
  "channels": {
    "feishu": {
      "botMentionWebhook": {
        "enabled": true,
        "pollingIntervalMs": 5000,
        "timeoutMs": 30000,
        "botMapping": {
          "m-1": {
            "agentId": "m-1",
            "openId": "ou_xxx",
            "name": "M-1号"
          },
          "m-2": {
            "agentId": "m-2",
            "openId": "ou_yyy",
            "name": "M-2号"
          }
        }
      }
    }
  }
}

完整示例见：

examples/openclaw.feishu.bot-mention.jsonc

给 AI/Agent 的配置理解方式

如果你希望 AI 帮你改配置，可以直接告诉它下面这几个规则：

1. plugins.load.paths 必须包含 ~/.openclaw/extensions/feishu 2. plugins.entries.feishu.enabled 必须为 true 3. hooks.allowedSessionKeyPrefixes 必须包含 agent: 4. channels.feishu.botMentionWebhook.enabled = true 才会启用 bot-to-bot mention 转发 5. botMapping 里：

• key 是 AI 文本里写的别名，例如 m-2
• agentId 是 OpenClaw agent id
• openId 是飞书 bot open id
• name 是飞书前端展示名

你可以把这段直接贴给 AI：

请只做非破坏式修改：
1. 保留现有 openclaw.json 其他字段不变
2. 确保 plugins.load.paths 包含 ~/.openclaw/extensions/feishu
3. 确保 plugins.entries.feishu.enabled = true
4. 确保 hooks.allowedSessionKeyPrefixes 包含 agent:
5. 如果我要启用 botMentionWebhook，请只补 channels.feishu.botMentionWebhook 下的字段，不要覆盖其他 feishu 配置

安装脚本参数

scripts/install.sh 支持这些可选参数：

bash scripts/install.sh --help

常用环境变量/参数：

• --repo-url：默认 https://github.com/zhangshihai1232/openclaw-feishu.git
• --branch：默认 main
• --install-dir：默认 ~/.openclaw/extensions/feishu
• --config-file：默认 ~/.openclaw/openclaw.json
• --skip-deps：跳过 npm install --omit=dev

使用示例

示例 1：让插件接管内置 feishu

curl -fsSL https://raw.githubusercontent.com/zhangshihai1232/openclaw-feishu/main/scripts/install.sh | bash

示例 2：本地仓库调试安装

bash scripts/install.sh \
  --repo-url "$(pwd)" \
  --branch main \
  --install-dir ~/.openclaw/extensions/feishu-dev \
  --config-file ~/.openclaw/openclaw.json \
  --skip-deps

示例 3：启用 bot-to-bot mention

把 examples/openclaw.feishu.bot-mention.jsonc 中的 botMapping 按你的 bot 列表填写后，合并进 ~/.openclaw/openclaw.json，然后重启 openclaw gateway。

设计取舍

当前版本的转发策略是：

• 同一 session 串行：保证旧 transcript 不乱序
• 不同 session 并行：提升多 bot / 多群吞吐
• 共享懒加载 WS client：降低每条消息重建连接的开销
• 空闲自动断开：避免做成永久长连接守护状态机

这比“全局串行”快，也比“完全并发”稳。

已知边界

• 同一个目标 session 内，多条消息仍然会等待前一条目标 LLM 完成，这是故意的保序设计
• sessions.json 中的 sessionId / sessionFile 映射残留问题属于 OpenClaw 本体行为，本仓库没有改 core
• 如果源 bot 自己没有按预期发出 @m-x 文本，目标 bot 不会被触发；这属于源 bot 输出问题，不是转发器问题

License

当前仓库尚未单独附带 License 文件。在公开分发、二次封装或商业使用前，请先核对上游 OpenClaw 及其插件源码的许可要求。