OpenClaw Nextcloud Talk 頻道
企業
中等
將 OpenClaw 連接至 Nextcloud Talk——這是一個內建於 Nextcloud 生態系統中、注重隱私的企業通訊平台。整合採用基於 Webhook 的機器人架構——Nextcloud Talk 透過 Webhook 將訊息事件傳送至您的 Gateway，機器人再透過 Talk REST API 回覆。這讓您的 AI 助手能在自架的 Nextcloud 環境中參與私訊、群組對話，以及使用表情回應訊息。
快速資訊
難度中等
分類企業
支援功能數4 / 6
Nextcloud Talk 支援功能
文字訊息
支援
媒體與檔案
支援
表情回應
支援
討論串
不支援
語音訊息
不支援
群組聊天
支援
Nextcloud Talk 前置條件
- 一台 Nextcloud 伺服器（v27.1+），具有管理員權限且已安裝 Talk 應用程式
- 一組共享金鑰（40-128 個字元），用於 Webhook 簽名驗證
- Gateway 的 Webhook 端點可從 Nextcloud 伺服器存取（公開 URL 或內部網路）
- OpenClaw Gateway 已安裝並執行
- 已透過 'openclaw plugins install @openclaw/nextcloud-talk' 安裝 Nextcloud Talk 外掛
Nextcloud Talk 快速設定
1
安裝 Nextcloud Talk 外掛
執行 'openclaw plugins install @openclaw/nextcloud-talk' 為您的 Gateway 新增 Nextcloud Talk 支援。
2
在 Nextcloud 伺服器上註冊機器人
透過 SSH 登入您的 Nextcloud 伺服器並執行 OCC 指令：./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction。將 <shared-secret> 替換為一組強度足夠的 40 個字元以上的金鑰，將 <webhook-url> 替換為 Gateway 可公開存取的 Webhook 端點（例如 https://gateway.example.com:8788/webhook）。
3
啟用機器人並進行設定
在 Nextcloud Talk 中，前往房間設定並啟用 OpenClaw 機器人。然後在 ~/.openclaw/openclaw.json 中新增頻道設定，填入您的 baseUrl 和 botSecret。使用 'openclaw start' 啟動 Gateway，並在房間中傳送一則訊息以驗證連線。
Nextcloud Talk 設定範例
config.json
{
"channels": {
"nextcloud-talk": {
"enabled": true,
"baseUrl": "https://nextcloud.example.com",
"botSecret": "your-shared-secret-min-40-chars",
"dmPolicy": "pairing"
}
}
}Nextcloud Talk 深入了解
架構概述
OpenClaw 透過 Talk Bot API（自 Nextcloud 27.1 起可用）與 Nextcloud Talk 整合。架構基於 Webhook：
1. 使用 OCC 命令列工具在 Nextcloud 伺服器上註冊機器人，提供共享金鑰和 Webhook URL。
2. 當訊息發佈到已啟用機器人的房間時，Nextcloud Talk 會向設定的 Webhook URL 傳送一個 HTTP POST 請求，其中包含訊息內容，並使用共享金鑰進行簽名。
3. Gateway 驗證 Webhook 簽名後，透過您的 AI 代理處理訊息，再透過 Talk REST API 將回覆發佈到對話中。
這種設計意味著 Gateway 必須公開一個可從 Nextcloud 伺服器存取的 Webhook 端點。Webhook 監聽器預設在連接埠 8788 執行，可透過 webhookPort 和 webhookHost 設定選項進行自訂。
Webhook URL 必須可從 Nextcloud 伺服器存取。在本機開發時，可使用 ngrok 等通道服務。
每次機器人安裝會產生一個唯一的 URL 雜湊值（bot-<hash>），作為訊息的發送者 ID。
透過 OCC 註冊機器人
Nextcloud Talk 機器人是透過 OCC（Nextcloud Command Console）指令在伺服器上註冊的。這是一個伺服器端操作，需要 SSH 或主控台存取權限。
安裝機器人的指令：
./occ talk:bot:install "OpenClaw" "<secret>" "<webhook-url>" --feature reaction
參數說明：
• name（必填）：顯示名稱，作為訊息發送者（1-64 個字元）
• secret（必填）：用於 Webhook 簽名驗證的共享金鑰（40-128 個字元）
• url（必填）：您的 Gateway Webhook 端點 URL
• --feature：機器人功能——使用 'reaction' 啟用表情回應
• --no-setup：防止管理員在各房間切換機器人開關
其他實用的 OCC 指令：
• talk:bot:list — 列出所有已安裝的機器人
• talk:bot:remove <bot-id> — 從特定對話中移除機器人
• talk:bot:setup <bot-id> <token> — 在對話中啟用機器人
• talk:bot:state <bot-id> <state> — 變更機器人狀態（0=停用、1=啟用、2=禁止設定）
• talk:bot:uninstall <id> — 從伺服器完全移除機器人
Terminal
./occ talk:bot:install "OpenClaw" "a]72@Bz&V!LKMO*xhQib7p^E%yzGMG(8a7Bp*x6o" "https://gateway.example.com:8788/webhook" --feature reaction使用以下指令產生強度足夠的共享金鑰：openssl rand -base64 48
建議使用 --feature reaction 旗標，讓機器人可以對訊息進行表情回應。
私訊策略
私訊（DM）策略控制機器人如何處理一對一的私人對話。
**pairing（預設）** — 未知的發送者會收到一組配對碼，必須驗證後機器人才會回覆。這是最安全的模式，需要明確的使用者授權。
**open** — 任何向機器人傳送訊息的使用者都會收到回覆。需要將 allowFrom 設定為 ["*"]。
**disabled** — 機器人完全不回覆私訊。
注意：Nextcloud Talk 機器人無法主動發起私訊——必須由使用者先向機器人傳送訊息。allowFrom 欄位匹配的是 Nextcloud 使用者 ID（非顯示名稱）。
openclaw.json
{
"channels": {
"nextcloud-talk": {
"dmPolicy": "pairing",
"allowFrom": ["user-id-1", "user-id-2"]
}
}
}Nextcloud Talk 中的機器人無法主動發起私訊。使用者必須先聯絡機器人才能開始對話。
房間設定
房間（群組聊天）策略控制機器人參與哪些對話以及如何觸發。
**allowlist（預設）** — 機器人僅在管理員透過房間設定明確啟用的房間中回覆。
可透過 rooms 物件自訂各房間的設定。每個房間以其對話 token 識別，可擁有獨立的設定：
• requireMention — 設為 true 時，機器人僅在被 @提及 時才回覆（房間中的預設行為）
• 未列在設定中的房間使用預設的房間設定
要查找房間的 token，請查看在 Nextcloud Talk 中檢視房間時的 URL（例如 https://nextcloud.example.com/call/<token>）。
openclaw.json
{
"channels": {
"nextcloud-talk": {
"groupPolicy": "allowlist",
"rooms": {
"abc123token": {
"requireMention": true
},
"def456token": {
"requireMention": false
}
}
}
}
}房間管理員必須在房間設定中啟用機器人，機器人才能接收訊息。
在訊息頻繁的房間中使用 requireMention: true，以避免機器人回覆每一則訊息。
用於房間偵測的 API 憑證
預設情況下，Nextcloud Talk 的 Webhook 負載不會區分私訊和房間訊息。若要啟用精確的房間類型偵測，您可以提供 API 憑證。
當設定了 apiUser 和 apiPassword 時，Gateway 會進行額外的 API 呼叫，以判斷收到的訊息來自私訊還是房間對話。這讓機器人能正確套用不同的策略（dmPolicy 與 groupPolicy）。
若未設定 API 憑證，機器人會對所有訊息套用統一的策略，這對於簡單的部署可能已經足夠。
openclaw.json
{
"channels": {
"nextcloud-talk": {
"apiUser": "bot-service-account",
"apiPassword": "service-account-password",
"apiPasswordFile": "/run/secrets/nc-api-password"
}
}
}請建立專用的 Nextcloud 使用者帳號作為 API 憑證，避免使用管理員帳號。
使用 apiPasswordFile 從檔案（例如 Docker secret）載入密碼，而非將其儲存在設定檔中。
若未設定 API 憑證，機器人將無法區分私訊和房間訊息。這可能導致僅限私訊的策略無法正常運作。
Webhook 設定
Gateway 會啟動一個內建的 HTTP 伺服器來接收 Nextcloud Talk 的 Webhook 事件。Webhook 監聽器設定控制伺服器的監聽方式和位置。
**webhookPort**（預設：8788）— Webhook HTTP 伺服器的連接埠。
**webhookHost**（預設：0.0.0.0）— 綁定的網路介面。使用 0.0.0.0 監聽所有介面，或使用 127.0.0.1 僅監聽本機。
**webhookPath** — Webhook 端點的自訂 URL 路徑。
**webhookPublicUrl** — Nextcloud 用於存取 Webhook 的完整公開 URL。在反向代理或 NAT 後面時為必填。
在機器人安裝（OCC 指令）期間提供的 Webhook URL 必須與解析到此監聽器的公開 URL 一致。
openclaw.json
{
"channels": {
"nextcloud-talk": {
"webhookPort": 8788,
"webhookHost": "0.0.0.0",
"webhookPath": "/webhook",
"webhookPublicUrl": "https://gateway.example.com:8788/webhook"
}
}
}若在反向代理後面執行，請將 webhookPublicUrl 設定為外部可存取的 URL。
確保防火牆允許從 Nextcloud 伺服器到 Webhook 連接埠的入站連線。
訊息處理與串流
OpenClaw 提供精細的控制，管理訊息如何分段並傳送至 Nextcloud Talk。
**textChunkLimit** — 每則訊息分段的最大字元數。Nextcloud Talk 支援長訊息，但分段可提升長篇 AI 回覆的可讀性。
**chunkMode** — 控制文字分割方式：'length' 在字元限制處分割，'newline' 在段落邊界分割，使斷點更自然。
**blockStreaming** — 啟用後，機器人會等待完整的 AI 回覆後再傳送，而非串流傳送部分回覆。
**blockStreamingCoalesce** — 在啟用 blockStreaming 時，將最終回覆合併為一則訊息，而非多個分段。
**mediaMaxMb** — 媒體附件的最大檔案大小（MB）。請注意 Nextcloud Talk 以 URL 形式傳輸媒體，而非直接上傳檔案。
openclaw.json
{
"channels": {
"nextcloud-talk": {
"textChunkLimit": 4000,
"chunkMode": "newline",
"blockStreaming": true,
"blockStreamingCoalesce": true,
"mediaMaxMb": 10
}
}
}在多人活躍的房間中使用 blockStreaming: true，以獲得更整潔的回覆。
Nextcloud Talk 中的媒體以 URL 形式分享——機器人無法直接上傳檔案。
對話歷史紀錄
控制 AI 代理在處理新訊息時，包含多少則先前的訊息作為上下文。
**historyLimit** — 房間對話中包含的先前訊息最大數量。
**dmHistoryLimit** — 私訊對話中包含的先前訊息最大數量。此設定可獨立於房間歷史紀錄限制進行調整。
也支援針對個別私訊的覆寫設定，讓您可以為特定使用者設定不同的歷史紀錄限制。
較高的歷史紀錄限制可為 AI 提供更多上下文，但會增加 token 用量和處理時間。
openclaw.json
{
"channels": {
"nextcloud-talk": {
"historyLimit": 20,
"dmHistoryLimit": 50
}
}
}表情回應支援
Nextcloud Talk 支援對訊息進行表情回應，OpenClaw 機器人可以讀取和新增回應。
要啟用表情回應支援，機器人在 OCC 安裝時必須使用 --feature reaction 旗標進行註冊。啟用後，AI 代理可以對使用者訊息進行表情回應，以提供確認或回饋。
表情回應是機器人在不發佈完整文字回覆的情況下進行互動的輕量方式——例如，對已完成的任務回應一個打勾表情。
Nextcloud Talk Reaction API（自 bots-v1 功能起可用）負責處理新增和移除回應的底層機制。
安裝機器人時必須設定 --feature reaction 旗標，表情回應功能才能運作。
在訊息頻繁的房間中，表情回應可作為一種不干擾的確認機制。
安全性與 Webhook 簽名
所有來自 Nextcloud Talk 的 Webhook 負載都使用在機器人安裝期間設定的共享金鑰進行簽名。Gateway 會驗證每個簽名以確保真實性和完整性。
簽名機制使用 HMAC-SHA256：
1. Nextcloud 使用共享金鑰對 Webhook 負載本體計算 HMAC-SHA256 雜湊值。
2. 簽名包含在 Webhook 請求的 HTTP 標頭中。
3. Gateway 獨立計算雜湊值並與收到的簽名進行比對。
4. 若簽名不匹配，請求將被拒絕。
這確保只有來自您的 Nextcloud 伺服器的合法請求會被處理。請妥善保管共享金鑰，並透過重新安裝機器人與新金鑰來定期輪換。
使用高強度的加密金鑰：openssl rand -base64 48 可產生適合的值。
使用 botSecretFile 儲存金鑰，避免將其提交至版本控制系統。
切勿在公開的程式碼儲存庫或日誌中暴露共享金鑰。在正式環境部署時，請使用環境變數或金鑰檔案。
Nextcloud Talk 設定參考
| Key | Type | Default | Description |
|---|---|---|---|
| enabled | boolean | true | 啟用或停用 Nextcloud Talk 頻道 |
| baseUrl | string | "" | Nextcloud 伺服器的完整 URL（例如 https://nextcloud.example.com） |
| botSecret | string | "" | 用於 Webhook 簽名驗證的共享金鑰（必須與 OCC 安裝時的金鑰一致） |
| botSecretFile | string | "" | 包含共享金鑰的檔案路徑（作為內嵌 botSecret 的替代方案） |
| apiUser | string | "" | 用於 API 呼叫的 Nextcloud 使用者名稱（用於房間類型偵測） |
| apiPassword | string | "" | API 使用者帳號的密碼 |
| apiPasswordFile | string | "" | 包含 API 密碼的檔案路徑（作為內嵌 apiPassword 的替代方案） |
| dmPolicy | string | "pairing" | 私訊存取策略：'pairing'（驗證碼）、'open'（任何使用者）或 'disabled'（停用私訊） |
| allowFrom | string[] | [] | 允許向機器人傳送私訊的 Nextcloud 使用者 ID（使用 ["*"] 開放所有存取） |
| groupPolicy | string | "allowlist" | 房間存取策略：'allowlist'（僅限管理員啟用的房間） |
| webhookPort | number | 8788 | 內建 Webhook HTTP 伺服器的連接埠 |
| webhookHost | string | "0.0.0.0" | Webhook 伺服器綁定的網路介面 |
| webhookPath | string | "/webhook" | Webhook 端點的 URL 路徑 |
| webhookPublicUrl | string | "" | Webhook 端點的完整公開 URL（在反向代理後面時為必填） |
| historyLimit | number | 20 | 房間對話中作為上下文包含的先前訊息最大數量 |
| dmHistoryLimit | number | 50 | 私訊對話中作為上下文包含的先前訊息最大數量 |
| textChunkLimit | number | 4000 | 每則訊息分段的最大字元數 |
| chunkMode | string | "length" | 文字分割模式：'length'（字元限制）或 'newline'（段落邊界） |
| blockStreaming | boolean | false | 等待完整的 AI 回覆後再傳送（不串流） |
| blockStreamingCoalesce | boolean | false | 將串流分段合併為一則最終訊息 |
| mediaMaxMb | number | 10 | 媒體 URL 參照的最大檔案大小（MB） |
enabled
Type: booleanDefault: true
啟用或停用 Nextcloud Talk 頻道
baseUrl
Type: stringDefault: ""
Nextcloud 伺服器的完整 URL（例如 https://nextcloud.example.com）
botSecret
Type: stringDefault: ""
用於 Webhook 簽名驗證的共享金鑰（必須與 OCC 安裝時的金鑰一致）
botSecretFile
Type: stringDefault: ""
包含共享金鑰的檔案路徑（作為內嵌 botSecret 的替代方案）
apiUser
Type: stringDefault: ""
用於 API 呼叫的 Nextcloud 使用者名稱（用於房間類型偵測）
apiPassword
Type: stringDefault: ""
API 使用者帳號的密碼
apiPasswordFile
Type: stringDefault: ""
包含 API 密碼的檔案路徑（作為內嵌 apiPassword 的替代方案）
dmPolicy
Type: stringDefault: "pairing"
私訊存取策略：'pairing'（驗證碼）、'open'（任何使用者）或 'disabled'（停用私訊）
allowFrom
Type: string[]Default: []
允許向機器人傳送私訊的 Nextcloud 使用者 ID（使用 ["*"] 開放所有存取）
groupPolicy
Type: stringDefault: "allowlist"
房間存取策略：'allowlist'（僅限管理員啟用的房間）
webhookPort
Type: numberDefault: 8788
內建 Webhook HTTP 伺服器的連接埠
webhookHost
Type: stringDefault: "0.0.0.0"
Webhook 伺服器綁定的網路介面
webhookPath
Type: stringDefault: "/webhook"
Webhook 端點的 URL 路徑
webhookPublicUrl
Type: stringDefault: ""
Webhook 端點的完整公開 URL（在反向代理後面時為必填）
historyLimit
Type: numberDefault: 20
房間對話中作為上下文包含的先前訊息最大數量
dmHistoryLimit
Type: numberDefault: 50
私訊對話中作為上下文包含的先前訊息最大數量
textChunkLimit
Type: numberDefault: 4000
每則訊息分段的最大字元數
chunkMode
Type: stringDefault: "length"
文字分割模式：'length'（字元限制）或 'newline'（段落邊界）
blockStreaming
Type: booleanDefault: false
等待完整的 AI 回覆後再傳送（不串流）
blockStreamingCoalesce
Type: booleanDefault: false
將串流分段合併為一則最終訊息
mediaMaxMb
Type: numberDefault: 10
媒體 URL 參照的最大檔案大小（MB）
Nextcloud Talk 常見問題
Nextcloud Talk 故障排除
機器人未回覆訊息
Webhook URL 無法存取、機器人未在房間中啟用，或共享金鑰不匹配。
驗證 Webhook URL 是否可從 Nextcloud 伺服器存取（使用 curl 測試）。確認機器人已在房間設定中啟用。確保 openclaw.json 中的 botSecret 與 OCC 安裝指令中使用的金鑰一致。
Webhook 簽名驗證失敗
openclaw.json 中的共享金鑰與機器人安裝時使用的金鑰不匹配。
驗證兩組金鑰完全一致。如果不確定，請解除安裝並使用已知的金鑰重新安裝機器人。檢查 Gateway 日誌中的簽名不匹配錯誤。
機器人在私訊中回覆但在房間中不回覆
管理員未在目標房間中啟用機器人，或 requireMention 為 true 但機器人未被 @提及。
請房間管理員在房間設定中啟用機器人。若已設定 requireMention，請確保使用者 @提及 機器人名稱。檢查 openclaw.json 中的 rooms 設定。
無法區分私訊和房間訊息
未設定 API 憑證（apiUser、apiPassword）。
在 nextcloud-talk 頻道設定中新增 apiUser 和 apiPassword。請建立專用的 Nextcloud 服務帳號。Gateway 使用這些憑證查詢 Talk API 以偵測對話類型。
Gateway 無法啟動 Webhook 監聽器
設定的 Webhook 連接埠已被佔用或主機綁定無效。
將 webhookPort 更改為可用的連接埠（預設：8788）。若綁定到特定介面，請驗證 webhookHost IP 位址是否正確。使用 'lsof -i :8788' 或 'netstat -tlnp' 檢查連接埠衝突。