openclaw飞书流式回复配置指南

OpenClaw 飞书流式回复配置指南

概述

OpenClaw 支持飞书（Feishu/Lark）通过 Card Kit 交互式卡片 实现流式回复。启用后，机器人会在生成过程中实时更新卡片内容，用户可以看到文字逐步出现，而不是等待完整回复后一次性弹出。

本文基于 OpenClaw 2026.2.26+ 版本，结合实际部署调试经验编写。

飞书流式的工作原理

ini 复制代码

用户发送消息 → OpenClaw 接收
                    ↓
        OpenClaw 调用模型 API（stream=true）
                    ↓
        模型返回 SSE 流式数据（text_delta）
                    ↓
        OpenClaw 创建飞书 Streaming Card Session
                    ↓
        每收到一段文本 → 调用飞书 Card Kit API 更新卡片
                    ↓
        模型输出完毕 → 关闭 Streaming Session → 卡片定稿

关键组件：

FeishuStreamingSession：OpenClaw 内置的飞书流式卡片管理器，负责创建、更新、关闭卡片
Card Kit API：飞书官方的卡片流式更新接口，支持约 10 次/秒的更新频率
onPartialReply：OpenClaw 的回调机制，模型每产生一段文本就触发一次卡片更新

配置方法

最小配置（推荐）

编辑 ~/.openclaw/openclaw.json：

json 复制代码

{
  "channels": {
    "feishu": {
      "appId": "你的飞书应用 App ID",
      "appSecret": "你的飞书应用 App Secret",
      "enabled": true,
      "renderMode": "card",
      "streaming": true
    }
  }
}

配置项详解

配置项	类型	默认值	说明
`renderMode`	`"auto"` \| `"card"` \| `"raw"`	`"auto"`	回复渲染模式，必须设为 `"card"` 才能保证流式生效
`streaming`	`boolean`	`true`	是否启用流式卡片输出
`blockStreaming`	`boolean`	`true`	是否启用块级流式（分块发送多条消息）
`blockStreamingCoalesce`	`object`	-	块级流式的合并参数（飞书专用格式）

关于 renderMode（核心配置）

这是官方文档中没有明确说明 但实际部署中最关键的配置项：

值	行为	流式效果
`"auto"`（默认）	根据回复内容自动选择：含代码块/表格用卡片，纯文本用普通消息	纯文本回复无流式效果
`"card"`	所有回复都用卡片渲染	所有回复都有流式效果
`"raw"`	所有回复用纯文本	无流式效果

为什么 renderMode: "auto" 不行？

在 auto 模式下，OpenClaw 的 Feishu Reply Dispatcher 的判断逻辑是：

ini 复制代码

useCard = renderMode === "card"
       || (renderMode === "auto" && 回复包含代码块或表格)

只有 useCard === true 时，才会创建 Streaming Card Session。对于日常对话中的纯文本回复，useCard 为 false，流式卡片不会被创建，回复就是一次性发送的普通文本消息。

可选：块级流式（Block Streaming）

块级流式是另一种流式机制，将长回复拆分成多个消息块分批发送。与卡片流式可以组合使用。

json 复制代码

{
  "agents": {
    "defaults": {
      "blockStreamingDefault": "on",
      "blockStreamingBreak": "text_end",
      "blockStreamingCoalesce": {
        "minChars": 200,
        "maxChars": 2000,
        "idleMs": 500
      }
    }
  },
  "channels": {
    "feishu": {
      "blockStreaming": true,
      "blockStreamingCoalesce": {
        "enabled": true,
        "minDelayMs": 300,
        "maxDelayMs": 800
      }
    }
  }
}

注意：飞书的 blockStreamingCoalesce 格式与全局不同，使用 minDelayMs / maxDelayMs 而非 minChars / maxChars / idleMs。

全局配置项（`agents.defaults`）	类型	说明
`blockStreamingDefault`	`"on"` \| `"off"`	全局开关（注意是字符串，不是 boolean）
`blockStreamingBreak`	`"text_end"` \| `"message_end"`	分块时机
`blockStreamingCoalesce`	`object`	合并参数 `{ minChars, maxChars, idleMs }`

启用块级流式后，dispatch complete 日志中的 replies（对应 counts.final）会显示为 0，这是正常行为------内容已通过 block 发送，final 被跳过以避免重复。

模型代理的流式支持

OpenClaw 始终以 stream=true 请求模型，即使未启用卡片流式。模型代理需要正确返回 SSE（Server-Sent Events）格式的流式数据：

css 复制代码

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"你"},"index":0}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"好"},"index":0}]}

data: [DONE]

如果模型代理不支持流式，OpenClaw 仍然可以工作，但所有文本会在最后一刻一次性出现在卡片中。

验证流式是否生效

1. 检查配置

bash 复制代码

openclaw config get channels.feishu.renderMode
# 应输出: card

openclaw config get channels.feishu.streaming
# 应输出: true

2. 检查日志

发送消息后查看日志：

bash 复制代码

openclaw logs

正常流式回复的日志应包含：

ini 复制代码

feishu[default] Started streaming: cardId=xxx, messageId=xxx
...（模型处理中）...
feishu[default] Closed streaming: cardId=xxx
feishu[default]: dispatch complete (queuedFinal=true, replies=1)

如果日志中没有 Started streaming 行，说明流式卡片未创建，需要检查 renderMode 配置。

3. 常见日志对比

日志特征	含义
有 `Started streaming` + `Closed streaming`	流式正常工作
无 `Started streaming`，有 `replies=1`	非流式，一次性回复
有 `Started streaming`，`replies=0`	块级流式生效，内容已通过 block 发送

注意事项

消息引用与流式互斥 ：启用流式输出（streaming: true）时，回复以卡片形式呈现，不支持消息引用功能。
卡片渲染差异 ：renderMode: "card" 会使所有回复都以卡片形式呈现，视觉上与普通文本消息不同。如果介意卡片样式，可以保持 renderMode: "auto"，但只有包含代码块或表格的回复才有流式效果。
飞书应用权限：确保飞书应用具有发送交互式卡片的权限（通常在开发者后台的应用权限中配置）。
更新频率限制：飞书 Card Kit API 有更新频率限制（约 10 次/秒），OpenClaw 内部已做节流处理。

故障排查

问题：飞书回复仍然是一次性的

检查清单：

renderMode 是否设为 "card"
streaming 是否为 true（或未设置，默认 true）
模型代理是否支持流式返回（SSE 格式）
Gateway 是否已重启（修改配置后需要 openclaw gateway restart）
日志中是否出现 Started streaming

问题：启用 blockStreaming 后 replies=0

这是正常行为 。启用块级流式后，内容通过 sendBlockReply 发送，sendFinalReply 被跳过（避免重复），所以 counts.final 为 0。只要飞书端收到了回复，就说明工作正常。

问题：Gateway 启动后飞书无响应

bash 复制代码

# 检查飞书连接状态
openclaw health

# 查看是否有错误日志
openclaw logs | grep -i error

# 重启 Gateway
openclaw gateway restart

完整配置示例

json 复制代码

{
  "models": {
    "providers": {
      "local-agent-proxy": {
        "baseUrl": "http://localhost:3000/v1",
        "apiKey": "your-api-key",
        "api": "openai-completions",
        "models": [
          {
            "id": "your-model",
            "name": "your-model",
            "reasoning": false,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "local-agent-proxy/your-model"
      }
    }
  },
  "channels": {
    "feishu": {
      "appId": "cli_xxxxxxxxxx",
      "appSecret": "your-app-secret",
      "enabled": true,
      "renderMode": "card",
      "streaming": true
    }
  }
}