概述

OpenClaw 支持飛書（Feishu/Lark）通過 Card Kit 交互式卡片 實現(xiàn)流式回復。啟用后，機器人會在生成過程中實時更新卡片內(nèi)容，用戶可以看到文字逐步出現(xiàn)，而不是等待完整回復后一次性彈出。

本文基于 OpenClaw 2026.2.26+ 版本，結(jié)合實際部署調(diào)試經(jīng)驗編寫。

飛書流式的工作原理

用戶發(fā)送消息 → OpenClaw 接收
                    ↓
        OpenClaw 調(diào)用模型 API（stream=true）
                    ↓
        模型返回 SSE 流式數(shù)據(jù)（text_delta）
                    ↓
        OpenClaw 創(chuàng)建飛書 Streaming Card Session
                    ↓
        每收到一段文本 → 調(diào)用飛書 Card Kit API 更新卡片
                    ↓
        模型輸出完畢 → 關(guān)閉 Streaming Session → 卡片定稿

關(guān)鍵組件：

• FeishuStreamingSession：OpenClaw 內(nèi)置的飛書流式卡片管理器，負責創(chuàng)建、更新、關(guān)閉卡片
• Card Kit API：飛書官方的卡片流式更新接口，支持約 10 次/秒的更新頻率
• onPartialReply：OpenClaw 的回調(diào)機制，模型每產(chǎn)生一段文本就觸發(fā)一次卡片更新

配置方法

最小配置（推薦）

編輯 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "appId": "你的飛書應用 App ID",
      "appSecret": "你的飛書應用 App Secret",
      "enabled": true,
      "renderMode": "card",
      "streaming": true
    }
  }
}

配置項詳解

關(guān)于 renderMode（核心配置）

這是官方文檔中沒有明確說明但實際部署中最關(guān)鍵的配置項：

為什么 renderMode: "auto" 不行？

在 auto 模式下，OpenClaw 的 Feishu Reply Dispatcher 的判斷邏輯是：

useCard = renderMode === "card"
       || (renderMode === "auto" && 回復包含代碼塊或表格)

只有 useCard === true 時，才會創(chuàng)建 Streaming Card Session。對于日常對話中的純文本回復，useCard 為 false，流式卡片不會被創(chuàng)建，回復就是一次性發(fā)送的普通文本消息。

可選：塊級流式（Block Streaming）

塊級流式是另一種流式機制，將長回復拆分成多個消息塊分批發(fā)送。與卡片流式可以組合使用。

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

啟用塊級流式后，dispatch complete 日志中的 replies（對應 counts.final）會顯示為 0，這是正常行為——內(nèi)容已通過 block 發(fā)送，final 被跳過以避免重復。

模型代理的流式支持

OpenClaw 始終以 stream=true 請求模型，即使未啟用卡片流式。模型代理需要正確返回 SSE（Server-Sent Events）格式的流式數(shù)據(jù)：

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

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

驗證流式是否生效

1. 檢查配置

openclaw config get channels.feishu.renderMode
# 應輸出: card
openclaw config get channels.feishu.streaming
# 應輸出: true

2. 檢查日志

發(fā)送消息后查看日志：

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 行，說明流式卡片未創(chuàng)建，需要檢查 renderMode 配置。

3. 常見日志對比

注意事項

• 消息引用與流式互斥：啟用流式輸出（streaming: true）時，回復以卡片形式呈現(xiàn)，不支持消息引用功能。
• 卡片渲染差異：renderMode: "card" 會使所有回復都以卡片形式呈現(xiàn)，視覺上與普通文本消息不同。如果介意卡片樣式，可以保持 renderMode: "auto"，但只有包含代碼塊或表格的回復才有流式效果。
• 飛書應用權(quán)限：確保飛書應用具有發(fā)送交互式卡片的權(quán)限（通常在開發(fā)者后臺的應用權(quán)限中配置）。
• 更新頻率限制：飛書 Card Kit API 有更新頻率限制（約 10 次/秒），OpenClaw 內(nèi)部已做節(jié)流處理。

故障排查

問題：飛書回復仍然是一次性的

檢查清單：

• renderMode 是否設(shè)為 "card"
• streaming 是否為 true（或未設(shè)置，默認 true）
• 模型代理是否支持流式返回（SSE 格式）
• Gateway 是否已重啟（修改配置后需要 openclaw gateway restart）
• 日志中是否出現(xiàn) Started streaming

問題：啟用 blockStreaming 后 replies=0

這是正常行為。啟用塊級流式后，內(nèi)容通過 sendBlockReply 發(fā)送，sendFinalReply 被跳過（避免重復），所以 counts.final 為 0。只要飛書端收到了回復，就說明工作正常。

問題：Gateway 啟動后飛書無響應

# 檢查飛書連接狀態(tài)
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
    }
  }
}

到此這篇關(guān)于openclaw飛書流式回復配置指南的文章就介紹到這了,更多相關(guān)openclaw飛書流式回復內(nèi)容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評論