Feishu Progress Card

Name: Feishu Progress Card
Rating: 3.5 (1 reviews)
Author: theo-lee1

By theo-lee1 👁 17 views ▲ 0 votes

Real-time multi-step tool-call progress pushed to Feishu as an updatable interactive card. OpenClaw plugin.

GitHub

Install

openclaw plugins install ./feishu-progress-card

Configuration Example

{
  "plugins": {
    "entries": {
      "feishu-progress-card": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

README

# feishu-progress-card

把 OpenClaw agent 的多步工具调用进度（开始/结束/失败/心跳）实时推送到飞书，
用可更新的交互卡片展示。新消息进来时发送第一张卡，之后每次工具调用都**更新**同一张卡。

> 依赖：飞书 IM、OpenClaw gateway 2026.5+。

## 安装

```bash
cd ~/.openclaw/plugins
git clone <repo-url> feishu-progress-card
openclaw plugins install ./feishu-progress-card --link
```

> 如果用打包版：直接 `openclaw plugins install ./feishu-progress-card-0.1.0.tgz` 即可。

## 配置 `openclaw.json`

插件本身**不需要**配置参数（configSchema 都有 default），但**一个字段**必须加：

### 启用插件（**必填**）

OpenClaw 的安全策略要求**非内置插件**显式声明**允许访问会话内容**：

```jsonc
{
  "plugins": {
    "entries": {
      "feishu-progress-card": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}
```

> 飞书凭据写在 `openclaw.json` 的 `channels.feishu` 下：
>
> ```jsonc
> {
>   "channels": {
>     "feishu": {
>       "appId": "cli_xxxxxxxxxxxxxxxx",
>       "appSecret": "***"
>     }
>   }
> }
> ```

## 重启

```bash
# 如果用 systemd：
systemctl --user restart openclaw-gateway

# 如果是手动：
pkill -TERM -f "openclaw.*gateway"
sleep 6
nohup .../node .../dist/index.js gateway --port 18789 > /tmp/openclaw/manual-start.log 2>&1 &
disown
```

## 验证

给 agent 发一条会调工具的消息（比如 "查杭州天气" 或 "执行 exec sleep 3"），
飞书里会立即出现一张"🤖 任务进度 · 🟡 进行中"卡片，
每次工具调用都会自动更新这张卡，结束时切到 "✅ 已完成"。
如果卡片没出现，**第一件事**就是查 gateway 日志：

```bash
tail -f /tmp/openclaw/openclaw-$(date +%F).log | grep -E "feishu-progress-card"
```

常见错误：
- `feishu auth failed` → `openclaw.json` 的 `channels.feishu` 配置问题
- `code=230099` → 卡片 schema 用了 V1 不支持的 block（callout 等）
- 卡片出现但内容是"请升级客户端" → 飞书客户端太老，折叠面板降级提示，**不影响**主卡片

## 可选配置

| Key | Default | 含义 |
| --- | --- | --- |
| `enabled` | `true` | 设为 `false` 整个插件不挂载 |
| `hooks.timeoutMs` | - | 单个 hook 最大执行时间（毫秒），默认 30000 |
| `config.minEmitIntervalMs` | 1000 | 同一 run 相邻 emit 至少间隔（ms），防刷飞书频率限制 |
| `config.heartbeatIntervalMs` | 5000 | 工具调用没动静时隔多久发一次"心跳"保活 |
| `config.messageTemplate` | - | 自定义文案（高级用法） |

## 卸载

```bash
openclaw plugins uninstall feishu-progress-card
rm -rf ~/.openclaw/plugins/feishu-progress-card
rm -f ~/.openclaw/feishu-progress-card.state.json
```

voice