openclaw-magnus

OpenClaw channel plugin for Magnus — connects your AI agent to Magnus platform conversations via WebSocket.

Prerequisites

• OpenClaw ≥ 2026.2.9
• A running Magnus instance

Installation

Interactive wizard (recommended):

npx openclaw-magnus install

The wizard will install the plugin, prompt for credentials, and optionally install the Magnus Python SDK and skill.

Manual install:

openclaw plugins install openclaw-magnus

Configuration

In the Magnus web UI, go to People → Recruit, create a new Agent, and select OpenClaw as the connector. The credentials dialog displays the exact commands to run:

openclaw config set channels.magnus.appSecret "your-app-secret"
openclaw config set channels.magnus.magnusUrl  "https://your-magnus-server"

| Field | Required | Description | | ------------ | :------: | ---------------------------------------------------- | | appSecret | ✓ | Bot credential from Magnus People page | | magnusUrl | ✓ | Base URL of your Magnus instance (no trailing slash) | | name | | Display name for this account | | enabled | | Set to false to disable without removing config |

Multi-account

To run multiple bots or connect to multiple Magnus instances:

{
  channels: {
    magnus: {
      accounts: {
        work: {
          appSecret: "secret-a",
          magnusUrl: "https://magnus.work.example.com",
        },
        personal: {
          appSecret: "secret-b",
          magnusUrl: "https://magnus.home.example.com",
        },
      },
    },
  },
}

Usage

openclaw start

The bot will connect to Magnus and start handling messages in any conversation it has been added to.

How It Works

The plugin establishes a persistent WebSocket connection to Magnus (/ws/chat?app_secret=...). When a message arrives, it is routed to the configured OpenClaw agent. The agent's reply is chunked if needed and sent back to the same conversation.

• Reconnection — exponential backoff with jitter (1 s base, 60 s cap)
• Heartbeat — ping every 25 s, reconnects on missed pong
• Self-message filtering — bot echo suppressed automatically
• Deduplication — 30-minute sliding window prevents double-processing

Repository Structure

openclaw-magnus/
├── src/          # Plugin source (channel, ws-client, bot, types)
├── bin/
│   └── install.mjs   # Interactive install wizard
└── index.ts      # Plugin entry point