Integrate Nostr with OpenClaw: Setup Guide

Setting up a bot to communicate over decentralized networks can often feel like a chore, especially when you have to juggle cryptographic keys and relay connections. If you have ever felt the frustration of trying to get a simple service to talk to the open social web without hitting a wall of complex configurations, you are in the right place.

Nostr gives you a decentralized way to handle social networking. This channel allows OpenClaw to receive and respond to encrypted direct messages (DMs) using the NIP-04 standard.

Install (on demand)

Onboarding (recommended)

When you run onboarding (openclaw onboard) or use openclaw channels add, you will see a list of optional channel plugins. If you pick Nostr, the system asks to install the plugin right then and there.

Install defaults work like this:

• Dev channel + git checkout available: This uses your local plugin path.
• Stable/Beta: This downloads the plugin from npm.

You can change your mind and override these choices in the prompt.

Manual install

If you prefer the command line, run this:

openclaw plugins install @openclaw/nostr

For those working on development workflows, use a local checkout:

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

Remember to restart the Gateway after you install or enable any plugins.

Non-interactive setup

If you want to skip the prompts, use these commands:

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"

Use the --use-env flag if you want to keep your NOSTR_PRIVATE_KEY in the environment instead of saving it in the config file.

Quick setup

1. Generate a Nostr keypair if you do not have one:

# Using nak
nak key generate

2. Add the details to your config:

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

3. Export your key:

export NOSTR_PRIVATE_KEY="nsec1..."

4. Restart the Gateway.

Configuration reference

Key	Type	Default	Description
privateKey	string	required	Private key in nsec or hex format
relays	string[]	['wss://relay.damus.io', 'wss://nos.lol']	Relay URLs (WebSocket)
dmPolicy	string	pairing	DM access policy
allowFrom	string[]	[]	Allowed sender pubkeys
enabled	boolean	true	Enable/disable channel
name	string	-	Display name
profile	object	-	NIP-01 profile metadata

Profile metadata

Your profile data is sent out as a NIP-01 kind:0 event. You can manage these details from the Control UI by going to Channels -> Nostr -> Profile, or you can set them directly in your config.

Example:

{
  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",
      },
    },
  },
}

Keep these notes in mind:

• Profile URLs must use https://.
• When you import from relays, the system merges fields and keeps your local overrides.

Access control

DM policies

• pairing (default): People you don’t know will get a pairing code.
• allowlist: Only the pubkeys you put in allowFrom can send DMs.
• open: This allows public inbound DMs (you must set allowFrom: ["*"]).
• disabled: This tells the bot to ignore all inbound DMs.

How it is enforced:

• The system checks the sender policy before it verifies signatures or decrypts NIP-04 content.
• Pairing replies go out without the bot looking at the original DM body.
• Inbound DMs have rate limits, and the bot drops payloads that are too large before decryption.

Allowlist example

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

Key formats

The system accepts these formats:

• Private key: Use nsec... or a 64-character hex string.
• Pubkeys (allowFrom): Use npub... or a hex string.

Relays

The default relays are relay.damus.io and nos.lol.

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

A few tips for you:

• Use 2 or 3 relays so you have a backup.
• Do not use too many relays, as this causes latency and message duplication.
• Paid relays can make your setup more reliable.
• You can use local relays like ws://localhost:7777 for testing.

Protocol support

NIP	Status	Description
NIP-01	Supported	Basic event format + profile metadata
NIP-04	Supported	Encrypted DMs (kind:4)
NIP-17	Planned	Gift-wrapped DMs
NIP-44	Planned	Versioned encryption

Testing

Local relay

You can start a local relay using Docker:

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

Then update your config:

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

Manual test

1. Find the bot’s pubkey (npub) in your logs.
2. Open a Nostr client like Damus or Amethyst.
3. Send a DM to the bot’s pubkey.
4. Check if you get a response.

Troubleshooting

Not receiving messages

• Make sure your private key is valid.
• Check that your relay URLs are reachable and use wss:// (or ws:// for local testing).
• Verify that enabled is not set to false.
• Look at the Gateway logs to see if there are relay connection errors.

Not sending responses

• Check if the relay allows write operations.
• Verify that your outbound connection is working.
• Keep an eye out for relay rate limits.

Duplicate responses

• This is normal when you use multiple relays.
• The system deduplicates messages by event ID, so only the first one that arrives triggers a response.

Security

• Do not commit your private keys to version control.
• Use environment variables to handle your keys safely.
• Use an allowlist for bots you put into production.
• The pairing and allowlist policies run before decryption, so unknown senders cannot waste your CPU on crypto work.

Limitations (MVP)

• The plugin only supports direct messages; there are no group chats.
• You cannot send or receive media attachments.
• Only NIP-04 is supported right now (NIP-17 gift-wrap is coming later).

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

If you want to explore more about how OpenClaw handles different platforms, check out the Channels Overview or see how Pairing works to secure your DMs.

Need more help? Talk to the AI Setup Assistant.