Integrate Nextcloud Talk with OpenClaw in 5 Minutes

Ever tried to hook up a bot to your self-hosted setup and ended up fighting with documentation for hours? It is a common headache when you want your tools to actually talk to each other without jumping through hoops.

If you are using Nextcloud Talk, getting a bot running should be a straightforward process. This guide helps you get the plugin configured so you can handle direct messages, rooms, and reactions without the usual configuration stress.

Plugin required

Nextcloud Talk does not come bundled with the core install, so you need to add it as a plugin. You can grab it from the npm registry or use a local path if you are running from a git repo.

Install via CLI (npm registry):

openclaw plugins install @openclaw/nextcloud-talk

Local checkout (when running from a git repo):

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

If you choose Nextcloud Talk during setup and a git checkout is detected, OpenClaw offers the local install path automatically.

Details: Plugins

Quick setup (beginner)

Getting started is simple. You just need to install the plugin, set up the bot on your Nextcloud server, and update your config file.

1. Install the Nextcloud Talk plugin.

2. On your Nextcloud server, create a bot:

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

3. Enable the bot in the target room settings.

4. Configure OpenClaw:

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

5. Restart the gateway (or finish setup).

Minimal config:

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

Notes

Keep these points in mind to avoid common pitfalls:

• Bots cannot initiate DMs. The user must message the bot first.
• Webhook URL must be reachable by the Gateway; set 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 apiUser + apiPassword to enable room-type lookups (otherwise DMs are treated as rooms).

Access control (DMs)

By default, the system uses pairing for direct messages. This means unknown senders get a pairing code that you need to approve manually.

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

• Approve via:

  openclaw pairing list nextcloud-talk

  openclaw pairing approve nextcloud-talk <CODE>

If you want public DMs, set channels.nextcloud-talk.dmPolicy="open" and include channels.nextcloud-talk.allowFrom=["*"]. Remember that allowFrom matches Nextcloud user IDs, not display names.

Rooms (groups)

For group chats, the default setting is allowlist, which uses mention-gating. You can specify which rooms are allowed in your configuration.

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

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

To allow no rooms, keep the allowlist empty or set channels.nextcloud-talk.groupPolicy="disabled".

Capabilities

Here is a quick look at what the Nextcloud Talk plugin supports:

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

Configuration reference (Nextcloud Talk)

If you need to tweak specific behaviors, here are the available provider options. You can find the full configuration details in the Configuration guide.

• channels.nextcloud-talk.enabled: enable/disable channel startup.
• channels.nextcloud-talk.baseUrl: Nextcloud instance URL.
• channels.nextcloud-talk.botSecret: bot shared secret.
• channels.nextcloud-talk.botSecretFile: regular-file secret path. Symlinks are rejected.
• channels.nextcloud-talk.apiUser: API user for room lookups (DM detection).
• channels.nextcloud-talk.apiPassword: API/app password for room lookups.
• channels.nextcloud-talk.apiPasswordFile: API password file path.
• channels.nextcloud-talk.webhookPort: webhook listener port (default: 8788).
• channels.nextcloud-talk.webhookHost: webhook host (default: 0.0.0.0).
• channels.nextcloud-talk.webhookPath: webhook path (default: /nextcloud-talk-webhook).
• channels.nextcloud-talk.webhookPublicUrl: externally reachable webhook URL.
• channels.nextcloud-talk.dmPolicy: pairing | allowlist | open | disabled.
• channels.nextcloud-talk.allowFrom: DM allowlist (user IDs). open requires "*".
• channels.nextcloud-talk.groupPolicy: allowlist | open | disabled.
• channels.nextcloud-talk.groupAllowFrom: group allowlist (user IDs).
• channels.nextcloud-talk.rooms: per-room settings and allowlist.
• channels.nextcloud-talk.historyLimit: group history limit (0 disables).
• channels.nextcloud-talk.dmHistoryLimit: DM history limit (0 disables).
• channels.nextcloud-talk.dms: per-DM overrides (historyLimit).
• channels.nextcloud-talk.textChunkLimit: outbound text chunk size (chars).
• channels.nextcloud-talk.chunkMode: length (default) or newline to split on blank lines (paragraph boundaries) before length chunking.
• channels.nextcloud-talk.blockStreaming: disable block streaming for this channel.
• channels.nextcloud-talk.blockStreamingCoalesce: block streaming coalesce tuning.
• 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

Next Steps

Need help getting everything wired up? Check out the AI Setup Assistant for a guided configuration experience.