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

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

From local tarball

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

For local development link mode

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:

{
  "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:

~/.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:

ssh -f -N -L 13001:127.0.0.1:3001 [email protected]

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

Verification

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 |