How to Connect OpenClaw to Nextcloud Talk - Bot Webhook Setup

Nextcloud Talk is a nice fit when you want your assistant inside the same self-hosted collaboration stack that already holds your files and calls. OpenClaw documents this integration as a bundled webhook bot with support for direct messages, rooms, reactions, and markdown messages.

What the official docs support

The official docs keep the setup intentionally narrow. You install a Talk bot on the Nextcloud side, give it a shared secret and webhook URL, then tell OpenClaw the base URL and bot secret. Threads are not supported, media is URL-only, and bots cannot initiate DMs on their own.

That limited but clear model is actually a strength. If you want a reliable internal assistant instead of a platform experiment, a webhook bot with pairing, room allowlists, and explicit room lookup options is easier to reason about than a highly magical integration.

What you need first

• A Nextcloud server with Talk
• Shell access to run occ talk:bot:install
• A reachable webhook URL for the gateway
• A shared secret you can store in Nextcloud and OpenClaw

Recommended setup flow

The easiest way to keep this one clean is to treat it like a bot registration problem, not a general chat login flow.

1. On the Nextcloud server, create the bot with the documented occ talk:bot:install command, passing the bot name, shared secret, webhook URL, and the reaction feature flag if you want reaction support enabled from the start.
2. Enable the bot inside the target room settings on the Nextcloud side. Without that room-level enablement, the rest of the OpenClaw config can be perfect and the bot still looks absent.
3. Configure channels.nextcloud-talk in OpenClaw with baseUrl and botSecret, or use NEXTCLOUD_TALK_BOT_SECRET for the default account. Then restart the gateway so the webhook listener and channel state come up together.
4. Decide whether you need apiUser and apiPassword for room lookups. The docs explain that webhook payloads do not distinguish DMs from rooms by themselves, so those extra API credentials help OpenClaw tell them apart instead of treating DMs as rooms.
5. Keep room access explicit. The documented baseline is groupPolicy allowlist with channels.nextcloud-talk.rooms holding room-token entries, each of which can require mentions or carry other room-level settings.

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

Access, safety, and operational notes

DMs default to pairing, and rooms default to allowlist. That is exactly what I would want here. The docs also note that allowFrom matches Nextcloud user IDs only, not display names, which is a good reminder to build access rules on stable identifiers whenever possible.

The operational detail I would remember is that bots cannot initiate DMs. Users have to message the bot first. If someone expects a cold-start proactive DM and it never arrives, that may not be a bug at all, it may just be the documented Nextcloud Talk bot behavior.

One subtle but useful habit from the docs is treating room tokens as infrastructure, not as casual labels. If you save the real room token under channels.nextcloud-talk.rooms and keep mention rules there too, later troubleshooting gets much easier because your access policy matches the webhook target exactly.

How to verify it is working

Test with one room and one user who is prepared to trigger the pairing flow. If messages show up but DM classification feels odd, add the apiUser and apiPassword lookup path before you spend time debugging room policy that is actually correct.

Common gotchas

• Bots cannot initiate DMs, users must contact the bot first
• The webhook payload alone does not distinguish DMs from rooms
• Media is delivered as URLs, not native file uploads

If you want the operator version with tighter rollout checklists, safer defaults, and more production patterns, The OpenClaw Playbook is the easiest shortcut.