Docs: integrate XMTP channel into docs structure and remove changelog entry per PR workflow

2026-01-26 22:07:54 -08:00 · 2026-01-26 22:07:54 -08:00 · 0e0c550944
commit 0e0c550944
parent 9a831636a5
5 changed files with 309 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -67,6 +67,15 @@ apps/ios/*.mobileprovision
 .vscode/
 IDENTITY.md
 USER.md
+SOUL.md
+TOOLS.md
+MEMORY.md
+HEARTBEAT.md
+SUB_AGENT_RULES.md
+memory/
+xmtp-plugin/
+xmtp-research.md
+xmtp-reaction-bug-analysis.md
 .tgz

 # local tooling
--- a/README.md
+++ b/README.md
@ -98,6 +98,8 @@ pnpm clawdbot onboard --install-daemon
 pnpm gateway:watch
 ```

+**Important**: When developing from the repo, always use `pnpm clawdbot` (not just `clawdbot`) to run your local dev version. Running `clawdbot` alone uses the globally installed npm package, which won't include your changes.
+
 Note: `pnpm clawdbot ...` runs TypeScript directly (via `tsx`). `pnpm build` produces `dist/` for running via Node / the packaged `clawdbot` binary.

 ## Security defaults (DM access)
--- a/docs/channels/index.md
+++ b/docs/channels/index.md
@ -25,6 +25,7 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (plugin, installed separately).
 - [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
 - [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (plugin, installed separately).
+- [XMTP](/channels/xmtp) — Web3 wallet-to-wallet encrypted messaging (plugin, installed separately).
 - [Tlon](/channels/tlon) — Urbit-based messenger (plugin, installed separately).
 - [Twitch](/channels/twitch) — Twitch chat via IRC connection (plugin, installed separately).
 - [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).
--- a/docs/channels/xmtp.md
+++ b/docs/channels/xmtp.md
@ -0,0 +1,296 @@
+---
+summary: "XMTP decentralized messaging channel via wallet-to-wallet encrypted communication"
+read_when:
+  - You want Clawdbot to use XMTP for messaging
+  - You're setting up Web3 messaging
+---
+# XMTP (plugin)
+
+XMTP (Extensible Message Transport Protocol) is an open, decentralized messaging protocol for wallet-to-wallet encrypted communication. Clawdbot connects via a wallet identity, enabling direct messages and group conversations with quantum-resistant encryption.
+
+Status: supported via plugin (@xmtp/agent-sdk). Direct messages, group chats, text messages, reactions, attachments, and ENS address resolution.
+
+## Plugin required
+
+XMTP ships as a plugin and is not bundled with the core install.
+
+Install via CLI (npm registry):
+
+```bash
+clawdbot plugins install @clawdbot/xmtp
+```
+
+Local checkout (when running from a git repo):
+
+```bash
+clawdbot plugins install ./extensions/xmtp
+```
+
+If you choose XMTP during configure/onboarding and a git checkout is detected, Clawdbot will offer the local install path automatically.
+
+Details: [Plugins](/plugin)
+
+## Setup
+
+### 1. Install the plugin
+
+From npm:
+```bash
+clawdbot plugins install @clawdbot/xmtp
+```
+
+From a local checkout:
+```bash
+clawdbot plugins install ./extensions/xmtp
+```
+
+### 2. Generate a wallet for the bot
+
+XMTP uses Ethereum wallet identities. Generate a new wallet for your bot:
+
+```bash
+# Using the provided script
+cd extensions/xmtp
+npx tsx scripts/generate-wallet.ts
+```
+
+Example output:
+```
+Private Key: 0xef0760...d3e58b54
+Ethereum Address: 0x726149b70827960A6954B159B898C88D42cB7137
+```
+
+**Save the private key securely!** This is your bot's identity on XMTP.
+
+### 3. Configure credentials
+
+Add to your config at `~/.clawdbot/clawdbot.json`:
+
+```json
+{
+  "channels": {
+    "xmtp": {
+      "enabled": true,
+      "env": "dev",
+      "walletKey": "0xYOUR_PRIVATE_KEY_HERE",
+      "dbPath": "/Users/you/.clawdbot/.xmtp/db",
+      "dmPolicy": "pairing"
+    }
+  }
+}
+```
+
+Or use environment variables:
+
+```bash
+export XMTP_WALLET_KEY=0xYOUR_PRIVATE_KEY_HERE
+export XMTP_ENV=dev
+export XMTP_DB_PATH=/Users/you/.clawdbot/.xmtp/db
+```
+
+### 4. Restart the gateway
+
+```bash
+clawdbot gateway restart
+```
+
+### 5. Test the connection
+
+Install an XMTP client app:
+- [Converse](https://getconverse.app/) (iOS/Android)
+- [xmtp.chat](https://xmtp.chat/) (Web)
+
+Message your bot's Ethereum address (from step 2) and your bot should reply!
+
+## Configuration reference
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `false` | Enable XMTP channel |
+| `env` | string | `"dev"` | Network environment: `"dev"` or `"production"` |
+| `walletKey` | string | required | Bot's Ethereum private key (hex format with 0x prefix) |
+| `dbPath` | string | `".xmtp/db"` | Local database path for XMTP state |
+| `encryptionKey` | string | (optional) | Database encryption key (auto-generated if not set) |
+| `dmPolicy` | string | `"pairing"` | DM access policy (`"open"`, `"pairing"`, or `"allowlist"`) |
+| `allowFrom` | string[] | `[]` | Allowed sender addresses (when using allowlist policy) |
+
+## Networks
+
+### Development Network
+- **Purpose:** Testing and development
+- **Cost:** Free
+- **Persistence:** Messages may not persist long-term
+- **Configuration:** Set `env: "dev"`
+- **Use when:** Building and testing your bot
+
+### Production Network
+- **Purpose:** Production use
+- **Cost:** ~5 USDC per 100,000 messages
+- **Persistence:** Long-term message storage
+- **Configuration:** Set `env: "production"`
+- **Use when:** Deploying for real users
+
+**Important:** Development and production are separate networks. Users on dev cannot message users on production and vice versa.
+
+## Security
+
+### Wallet key management
+
+- **Never commit your wallet private key** to version control
+- Use environment variables or encrypted config for production
+- Keep separate wallets for dev and production environments
+- Consider using a dedicated bot wallet with minimal assets
+
+### DM policies
+
+Like other channels, XMTP supports DM access policies:
+
+- `"open"` - Anyone can message the bot (not recommended)
+- `"pairing"` - Users must pair first (recommended)
+- `"allowlist"` - Only specific addresses can message
+
+Example allowlist config:
+
+```json
+{
+  "channels": {
+    "xmtp": {
+      "enabled": true,
+      "env": "production",
+      "walletKey": "${XMTP_WALLET_KEY}",
+      "dmPolicy": "allowlist",
+      "allowFrom": [
+        "0x0a8138c495cd47367e635b94feb7612a230221a4"
+      ]
+    }
+  }
+}
+```
+
+## Features
+
+### Supported
+- ✅ Direct messages (DMs)
+- ✅ Group conversations
+- ✅ Text messages
+- ✅ Reactions
+- ✅ Attachments
+- ✅ ENS address resolution
+- ✅ Multi-account support (via config)
+- ✅ Quantum-resistant encryption (MLS protocol)
+
+### Coming soon
+- ⏳ Read receipts
+- ⏳ Thread replies
+
+## ENS resolution
+
+XMTP supports ENS (Ethereum Name Service) for human-readable addresses:
+
+```
+# Message via ENS name
+Send "Hello!" to vitalik.eth
+```
+
+The plugin automatically resolves ENS names to Ethereum addresses.
+
+## Multi-account support
+
+Future versions will support multiple XMTP accounts. Configuration structure:
+
+```json
+{
+  "channels": {
+    "xmtp": {
+      "enabled": true,
+      "accounts": [
+        {
+          "label": "primary",
+          "env": "production",
+          "walletKey": "${XMTP_PRIMARY_KEY}",
+          "dbPath": ".xmtp/primary"
+        },
+        {
+          "label": "dev-bot",
+          "env": "dev",
+          "walletKey": "${XMTP_DEV_KEY}",
+          "dbPath": ".xmtp/dev"
+        }
+      ]
+    }
+  }
+}
+```
+
+See [examples/multi-account.json5](https://github.com/clawdbot/clawdbot/blob/main/extensions/xmtp/examples/multi-account.json5) for details.
+
+## Example configurations
+
+The XMTP plugin includes ready-to-use configuration templates in the `examples/` directory:
+
+- **quickstart.json5** - Minimal 2-minute setup
+- **dev-network.json5** - Full dev network config with comments
+- **production-network.json5** - Production-ready config with security best practices
+- **multi-account.json5** - Multi-wallet support (planned feature)
+
+Browse them at: https://github.com/clawdbot/clawdbot/tree/main/extensions/xmtp/examples
+
+## Troubleshooting
+
+### "XMTP wallet key not configured"
+
+Generate a wallet:
+```bash
+cd extensions/xmtp
+npx tsx scripts/generate-wallet.ts
+```
+
+Set the key:
+```bash
+export XMTP_WALLET_KEY="0x..."
+```
+
+### Messages not appearing
+
+Check if XMTP is connected:
+```bash
+clawdbot channels status
+```
+
+Check for errors:
+```bash
+clawdbot logs | grep -i xmtp
+```
+
+Verify network environment matches (both on `dev` or both on `production`).
+
+### Can't send to an address
+
+- Recipient must have XMTP enabled (used an XMTP client before)
+- Both sender and recipient must be on the same network (dev or production)
+- Check that the address is valid (0x prefix, 40 hex characters)
+
+### Database errors
+
+If you see database corruption errors, stop the gateway and remove the database:
+
+```bash
+clawdbot gateway stop
+rm -rf ~/.clawdbot/.xmtp/db
+clawdbot gateway start
+```
+
+The database will be recreated on next start.
+
+## Resources
+
+- [XMTP Protocol](https://xmtp.org)
+- [XMTP Documentation](https://docs.xmtp.org/)
+- [XMTP Agent SDK](https://github.com/xmtp/xmtp-js/tree/main/sdks/agent-sdk)
+- [Test Your Bot](https://xmtp.chat/)
+- [Converse App](https://getconverse.app/)
+- [Plugin README](https://github.com/clawdbot/clawdbot/blob/main/extensions/xmtp/README.md)
+
+## Contributing
+
+See the main [Contributing Guide](https://github.com/clawdbot/clawdbot/blob/main/CONTRIBUTING.md) for details on contributing to Clawdbot and its channel plugins.
--- a/docs/docs.json
+++ b/docs/docs.json
@ -994,6 +994,7 @@
          "channels/msteams",
          "channels/line",
          "channels/matrix",
+          "channels/xmtp",
          "channels/zalo",
          "channels/zalouser",
          "broadcast-groups",