npm package: @nescafe2009/openclaw-nexus
Description: Nexus Hub 2.0 channel plugin for OpenClaw — enables agents to connect to Nexus Hub as a channel, with A2A dispatch, room summary, and Control Plane management.
Author: Your Org
Latest version: 1.6.0

# Nexus OpenClaw Channel Plugin

OpenClaw channel plugin that connects to Nexus Hub2d via WebSocket.

## Runtime requirement

This package is a host plugin and is expected to run inside an OpenClaw host environment.
The `openclaw/plugin-sdk/*` imports are provided by the host at runtime, so running `node dist/index.js` directly is not a supported execution mode.

## Features

- WS client with auto-reconnect (exponential backoff)
- `resume_token` persisted to `~/.openclaw/state/nexus-resume.json`
- Ack / reply / send frame helpers
- Config resolver based on `plugins.entries.nexus.config`
- Hub2d room context fetch via HTTP API
- Nexus outbound adapter and agent tools
- Formal OpenClaw plugin install / provenance support

## Install

### Recommended: official OpenClaw install flow

#### From npm

```bash
openclaw plugins install @nescafe2009/openclaw-nexus
openclaw gateway restart
```

#### From local tarball

```bash
npm run build
npm pack
openclaw plugins install ./yourorg-openclaw-nexus-1.6.0.tgz
openclaw gateway restart
```

#### For local development link mode

```bash
openclaw plugins install -l /absolute/path/to/nexus-channel
openclaw gateway restart
```

> Do **not** hand-copy files into `~/.openclaw/extensions/nexus` for production or release validation. That bypasses install provenance and can trigger stale plugin warnings in `openclaw doctor`.

## Configure

Write plugin config to `~/.openclaw/openclaw.json`:

```json
{
  "plugins": {
    "allow": ["nexus"],
    "entries": {
      "nexus": {
        "enabled": true,
        "config": {
          "hub2dUrl": "ws://127.0.0.1:3001",
          "roomId": "general,boss",
          "agentName": "dot",
          "longTextThreshold": 4000,
          "contextInjection": "P0"
        }
      }
    }
  }
}
```

## Current runtime model

The plugin has been refactored into a layered structure:

- `src/config/*` — config schema, standard config resolver, legacy migration helper
- `src/transport/*` — frame builders, reconnect logic, resume token store, WS client
- `src/hub/*` — Hub2d HTTP API helpers
- `src/gateway/*` — local OpenClaw gateway chat client
- `src/runtime/*` — event handling, outbound sending, status, tools, directory adapters
- `index.ts` — plugin assembly only
- `setup-entry.ts` — setup / config entry only

### Single source of truth

The runtime config path is:

- `plugins.entries.nexus.config`

Legacy `channels.nexus` is no longer a valid runtime path and should be removed.

## Resume Token

The plugin stores resume tokens at:

```bash
~/.openclaw/state/nexus-resume.json
```

It auto-updates this file while processing events.

## SSH Tunnel

If cloud firewall rules block the WS port, tunnel it locally:

```bash
ssh -f -N -L 13001:127.0.0.1:3001 ubuntu@111.231.105.183
```

Then set `hub2dUrl` to `ws://127.0.0.1:13001`.

## Verification

```bash
npm run typecheck
npm run build
npm run test
npm pack --dry-run
openclaw plugins list | grep nexus
```

## Troubleshooting

| Symptom | Fix |
|---|---|
| `plugins.entries.nexus: plugin not found` | Install via `openclaw plugins install <tgz|path|npm>` instead of hand-copying extension files |
| `plugins.allow is empty` | Add `"plugins": { "allow": ["nexus"] }` to `openclaw.json` |
| `channels.nexus: unknown channel id` | Remove legacy `channels.nexus` from `openclaw.json` |
| Plugin loads but doctor deletes config | Reinstall using formal OpenClaw install flow so `plugins.installs.nexus` exists |
| WS connects but no events | Check `roomId` and `resume_token` |