Nextcloud Talk
Nextcloud Talk 是一个可下载的通道插件(@openclaw/nextcloud-talk),通过 Talk webhook 机器人将 OpenClaw 连接到自托管的 Nextcloud 实例。支持直接消息、房间、表情回应和 Markdown 消息;媒体以 URL 形式发出。
安装¶
使用裸包规范以跟随当前官方发布标签。仅在需要可复现安装时固定确切版本。
从本地检出(开发工作流):
安装后检查应用结果。
消息如何到达代理¶
sequenceDiagram
participant User as Talk user
participant Talk as Nextcloud Talk
participant Hook as OpenClaw webhook
participant Agent as OpenClaw agent
User->>Talk: Send a message
Talk->>Hook: Signed webhook
Hook->>Hook: Verify signature and store the message durably
Hook-->>Talk: HTTP 200 with durable acceptance marker
Hook->>Hook: Check sender, room, and mention access
alt Message is allowed
Hook->>Agent: Route to the agent session
Agent-->>Talk: Reply through the Talk API
Talk-->>User: Show the reply
else Message is not allowed
Note over Hook: No agent turn
end
Webhook 确认表示已持久接收,而不是允许运行代理或其回复已完成。接受后仍会应用访问检查。未知直接消息发送者可能会收到配对码,而不是代理回复。
Webhook URL 必须可从 Nextcloud 访问;回复通过 Talk API 返回,而不是在 webhook 响应中返回。
快速设置(初学者)¶
- 安装插件(如上)。
- 通过 HTTPS 反向代理发布 Gateway webhook 路由
/nextcloud-talk-webhook,并转发到 Gateway 端口(默认18789)。在你的 Nextcloud 服务器上,使用该公共 URL 创建一个机器人:
./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature webhook --feature response --feature reaction
保留 --feature response:缺少它时,出站回复会以 401 失败。使用 ./occ talk:bot:state --feature webhook --feature response --feature reaction <botId> 1 修复现有机器人。
3. 在目标房间设置中启用机器人。
4. 配置 OpenClaw:
- 配置:channels.nextcloud-talk.baseUrl + channels.nextcloud-talk.botSecret
- 或环境变量:NEXTCLOUD_TALK_BOT_SECRET(仅限默认账户)
CLI 设置(--url/--token 是显式字段的别名;nc-talk 和 nc 可作为通道别名使用):
openclaw channels add --channel nextcloud-talk \
--url https://cloud.example.com \
--token "<shared-secret>"
等效的显式字段:
openclaw channels add --channel nextcloud-talk \
--base-url https://cloud.example.com \
--secret "<shared-secret>"
基于文件的密钥:
openclaw channels add --channel nextcloud-talk \
--base-url https://cloud.example.com \
--secret-file /path/to/nextcloud-talk-secret
openclaw channels status --probe;如果 Gateway 离线,请启动它。配置更改遵循热重载。如果你更改了服务环境,请重启 Gateway 以加载它。
最小配置:
{
channels: {
"nextcloud-talk": {
enabled: true,
baseUrl: "https://cloud.example.com",
botSecret: "shared-secret",
dmPolicy: "pairing",
},
},
}
说明¶
- 机器人无法发起直接消息。用户必须先向机器人发送消息。
- Webhook URL 必须可从 Nextcloud 服务器访问。Gateway 在其自己的 HTTP 端口上提供
webhookPath。现有安装可能保留针对旧端口8788的显式legacyWebhook固定;新安装不会打开单独端口。使用代理时,将webhookPublicUrl设置为机器人的外部回调 URL。Webhook 请求使用机器人密钥进行 HMAC-SHA256 签名;无效签名会被拒绝并受到速率限制。 - 消息 webhook 只有在原始事件被持久存储后才返回 HTTP 200;存储失败返回 HTTP 500。持久
200携带x-openclaw-delivery-accepted: durable,因此反向代理可以要求该标记以区分 OpenClaw 接受和通用200。不支持的非消息事件返回不带该标记的 HTTP 200,并记录为已忽略。 - Webhook 监听器最多允许 64 个并发未认证正文读取;溢出请求会收到带
Connection: close的HTTP/1.1 429。同一 keep-alive 连接上的请求按顺序应答,因此排队投递的200确认总是在任何溢出拒绝关闭套接字之前刷新。64 读取预算固定且不可配置。共享 Gateway 路径名的账户共享其准入和认证失败预算;每个保留的旧主机和端口保持独立预算。经常使其饱和的部署应减少或缓冲上游并发(例如,限制反向代理向监听器的扇入),并接受饱和期间被拒绝的投递可能会丢失。 - 机器人 API 不支持媒体上传;出站媒体作为
Attachment: <url>行附加。 - Webhook 负载不区分直接消息和房间;设置
apiUser+apiPassword以启用房间类型查找(缓存约 5 分钟)。没有它们时,每个会话都被视为房间。 - 出站请求经过 SSRF 防护。对于位于受信任私有/内部网络上的 Nextcloud 主机,使用
channels.nextcloud-talk.network.dangerouslyAllowPrivateNetwork: true选择加入。 - 设置
apiUser/apiPassword和webhookPublicUrl后,openclaw channels status会检查机器人,并在缺少response功能时发出警告。
2026 年 7 月之前的 JSON 重放缓存位于 <state-dir>/nextcloud-talk/replay-dedupe/ 下,不在支持的升级窗口内。Doctor 会保持这些文件不变,停止并给出恢复指导。通过 2026.9.5 升级并在安装最新版本之前运行其 Doctor。受支持的 SQLite 重放状态会继续迁移到持久 webhook 去重中。
迁移现有 Webhook 端点到 Gateway¶
Doctor 会为现有安装中依赖隐式端点的已启用账户,使用一次性 legacyWebhook: { port: 8788, host: "0.0.0.0" } 固定项保留之前的 Webhook 监听器地址。需要先前运行的证据;新安装不会打开单独的端口。显式的 { port, host? } 对象选择该端点;省略 host 时使用 0.0.0.0。省略或 false 不打开监听器,具体取决于账户继承。显式监听器使用相同的 Gateway 路由、HMAC 验证和通道处理器。
Nextcloud 在 OpenClaw 外部存储机器人回调 URL,因此更新无法安全地重写它。若要仅使用 Gateway 监听器,请保留公共 HTTPS 地址,并将反向代理的上游更改为 Gateway HTTP 端口(默认为 18789),同时保留 /nextcloud-talk-webhook 或你配置的 webhookPath。如果 Nextcloud 直接连接,请改为将机器人回调更新为该 Gateway 路由可访问的 HTTPS 端点。如果其公共地址发生变化,请更新 webhookPublicUrl;此字段记录用于状态检查的地址,不会更改 Nextcloud 的机器人注册。
openclaw doctor --fix 将旧的 webhookPort 和 webhookHost 设置迁移到 legacyWebhook,使用 Doctor 的常规配置备份和写入流程。仅主机设置会保留该主机,端口为 8788。命名账户保留其有效端点。现有规范设置(包括继承的 false)优先于已弃用的键。Doctor 和启动过程会报告有效监听器和 Gateway 目标,而不更改外部回调 URL。
已弃用的 TypeScript webhookPort 和 webhookHost 输入字段在下一个 Plugin SDK 主要版本之前保持源码兼容。运行时配置使用 legacyWebhook;运行 openclaw doctor --fix 以迁移旧键。
账户可以共享 Gateway 路径:后端来源和签名必须恰好标识一个账户,因此在共享 Gateway 路径时,请为同一 Nextcloud 后端上的账户设置不同的机器人密钥。独立的旧版端点会保留其原始账户选择以及独立的准入和认证失败预算,即使这些账户具有相同的后端和密钥。
Webhook 路径保留精确的请求匹配,包括查询字符串、大小写和尾部斜杠。/health、/healthz、/ready、/readyz、/startup 和 /startupz 属于 Gateway 检查,即使后面跟随查询字符串也是如此。/api/channels 下的路径需要 Gateway 认证,包括编码别名;Nextcloud 的签名不提供该认证。Doctor 会警告这些路径,并且没有显式旧版监听器的账户不能启动一个旧版监听器。将 webhookPath 设置为 /nextcloud-talk-webhook,并将 Nextcloud 机器人回调和反向代理上游更新为 Gateway 端口及该路径。在此切换期间,已启用的旧版监听器会继续提供其配置的路径;OpenClaw 不会静默重写回调路径。
在通过 Gateway 路由验证投递后,移除 legacyWebhook 固定项并重启账户,以禁用其旧版转发。当另一个账户使用该端点时,共享监听器会保持打开。保留 meta.migrations.webhookListeners,Doctor 会将其与固定项一起保存,以便后续运行不会重新创建它。有关包含的配置源和只读配置源,请参阅 Webhook 迁移。在账户上使用显式 false 以覆盖继承的根监听器。旧版端口保留精确的 /healthz 响应:对于每种常规 HTTP 方法,均返回 200 ok 和 Content-Type: text/plain(HEAD 没有正文)。查询字符串、大小写变化和尾部斜杠不会匹配该健康检查路径。这使现有的反向代理健康检查继续工作。在移动代理上游时,使用 Gateway 自身的健康检查和 openclaw channels status --probe;主 Gateway 端口保留其现有的 JSON 检查响应。
访问控制(私信)¶
- 默认:
channels.nextcloud-talk.dmPolicy = "pairing"。未知发送者会收到配对码。 - 通过以下方式批准:
openclaw pairing list nextcloud-talkopenclaw pairing approve nextcloud-talk <CODE>- 公开私信:
channels.nextcloud-talk.dmPolicy="open"加上channels.nextcloud-talk.allowFrom=["*"]。 allowFrom仅匹配 Nextcloud 用户 ID(小写);显示名称会被忽略。
房间(群组)¶
- 默认:
channels.nextcloud-talk.groupPolicy = "allowlist"(提及门控)。 - 使用
channels.nextcloud-talk.rooms允许列表房间,以房间令牌为键;"*"设置通配符默认值:
- 每房间键:
requireMention(默认 true)、enabled(false 禁用该房间)、allowFrom(每房间发送者允许列表)、tools(允许/拒绝工具覆盖)、skills(限制加载的技能)、systemPrompt。 - 若要不允许任何房间,保持允许列表为空或设置
channels.nextcloud-talk.groupPolicy="disabled"。
功能支持¶
| 功能 | 状态 |
|---|---|
| 私信 | 支持 |
| 房间 | 支持 |
| 线程 | 不支持 |
| 媒体 | 仅 URL |
| 表情回应 | 支持 |
| 原生命令 | 不支持 |
配置参考(Nextcloud Talk)¶
完整配置:配置
提供商选项:
channels.nextcloud-talk.enabled:启用/禁用通道启动。channels.nextcloud-talk.baseUrl:Nextcloud 实例 URL。channels.nextcloud-talk.botSecret:机器人共享密钥(字符串或密钥引用)。channels.nextcloud-talk.botSecretFile:常规文件密钥路径。符号链接会被拒绝。channels.nextcloud-talk.apiUser:用于房间查找(私信检测)和状态检查的 API 用户。channels.nextcloud-talk.apiPassword:用于房间查找的 API/应用密码。channels.nextcloud-talk.apiPasswordFile:API 密码文件路径。channels.nextcloud-talk.legacyWebhook:false | { port, host? }。对象会打开转发监听器;host默认为0.0.0.0。省略或false不打开监听器。命名账户继承根设置,除非它们覆盖它。channels.nextcloud-talk.webhookPath:Webhook 路径(默认:/nextcloud-talk-webhook)。channels.nextcloud-talk.webhookPublicUrl:外部可访问的 Webhook URL。channels.nextcloud-talk.dmPolicy:pairing | allowlist | open | disabled(默认:pairing)。open需要allowFrom=["*"]。channels.nextcloud-talk.allowFrom:私信允许列表(用户 ID)。channels.nextcloud-talk.groupPolicy:allowlist | open | disabled(默认:allowlist)。channels.nextcloud-talk.groupAllowFrom:房间发送者允许列表(用户 ID);未设置时回退到allowFrom。channels.nextcloud-talk.rooms:每房间设置和允许列表(见上文)。- 静态发送者访问组可以通过
allowFrom和groupAllowFrom使用accessGroup:<name>引用。 channels.nextcloud-talk.historyLimit:群组历史限制(0 禁用)。channels.nextcloud-talk.dmHistoryLimit:私信历史限制(0 禁用)。channels.nextcloud-talk.dms:按用户 ID 为键的每私信覆盖(historyLimit)。channels.nextcloud-talk.textChunkLimit:出站文本块大小(字符数,默认:4000)。channels.nextcloud-talk.streaming.chunkMode:length(默认)或newline,在长度分块前按空行(段落边界)拆分。channels.nextcloud-talk.streaming.block.enabled:启用或禁用此通道的块流式传输。channels.nextcloud-talk.streaming.block.coalesce:块流式传输合并调优。channels.nextcloud-talk.replyToMode:回复引用模式(off | first | all | batched;默认:all)。命名账户可以使用channels.nextcloud-talk.accounts.<id>.replyToMode覆盖它。channels.nextcloud-talk.responsePrefix:出站回复前缀。channels.nextcloud-talk.markdown.tables:Markdown 表格渲染模式(off | bullets | code | block)。channels.nextcloud-talk.network.dangerouslyAllowPrivateNetwork:允许私有/内部 Nextcloud 主机绕过 SSRF 防护。channels.nextcloud-talk.accounts.<id>:每账户覆盖(相同键);defaultAccount选择默认账户。环境变量NEXTCLOUD_TALK_BOT_SECRET/NEXTCLOUD_TALK_API_PASSWORD仅适用于默认账户。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw