openclaw飞书流式回复配置指南

目录

• 概述
• 飞书流式的工作原理
• 配置方法
• 最小配置（推荐）
• 配置项详解
• 关于 renderMode（核心配置）
• 可选：块级流式（Block Streaming）
• 模型代理的流式支持
• 验证流式是否生效
• 1. 检查配置
• 2. 检查日志
• 3. 常见日志对比
• 注意事项
• 故障排查
• 问题：飞书回复仍然是一次性的
• 问题：启用 blockStreaming 后 replies=0
• 问题：Gateway 启动后飞书无响应
• 完整配置示例

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

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

用户发送消息 → 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：

{
  "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	–	块级流式的合并参数（飞书专用格式）

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

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

为什么 renderMode: "auto" 不行？

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

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

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

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

{
  "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）格式的流式数据：

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

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

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

发送消息后查看日志：

openclaw logs

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

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 配置。

日志特征	含义
有 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

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

# 检查飞书连接状态
openclaw health
# 查看是否有错误日志
openclaw logs | grep -i error
# 重启 Gateway
openclaw gateway restart

{
  "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
    }
  }
}

到此这篇关于openclaw飞书流式回复配置指南的文章就介绍到这了,更多相关openclaw飞书流式回复内容请搜索风君子博客以前的文章或继续浏览下面的相关文章，希望大家以后多多支持风君子博客！