OpenClaw Manual OpenClaw

OpenClaw Nostr Channel

Decentralized
Advanced

Connect OpenClaw to the Nostr decentralized network via an optional plugin. This integration enables your AI assistant to receive and respond to NIP-04 encrypted direct messages across any Nostr relay — no centralized servers, no accounts to register, just a cryptographic keypair and a relay connection. Ideal for privacy-focused deployments where censorship resistance and self-sovereignty matter.

Quick Info
Difficulty Advanced
Category Decentralized
Features Supported 2 / 6

Nostr Supported Features

Text Messages

Supported

Media & Files

Not Supported

Reactions

Supported

Threads

Not Supported

Voice Messages

Not Supported

Group Chat

Not Supported

Nostr Prerequisites

  • OpenClaw Gateway installed and running
  • A Nostr keypair (private key in nsec or hex format) — generate with 'nak key generate'
  • At least one Nostr relay accessible via WebSocket (e.g., wss://relay.damus.io)
  • Node.js 18+ installed on your server

Nostr Quick Setup

1

Install the Nostr plugin

Run 'openclaw plugins install @openclaw/nostr' to add the Nostr channel. Alternatively, use 'openclaw onboard' or 'openclaw channels add' and select Nostr from the plugin list. Restart the Gateway after installation.

2

Generate a keypair and configure

Generate a Nostr keypair using 'nak key generate'. Set the private key as an environment variable (export NOSTR_PRIVATE_KEY="nsec1...") and reference it in your openclaw.json configuration using ${NOSTR_PRIVATE_KEY}.

3

Start and send a test DM

Restart the Gateway with 'openclaw start'. Find your bot's public key (npub) in the startup logs. Open any Nostr client (e.g., Damus, Amethyst, Primal), and send an encrypted DM to the bot's npub. If using the default pairing policy, approve the sender via the CLI.

Nostr Configuration Example

config.json 
{
  "channels": {
    "nostr": {
      "privateKey": "${NOSTR_PRIVATE_KEY}",
      "relays": [
        "wss://relay.damus.io",
        "wss://nos.lol"
      ],
      "dmPolicy": "pairing"
    }
  }
}

Nostr Deep Dive

Architecture Overview

Unlike centralized messaging platforms, Nostr is a decentralized protocol where messages are distributed through independent relay servers. OpenClaw connects to one or more relays via WebSocket and subscribes to NIP-04 encrypted direct messages addressed to the bot's public key. The message flow is straightforward: 1. A user sends an encrypted DM from any Nostr client (Damus, Amethyst, Primal, etc.) 2. The message propagates to relays the user publishes to 3. OpenClaw's relay subscription picks up the event 4. The Gateway decrypts the message, processes it through your AI agent, encrypts the response, and publishes it back to the configured relays Because Nostr is relay-based, there is no single point of failure — if one relay goes down, messages can still flow through others. The bot and its users do not need to use the exact same relays, as relays often exchange events.
The bot's public key is derived from the private key and displayed in the Gateway startup logs. Share this npub with users so they can find and message your bot.
Nostr has no concept of 'online status' — messages are stored on relays and delivered whenever the client connects.

Plugin Installation

The Nostr channel is distributed as an optional OpenClaw plugin rather than being built into the core Gateway. This keeps the base installation lightweight while allowing you to add Nostr support when needed. There are several installation methods: • **npm (recommended):** Run 'openclaw plugins install @openclaw/nostr' to install the stable release. • **Beta channel:** Use 'openclaw plugins install @openclaw/nostr@beta' for pre-release features. • **Local development:** Clone the plugin repo and use 'openclaw plugins install --link /path/to/local/checkout' to link it. • **Interactive setup:** Run 'openclaw onboard' or 'openclaw channels add' and select Nostr from the list. After installation, restart the Gateway for the plugin to take effect.
Run 'openclaw plugins list' to verify the Nostr plugin is installed and active.

Key Generation & Management

Nostr identity is based on public-key cryptography. Your bot's identity is its keypair — a private key (nsec) used for signing and decrypting, and a public key (npub) used as its address. Generate a keypair using the 'nak' CLI tool: 1. Install nak: 'go install github.com/fiatjaf/nak@latest' (or download from releases) 2. Generate: 'nak key generate' — this outputs the private key in hex format 3. Derive public key: 'nak key public <hex-private-key>' — convert to npub if needed OpenClaw accepts private keys in both nsec (Bech32-encoded) and 64-character hex format. Public keys in allowFrom can use npub or hex format.
openclaw.json 
{
  "channels": {
    "nostr": {
      "privateKey": "${NOSTR_PRIVATE_KEY}"
    }
  }
}
Never hardcode your private key directly in openclaw.json. Always use an environment variable (e.g., ${NOSTR_PRIVATE_KEY}) and set it via 'export NOSTR_PRIVATE_KEY="nsec1..."' in your shell or a .env file.

Relay Configuration

Relays are the backbone of Nostr — they store and distribute events. OpenClaw connects to your configured relays via WebSocket to send and receive encrypted DMs. The default configuration uses two well-known public relays: relay.damus.io and nos.lol. For production use, you should customize this based on your needs. Relay selection tips: • Use 2–3 relays for a good balance of redundancy and performance • Too many relays increase latency and bandwidth usage • Paid relays (e.g., relay.nostr.band) offer better reliability and less spam • For development, run a local relay (e.g., Strfry via Docker) on ws://localhost:7777
openclaw.json 
{
  "channels": {
    "nostr": {
      "relays": [
        "wss://relay.damus.io",
        "wss://nos.lol",
        "wss://relay.nostr.band"
      ]
    }
  }
}
Public relays are free but may have rate limits or spam. Paid relays generally offer better performance and filtering.
Your bot and its users do not need to be on the same relays — most relays exchange events with each other.

DM Policies

DM (Direct Message) policies control who can interact with your AI assistant over Nostr. Because Nostr is open by design, access control is especially important to prevent unauthorized usage of your AI quota. OpenClaw supports four policies: • **pairing (default)** — Unknown senders receive a pairing code. You approve or deny them via 'openclaw pairing approve nostr <code>'. Once approved, they can chat freely. • **allowlist** — Only public keys (npub or hex) listed in allowFrom can message the bot. All others are silently ignored. • **open** — Anyone can message the bot. Requires allowFrom: ["*"] to enable. Use with caution. • **disabled** — The bot does not respond to any incoming DMs.
openclaw.json 
{
  "channels": {
    "nostr": {
      "dmPolicy": "allowlist",
      "allowFrom": [
        "npub1abc...xyz",
        "npub1def...uvw"
      ]
    }
  }
}

Profile Metadata (NIP-01)

You can publish a profile for your bot on the Nostr network using NIP-01 kind:0 metadata events. This makes your bot discoverable in Nostr clients — users will see its name, avatar, bio, and other details when they look up the bot's npub. Configurable profile fields include: • **name** — Short username (e.g., "openclaw-bot") • **display_name** — Full display name • **about** — Biography / description • **picture** — Avatar URL (must be HTTPS) • **banner** — Banner image URL (must be HTTPS) • **website** — Bot or project website • **nip05** — NIP-05 verification identifier (e.g., "bot@yourdomain.com") • **lud16** — Lightning address for zaps
openclaw.json 
{
  "channels": {
    "nostr": {
      "profile": {
        "name": "openclaw-bot",
        "display_name": "OpenClaw AI Assistant",
        "about": "AI-powered assistant on Nostr. DM me!",
        "picture": "https://example.com/bot-avatar.png",
        "nip05": "bot@yourdomain.com"
      }
    }
  }
}
NIP-05 verification (bot@yourdomain.com) adds a checkmark in most Nostr clients and helps users verify your bot's identity.
All image URLs (picture, banner) must use HTTPS.

Encryption & Protocol Support

All direct messages in OpenClaw's Nostr integration use NIP-04 encryption — messages are encrypted with a shared secret derived from the sender's and recipient's keypairs using ECDH (Elliptic Curve Diffie-Hellman). Currently supported NIPs: • **NIP-01** — Basic protocol: events, subscriptions, metadata (kind:0) • **NIP-04** — Encrypted direct messages (kind:4) Planned future support: • **NIP-17** — Gift-wrapped private messages (improved metadata privacy) • **NIP-44** — Versioned encryption (stronger cryptographic primitives) While NIP-04 is widely supported across all Nostr clients, it has known metadata leaks (relay operators can see who is messaging whom, though not the content). NIP-17 and NIP-44 will address these limitations once adopted.
NIP-04 encrypts message content but not metadata. Relay operators can see sender/receiver public keys and timestamps.
For maximum privacy, use a dedicated keypair for your bot and connect through a paid or self-hosted relay.

Testing with a Local Relay

For development and testing, you can run a local Nostr relay instead of connecting to public relays. The recommended approach uses Strfry, a high-performance relay that runs easily via Docker. Setup steps: 1. Run the relay: 'docker run -p 7777:7777 hoytech/strfry' 2. Configure OpenClaw to use the local relay: ws://localhost:7777 3. Start the Gateway 4. Use a Nostr client configured to connect to your local relay to send test DMs This isolates your testing from the public Nostr network and provides faster iteration cycles.
openclaw.json (development) 
{
  "channels": {
    "nostr": {
      "relays": ["ws://localhost:7777"],
      "dmPolicy": "open",
      "allowFrom": ["*"]
    }
  }
}
Use dmPolicy: 'open' with allowFrom: ['*'] during local testing to skip the pairing flow.

Nostr Configuration Reference

privateKey
Type: string Default: (required)

Nostr private key in nsec (Bech32) or 64-character hex format. Use an environment variable reference.

relays
Type: string[] Default: ["wss://relay.damus.io", "wss://nos.lol"]

List of Nostr relay WebSocket URLs to connect to

dmPolicy
Type: string Default: "pairing"

DM access control policy: 'pairing', 'allowlist', 'open', or 'disabled'

allowFrom
Type: string[] Default: []

Public keys (npub or hex) allowed to message the bot (when dmPolicy is 'allowlist')

enabled
Type: boolean Default: true

Enable or disable the Nostr channel

name
Type: string Default: ""

Display name for this channel instance

profile.name
Type: string Default: ""

Bot username published as NIP-01 metadata

profile.display_name
Type: string Default: ""

Full display name published as NIP-01 metadata

profile.about
Type: string Default: ""

Bot biography / description published as NIP-01 metadata

profile.picture
Type: string Default: ""

Avatar image URL (HTTPS required) published as NIP-01 metadata

profile.banner
Type: string Default: ""

Banner image URL (HTTPS required) published as NIP-01 metadata

profile.website
Type: string Default: ""

Website URL published as NIP-01 metadata

profile.nip05
Type: string Default: ""

NIP-05 verification identifier (e.g., 'bot@yourdomain.com')

profile.lud16
Type: string Default: ""

Lightning address for receiving zaps

Nostr Frequently Asked Questions

Nostr Troubleshooting

Bot starts but does not receive any messages

The relay connection may have failed, or the sender is publishing to different relays than the bot is subscribed to.

Check the Gateway logs for WebSocket connection errors. Verify your relay URLs are correct and accessible. Try adding a common public relay (e.g., wss://relay.damus.io) that the sender also uses. Ensure the private key is correctly set.
Error: invalid private key format

The private key is not in a valid nsec (Bech32) or 64-character hex format, or the environment variable is not set.

Verify the environment variable is exported correctly: 'echo $NOSTR_PRIVATE_KEY'. Ensure the key starts with 'nsec1' (Bech32 format) or is exactly 64 hex characters. Regenerate with 'nak key generate' if needed.
Messages are sent but never delivered to the recipient

The bot's configured relays and the recipient's client relays do not overlap, so events cannot propagate.

Add at least one relay that the recipient's Nostr client also uses. Common public relays like relay.damus.io and nos.lol are connected by most clients. Check the relay list in the recipient's Nostr client profile.
Plugin not found after installation

The Gateway was not restarted after plugin installation, or the installation failed silently.

Run 'openclaw plugins list' to verify the Nostr plugin is installed. If not listed, re-run 'openclaw plugins install @openclaw/nostr'. Restart the Gateway with 'openclaw start' after installation.
View Full Documentation Back to All Channels

Related Channels

Matrix

Medium

OpenClaw Federation Protocol integration

Setup Guide

Tlon

Advanced

OpenClaw Urbit messenger integration

Setup Guide