跨平台機器人的 Markdown 格式化：OpenClaw 的統一渲染方案

你是否遇過在開發跨平台機器人時，Markdown 在 Slack 顯示正常，但在 Telegram 卻因為 HTML 標籤沒對齊而破圖？最煩人的是當訊息太長需要分段（Chunking）時，粗體或斜體標籤剛好被切在中間，導致後半段的文字格式全部跑掉。

處理多平台的格式差異一向是個體力活，每個平台對 Markdown 的支援程度不同，有些甚至只吃 HTML 或特定的 Style Range。OpenClaw 透過一套中間表示層 (IR) 機制解決了這個問題，讓你的機器人訊息在不同頻道都能保持一致。

需要準備的東西

• OpenClaw 核心框架
• 支援的頻道 Adapter (Slack, Telegram, Signal, WhatsApp 等)

快速開始

要在 OpenClaw 中實作或更新頻道的格式化，請遵循這四個核心步驟：

1. 解析 (Parse): 使用 markdownToIR(...) 助手將 Markdown 轉換為 IR。
2. 分段 (Chunk): 在渲染前呼叫 chunkMarkdownIR(...)，這能確保行內樣式不會被切斷。
3. 渲染 (Render): 實作 renderMarkdownWithMarkers(...) 來對應各頻道的特定語法（如 Slack 的 mrkdwn 或 Telegram 的 HTML）。
4. 測試: 更新格式測試與出站遞送測試，確保分段後的渲染結果正確。

運作流程與 IR 機制

OpenClaw 不會直接將 Markdown 丟給頻道，而是先轉換成一個中間表示層 (IR)。這個 IR 會保留原始文本，並帶有樣式與連結的範圍（Spans）。

IR 範例

假設你的輸入是：

Hello **world** — see [docs](https://docs.openclaw.ai).

轉換後的 IR 結構如下：

{
  "text": "Hello world — see docs.",
  "styles": [{ "start": 6, "end": 11, "style": "bold" }],
  "links": [{ "start": 19, "end": 23, "href": "https://docs.openclaw.ai" }]
}

這種做法有兩個好處：

• 安全分段: 系統會在 IR 層級進行文字切分，確保粗體或代碼塊等樣式標記不會在分段時被拆散。
• 精準對應: 針對 Signal 這種使用 UTF-16 編碼單位來計算樣式範圍的 API，IR 能提供精確的偏移量。

表格處理

由於各個聊天客戶端對 Markdown 表格的支援極度不統一，你可以透過 markdown.tables 選項來控制轉換邏輯：

• code: 將表格渲染為代碼塊（多數頻道的預設值）。
• bullets: 將每一行轉換為項目符號（Signal 與 WhatsApp 的預設值）。
• off: 停用表格解析，直接輸出原始文字。

你可以在 YAML 設定中針對不同頻道或帳號進行配置：

channels:
  discord:
    markdown:
      tables: code
    accounts:
      work:
        markdown:
          tables: off

頻道特定規則

不同的頻道在渲染時有不同的策略：

• Slack: 使用 mrkdwn 標記，連結轉為 <url|label>，並停用自動連結解析以避免重複連結。
• Telegram: 使用 HTML 標籤（如 <b>, <i>, <a>），所有標籤外的文字都會進行轉義。
• Signal: 輸出純文字搭配 text-style 範圍，連結則顯示為 label (url)。
• Spoilers: 目前僅在 Signal 中解析 ||spoiler|| 標記，其他頻道會視為純文字。

疑難排解

如果你遇到格式跑掉的問題，請檢查以下常見原因：

• Slack 角括號: Slack 的特殊標記（如 <@U123> 或 <#C123>）必須保留，請確保你的渲染器有正確處理 HTML 轉義。
• Telegram HTML 錯誤: 如果 Telegram 訊息發不出去，通常是因為標籤外的特殊字元沒有正確轉義，導致 HTML 結構損壞。
• Signal 偏移量: Signal 的樣式範圍是基於 UTF-16 的，不要使用一般的字元計數或代碼點（Code Point）計數。
• 代碼塊換行: 確保圍欄代碼塊（Fenced code blocks）保留結尾的換行符號，否則結束標記可能會失效。

如果你在設定過程中遇到困難，可以使用 AI Setup Assistant 獲取即時協助。

下一步

• 串流與分段處理 (Streaming + chunking)