Nextcloud Talk Plugin Setup

Nextcloud Talk is a channel plugin you install separately (@openclaw/nextcloud-talk) that links OpenClaw to a self-hosted Nextcloud server via a Talk webhook bot. It handles direct messages, rooms, reactions, and markdown-formatted messages; media is delivered as URLs.

Install

openclaw plugins install @openclaw/nextcloud-talk

For tracking the latest official release, use the bare package spec. Only pin a specific version when you need a reproducible setup.

For a local checkout (development workflows):

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

After installation, restart the gateway. See Plugins for details.

Quick setup (beginner)

Install the plugin (see above).
On your Nextcloud server, set up a bot:
```
./occ talk:bot:install "OpenClaw" "<shared-secret>" "<webhook-url>" --feature webhook --feature response --feature reaction
```
--feature response must be retained: without it, outgoing replies return 401 errors. Use ./occ talk:bot:state --feature webhook --feature response --feature reaction <botId> 1 to fix an existing bot.
Turn on the bot in the target room's settings.

Configure OpenClaw:

Config: channels.nextcloud-talk.baseUrl + channels.nextcloud-talk.botSecret
Or env: NEXTCLOUD_TALK_BOT_SECRET (applies to the default account only)

CLI setup (--url/--token serve as shortcuts for the explicit fields; nc-talk and nc function as channel aliases):

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

The explicit equivalents:

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

Secret stored in a file:

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

Restart the gateway (or complete the setup).

A minimal configuration:

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

Notes

Bots can't start DMs; the user has to send the first message.
The Nextcloud server needs to reach the webhook URL; when the gateway is behind a proxy, set webhookPublicUrl. Webhook requests are signed with HMAC-SHA256 using the bot secret; signatures that don't validate are rejected and throttled.
Message webhooks only return HTTP 200 once the raw event is persisted; if storage fails, HTTP 500 is returned. The durable 200 includes x-openclaw-delivery-accepted: durable, letting reverse proxies require that marker to tell OpenClaw acceptance apart from a generic 200. Non-message events that aren't supported get HTTP 200 without the marker and are logged as ignored.
The bot API doesn't support media uploads; outgoing media is added as an Attachment: <url> line.
DMs and rooms aren't distinguished in the webhook payload; set apiUser + apiPassword to enable room-type lookups (cached for roughly 5 minutes). Without these, every conversation is treated as a room.
Outbound requests pass through the SSRF guard. For a Nextcloud host on a trusted private/internal network, opt in with channels.nextcloud-talk.network.dangerouslyAllowPrivateNetwork: true.
With apiUser/apiPassword and webhookPublicUrl configured, openclaw channels status checks the bot and alerts when the response capability is absent.

Access control (DMs)

Default: channels.nextcloud-talk.dmPolicy = "pairing". Unknown senders receive a pairing code.
Approve using:
- openclaw pairing list nextcloud-talk
- openclaw pairing approve nextcloud-talk <CODE>
Public DMs: channels.nextcloud-talk.dmPolicy="open" plus channels.nextcloud-talk.allowFrom=["*"].
allowFrom only matches Nextcloud user IDs (lowercased); display names are not considered.

Rooms (groups)

Default: channels.nextcloud-talk.groupPolicy = "allowlist" (mention-gated).
Allowlist rooms with channels.nextcloud-talk.rooms, keyed by room token; "*" sets a wildcard default:

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

Per-room keys: requireMention (default true), enabled (false disables the room), allowFrom (per-room sender allowlist), tools (allow/deny tool overrides), skills (limit loaded skills), systemPrompt.
To allow no rooms, keep the allowlist empty or set channels.nextcloud-talk.groupPolicy="disabled".

Capabilities

Feature	Status
Direct messages	Supported
Rooms	Supported
Threads	Not supported
Media	URL-only
Reactions	Supported
Native commands	Not supported

Configuration reference (Nextcloud Talk)

Complete configuration: Configuration

Provider options:

channels.nextcloud-talk.enabled: turns channel startup on or off.
channels.nextcloud-talk.baseUrl: the URL for your Nextcloud instance.
channels.nextcloud-talk.botSecret: shared secret for the bot, provided as a string or a secret reference.
channels.nextcloud-talk.botSecretFile: path to a regular-file secret. Symlinks are not allowed.
channels.nextcloud-talk.apiUser: API user used for room lookups (including DM detection) and the status probe.
channels.nextcloud-talk.apiPassword: API or app password for room lookups.
channels.nextcloud-talk.apiPasswordFile: file path where the API password is stored.
channels.nextcloud-talk.webhookPort: port the webhook listens on, defaulting to 8788.
channels.nextcloud-talk.webhookHost: host the webhook binds to, defaulting to 0.0.0.0.
channels.nextcloud-talk.webhookPath: webhook endpoint path, defaulting to /nextcloud-talk-webhook.
channels.nextcloud-talk.webhookPublicUrl: webhook URL that is reachable from outside.
channels.nextcloud-talk.dmPolicy: pairing | allowlist | open | disabled, with a default of pairing. When open is used, allowFrom=["*"] becomes a requirement.
channels.nextcloud-talk.allowFrom: allowlist of user IDs for direct messages.
channels.nextcloud-talk.groupPolicy: allowlist | open | disabled, defaulting to allowlist.
channels.nextcloud-talk.groupAllowFrom: allowlist of user IDs permitted to send in rooms; if not set, it inherits from allowFrom.
channels.nextcloud-talk.rooms: settings and allowlist scoped to individual rooms, as described earlier.
Static sender access groups can be pulled into allowFrom and groupAllowFrom through accessGroup:<name>.
channels.nextcloud-talk.historyLimit: maximum history kept for groups, where 0 turns it off.
channels.nextcloud-talk.dmHistoryLimit: maximum history kept for DMs, where 0 turns it off.
channels.nextcloud-talk.dms: per-DM overrides, keyed by user ID, using historyLimit.
channels.nextcloud-talk.textChunkLimit: maximum size of outbound text chunks in characters, defaulting to 4000.
channels.nextcloud-talk.streaming.chunkMode: length is the default, while newline splits on blank lines (paragraph breaks) before applying the length limit.
channels.nextcloud-talk.streaming.block.enabled: controls whether block streaming is active for this channel.
channels.nextcloud-talk.streaming.block.coalesce: tuning for block streaming coalescing.
channels.nextcloud-talk.replyToMode: how reply references are handled (off | first | all | batched; default is all). Named accounts can override this with channels.nextcloud-talk.accounts.<id>.replyToMode.
channels.nextcloud-talk.responsePrefix: prefix added to outbound replies.
channels.nextcloud-talk.markdown.tables: rendering mode for markdown tables (off | bullets | code | block).
channels.nextcloud-talk.network.dangerouslyAllowPrivateNetwork: permits private or internal Nextcloud hosts to bypass the SSRF guard.
channels.nextcloud-talk.accounts.<id>: per-account overrides using the same keys; defaultAccount selects the default. Environment variables NEXTCLOUD_TALK_BOT_SECRET and NEXTCLOUD_TALK_API_PASSWORD only affect the default account.

Channels Overview, every channel that is supported
Pairing, the flow for DM authentication and pairing
Groups, behavior in group chats and mention restrictions
Channel Routing, how messages are routed across sessions
Security, the access model and how to harden it