> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Nextcloud Talk

Nextcloud Talk 是一个可下载的渠道插件（`@openclaw/nextcloud-talk`），它通过 Talk webhook bot 将 OpenClaw 连接到自托管的 Nextcloud 实例。支持私信、房间、表情回应和 markdown 消息；媒体会以 URL 形式发出。

## 安装

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/nextcloud-talk
```

使用裸包规范以跟随当前官方发布标签。只有在需要可复现安装时，才固定到确切版本。

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install ./path/to/local/nextcloud-talk-plugin
```

安装后重启 Gateway 网关。详情：[插件](/zh-CN/tools/plugin)

## 快速设置（初学者）

1. 安装插件（见上文）。

2. 在你的 Nextcloud 服务器上创建 bot：

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   ./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` 修复现有 bot。

3. 在目标房间设置中启用 bot。

4. 配置 OpenClaw：

   * 配置：`channels.nextcloud-talk.baseUrl` + `channels.nextcloud-talk.botSecret`
   * 或环境变量：`NEXTCLOUD_TALK_BOT_SECRET`（仅默认账号）

   CLI 设置（`--url`/`--token` 是显式字段的别名；`nc-talk` 和 `nc` 可作为渠道别名）：

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   openclaw channels add --channel nextcloud-talk \
     --url https://cloud.example.com \
     --token "<shared-secret>"
   ```

   等效的显式字段：

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   openclaw channels add --channel nextcloud-talk \
     --base-url https://cloud.example.com \
     --secret "<shared-secret>"
   ```

   文件支持的密钥：

   ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
   openclaw channels add --channel nextcloud-talk \
     --base-url https://cloud.example.com \
     --secret-file /path/to/nextcloud-talk-secret
   ```

5. 重启 Gateway 网关（或完成设置）。

最小配置：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    "nextcloud-talk": {
      enabled: true,
      baseUrl: "https://cloud.example.com",
      botSecret: "shared-secret",
      dmPolicy: "pairing",
    },
  },
}
```

## 说明

* Bot 不能主动发起私信。用户必须先给 bot 发送消息。
* webhook URL 必须能从 Nextcloud 服务器访问；当 Gateway 网关位于代理后面时，设置 `webhookPublicUrl`。Webhook 请求使用 bot 密钥进行 HMAC-SHA256 签名；无效签名会被拒绝并受到速率限制。
* bot API 不支持媒体上传；出站媒体会附加为一行 `Attachment: <url>`。
* webhook 载荷不会区分私信和房间；设置 `apiUser` + `apiPassword` 以启用房间类型查询（缓存约 5 分钟）。没有它们时，每个会话都会被视为房间。
* 出站请求会经过 SSRF 防护。对于受信任的私有/内部网络上的 Nextcloud 主机，可通过 `channels.nextcloud-talk.network.dangerouslyAllowPrivateNetwork: true` 选择启用。
* 设置了 `apiUser`/`apiPassword` 和 `webhookPublicUrl` 后，`openclaw channels status` 会探测 bot，并在缺少 `response` 功能时发出警告。

## 访问控制（私信）

* 默认：`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` 允许列出房间，按房间令牌作为键；`"*"` 设置通配符默认值：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    "nextcloud-talk": {
      rooms: {
        "room-token": { requireMention: true },
      },
    },
  },
}
```

* 按房间键：`requireMention`（默认 true）、`enabled`（false 会禁用该房间）、`allowFrom`（按房间发送者允许列表）、`tools`（工具允许/拒绝覆盖）、`skills`（限制加载的 Skills）、`systemPrompt`。
* 要不允许任何房间，请保持允许列表为空，或设置 `channels.nextcloud-talk.groupPolicy="disabled"`。

## 能力

| 功能   | 状态    |
| ---- | ----- |
| 私信   | 支持    |
| 房间   | 支持    |
| 线程   | 不支持   |
| 媒体   | 仅 URL |
| 表情回应 | 支持    |
| 原生命令 | 不支持   |

## 配置参考（Nextcloud Talk）

完整配置：[配置](/zh-CN/gateway/configuration)

提供商选项：

* `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/app 密码。
* `channels.nextcloud-talk.apiPasswordFile`：API 密码文件路径。
* `channels.nextcloud-talk.webhookPort`：webhook 监听器端口（默认：8788）。
* `channels.nextcloud-talk.webhookHost`：webhook 主机（默认：0.0.0.0）。
* `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.chunkMode`：`length`（默认）或 `newline`，用于在按长度分块之前按空行（段落边界）拆分。
* `channels.nextcloud-talk.blockStreaming`：禁用此渠道的分块流式传输。
* `channels.nextcloud-talk.blockStreamingCoalesce`：分块流式传输合并调优。
* `channels.nextcloud-talk.responsePrefix`：出站回复前缀。
* `channels.nextcloud-talk.markdown.tables`：markdown 表格渲染模式（`off | bullets | code | block`）。
* `channels.nextcloud-talk.mediaMaxMb`：入站媒体上限（MB）。
* `channels.nextcloud-talk.network.dangerouslyAllowPrivateNetwork`：允许私有/内部 Nextcloud 主机通过 SSRF 防护。
* `channels.nextcloud-talk.accounts.<id>`：按账号覆盖（相同键）；`defaultAccount` 选择默认账号。环境变量 `NEXTCLOUD_TALK_BOT_SECRET` / `NEXTCLOUD_TALK_API_PASSWORD` 仅应用于默认账号。

## 相关

* [渠道概览](/zh-CN/channels) — 所有支持的渠道
* [配对](/zh-CN/channels/pairing) — 私信认证和配对流程
* [群组](/zh-CN/channels/groups) — 群聊行为和提及门控
* [频道路由](/zh-CN/channels/channel-routing) — 消息的会话路由
* [安全](/zh-CN/gateway/security) — 访问模型和加固