概述

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

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

飛書(shū)流式的工作原理

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

關(guān)鍵組件：

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

配置方法

最小配置（推薦）

編輯 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "appId": "你的飛書(shū)應(yīng)用 App ID",
      "appSecret": "你的飛書(shū)應(yīng)用 App Secret",
      "enabled": true,
      "renderMode": "card",
      "streaming": true
    }
  }
}

配置項(xiàng)詳解

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

這是官方文檔中沒(méi)有明確說(shuō)明但實(shí)際部署中最關(guān)鍵的配置項(xiàng)：

為什么 renderMode: "auto" 不行？

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

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

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

可選：塊級(jí)流式（Block Streaming）

塊級(jí)流式是另一種流式機(jī)制，將長(zhǎng)回復(fù)拆分成多個(gè)消息塊分批發(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
      }
    }
  }
}

注意：飛書(shū)的 blockStreamingCoalesce 格式與全局不同，使用 minDelayMs / maxDelayMs 而非 minChars / maxChars / idleMs。

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

模型代理的流式支持

OpenClaw 始終以 stream=true 請(qǐng)求模型，即使未啟用卡片流式。模型代理需要正確返回 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 仍然可以工作，但所有文本會(huì)在最后一刻一次性出現(xiàn)在卡片中。

驗(yàn)證流式是否生效

1. 檢查配置

openclaw config get channels.feishu.renderMode
# 應(yīng)輸出: card
openclaw config get channels.feishu.streaming
# 應(yīng)輸出: true

2. 檢查日志

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

openclaw logs

正常流式回復(fù)的日志應(yīng)包含：

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

如果日志中沒(méi)有 Started streaming 行，說(shuō)明流式卡片未創(chuàng)建，需要檢查 renderMode 配置。

3. 常見(jiàn)日志對(duì)比

注意事項(xiàng)

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

故障排查

問(wèn)題：飛書(shū)回復(fù)仍然是一次性的

檢查清單：

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

問(wèn)題：?jiǎn)⒂?blockStreaming 后 replies=0

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

問(wèn)題：Gateway 啟動(dòng)后飛書(shū)無(wú)響應(yīng)

# 檢查飛書(shū)連接狀態(tài)
openclaw health
# 查看是否有錯(cuò)誤日志
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飛書(shū)流式回復(fù)配置指南的文章就介紹到這了,更多相關(guān)openclaw飛書(shū)流式回復(fù)內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！

最新評(píng)論