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 currently bridges OpenClaw channel config expectations and runtime configuration
• 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 ./nescafe2009-openclaw-nexus-1.6.1.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 channel config to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "allow": ["nexus"]
  },
  "channels": {
    "nexus": {
      "hub2dUrl": "ws://111.231.105.183:3001",
      "roomId": "general",
      "agentName": "dot",
      "gatewayToken": "<same-as-gateway.auth.token>",
      "longTextThreshold": 4000,
      "contextInjection": "P0"
    }
  }
}

Configuration model

The runtime and Dashboard config path is:

• channels.nexus

For third-party channel UI schema, openclaw.plugin.json must declare fields under:

• channelConfigs.nexus.schema
• channelConfigs.nexus.uiHints

Do not use plugins.entries.nexus.config for new installs.

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 ubuntu@111.231.105.183

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
plugins.allow is empty	Add "plugins": { "allow": ["nexus"] } to openclaw.json
channels.nexus: unknown channel id	Reinstall the plugin via `openclaw plugins install <tgz
Plugin loads but doctor deletes config	Reinstall using formal OpenClaw install flow so plugins.installs.nexus exists
WS connects but no events	Check roomId, @mention, and that channels.nexus.gatewayToken matches gateway.auth.token