openclaw-zulip

@openclaw/zulip

Zulip channel plugin for OpenClaw.

Why Zulip + OpenClaw?

Zulip's topic-based threading model is ideal for structured AI agent workflows:

• Brain channels — Dedicate streams to domains (🧠 memory, 🛠️ devops, 🔍 research, 📅 triage) so your agent has organized context.
• Topic isolation — Each topic gets its own agent session. Conversations don't bleed across topics.
• Open-source and Self-hosted — Full control over your data. No third-party SaaS dependency for your agent's communication layer.
• Multi-agent — Run multiple bots (different models, different personalities) on the same Zulip server via multi-account config.

Replaces external bridge scripts with an in-process TypeScript plugin that connects directly to Zulip's event queue API. Zero external dependencies beyond OpenClaw itself.

Features

• Direct Messages — Full DM handling with session persistence
• Stream @Mentions — Responds when @mentioned in channels (chatmode: oncall)
• Topic Threading — Separate conversation context per stream+topic
• Emoji Reactions — Add/remove reactions via the message tool
• Pairing & Access Control — Allowlists, pairing codes, group policies
• Auto-Reconnection — Exponential backoff on disconnect, queue re-registration on expiry
• Multi-Account — Run multiple bots with different agents/models
• Message History — Agent tool to fetch channel/topic history (zulip_fetch_messages)
• File Downloads — Agent tool to download uploaded files (zulip_download_file)
• Onboarding Wizard — Interactive CLI setup via openclaw channels add
• Companion Skills — Agent skills for Zulip conventions and organization administration

Requirements

• OpenClaw (2026.2.x or later)
• A Zulip server (self-hosted or Zulip Cloud) — see Deploying Zulip on AWS EC2 if you need one

Installation

1. Copy the plugin to your OpenClaw extensions directory:

   cp -r openclaw-zulip ~/.openclaw/extensions/zulip
   

2. Symlink dependencies (the plugin uses OpenClaw's bundled zod and plugin SDK):

   mkdir -p ~/.openclaw/extensions/zulip/node_modules
   OPENCLAW_DIR=$(dirname $(dirname $(which openclaw)))
   ln -sf "$OPENCLAW_DIR/lib/node_modules/openclaw/node_modules/zod" \
     ~/.openclaw/extensions/zulip/node_modules/zod
   ln -sf "$OPENCLAW_DIR/lib/node_modules/openclaw" \
     ~/.openclaw/extensions/zulip/node_modules/openclaw
   

3. Configure via the onboarding wizard or manually:

   # Interactive setup
   openclaw channels add --channel zulip
   
   # Or add to ~/.openclaw/openclaw.json manually:
   

   {
     "channels": {
       "zulip": {
         "enabled": true,
         "botEmail": "your-bot@your-zulip-server.example.com",
         "botToken": "your-bot-api-key",
         "baseUrl": "https://your-zulip-server.example.com",
         "chatmode": "oncall",
         "dmPolicy": "open",
         "allowFrom": ["*"]
       }
     }
   }
   

4. Restart the gateway:

   openclaw gateway restart
   

5. Verify:

   openclaw status
   # Should show: Zulip ON · OK
   

Install the Companion Skills

This repo includes two companion skills that teach agents how to work in Zulip:

Zulip Conventions Skill (skill/)

Teaches agents Zulip-specific conventions: topic discipline, @**Name|ID** mention syntax, #**channel>topic** linking, reaction etiquette, and how to use the plugin's message history and file download tools.

Recommended for: All agents operating in Zulip.

cp -r skill ~/.openclaw/skills/zulip

Zulip Admin Skill (skill-admin/)

Comprehensive Zulip organization administration: user management (create, deactivate, update roles), channel operations (create, archive, update permissions, subscribe/unsubscribe), user groups, custom emoji, linkifiers, invitations, and audit workflows. Includes a bundled zulip-audit.py script for quick realm health checks.

Recommended for: A dedicated admin agent with Organization Administrator privileges. Not needed by every agent — only the one responsible for realm maintenance.

cp -r skill-admin ~/.openclaw/skills/zulip-admin

Verify

openclaw skills
# Should show both: zulip (ready), zulip-admin (ready)

Configuration

Environment Variables

Config Options

Multi-Account

Run multiple bots (e.g., different models) by adding named accounts:

{
  "channels": {
    "zulip": {
      "enabled": true,
      "baseUrl": "https://your-zulip.example.com",
      "accounts": {
        "default": {
          "botEmail": "main-bot@your-zulip.example.com",
          "botToken": "key-1"
        },
        "research": {
          "botEmail": "research-bot@your-zulip.example.com",
          "botToken": "key-2"
        }
      }
    }
  }
}

Bind accounts to agents in your agents.list[] configuration.

webmaster Skill (skills/webmaster/)

Static site deployment and management for OpenClaw agents. Provides a CLI for building, deploying, and monitoring HTML/CSS/JS websites with S3 and CloudFront integration.

Use cases:

• Agent-generated documentation sites
• Monitoring dashboards
• Reports and analytics publishing
• Static web applications

Features:

• 🏗️ Site scaffolding with templates
• 📦 Build pipeline (validation, minification)
• 🚀 S3 deployment
• ☁️ CloudFront CDN integration
• 📊 Health checks and analytics
• 🔐 PVM integration for temporary AWS permissions

cp -r skills/webmaster ~/.openclaw/skills/webmaster
cd ~/.openclaw/skills/webmaster
npm install

See skills/webmaster/README.md for documentation.

Dependencies: Requires PVM (Permissions Vending Machine) for S3/CloudFront access.

Agent Tools

The plugin registers two tools available to all agents:

zulip_fetch_messages

Fetch message history from a Zulip channel/topic. Use when the agent needs context beyond the auto-injected recent messages.

Parameters:
  channel  — Stream name or ID
  topic    — Topic name
  sender   — Filter by sender email
  keyword  — Search keyword
  limit    — Max messages (1-100, default 20)
  anchor   — "newest", "oldest", or message ID

zulip_download_file

Download a file uploaded to Zulip. Accepts /user_uploads/... paths or full URLs. Returns content for text files, saves binary files to temp.

Parameters:
  url — Zulip upload URL or /user_uploads/... path

Architecture

Zulip Server
  ↕ POST /api/v1/register (event queue)
  ↕ GET /api/v1/events (long-poll)
src/zulip/client.ts (REST client)
  ↕
src/zulip/monitor.ts (event loop + routing)
  ↕
OpenClaw Gateway (in-process agent session)
  ↕
src/zulip/send.ts (outbound delivery)
  ↕
Zulip Server

Session Key Mapping

File Structure

├── index.ts                    # Plugin entry point
├── openclaw.plugin.json        # Plugin manifest
├── package.json                # Package metadata
├── skill/
│   └── SKILL.md                # Zulip conventions skill
├── skill-admin/
│   ├── SKILL.md                # Zulip admin skill
│   └── scripts/
│       └── zulip-audit.py      # Realm audit tool
└── src/
    ├── channel.ts              # ChannelPlugin implementation
    ├── config-schema.ts        # Zod config validation
    ├── group-mentions.ts       # @mention resolution
    ├── normalize.ts            # Target normalization
    ├── onboarding.ts           # CLI setup wizard
    ├── onboarding-helpers.ts   # Re-export helpers
    ├── runtime.ts              # Runtime singleton
    ├── types.ts                # Type definitions
    └── zulip/
        ├── accounts.ts         # Multi-account resolution
        ├── client.ts           # REST API client
        ├── index.ts            # Re-exports
        ├── monitor.ts          # Event loop + message routing
        ├── monitor-auth.ts     # Access control
        ├── monitor-helpers.ts  # Dedup, labels, thread keys
        ├── monitor-onchar.ts   # Trigger prefix handling
        ├── probe.ts            # Health check
        ├── reactions.ts        # Emoji reactions
        ├── reconnect.ts        # Reconnection logic
        ├── send.ts             # Outbound messaging
        └── tools.ts            # Agent tools (fetch/download)

Security Notes

• No credentials are stored in the plugin source. All secrets come from openclaw.json config or environment variables.
• The insecure option uses a per-request HTTPS agent — it does NOT set the global NODE_TLS_REJECT_UNAUTHORIZED. Only Zulip connections are affected.
• For production, use proper TLS certificates (e.g., Let's Encrypt) instead of insecure: true.

Deploying Your Own Zulip Server

Don't have a Zulip server yet? See ZULIP_SERVER_DEPLOYMENT.md for a step-by-step guide to deploying Zulip on AWS EC2, including:

• Native install (not Docker — lessons learned the hard way)
• PostgreSQL version gotchas on ARM/Graviton
• SSL, SES email, authentication troubleshooting
• Production hardening checklist
• Cost breakdown (~$16-33/month)

License

MIT — see LICENSE.