跳转至

Nextcloud Talk

Nextcloud Talk 是一个可下载的频道插件（@openclaw/nextcloud-talk），通过 Talk webhook 机器人将 OpenClaw 连接到自托管的 Nextcloud 实例。支持直接消息、房间、表情回应和 Markdown 消息；媒体内容以 URL 形式发出。

安装

openclaw plugins install @openclaw/nextcloud-talk

使用不带版本的包规范以跟随当前官方发布标签。仅在需要可复现安装时固定确切版本。

从本地检出（开发工作流）：

openclaw plugins install ./path/to/local/nextcloud-talk-plugin

安装后，检查应用结果。

快速设置（初学者）

  1. 安装插件（如上）。
  2. 通过 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 修复现有机器人。

  1. 在目标房间设置中启用该机器人。
  2. 配置 OpenClaw：
  3. 配置：channels.nextcloud-talk.baseUrl + channels.nextcloud-talk.botSecret
  4. 或环境变量：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
  1. 检查 openclaw channels status --probe；如果 Gateway 离线，请启动它。配置更改遵循热重载。如果你更改了服务环境，请重启 Gateway 以加载它。

最小配置：

{
  channels: {
    "nextcloud-talk": {
      enabled: true,
      baseUrl: "https://cloud.example.com",
      botSecret: "shared-secret",
      legacyWebhook: false,
      dmPolicy: "pairing",
    },
  },
}

说明

  • 机器人无法主动发起直接消息。用户必须先向机器人发送消息。
  • webhook URL 必须可从 Nextcloud 服务器访问。Gateway 在其自身 HTTP 端口上提供 webhookPath。共享兼容性监听器默认还会转发旧端口 8788；设置 legacyWebhook: false 以仅使用 Gateway 端口。使用代理时，将 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 功能时发出警告。

将现有 webhook 端点迁移到 Gateway

更新会保留之前的 webhook 监听器地址。当省略 legacyWebhook 时，Gateway 会在 0.0.0.0:8788 上打开一个共享转发监听器。显式的 { port, host? } 对象选择该端点；省略 host 时使用 0.0.0.0。legacyWebhook: 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 后端上的账户设置不同的 bot 密钥。独立的旧版端点会保留其原始账户选择以及独立的准入和认证失败预算，即使这些账户具有相同的后端和密钥。

Webhook 路径保留精确的请求匹配，包括查询字符串、大小写和末尾斜杠。/health、/healthz、/ready、/readyz、/startup 和 /startupz 属于 Gateway 探针，即使后面跟随查询字符串也是如此。/api/channels 下的路径需要 Gateway 身份验证，包括编码后的别名；Nextcloud 的签名不提供该身份验证。Doctor 会警告这些路径，并且具有 legacyWebhook: false 的账户不能携带这样的路径启动。将 webhookPath 设置为 /nextcloud-talk-webhook，并更新 Nextcloud bot 回调和反向代理上游，使其指向 Gateway 端口和该路径。在此切换期间，已启用的旧版监听器会继续提供其配置的路径；OpenClaw 不会静默重写回调路径。

在通过 Gateway 路由验证消息投递后，设置 legacyWebhook: false 并重启账户，以禁用其旧版转发。只要另一个账户使用该端点，共享监听器就会保持打开。删除 legacyWebhook 会重新启用默认监听器；使用显式的 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-talk
  • openclaw 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 将房间加入允许列表，以房间令牌为键；"*" 设置通配符默认值：
{
  channels: {
    "nextcloud-talk": {
      rooms: {
        "room-token": { requireMention: true },
      },
    },
  },
}
  • 每个房间的键：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：bot 共享密钥（字符串或密钥引用）。
  • 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? }。省略时：将 0.0.0.0:8788 转发到 Gateway 路由。对象会覆盖端口，并可选覆盖主机；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：每个房间的设置和允许列表（见上文）。
  • 静态发送者访问组可以通过 accessGroup:<name> 从 allowFrom 和 groupAllowFrom 中引用。
  • 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