Skip to content

nextcloud-talk-setup.zh-CN.md

Latest commit

 

History

History
78 lines (51 loc) · 2.31 KB

nextcloud-talk-setup.zh-CN.md

File metadata and controls

78 lines (51 loc) · 2.31 KB

Nextcloud Talk 安装指南

本指南介绍 ZeroClaw 的原生 Nextcloud Talk 集成。

1. 集成功能

  • 通过 POST /nextcloud-talk 接收传入的 Talk 机器人 webhook 事件。
  • 配置密钥时验证 webhook 签名（HMAC-SHA256）。
  • 通过 Nextcloud OCS API 向 Talk 房间发送机器人回复。

2. 配置

在 ~/.zeroclaw/config.toml 中添加以下部分：

[channels_config.nextcloud_talk]
base_url = \"https://cloud.example.com\"
app_token = \"nextcloud-talk-app-token\"
webhook_secret = \"optional-webhook-secret\"
allowed_users = [\"*\"]

字段说明：

  • base_url：Nextcloud 基础 URL。
  • app_token：机器人应用令牌，用作 OCS 发送 API 的 Authorization: Bearer <token>。
  • webhook_secret：用于验证 X-Nextcloud-Talk-Signature 的共享密钥。
  • allowed_users：允许的 Nextcloud 参与者 ID（[] 拒绝所有，\"*\" 允许所有）。

环境变量覆盖：

  • 设置 ZEROCLAW_NEXTCLOUD_TALK_WEBHOOK_SECRET 时会覆盖 webhook_secret。

3. 网关端点

运行守护进程或网关并暴露 webhook 端点：

zeroclaw daemon
# 或
zeroclaw gateway --host 127.0.0.1 --port 3000

将你的 Nextcloud Talk 机器人 webhook URL 配置为：

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

4. 签名验证规则

配置 webhook_secret 时，ZeroClaw 会验证：

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

验证公式：

  • hex(hmac_sha256(secret, random + raw_request_body))

如果验证失败，网关返回 401 Unauthorized。

5. 消息路由行为

  • ZeroClaw 忽略来自机器人的 webhook 事件（actorType = bots）。
  • ZeroClaw 忽略非消息/系统事件。
  • 回复路由使用 webhook 负载中的 Talk 房间令牌。

6. 快速验证清单

  1. 首次验证时设置 allowed_users = [\"*\"]。
  2. 在目标 Talk 房间发送测试消息。
  3. 确认 ZeroClaw 收到消息并在同一房间回复。
  4. 将 allowed_users 收紧为明确的参与者 ID。

7. 故障排除

  • 404 Nextcloud Talk not configured：缺少 [channels_config.nextcloud_talk] 配置。
  • 401 Invalid signature：webhook_secret、随机数请求头或原始体签名不匹配。
  • webhook 返回 200 但无回复：事件被过滤（机器人/系统/非允许用户/非消息负载）。