Nextcloud Talk

通过 Talk Bot webhook 协议集成 Nextcloud Talk。自托管、联邦化并支持端到端加密：除了 Matrix 和 Mattermost 之外的又一种自主通信选择。

谁可以与代理通信

入站发送方会根据为绑定代理解析出的对等集合进行限制，该集合来自代理所属的 peer_groups 配置。匹配时会去除开头的 @，并对通道的原生发送方标识符执行不区分大小写的比对。空集合会拒绝所有人；包含 "*" 的集合会接受所有人；否则仅接受列出的外部对等方（以及对等代理）。这与网关配对（gateway.require_pairing）不同，后者验证的是 HTTP/WebSocket 客户端，而非聊天通道的发送方。

nextcloud 的对等组将 channel 设置为 nextcloud，在 external_peers 中列出允许的发送者（对于 nextcloud，即 Nextcloud actor ID；["*"] 接受任何人），可选地命名对等 agents 以进行跨代理分发、一个 ignore 屏蔽列表，以及一个 output_modality（mirror、voice 或 text）。字段参考请参阅 Peer Groups。

在何处设置：

此集成实现的功能

• 通过网关上的 POST /nextcloud-talk/<alias> 接收入站 Talk 事件（裸 /nextcloud-talk 仍然有效，但已弃用，作为后备方案）
• 需要并验证 Webhook 签名（HMAC-SHA256）与已安装的机器人密钥
• 通过已签名的 Nextcloud Talk Bot API 将回复发送回 Talk 房间

前置条件

• Nextcloud server 27.1 或更高版本，以及 Talk 17.1 或更高版本。 这是硬性最低要求，而非建议：此集成用于发送回复的已签名 Talk Bot API 是在 Talk 17.1 中引入的，且早期版本不支持下方的 occ talk:bot:install。

• 已安装机器人，同时启用了 webhook 和 response 功能，使 Nextcloud 能够将房间消息传递给 ZeroClaw，并让 ZeroClaw 发送回复：

  sudo -u www-data php occ talk:bot:install \
    -f webhook -f response \
    zeroclaw-bot '<shared-secret>' \
    'https://<your-public-url>/nextcloud-talk/<alias>'
  

• Bot 密钥来自该安装。Nextcloud 为每个 bot 生成一个共享密钥，同时用于验证传入 webhook 签名以及为传出的 bot-API 回复签名。将其设置为 webhook_secret，这是规范配置项。bot_token 是同一值的已弃用别名：如果两者都已设置，则必须完全相同。它不能保存不同的出站密钥。对于冲突的非空值，系统不会静默地选择其中一个；冲突会被记录到日志中，并且该别名会解析为无密钥，因此该频道的行为将完全等同于未配置：传入请求返回 401，不发送出站消息。

• 可公开访问的网关：如果自托管，请参阅 Setup → Container 了解隧道选项

两个方向在密钥缺失时均以关闭状态失败，且不存在未认证模式：

• 入站：签名验证是强制性的。若无法解析密钥，Webhook 端点将返回 401 且请求永远不会到达 Agent。不存在接受未验证 Webhook 的“公开“模式。
• 出站：完全不发送任何请求，因此配置错误永远不会将未签名或签名错误的请求发送到网络上。

升级是一个破坏性变更。 之前在没有密钥的情况下运行的部署会接受 webhook；升级后将以 401 拒绝所有请求。请先使用 occ talk:bot:install 安装机器人，然后在升级之前将该密钥设置为 webhook_secret，否则入站消息将停止被处理。

配置

zeroclaw config set channels.nextcloud_talk.<alias>.app_token    # 掩码输入，加密存储

export ZEROCLAW_channels__nextcloud_talk__<alias>__app_token=

zeroclaw config set channels.nextcloud_talk.<alias>.base_url <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__base_url=

zeroclaw config set channels.nextcloud_talk.<alias>.bot_name <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__bot_name=

zeroclaw config set channels.nextcloud_talk.<alias>.bot_token    # 掩码输入，加密存储

export ZEROCLAW_channels__nextcloud_talk__<alias>__bot_token=

zeroclaw config set channels.nextcloud_talk.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__draft_update_interval_ms=

zeroclaw config set channels.nextcloud_talk.<alias>.excluded_tools <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__excluded_tools=

zeroclaw config set channels.nextcloud_talk.<alias>.proxy_url <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__proxy_url=

zeroclaw config set channels.nextcloud_talk.<alias>.stream_mode <value>

export ZEROCLAW_channels__nextcloud_talk__<alias>__stream_mode=

zeroclaw config set channels.nextcloud_talk.<alias>.webhook_secret    # 掩码输入，加密存储

export ZEROCLAW_channels__nextcloud_talk__<alias>__webhook_secret=

通道是从 default 别名读取的。可通过任意配置入口进行设置：

webhook_secret 也可以在运行时通过通用环境变量覆盖 ZEROCLAW_channels__nextcloud_talk__default__webhook_secret 提供，这对于在不编辑配置的情况下轮换它非常有用。

app_token 已弃用且未使用（回复不再通过 OCS bearer 身份验证）；之所以仍接受它，只是为了让设置了它的旧配置不会解析失败。

网关端点

zeroclaw daemon

配置 Talk 机器人的 webhook URL，使其指向应接收该消息的 [channels.nextcloud_talk.<alias>] 实例的别名：

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

例如，[channels.nextcloud_talk.work] 会接收 POST /nextcloud-talk/work。这种按别名路由（#6312）的方式让你可以同时运行多个 Talk 机器人，并将各自的 webhook 投递到对应的实例。

裸 https://<your-public-url>/nextcloud-talk 路径仍可使用，但已弃用：它会解析到按字典序排在首位的别名（在重启后保持确定性），并返回 X-Zeroclaw-Deprecation 响应头。单实例部署可以继续原样使用它。未知别名将返回 404。

本地开发？在配置中设置 [tunnel]（ngrok、Cloudflare 或 Tailscale），网关将在启动时自动对外暴露：参见 运维 → 网络部署。

签名验证

入站请求必须携带：

• 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

如果没有解析到密钥，ZeroClaw 会在解析或分派 webhook 之前返回 401。不存在接受未经验证请求的模式。

消息路由

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

快速验证

1. 在对等组中设置 external_peers = ["*"] 以进行首次测试
2. 在配置的 Talk 房间中发送一条测试消息
3. 确认 ZeroClaw 在同一个房间中接收和回复
4. 将对等组收紧为明确的 actor ID（例如 ["alice", "bob"]）

故障排除

• 404 Nextcloud Talk not configured：缺少 [channels.nextcloud_talk.default] 区段或 enabled = false
• 401 Invalid signature：密钥不匹配、随机标头错误，或正文签名缺陷。请检查是否对原始正文进行签名（而非解析后的 JSON）
• 无回复，webhook 返回 200：事件已被过滤。请检查日志中是否存在 “actorType = bots” 或发送者不在对等集中的情况
• 回复已送达但显示异常：检查会话线程上下文；Talk 回复目前仅支持根级别

流式传输

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

自托管笔记

• TLS：在反向代理处终止；Webhook 签名验证通过 HTTP 到容器回环连接工作
• 出站回复通过 Bot API 的 HMAC 签名（webhook_secret/bot_token）进行身份验证，而不是使用 Bearer 令牌；无需管理单独的 OCS Bearer 凭据
• 速率限制取决于 Nextcloud-server；默认机器人不会在正常的对话频率中遇到这些限制。
• 按渠道代理：设置 proxy_url 可仅为 Nextcloud Talk 覆盖全局 [proxy] 设置（http://、https://、socks5://、socks5h://）

另见

• Matrix：更丰富的端到端加密，但运维复杂度更高
• Mattermost：类似的自托管定位，不同的协议
• 通道 → 概述