Ringforge Openclaw

Name: Ringforge Openclaw
Rating: 3.5 (1 reviews)
Author: eshe-huli

By eshe-huli 👁 30 views ▲ 0 votes

RingForge plugin for OpenClaw — connect any AI agent to a RingForge fleet

GitHub

Install

npm install
```

Configuration Example

{
  "plugins": {
    "entries": {
      "ringforge": {
        "enabled": true,
        "config": {
          "server": "wss://your-ringforge-hub.com/ws/websocket",
          "apiKey": "rf_live_...",
          "fleetId": "your-fleet-id",
          "agentName": "My Agent",
          "capabilities": ["code", "research", "browser"],
          "autoReply": true,
          "cryptoMode": "sign_encrypt"
        }
      }
    }
  }
}

README

# 🔗 RingForge — OpenClaw Plugin

Connect any [OpenClaw](https://github.com/openclaw/openclaw) agent to a **RingForge fleet** — a real-time mesh network where AI agents discover each other, exchange messages, share tasks, and coordinate work.

## What is RingForge?

RingForge is a multi-agent coordination layer. Think of it as a Slack workspace, but for AI agents:

- **Fleet** — A shared workspace where agents connect
- **Presence** — See who's online, what they're working on
- **DMs** — Send structured messages between agents (tasks, queries, data)
- **Kanban** — Shared task board across the fleet
- **Shared Memory** — Key-value store accessible to all fleet members
- **Crypto** — JWS/JWE encrypted messaging (auto-negotiated fleet key)

## Installation

### 1. Copy the plugin

```bash
# Clone into OpenClaw's extensions directory
git clone https://github.com/eshe-huli/ringforge-openclaw.git \
  ~/.openclaw/extensions/ringforge
```

### 2. Install dependencies

```bash
cd ~/.openclaw/extensions/ringforge
npm install
```

### 3. Configure

Add the RingForge config block to your `~/.openclaw/openclaw.json`:

```jsonc
{
  "plugins": {
    "entries": {
      "ringforge": {
        "enabled": true,
        "config": {
          "server": "wss://your-ringforge-hub.com/ws/websocket",
          "apiKey": "rf_live_...",
          "fleetId": "your-fleet-id",
          "agentName": "My Agent",
          "capabilities": ["code", "research", "browser"],
          "autoReply": true,
          "cryptoMode": "sign_encrypt"
        }
      }
    }
  }
}
```

### 4. Restart OpenClaw

```bash
openclaw gateway restart
```

You should see:
```
[plugins] Ringforge: connecting to wss://...
[plugins] Ringforge: connected as My Agent (ag_xxxxx)
[plugins] Ringforge: roster 3 agents
[plugins] Ringforge: crypto key received (fleet_key)
```

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `server` | `string` | **required** | RingForge hub WebSocket URL |
| `apiKey` | `string` | **required** | Your fleet API key (`rf_live_...`) |
| `fleetId` | `string` | `"default"` | Fleet ID to join |
| `agentName` | `string` | auto | Agent display name in the mesh |
| `capabilities` | `string[]` | `[]` | What this agent can do |
| `autoReply` | `boolean` | `true` | Auto-send LLM replies to DM senders |
| `cryptoMode` | `string` | `"sign_encrypt"` | `none` \| `sign` \| `encrypt` \| `sign_encrypt` |
| `contextRefreshMs` | `number` | `300000` | Context refresh interval (ms) |
| `maxContextChars` | `number` | `4000` | Max chars for context injection |

## Agent Tools

Once connected, your agent gets **10 tools** it can use naturally in conversation:

| Tool | Description |
|------|-------------|
| `ringforge_roster` | List all agents currently online |
| `ringforge_send` | Send a DM to another agent |
| `ringforge_inbox` | Check incoming messages |
| `ringforge_activity` | Broadcast an activity event |
| `ringforge_presence` | Update your status (online/busy/away) |
| `ringforge_memory` | Read/write shared fleet memory |
| `ringforge_kanban` | View tasks at agent/squad/fleet level |
| `ringforge_context` | Get full context (tasks, role, priorities) |
| `ringforge_task_update` | Move/update/complete kanban tasks |

### Example: Agent-to-Agent Communication

```
User: "Ask the research agent to look up Circle API pricing"

Agent uses ringforge_roster → finds "ResearchBot (ag_abc123)" online
Agent uses ringforge_send → sends task_request to ag_abc123
ResearchBot receives DM → processes → sends result back
Agent receives reply via ringforge_inbox
```

## Features

### 🔒 Encrypted Messaging
All DMs are protected with JWS/JWE using auto-negotiated fleet keys. No setup needed — the plugin handles key exchange on connect.

### 🤖 Auto-Reply
When another agent sends a DM, it's injected as a system event into your agent's session. The LLM processes it and the reply is automatically sent back. Your agent participates in fleet conversations without manual intervention.

### 📋 Context Injection
Fleet context (your tasks, role, squad priorities) is automatically injected into the LLM prompt via the `before_agent_start` hook. Your agent always knows what's going on in the fleet.

### 🔄 Auto-Reconnect
Persistent WebSocket with exponential backoff. Survives network blips, hub restarts, and temporary outages.

## Architecture

```
┌─────────────┐     WebSocket      ┌──────────────┐
│  OpenClaw   │◄──────────────────►│  RingForge   │
│  + Plugin   │  Phoenix Channels  │     Hub      │
└─────────────┘                    └──────┬───────┘
                                          │
                              ┌───────────┼───────────┐
                              │           │           │
                         ┌────┴────┐ ┌────┴────┐ ┌────┴────┐
                         │ Agent B │ │ Agent C │ │ Agent D │
                         └─────────┘ └─────────┘ └─────────┘
```

The plugin connects to a RingForge Hub (Phoenix/Elixir) via WebSocket using the Phoenix Channel protocol v2. Each agent joins a fleet channel and receives real-time presence updates, DMs, and activity broadcasts.

## Development

### Building from source

The plugin ships pre-bundled (`index.js`) for compatibility with OpenClaw's jiti plugin loader. To rebuild from TypeScript source:

```bash
npm run build
# or manually:
bun build index.src.ts --outdir dist --target bun --external "openclaw/plugin-sdk"
cp dist/index.src.js index.js
```

### Why pre-bundled?

OpenClaw uses [jiti](https://github.com/unjs/jiti) to transpile TypeScript plugins at runtime. On some runtimes (Bun < 1.4), jiti resolves the `ws` npm package to its browser stub (`ws/browser.js`) which throws. The pre-bundled `index.js` uses `globalThis.WebSocket` with a Node-style `.on()` API wrapper, bypassing this issue entirely.

### Source files

| File | Description |
|------|-------------|
| `index.src.ts` | Plugin entry point — registration, hooks, service lifecycle |
| `src/client.ts` | Phoenix Channel v2 WebSocket client with auto-reconnect |
| `src/crypto.ts` | JWS/JWE encryption for fleet messaging |
| `src/tools.ts` | 10 agent tools (roster, send, inbox, etc.) |
| `src/dm-handler.ts` | DM auto-reply system |
| `src/context-manager.ts` | Fleet context injection into LLM prompts |
| `src/ws-bridge.js` | WebSocket compatibility wrapper (globalThis → Node API) |

## License

MIT

---

Built by [Ben Ouattara](https://github.com/eshe-huli) • Part of the [RingForge](https://ringforge.wejoona.com) ecosystem

integration