OpenClaw 釘釘（DingTalk）頻道
企業
中等
透過社群外掛將 OpenClaw 連接到釘釘（DingTalk）。此整合使用釘釘 Stream 模式（WebSocket 長連線），無需公網 IP 或網域。支援私聊、群聊、文字/圖片/語音/影片/檔案等訊息類型，以及 AI Card 串流回覆。安裝外掛、建立釘釘企業內部應用、填入憑證即可啟動。
快速資訊
難度中等
分類企業
支援功能數4 / 6
DingTalk 支援功能
文字訊息
支援
媒體與檔案
支援
表情回應
不支援
討論串
不支援
語音訊息
支援
群組聊天
支援
DingTalk 前置條件
- 擁有釘釘組織管理員權限或應用程式開發權限
- 已安裝釘釘外掛：openclaw plugins install @soimy/dingtalk
- OpenClaw Gateway 已執行並設定
- 伺服器已安裝 Node.js 18+
DingTalk 快速設定
1
安裝釘釘外掛
在終端機中執行 'openclaw plugins install @soimy/dingtalk' 安裝社群釘釘外掛。如需串流 AI Card 回覆，也可選擇 '@dingtalk-real-ai/dingtalk-connector' 外掛。
2
建立釘釘企業內部應用
登入釘釘開放平台（open-dev.dingtalk.com），建立企業內部應用。在應用憑證頁面取得 ClientID（AppKey）和 ClientSecret（AppSecret）。在應用能力中新增「機器人」能力，訊息接收模式選擇 Stream 模式。
3
設定權限並發布
在權限管理中授予所需權限：Card.Instance.Write、Card.Streaming.Write、機器人訊息傳送、媒體檔案上傳等。完成後發布應用，等待審批通過。
4
設定 OpenClaw 並測試
在 ~/.openclaw/openclaw.json 中新增釘釘頻道設定，填入 clientId 和 clientSecret。執行 'openclaw gateway restart' 重新啟動 Gateway，在釘釘中向機器人傳送訊息測試。
DingTalk 設定範例
config.json
{
"channels": {
"dingtalk": {
"enabled": true,
"clientId": "dingXXXXXX",
"clientSecret": "your-app-secret",
"robotCode": "dingXXXXXX",
"corpId": "dingXXXXXX",
"dmPolicy": "open",
"groupPolicy": "open",
"messageType": "markdown"
}
}
}DingTalk 整合詳解
架構概述
OpenClaw 透過釘釘開放平台的 Stream 模式（WebSocket 長連線）連接釘釘。與傳統 Webhook 不同，Stream 模式由 Gateway 主動向釘釘伺服器發起 WebSocket 連線，即時接收事件推送，無需公網 IP 或網域。
訊息流程：使用者在釘釘中傳送訊息 → 釘釘開放平台 → Stream 推送至 Gateway → OpenClaw 使用 AI 處理 → 透過釘釘 Bot API 回覆 → 訊息在釘釘中送達。
此架構適合在 NAT 或企業防火牆後的自託管部署，Gateway 自動維護連線並處理斷線重連（指數退避策略）。
Stream 模式無需公網 IP、無需 SSL 憑證，可在企業內網和家庭網路中正常運作。
釘釘外掛為社群維護，與 OpenClaw 核心分離安裝，保持 Gateway 輕量。
外掛選擇
釘釘接入有兩個主流社群外掛可選：
• @soimy/dingtalk — 最熱門的外掛，社群活躍維護。支援 Markdown 和 AI Card 兩種回覆格式，功能全面穩定。
• @dingtalk-real-ai/dingtalk-connector — 釘釘官方關聯專案，專注 AI Card 串流回覆，支援多 Agent 路由和非同步模式，要求 OpenClaw v0.7.7+。
兩個外掛都使用 Stream 模式連線，核心體驗一致。選擇建議：新手用 @soimy 版本（資料更多），需要多 Agent 或非同步處理的用 @dingtalk-real-ai 版本。
terminal
# 安裝 @soimy 版本（推薦）
openclaw plugins install @soimy/dingtalk
# 或安裝 @dingtalk-real-ai 版本
openclaw plugins install @dingtalk-real-ai/dingtalk-connector釘釘應用建立與憑證取得
設定釘釘整合需要在釘釘開放平台建立應用：
1. 登入釘釘開放平台 open-dev.dingtalk.com，進入開發者後台。
2. 點選「建立應用」，選擇「企業內部開發」→「機器人」類型。
3. 填寫應用名稱和描述，建立完成後在「憑證與基本資訊」頁面複製 ClientID（即 AppKey，格式 dingXXX）和 ClientSecret（即 AppSecret）。
4. 在「機器人設定」中，訊息接收模式選擇 **Stream 模式**（非 HTTP 模式）。
5. 在權限管理中新增所需權限，關鍵權限包括：
- qyapi_robot_sendmsg（機器人傳送訊息）
- Card.Instance.Write（卡片實例寫入）
- Card.Streaming.Write（串流卡片寫入）
- mediaId.download 和 mediaId.upload（媒體檔案上傳下載）
6. 發布應用，等待組織管理員審批通過。
terminal
# 透過環境變數
export DINGTALK_CLIENT_ID="dingXXXXXX"
export DINGTALK_CLIENT_SECRET="your_app_secret"
# 或透過 CLI
openclaw channels add請妥善保管 ClientSecret。切勿將其提交至版本控制系統。正式環境請使用環境變數。如果洩露，請立即在釘釘開放平台主控台重設。
私聊與群聊策略
釘釘外掛支援靈活的訊息策略設定：
**私聊策略（dmPolicy）**：
• open — 任何人私聊機器人都能獲得回覆
• disabled — 關閉私聊功能
**群聊策略（groupPolicy）**：
• open — 群內任何成員 @機器人即可觸發回覆
• disabled — 完全忽略群聊訊息
群聊中預設需要 @機器人才觸發回覆，避免在活躍群聊中回覆每則訊息。
openclaw.json
{
"channels": {
"dingtalk": {
"dmPolicy": "open",
"groupPolicy": "open"
}
}
}群聊中 @機器人名稱即可觸發，無需額外設定。
工作階段隔離按對話維度，不同聊天有獨立的上下文。30 分鐘不活躍自動重設工作階段。
回覆格式與 AI Card 串流輸出
釘釘外掛支援多種回覆格式：
• **文字（text）** — 最基礎的純文字回覆
• **Markdown** — 支援標題、列表、連結等格式化內容，預設推薦
• **AI Card（串流）** — 類似 ChatGPT 的打字機效果，訊息在卡片中逐步更新
AI Card 串流輸出提供最佳使用者體驗，訊息原地更新不會產生多則訊息。需要在釘釘應用中授予 Card 相關權限。
openclaw.json
{
"channels": {
"dingtalk": {
"messageType": "markdown",
"streaming": true
}
}
}AI Card 串流輸出需要授予 Card.Instance.Write 和 Card.Streaming.Write 權限。
如果不需要串流效果，可將 messageType 設為 markdown 並關閉 streaming。
訊息類型與媒體支援
OpenClaw 釘釘外掛處理多種訊息類型：
**接收支援**：文字、圖片、語音（自動語音辨識）、影片、檔案
**檔案解析**：.docx、.pdf、.txt、.md、.json、.xlsx、.pptx、.zip 等格式可被 AI 讀取和分析
**傳送支援**：文字、Markdown、AI Card、圖片、檔案
語音訊息會自動轉為文字後傳給 AI 處理，無需額外設定。
傳送大檔案前確保釘釘應用已授予媒體上傳權限。
語音訊息自動辨識為文字，支援中英文。
多 Agent 路由
使用 @dingtalk-real-ai 版本的外掛可以設定多 Agent 路由，讓不同的 AI Agent 處理不同類型的對話。例如，私聊走通用助手，特定群聊走專業領域 Agent。
透過 OpenClaw 的 bindings 設定，可以精細控制每個對話的 Agent 分配。
openclaw.json
{
"bindings": [
{ "agentId": "main", "match": { "channel": "dingtalk", "peer": { "kind": "direct" } } },
{ "agentId": "tech-support", "match": { "channel": "dingtalk", "peer": { "kind": "group" } } }
]
}多 Agent 路由僅 @dingtalk-real-ai 版本支援，@soimy 版本暫不支援。
常用指令
OpenClaw 提供多個指令來管理釘釘機器人：
• openclaw gateway status — 檢查 Gateway 連線狀態
• openclaw gateway restart — 重新啟動 Gateway 服務
• openclaw logs --follow — 檢視即時日誌
• openclaw channels add — 互動式新增頻道
• openclaw plugins list — 檢視已安裝外掛
• openclaw plugins update @soimy/dingtalk — 更新釘釘外掛
• openclaw doctor — 綜合診斷
DingTalk 設定參考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 啟用或停用釘釘頻道 |
| clientId | string | "" | 釘釘應用的 ClientID（AppKey），格式 dingXXX，從釘釘開放平台取得 |
| clientSecret | string | "" | 釘釘應用的 ClientSecret（AppSecret），從釘釘開放平台取得 |
| robotCode | string | "" | 機器人的唯一識別碼，從釘釘開放平台的機器人設定頁取得 |
| corpId | string | "" | 企業的 CorpId，格式 dingXXX，從釘釘管理後台取得 |
| agentId | string | "" | 應用的 AgentId，從釘釘開放平台取得 |
| dmPolicy | string | "open" | 私聊策略。選項：open（開放）、disabled（停用） |
| groupPolicy | string | "open" | 群聊策略。選項：open（開放）、disabled（停用） |
| messageType | string | "markdown" | 回覆訊息格式。選項：text（純文字）、markdown、card（AI Card） |
| streaming | boolean | true | 啟用 AI Card 串流回覆（打字機效果） |
| debug | boolean | false | 開啟偵錯模式，輸出詳細的連線和訊息日誌 |
enabled
Type: booleanDefault: true
啟用或停用釘釘頻道
clientId
Type: stringDefault: ""
釘釘應用的 ClientID（AppKey），格式 dingXXX，從釘釘開放平台取得
clientSecret
Type: stringDefault: ""
釘釘應用的 ClientSecret（AppSecret），從釘釘開放平台取得
robotCode
Type: stringDefault: ""
機器人的唯一識別碼，從釘釘開放平台的機器人設定頁取得
corpId
Type: stringDefault: ""
企業的 CorpId，格式 dingXXX，從釘釘管理後台取得
agentId
Type: stringDefault: ""
應用的 AgentId，從釘釘開放平台取得
dmPolicy
Type: stringDefault: "open"
私聊策略。選項：open（開放）、disabled（停用）
groupPolicy
Type: stringDefault: "open"
群聊策略。選項：open（開放）、disabled（停用）
messageType
Type: stringDefault: "markdown"
回覆訊息格式。選項：text（純文字）、markdown、card（AI Card）
streaming
Type: booleanDefault: true
啟用 AI Card 串流回覆（打字機效果）
debug
Type: booleanDefault: false
開啟偵錯模式，輸出詳細的連線和訊息日誌
DingTalk 常見問題
DingTalk 故障排除
機器人完全不回覆
應用可能未發布、Stream 模式未啟用、ClientID 或 ClientSecret 錯誤、或外掛未正確安裝。
逐步排查：1) 確認應用已發布並審批通過；2) 確認訊息接收模式為 Stream 模式；3) 核對 ClientID 和 ClientSecret；4) 執行 openclaw plugins list 確認外掛已安裝；5) 執行 openclaw gateway status 檢查連線狀態。
能收到訊息但 AI 不回覆
OpenClaw 版本升級後可能出現的相容性問題，或 AI 模型 API Key 未設定。
檢查 AI 模型的 API Key 是否正確設定。嘗試更新釘釘外掛：openclaw plugins update @soimy/dingtalk。查看 openclaw logs --follow 取得詳細錯誤資訊。參考
Stream 連線頻繁斷開
網路不穩定或釘釘 Stream 模式已知的訊息遺失問題。
Gateway 會自動處理斷線重連（指數退避策略）。如果頻繁斷線，檢查伺服器網路穩定性，確保防火牆允許出站 WebSocket 連線。開啟 debug 模式查看詳細連線日誌。
群檔案或釘盤檔案無法存取
群檔案和釘盤 API 可能需要企業認證，未認證的組織可能無法使用這些功能。
檢查組織是否已完成企業認證。如果未認證，某些進階檔案 API 將不可用。可以透過直接傳送檔案（而非釘盤分享）來規避此限制。
AI Card 串流輸出不運作
缺少 Card 相關權限，或 messageType 設定不正確。
確認已在釘釘開放平台授予 Card.Instance.Write 和 Card.Streaming.Write 權限。檢查設定中 streaming 是否為 true。權限變更後需要重新發布應用。