Nextcloud Talk

Status: bundled plugin (webhook bot). Direct messages, rooms, reactions, and markdown messages are supported.

Bundled plugin

Nextcloud Talk ships as a bundled plugin in current OpenClaw releases, so normal packaged builds do not need a separate install.

If you are on an older build or a custom install that excludes Nextcloud Talk, install a current npm package when one is published:

Install via CLI (npm registry, when a current package exists):

bash
Copy
openclaw plugins install @openclaw/nextcloud-talk

If npm reports the OpenClaw-owned package as deprecated, use a current packaged OpenClaw build or the local checkout path until a newer npm package is published.

Local checkout (when running from a git repo):

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

Details: Plugins

Quick setup (beginner)

1. Ensure the Nextcloud Talk plugin is available.

   • Current packaged OpenClaw releases already bundle it.
   • Older/custom installs can add it manually with the commands above.

2. On your Nextcloud server, create a bot:

   bash
   Copy
   ./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature reaction
   

3. Enable the bot in the target room settings.

4. Configure OpenClaw:

   • Config:
     text

     Copy

     channels.nextcloud-talk.baseUrl
     +
     text

     Copy

     channels.nextcloud-talk.botSecret
   • Or env:
     text

     Copy

     NEXTCLOUD_TALK_BOT_SECRET
     (default account only)

   CLI setup:

   bash
   Copy
   openclaw channels add --channel nextcloud-talk \
     --url https://cloud.example.com \
     --token "<shared-secret>"
   

   Equivalent explicit fields:

   bash
   Copy
   openclaw channels add --channel nextcloud-talk \
     --base-url https://cloud.example.com \
     --secret "<shared-secret>"
   

   File-backed secret:

   bash
   Copy
   openclaw channels add --channel nextcloud-talk \
     --base-url https://cloud.example.com \
     --secret-file /path/to/nextcloud-talk-secret
   

5. Restart the gateway (or finish setup).

Minimal config:

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

Notes

• Bots cannot initiate DMs. The user must message the bot first.
• Webhook URL must be reachable by the Gateway; set
  text

  Copy

  webhookPublicUrl
  if behind a proxy.
• Media uploads are not supported by the bot API; media is sent as URLs.
• The webhook payload does not distinguish DMs vs rooms; set
  text

  Copy

  apiUser
  +
  text

  Copy

  apiPassword
  to enable room-type lookups (otherwise DMs are treated as rooms).

Access control (DMs)

• Default:
  text

  Copy

  channels.nextcloud-talk.dmPolicy = "pairing"
  . Unknown senders get a pairing code.
• Approve via:
  • text

    Copy

    openclaw pairing list nextcloud-talk
  • text

    Copy

    openclaw pairing approve nextcloud-talk <CODE>
• Public DMs:
  text

  Copy

  channels.nextcloud-talk.dmPolicy="open"
  plus
  text

  Copy

  channels.nextcloud-talk.allowFrom=["*"]
  .
• text

  Copy

  allowFrom
  matches Nextcloud user IDs only; display names are ignored.

Rooms (groups)

• Default:
  text

  Copy

  channels.nextcloud-talk.groupPolicy = "allowlist"
  (mention-gated).
• Allowlist rooms with
  text

  Copy

  channels.nextcloud-talk.rooms
  :

json5
Copy
{
  channels: {
    "nextcloud-talk": {
      rooms: {
        "room-token": { requireMention: true },
      },
    },
  },
}

• To allow no rooms, keep the allowlist empty or set
  text

  Copy

  channels.nextcloud-talk.groupPolicy="disabled"
  .

Capabilities

Configuration reference (Nextcloud Talk)

Full configuration: Configuration

Provider options:

• text

  Copy

  channels.nextcloud-talk.enabled
  : enable/disable channel startup.
• text

  Copy

  channels.nextcloud-talk.baseUrl
  : Nextcloud instance URL.
• text

  Copy

  channels.nextcloud-talk.botSecret
  : bot shared secret.
• text

  Copy

  channels.nextcloud-talk.botSecretFile
  : regular-file secret path. Symlinks are rejected.
• text

  Copy

  channels.nextcloud-talk.apiUser
  : API user for room lookups (DM detection).
• text

  Copy

  channels.nextcloud-talk.apiPassword
  : API/app password for room lookups.
• text

  Copy

  channels.nextcloud-talk.apiPasswordFile
  : API password file path.
• text

  Copy

  channels.nextcloud-talk.webhookPort
  : webhook listener port (default: 8788).
• text

  Copy

  channels.nextcloud-talk.webhookHost
  : webhook host (default: 0.0.0.0).
• text

  Copy

  channels.nextcloud-talk.webhookPath
  : webhook path (default: /nextcloud-talk-webhook).
• text

  Copy

  channels.nextcloud-talk.webhookPublicUrl
  : externally reachable webhook URL.
• text

  Copy

  channels.nextcloud-talk.dmPolicy
  :
  text

  Copy

  pairing | allowlist | open | disabled
  .
• text

  Copy

  channels.nextcloud-talk.allowFrom
  : DM allowlist (user IDs).
  text

  Copy

  open
  requires
  text

  Copy

  "*"
  .
• text

  Copy

  channels.nextcloud-talk.groupPolicy
  :
  text

  Copy

  allowlist | open | disabled
  .
• text

  Copy

  channels.nextcloud-talk.groupAllowFrom
  : group allowlist (user IDs).
• text

  Copy

  channels.nextcloud-talk.rooms
  : per-room settings and allowlist.
• text

  Copy

  channels.nextcloud-talk.historyLimit
  : group history limit (0 disables).
• text

  Copy

  channels.nextcloud-talk.dmHistoryLimit
  : DM history limit (0 disables).
• text

  Copy

  channels.nextcloud-talk.dms
  : per-DM overrides (historyLimit).
• text

  Copy

  channels.nextcloud-talk.textChunkLimit
  : outbound text chunk size (chars).
• text

  Copy

  channels.nextcloud-talk.chunkMode
  :
  text

  Copy

  length
  (default) or
  text

  Copy

  newline
  to split on blank lines (paragraph boundaries) before length chunking.
• text

  Copy

  channels.nextcloud-talk.blockStreaming
  : disable block streaming for this channel.
• text

  Copy

  channels.nextcloud-talk.blockStreamingCoalesce
  : block streaming coalesce tuning.
• text

  Copy

  channels.nextcloud-talk.mediaMaxMb
  : inbound media cap (MB).

Related

• Channels Overview — all supported channels
• Pairing — DM authentication and pairing flow
• Groups — group chat behavior and mention gating
• Channel Routing — session routing for messages
• Security — access model and hardening