Feishu Execution Monitor

README

# Feishu Execution Monitor for OpenClaw

一个外挂式 OpenClaw 插件，用来监控“飞书消息进入 OpenClaw 后”的执行链路，并把阶段状态实时回传到飞书。

这个插件的设计边界很明确：

- 不修改 OpenClaw 核心代码
- 不修改官方 Feishu 插件代码
- 只通过官方插件 SDK 和运行时事件做增强
- 只展示可观测执行链，不暴露隐藏思维链

## 适用场景

适合这些场景：

- 你从飞书发指令给 OpenClaw，但长时间不知道程序是否仍在执行
- 你想知道当前任务卡在了哪一层：入口、Agent、模型、工具还是消息发送
- 你希望在飞书中看到类似 IDE 的阶段反馈，而不是只能等最终回复

## 当前能力

插件当前可以实时展示这些阶段：

- 已接收指令
- 已进入 Agent
- 模型处理中
- 工具执行中
- 工具执行完成
- 正在发送回复
- 已完成
- 执行失败
- 发送失败
- 等待超时
- 执行停滞

插件还支持：

- 单条飞书卡片持续更新，而不是不断刷屏发多条消息
- 从 OpenClaw session store 反查会话，绑定飞书入口消息与实际 sessionKey
- 可选显示助手输出预览
- 长时间没有新阶段时自动标记超时/停滞
- 写入结构化 JSONL 日志，便于排障

## 工作原理

整体链路如下：

```mermaid
flowchart LR
  A["飞书消息进入"] --> B["message_received"]
  B --> C["记录待匹配任务"]
  C --> D["before_agent_start"]
  D --> E["读取 session store 绑定 sessionKey"]
  E --> F["llm_input / onAgentEvent"]
  F --> G["before_tool_call / after_tool_call"]
  G --> H["message_sending / message_sent"]
  H --> I["agent_end / finalize"]
  I --> J["更新同一条飞书 interactive card"]
```

核心思路：

1. 在 `message_received` 记录一条“飞书入口任务”
2. 在 `before_agent_start` 读取 session store，把飞书消息和真实 `sessionKey` 绑定起来
3. 在模型、工具、发送、结束等事件上持续更新任务状态
4. 把所有阶段写回同一条飞书 `interactive card`
5. 如果长时间没有新进度，自动更新成“等待超时”或“执行停滞”

## 仓库结构

```text
feishu-execution-monitor/
├── index.ts
├── openclaw.plugin.json
├── README.md
├── docs/
│   ├── INSTALL.zh-CN.md
│   ├── IMPLEMENTATION.zh-CN.md
│   └── TROUBLESHOOTING.zh-CN.md
└── examples/
    └── plugin-config.json
```

## 快速开始

安装和配置步骤见：

- [安装使用指南](./docs/INSTALL.zh-CN.md)
- [实现原理说明](./docs/IMPLEMENTATION.zh-CN.md)
- [排障手册](./docs/TROUBLESHOOTING.zh-CN.md)
- [配置示例](./examples/plugin-config.json)

## 运行依赖

- OpenClaw
- 已启用的官方 Feishu 插件
- Feishu 机器人账号已在 OpenClaw 中配置完成
- 本插件目录放在 `~/.openclaw/extensions/feishu-execution-monitor`

## 配置项

插件配置定义在 [openclaw.plugin.json](./openclaw.plugin.json)。

主要配置项说明：

- `enabled`: 是否启用插件
- `updateThrottleMs`: 飞书卡片更新最小间隔，避免刷太快
- `staleSeconds`: 超过多久没有新阶段就判定为超时/停滞
- `includeAssistantText`: 是否在卡片中附带助手可见输出预览
- `maxAssistantChars`: 输出预览最大字符数
- `headerTitle`: 飞书卡片标题
- `showSessionKey`: 是否显示 sessionKey

## 日志位置

插件结构化日志：

- `~/.openclaw/logs/feishu-execution-monitor.jsonl`

Gateway 服务日志：

- `/tmp/openclaw/openclaw-YYYY-MM-DD.log`

## 当前限制

- 只监控通过 Feishu 触发的会话
- 只监控插件能观察到的运行时事件
- 不显示模型隐藏推理链
- 如果 OpenClaw 本身在更早层级挂死，插件最多只能显示“已进入 Agent”或“执行停滞”

## 发布说明

这是一个独立插件仓库，适合直接发布到 GitHub，供你在不同 OpenClaw 节点上复用。