Nextcloud Talk

通过 Talk Bot Webhook 协议集成 Nextcloud Talk。支持自托管、联邦化以及端到端加密——与 Matrix 和 Mattermost 并列的另一种自主通信选项。

此集成实现的功能

• 通过网关接收来自 POST /nextcloud-talk 的入站 Talk 事件
• 在配置了密钥时，验证 Webhook 签名（HMAC-SHA256）
• 通过 Nextcloud OCS API 将回复发送回 Talk 房间

前置条件

• Nextcloud 服务器，已启用 Talk 应用（建议使用 v17 或更高版本）
• Bot account in Talk settings — give it a display name (e.g. zeroclaw-bot)
• Bot app token from the Talk admin UI for OCS API bearer auth (used for outbound replies)
• 来自 Talk 管理界面的 Webhook 密钥，如果你希望进行签名验证（强烈建议）。
• 可公开访问的网关 — 如果是自托管，请参阅 设置 → 容器 以获取隧道选项

配置

[channels.nextcloud_talk]
enabled = true
base_url = "https://cloud.example.com"
app_token = "..."                              # OCS API bearer token (bot app token)
webhook_secret = "..."                         # shared secret for HMAC-SHA256 webhook verification
bot_name = "zeroclaw-bot"                      # display name; filters out the bot's own posts
allowed_users = ["*"]                          # actor IDs; "*" = allow all (use for first-time test only)
proxy_url = ""                                 # optional per-channel proxy override

环境变量覆盖：ZEROCLAW_NEXTCLOUD_TALK_WEBHOOK_SECRET 的优先级高于配置文件中的值。适用于在不修改配置文件的情况下轮换密钥。

完整字段参考：Config。

网关端点

zeroclaw daemon

将您的 Talk 机器人的 Webhook URL 配置为指向：

https://<your-public-url>/nextcloud-talk

本地开发？在配置文件中配置 [tunnel]（ngrok、Cloudflare 或 Tailscale），网关将在启动时自动暴露自身——参见 操作 → 网络部署。

签名验证

当设置了 webhook_secret 时，传入的请求必须携带：

• X-Nextcloud-Talk-Random 头
• X-Nextcloud-Talk-Signature 头

ZeroClaw 验证：

expected_sig = hex(hmac_sha256(secret, random + raw_request_body))
if X-Nextcloud-Talk-Signature != expected_sig:
    return 401

没有密钥就无法进行验证——在该模式下不要公开暴露此端点。

消息路由

• 由机器人发起的事件（actorType = "bots"）将被忽略——以防止反馈循环
• 系统事件（加入、离开、成员资格变更）将被忽略
• 非消息事件将被忽略
• 用户消息会被分发到代理循环中
• 回复会通过 webhook 负载中的 token 返回到原始房间

快速验证

1. 首次测试时，设置 allowed_users = ["*"]
2. 在配置的 Talk 房间中发送一条测试消息
3. 确认 ZeroClaw 在同一个房间中接收和回复
4. 将 allowed_users 收紧为明确的参与者 ID（例如 ["alice", "bob"]）

故障排除

• 404 Nextcloud Talk 未配置 — [channels.nextcloud_talk] 部分缺失或 enabled = false
• 401 签名无效 — 密钥不匹配、随机标头错误，或主体签名存在 bug。请检查是否对原始主体进行了签名（而非已解析的 JSON）。
• 无回复，webhook 200 — 事件已被过滤。请检查日志中的 “actorType = bots” 或 “user not in allowed_users”
• 已发送回复，但显示不正确 — 请检查线程上下文；目前 Talk 回复仅支持根级别

流式传输

Nextcloud Talk 不支持通过 Bot API 编辑消息，因此该通道的流式草稿更新已禁用。回复仅在流完成时发送。

自托管笔记

• TLS：在反向代理处终止；Webhook 签名验证通过 HTTP 到容器回环连接工作
• The OCS API is authenticated via Bearer token — use the bot app token from the Talk admin UI
• 速率限制取决于 Nextcloud-server；默认机器人不会在正常的对话频率中遇到这些限制。
• Per-channel proxy: set proxy_url to override the global [proxy] setting for Nextcloud Talk only (http://, https://, socks5://, socks5h://)

另见

• Matrix — 更丰富的端到端加密（E2EE），但操作复杂性更高
• Mattermost — 类似的自托管架构，但使用不同的协议
• 通道 → 概述