How to Connect OpenClaw to Nostr

Prerequisites

• ✓An existing OpenClaw Gateway deployment with access to the Control UI (Channels -> Nostr).
• ✓A Nostr client (for example Damus or Amethyst) to send and receive DMs for testing.
• ✓Access to at least one reachable Nostr relay such as `wss://relay.damus.io` or `wss://nos.lol`.
• ✓The `nak` CLI installed if you want to generate a Nostr keypair using `nak key generate`.

Steps

1. 1

   Install or enable the Nostr channel plugin

   Current OpenClaw releases ship Nostr as a bundled plugin, so in most cases you only need to enable and configure it. If you run an older or custom build that excludes bundled Nostr, install the plugin explicitly and restart the Gateway so it loads the new channel.

   bashCopy

   openclaw plugins install @openclaw/nostr

2. 2

   Link a local Nostr plugin checkout for development

   If you work on the Nostr plugin itself, link a local checkout instead of installing from the registry. This keeps your Gateway pointed at your working tree so changes are picked up after a restart.

   bashCopy

   openclaw plugins install --link <path-to-local-nostr-plugin>

3. 3

   Generate a Nostr keypair for your bot

   Your OpenClaw Nostr bot needs its own private key to decrypt DMs and sign responses. Use the `nak` CLI to generate a keypair, then keep the private key secure and out of version control.

   bashCopy

   # Using nak
   nak key generate

4. 4

   Export the Nostr private key as an environment variable

   Store the private key in an environment variable so you can reference it from config and non-interactive setup commands. This follows the security guidance to avoid committing keys and keeps rotation straightforward.

   bashCopy

   export NOSTR_PRIVATE_KEY="nsec1..."

5. 5

   Configure the Nostr channel in OpenClaw

   Add a `nostr` entry under `channels` so the Gateway knows which key to use and how to connect. This minimal config wires in the private key and relies on the default relay list and DM policy.

   jsonCopy

   {
     channels: {
       nostr: {
         privateKey: "${NOSTR_PRIVATE_KEY}",
       },
     },
   }

6. 6

   Optionally configure profile metadata for your bot

   Set NIP-01 profile metadata so your bot shows a friendly name, avatar, and other details in Nostr clients. All profile URLs must use `https://`, and imported data from relays merges with your local overrides.

   jsonCopy

   {
     channels: {
       nostr: {
         privateKey: "${NOSTR_PRIVATE_KEY}",
         profile: {
           name: "openclaw",
           displayName: "OpenClaw",
           about: "Personal assistant DM bot",
           picture: "https://example.com/avatar.png",
           banner: "https://example.com/banner.png",
           website: "https://example.com",
           nip05: "openclaw@example.com",
           lud16: "openclaw@example.com",
         },
       },
     },
   }

7. 7

   Set DM access control with policies and allowlist

   Control who can DM your bot by choosing a `dmPolicy` and, if needed, an `allowFrom` list. For example, an allowlist policy locks the bot down to specific pubkeys while still using your existing private key.

   jsonCopy

   {
     channels: {
       nostr: {
         privateKey: "${NOSTR_PRIVATE_KEY}",
         dmPolicy: "allowlist",
         allowFrom: ["npub1abc...", "npub1xyz..."],
       },
     },
   }

8. 8

   Customize relay URLs for production or testing

   Tune which relays your bot connects to so you get the right balance of redundancy and latency. For production, use 2–3 reliable `wss://` relays; for local testing, you can point at a local relay on `ws://localhost`.

   jsonCopy

   {
     channels: {
       nostr: {
         privateKey: "${NOSTR_PRIVATE_KEY}",
         relays: ["wss://relay.damus.io", "wss://relay.primal.net", "wss://nostr.wine"],
       },
     },
   }

9. 9

   Add the Nostr channel non-interactively from the CLI

   If you prefer CLI-driven setup or run in automation, add the Nostr channel with `openclaw channels add`. You can pass the private key directly or rely on the environment and specify custom relay URLs in one shot.

   bashCopy

   openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
   openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net"

10. 10

    Restart the OpenClaw Gateway to apply Nostr config

    After installing or configuring the Nostr plugin, restart the Gateway so it picks up the new channel configuration and environment variables. Without a restart, the bot will not connect to relays or handle DMs.

    textCopy

    Restart the Gateway after installing or enabling plugins.

11. 11

    Run a local Nostr relay for isolated testing

    For development, run a local relay so you can test DM flows without depending on public infrastructure. Point the Nostr channel at `ws://localhost:7777` to keep all traffic on your machine.

    bashCopy

    # Start strfry
    docker run -p 7777:7777 ghcr.io/hoytech/strfry

12. 12

    Point the Nostr channel at your local relay

    Update the channel config to use the local relay endpoint so your bot connects to the strfry instance you started. This keeps your test environment predictable and avoids relay rate limits while you iterate.

    jsonCopy

    {
      channels: {
        nostr: {
          privateKey: "${NOSTR_PRIVATE_KEY}",
          relays: ["ws://localhost:7777"],
        },
      },
    }

13. 13

    Manually test Nostr DMs end-to-end

    Once the Gateway is running with the Nostr channel configured, send a DM from a Nostr client to the bot’s pubkey. Watch for a response to confirm that the bot can receive, decrypt, and reply over your chosen relays.

Configuration

Troubleshooting

Frequently asked questions