@keychat-io/keychat 0.1.18

package/README.md

@@ -0,0 +1,170 @@
+# Keychat — OpenClaw Channel Plugin
+
+E2E encrypted AI agent communication via Keychat protocol.
+
+## What is this?
+
+This plugin gives your OpenClaw agent a **sovereign identity** — a self-generated Public Key ID (Nostr keypair) — and enables **end-to-end encrypted communication** using the Signal Protocol over Nostr relays.
+
+Your agent becomes a full Keychat citizen: it can receive friend requests, establish Signal Protocol sessions, and exchange messages with Keychat app users. All messages are encrypted with forward and backward secrecy — not even relay operators can read them.
+
+## Install
+
+```bash
+openclaw plugins install @keychat-io/keychat
+openclaw gateway restart
+```
+
+That's it. The plugin automatically downloads the bridge binary and initializes the config on first load.
+
+Supported platforms: macOS (ARM/x64), Linux (x64/ARM64).
+
+Alternatively, install via shell script:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/keychat-io/keychat/main/scripts/install.sh | bash
+```
+
+### Security Warnings
+
+During installation, OpenClaw's security scanner may show three warnings. All are expected:
+
+| Warning | Reason |
+|---------|--------|
+| Shell command execution (bridge-client.ts) | Spawns a Rust sidecar for Signal Protocol and MLS encryption. |
+| Shell command execution (keychain.ts) | Stores identity mnemonics in the OS keychain (macOS Keychain / Linux libsecret). |
+| Shell command execution (notify.ts) | Notifies the agent on startup so it can send the Keychat ID and QR code to the user. |
+
+Source code is fully open: [github.com/keychat-io/keychat](https://github.com/keychat-io/keychat)
+
+### Upgrade
+
+Tell your agent "upgrade keychat" in any chat, or manually:
+
+```bash
+openclaw plugins install @keychat-io/keychat@latest
+openclaw gateway restart
+```
+
+## Add Your Agent as a Keychat Contact
+
+After `openclaw gateway restart`, the agent will send you its **Keychat ID**, **contact link**, and **QR code** in your active chat (Telegram, webchat, etc.):
+
+```
+🔑 Keychat ID: npub1...
+📱 Add contact: https://www.keychat.io/u/?k=npub1...
+🖼️ QR code image
+```
+
+Open the [Keychat app](https://keychat.io) → tap the link, paste the npub, or scan the QR code to add as contact. If `dmPolicy` is `open` (default after auto-init), the agent accepts immediately.
+
+## Configuration
+
+All options go under `channels.keychat` in your OpenClaw config (`~/.openclaw/openclaw.json`):
+
+| Option             | Type     | Default                      | Description                                               |
+| ------------------ | -------- | ---------------------------- | --------------------------------------------------------- |
+| `enabled`          | boolean  | `true`                       | Enable/disable the Keychat channel                        |
+| `name`             | string   | —                            | Display name for this account                             |
+| `relays`           | string[] | `["wss://relay.keychat.io"]` | Nostr relay WebSocket URLs                                |
+| `dmPolicy`         | enum     | `"open"`                     | Access policy: `pairing`, `allowlist`, `open`, `disabled` |
+| `allowFrom`        | string[] | `[]`                         | Allowed sender pubkeys (npub or hex)                      |
+| `lightningAddress` | string   | —                            | Lightning address for receiving payments                  |
+| `nwcUri`           | string   | —                            | Nostr Wallet Connect URI for wallet access                |
+
+### DM Policies
+
+- **`open`**: Anyone can message the agent (default)
+- **`pairing`**: New contacts require owner approval via OpenClaw
+- **`allowlist`**: Only pubkeys in `allowFrom` can communicate
+- **`disabled`**: No inbound messages accepted
+
+## Lightning Wallet
+
+### Lightning Address (receive-only)
+
+```json
+{ "lightningAddress": "user@walletofsatoshi.com" }
+```
+
+### Nostr Wallet Connect (NWC)
+
+For full wallet access (create invoices, check balance, verify payments):
+
+```json
+{ "nwcUri": "nostr+walletconnect://pubkey?relay=wss://...&secret=..." }
+```
+
+Generate an NWC connection string from your wallet app (Keychat, Alby Hub, Mutiny, Coinos, etc.).
+
+**Security note**: The agent can receive payments freely. Outbound payments require owner approval.
+
+## Architecture
+
+```
+┌──────────────┐    JSON-RPC     ┌─────────────────────┐    Nostr     ┌─────────┐
+│  OpenClaw    │◄──────────────►│  keychat  │◄───────────►│  Relays  │
+│  (TypeScript │    stdin/stdout │  (Rust sidecar)     │  WebSocket  │         │
+│   plugin)    │                │                     │             │         │
+└──────────────┘                └─────────────────────┘             └─────────┘
+                                  │ Signal Protocol DB │
+                                  │ (SQLite)           │
+                                  └────────────────────┘
+```
+
+- **TypeScript plugin**: OpenClaw channel integration, routing, pairing, message dispatch
+- **Rust sidecar**: Signal Protocol sessions, Nostr transport, encryption/decryption
+- **Communication**: JSON-RPC over stdin/stdout
+- **Encryption**: Signal Protocol (Double Ratchet) with forward and backward secrecy
+- **Transport**: Nostr relays (kind:4 DMs + kind:1059 Gift Wrap for friend requests)
+
+## Security
+
+- **E2E Encryption**: All messages encrypted with Signal Protocol — relay operators cannot read content
+- **Forward & Backward Secrecy**: Double Ratchet ensures compromising current keys reveals neither past nor future messages
+- **Sovereign Identity**: Agent generates its own keypair — no third-party identity provider
+- **Key Storage**: Mnemonic stored in system keychain (macOS Keychain, Linux secret service)
+- **Sending Address Rotation**: Each outbound message uses a fresh Nostr keypair, preventing metadata correlation
+- **Receiving Address Rotation**: Ratchet-derived addresses rotate almost per message, preventing traffic analysis
+
+## Troubleshooting
+
+- **Bridge not starting**: Check `ls ~/.openclaw/extensions/keychat/bridge/target/release/keychat`. If missing, restart gateway (auto-downloads) or build from source: `cd bridge && cargo build --release`
+- **Relay issues**: Verify relay URLs (`wss://...`), try alternative relays
+- **Decryption errors**: Peer should delete old contact and re-add the agent
+- **Messages not delivered**: Plugin queues failed messages (up to 100) and retries every 30s
+
+## Development
+
+```bash
+cd bridge && cargo build --release
+cargo test
+```
+
+### Project Structure
+
+```
+├── src/
+│   ├── channel.ts        # Main channel plugin
+│   ├── bridge-client.ts  # RPC client for Rust sidecar
+│   ├── config-schema.ts  # Zod config schema
+│   ├── keychain.ts       # System keychain integration
+│   ├── lightning.ts      # LNURL-pay support
+│   ├── nwc.ts            # Nostr Wallet Connect (NIP-47)
+│   ├── media.ts          # Blossom media encryption/upload
+│   ├── qrcode.ts         # QR code generation
+│   ├── runtime.ts        # Plugin runtime accessor
+│   └── types.ts          # Account types and resolvers
+├── bridge/src/
+│   ├── main.rs           # Sidecar entry point
+│   ├── rpc.rs            # JSON-RPC dispatch
+│   ├── signal.rs         # Signal Protocol manager
+│   ├── protocol.rs       # Keychat protocol types
+│   ├── mls.rs            # MLS large group support
+│   └── transport.rs      # Nostr relay transport
+├── scripts/
+│   └── install.sh        # One-line installer
+├── index.ts              # Plugin entry point
+├── openclaw.plugin.json  # Plugin manifest
+└── LICENSE               # AGPL-3.0
+```

package/docs/setup-guide.md

@@ -0,0 +1,124 @@
+# Keychat — Setup Guide
+
+Step-by-step instructions to get your OpenClaw agent communicating via Keychat.
+
+## Prerequisites
+
+- **macOS or Linux** (arm64 or x86_64)
+- **Node.js 20+**
+- **OpenClaw**: Installed and configured (`openclaw gateway status` should work)
+
+## Step 1: Install the Plugin
+
+```bash
+openclaw plugins install @keychat-io/keychat
+```
+
+This auto-downloads the pre-compiled Rust sidecar binary for your platform. No Rust toolchain needed.
+
+> **Building from source** (optional): If no pre-compiled binary is available for your platform, install [Rust](https://rustup.rs/) and run `cd bridge && cargo build --release`.
+
+## Step 2: Configure OpenClaw
+
+Edit `~/.openclaw/openclaw.json` and add the Keychat channel config:
+
+```json
+{
+  "channels": {
+    "keychat": {
+      "enabled": true,
+      "relays": [
+        "wss://relay.keychat.io",
+        "wss://relay.damus.io"
+      ],
+      "dmPolicy": "pairing"
+    }
+  }
+}
+```
+
+### DM Policies
+
+| Policy | Description |
+|--------|-------------|
+| `pairing` | New contacts require owner approval (default) |
+| `allowlist` | Only pubkeys in `allowFrom` can communicate |
+| `open` | Anyone can message the agent |
+| `disabled` | No inbound messages accepted |
+
+## Step 3: Restart the Gateway
+
+```bash
+openclaw gateway restart
+```
+
+Watch the logs for your agent's Keychat ID:
+
+```
+═══════════════════════════════════════════════════
+  🔑 Agent Keychat ID (scan with Keychat app):
+
+  npub1...
+
+  Add contact link:
+  https://www.keychat.io/u/?k=npub1...
+═══════════════════════════════════════════════════
+```
+
+A QR code is also saved to `~/.openclaw/keychat/qr-default.png`.
+
+## Step 4: Connect with Keychat App
+
+1. Open the [Keychat app](https://www.keychat.io/) on your phone
+2. Tap **Add Contact**
+3. Scan the QR code at `~/.openclaw/keychat/qr-default.png`, or paste the npub / contact URL
+4. Send a friend request
+5. If `dmPolicy` is `pairing`, approve the request:
+   ```bash
+   openclaw pair approve keychat <sender-pubkey>
+   ```
+
+## Step 5: Start Chatting
+
+Send a message from the Keychat app — your agent will respond with E2E encrypted messages.
+
+## Identity Management
+
+- **First run**: Agent auto-generates a mnemonic and stores it in your system keychain (macOS Keychain / Linux libsecret)
+- **Backup**: Export the mnemonic from your keychain if needed
+- **Restore**: Set `mnemonic` in the channel config to restore an existing identity on a new machine
+- **Signal DB**: Stored at `~/.openclaw/keychat/signal-default.db` — **do not delete** (destroys all encrypted sessions)
+
+## Verifying the Setup
+
+```bash
+openclaw gateway status
+```
+
+The Keychat channel should show as running with the agent's npub.
+
+## Lightning Wallet (Optional)
+
+Add a Lightning address for receiving payments:
+
+```json
+{
+  "channels": {
+    "keychat": {
+      "lightningAddress": "user@walletofsatoshi.com"
+    }
+  }
+}
+```
+
+For full wallet access (balance, payments), configure [Nostr Wallet Connect](https://github.com/nostr-protocol/nips/blob/master/47.md):
+
+```json
+{
+  "channels": {
+    "keychat": {
+      "nwcUri": "nostr+walletconnect://pubkey?relay=wss://...&secret=..."
+    }
+  }
+}
+```

package/index.ts

@@ -0,0 +1,205 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { keychatPlugin, getAgentKeychatId, getAgentKeychatUrl, getAllAgentContacts } from "./src/channel.js";
+import { setKeychatRuntime } from "./src/runtime.js";
+import { existsSync, mkdirSync, chmodSync, writeFileSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import https from "node:https";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Download a URL following redirects, return a Buffer. */
+function downloadBinary(url: string): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    https.get(url, (res) => {
+      if (res.statusCode && res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return downloadBinary(res.headers.location).then(resolve, reject);
+      }
+      if (res.statusCode !== 200) {
+        return reject(new Error(`HTTP ${res.statusCode}`));
+      }
+      const chunks: Buffer[] = [];
+      res.on("data", (chunk: Buffer) => chunks.push(chunk));
+      res.on("end", () => resolve(Buffer.concat(chunks)));
+      res.on("error", reject);
+    }).on("error", reject);
+  });
+}
+
+/** Ensure bridge binary exists, download if missing. */
+async function ensureBinary(): Promise<void> {
+  const binaryDir = join(__dirname, "bridge", "target", "release");
+  const binaryPath = join(binaryDir, "keychat-bridge");
+
+  if (existsSync(binaryPath)) return;
+
+  const platform = process.platform;
+  const arch = process.arch;
+  const artifacts: Record<string, string> = {
+    "darwin-arm64": "keychat-openclaw-darwin-arm64",
+    "darwin-x64": "keychat-openclaw-darwin-x64",
+    "linux-x64": "keychat-openclaw-linux-x64",
+    "linux-arm64": "keychat-openclaw-linux-arm64",
+  };
+
+  const artifact = artifacts[`${platform}-${arch}`];
+  if (!artifact) {
+    console.warn(`[keychat] No pre-compiled binary for ${platform}-${arch}. Build from source: cd bridge && cargo build --release`);
+    return;
+  }
+
+  const url = `https://github.com/keychat-io/keychat-openclaw/releases/latest/download/${artifact}`;
+  console.log(`[keychat] Bridge binary not found, downloading ${artifact}...`);
+
+  try {
+    mkdirSync(binaryDir, { recursive: true });
+    const buffer = await downloadBinary(url);
+    writeFileSync(binaryPath, buffer);
+    chmodSync(binaryPath, 0o755);
+    console.log("[keychat] ✅ Bridge binary installed");
+  } catch (err: any) {
+    console.warn(`[keychat] Binary download failed: ${err.message}`);
+    console.warn("[keychat] Build from source: cd bridge && cargo build --release");
+  }
+}
+
+/** Ensure channels.keychat exists in openclaw.json config. */
+function ensureConfig(): void {
+  const configPath = join(homedir(), ".openclaw", "openclaw.json");
+  try {
+    let config: any = {};
+    if (existsSync(configPath)) {
+      config = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    if (config.channels?.keychat) return;
+
+    if (!config.channels) config.channels = {};
+    config.channels.keychat = { enabled: true, dmPolicy: "open" };
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    console.log("[keychat] ✅ Config initialized (channels.keychat.enabled = true)");
+  } catch (err: any) {
+    console.warn(`[keychat] Could not auto-configure: ${err.message}`);
+  }
+}
+
+const plugin = {
+  id: "keychat",
+  name: "Keychat",
+  description:
+    "Keychat channel plugin — sovereign identity + E2E encrypted chat. " +
+    "Agent generates its own Public Key ID, just like a human Keychat user.",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    console.log("[keychat] register() called");
+    try {
+      // Auto-setup: download binary + init config on first load
+      ensureConfig();
+      ensureBinary().catch((err) => console.warn("[keychat] ensureBinary error:", err));
+      setKeychatRuntime(api.runtime);
+      console.log("[keychat] runtime set, registering channel...");
+      api.registerChannel({ plugin: keychatPlugin });
+      console.log("[keychat] channel registered successfully");
+
+      // Register keychat_identity agent tool so the agent can fetch ID info
+      // and send it to the user on whatever channel they're on
+      api.registerTool({
+        name: "keychat_identity",
+        label: "Keychat Identity",
+        description:
+          "Get the Keychat identity (npub, contact link, QR code path) for all active agent accounts. " +
+          "Call this after Keychat setup/install to retrieve the agent's Keychat ID and share it with the user.",
+        parameters: { type: "object", properties: {}, required: [] },
+        async execute(_toolCallId: string, _params: any) {
+          const contacts = getAllAgentContacts();
+          if (contacts.length === 0) {
+            return {
+              details: null,
+              content: [
+                {
+                  type: "text" as const,
+                  text: "No Keychat accounts are active yet. The bridge may still be starting — try again in a few seconds.",
+                },
+              ],
+            };
+          }
+          const { generateQRDataUrl } = await import("./src/qrcode.js");
+          const results = [];
+          const contentParts: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }> = [];
+
+          for (const c of contacts) {
+            const qrDataUrl = await generateQRDataUrl(c.npub);
+            results.push({
+              accountId: c.accountId,
+              npub: c.npub,
+              contactUrl: c.contactUrl,
+            });
+            contentParts.push({
+              type: "text" as const,
+              text: `Account: ${c.accountId}\nnpub: ${c.npub}\nContact: ${c.contactUrl}`,
+            });
+            if (qrDataUrl) {
+              // Extract base64 from data URL: "data:image/png;base64,..."
+              const base64 = qrDataUrl.replace(/^data:image\/png;base64,/, "");
+              contentParts.push({
+                type: "image" as const,
+                data: base64,
+                mimeType: "image/png",
+              });
+            }
+          }
+
+          return {
+            details: null,
+            content: contentParts,
+          };
+        },
+      });
+
+      // Register /keychat-id command to show agent Keychat ID, link, and QR
+      api.registerCommand({
+        name: "keychat-id",
+        description: "Show Keychat agent ID(s), contact link(s), and QR code path(s)",
+        handler: () => {
+          const contacts = getAllAgentContacts();
+          if (contacts.length === 0) {
+            return { text: "⚠️ No Keychat accounts are active yet. Wait for the bridge to start." };
+          }
+          const lines = contacts.map((c) => {
+            const qrExists = existsSync(c.qrCodePath);
+            return [
+              `🔑 **${c.accountId}**`,
+              `  npub: \`${c.npub}\``,
+              `  📱 Link: ${c.contactUrl}`,
+              qrExists
+                ? `  🖼️ QR: ${c.qrCodePath}`
+                : `  (QR image not found)`,
+            ].join("\n");
+          });
+          return { text: lines.join("\n\n") };
+        },
+      });
+    } catch (err) {
+      console.error("[keychat] register failed:", err);
+    }
+  },
+};
+
+export default plugin;
+export { getAgentKeychatId, getAgentKeychatUrl, getAllAgentContacts, resetPeerSession } from "./src/channel.js";
+export { generateQRDataUrl } from "./src/qrcode.js";
+export {
+  requestInvoice,
+  fetchLnurlPayMetadata,
+  verifyPayment,
+  formatSats,
+  lightningAddressToLnurlp,
+} from "./src/lightning.js";
+export {
+  NwcClient,
+  parseNwcUri,
+  initNwc,
+  getNwcClient,
+  disconnectNwc,
+} from "./src/nwc.js";

package/openclaw.plugin.json

@@ -0,0 +1,38 @@
+{
+  "id": "keychat",
+  "channels": ["keychat"],
+  "name": "Keychat",
+  "description": "Sovereign identity + E2E encrypted chat via Signal Protocol over Nostr relays. Lightning wallet support via LNURL-pay and NWC.",
+  "version": "0.1.0",
+  "repository": "https://github.com/keychat-io/keychat-openclaw",
+  "license": "AGPL-3.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "name": { "type": "string", "description": "Display name for this account" },
+      "enabled": { "type": "boolean", "description": "Enable/disable the Keychat channel" },
+      "markdown": { "type": "object", "description": "Markdown formatting overrides" },
+      "mnemonic": { "type": "string", "description": "Identity mnemonic (auto-generated, stored in keychain)" },
+      "publicKey": { "type": "string", "description": "Derived hex public key (read-only)" },
+      "npub": { "type": "string", "description": "Derived bech32 npub (read-only)" },
+      "relays": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Nostr relay WebSocket URLs"
+      },
+      "dmPolicy": {
+        "type": "string",
+        "enum": ["pairing", "allowlist", "open", "disabled"],
+        "description": "DM access policy"
+      },
+      "allowFrom": {
+        "type": "array",
+        "items": { "type": ["string", "number"] },
+        "description": "Allowed sender pubkeys (npub or hex)"
+      },
+      "lightningAddress": { "type": "string", "description": "Lightning address for receiving payments" },
+      "nwcUri": { "type": "string", "description": "Nostr Wallet Connect URI" }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@keychat-io/keychat",
+  "version": "0.1.18",
+  "description": "Keychat — E2E encrypted chat + Lightning wallet for OpenClaw agents",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/keychat-io/keychat-openclaw.git"
+  },
+  "type": "module",
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "dependencies": {
+    "@nostr-dev-kit/ndk": "^3.0.0",
+    "qrcode": "^1.5.4",
+    "zod": "^4.3.6"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "keychat",
+      "label": "Keychat",
+      "selectionLabel": "Keychat (E2E Encrypted)",
+      "docsPath": "/channels/keychat",
+      "docsLabel": "keychat",
+      "blurb": "Sovereign identity + E2E encrypted chat via Signal Protocol over Nostr relays.",
+      "order": 56
+    }
+  }
+}

package/scripts/build-release.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# Build release binaries for all supported platforms.
+# Requires: cargo, cargo-zigbuild, zig
+# Linux targets use musl for static linking (no glibc dependency).
+#
+# Usage: ./scripts/build-release.sh [--upload v0.1.x]
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BRIDGE_DIR="$SCRIPT_DIR/../bridge"
+OUT_DIR="$SCRIPT_DIR/../dist"
+REPO="keychat-io/keychat-openclaw"
+
+cd "$BRIDGE_DIR"
+
+echo "🔨 Building release binaries..."
+echo ""
+
+mkdir -p "$OUT_DIR"
+
+# ── Darwin ARM64 (native) ──
+echo "  [1/4] darwin-arm64..."
+cargo build --release 2>&1 | grep -v "^warning:" || true
+cp target/release/keychat-openclaw "$OUT_DIR/keychat-openclaw-darwin-arm64"
+echo "  ✅ darwin-arm64"
+
+# ── Darwin x64 (cross) ──
+echo "  [2/4] darwin-x64..."
+if cargo zigbuild --target x86_64-apple-darwin --release 2>&1 | grep -v "^warning:" | tail -1; then
+  cp target/x86_64-apple-darwin/release/keychat-openclaw "$OUT_DIR/keychat-openclaw-darwin-x64"
+  echo "  ✅ darwin-x64"
+else
+  echo "  ⚠️  darwin-x64 failed (optional — most Macs are ARM now)"
+fi
+
+# ── Linux x64 (musl static) ──
+echo "  [3/4] linux-x64 (musl)..."
+cargo zigbuild --target x86_64-unknown-linux-musl --release 2>&1 | grep -v "^warning:" || true
+cp target/x86_64-unknown-linux-musl/release/keychat-openclaw "$OUT_DIR/keychat-openclaw-linux-x64"
+echo "  ✅ linux-x64 (statically linked)"
+
+# ── Linux ARM64 (musl static) ──
+echo "  [4/4] linux-arm64 (musl)..."
+cargo zigbuild --target aarch64-unknown-linux-musl --release 2>&1 | grep -v "^warning:" || true
+cp target/aarch64-unknown-linux-musl/release/keychat-openclaw "$OUT_DIR/keychat-openclaw-linux-arm64"
+echo "  ✅ linux-arm64 (statically linked)"
+
+echo ""
+echo "════════════════════════════════════════"
+echo "  📦 All binaries in: $OUT_DIR"
+ls -lh "$OUT_DIR"/keychat-openclaw-*
+echo "════════════════════════════════════════"
+
+# ── Optional: upload to GitHub Release ──
+if [ "$1" = "--upload" ] && [ -n "$2" ]; then
+  TAG="$2"
+  echo ""
+  echo "🚀 Uploading to GitHub Release $TAG..."
+  
+  if ! command -v gh &>/dev/null; then
+    echo "❌ gh CLI not found. Install: brew install gh"
+    exit 1
+  fi
+
+  # Create release if not exists
+  gh release view "$TAG" --repo "$REPO" &>/dev/null || \
+    gh release create "$TAG" --repo "$REPO" --title "$TAG" --notes "Release $TAG"
+
+  # Upload/overwrite artifacts
+  for f in "$OUT_DIR"/keychat-openclaw-*; do
+    echo "  Uploading $(basename "$f")..."
+    gh release upload "$TAG" "$f" --repo "$REPO" --clobber
+  done
+
+  echo "  ✅ All artifacts uploaded to $TAG"
+fi