@chatvia/openclaw-channel

Talk to your self-hosted OpenClaw agent from ChatVia.

Your agent shows up in ChatVia as an ordinary contact. You message it, it answers. The agent runs on your machine — ChatVia runs no model and pays for no tokens.

Setup

Two steps.

1. Set the agent up in ChatVia. Settings → Agents → Set up my agent. It walks you through it and gives you a short code like CVA-7K2M-94QP, good for 15 minutes.

2. Install and paste.

openclaw plugins install @chatvia/openclaw-channel
openclaw chatvia pair CVA-XXXX-XXXX   # the code from Settings -> Agents

Nothing prompts you for the code -- you hand it to pair. (openclaw chatvia on its own only prints help; an earlier version of this README claimed it would ask, which sent people looking for a prompt that does not exist.)

Check it worked with openclaw chatvia status.

That is it. The setup screen notices the moment the agent connects, and its chat appears in your ChatVia sidebar.

The code is single use: it is traded for a long-lived token on first connect, and that token is what gets saved. If a code expires before you use it, make another — they cost nothing.

Configuration

{
  "channels": {
    "chatvia": {
      "token": "cva_…",
      "serverUrl": "wss://api.chatvia.in",
      "allowFrom": []
    }
  }
}

• token — the pairing code from Settings → Agents, or a long-lived cva_… token. Required. A code is swapped for a token on first connect.
• serverUrl — override only for self-hosted or local development.
• allowFrom — optional extra allowlist of ChatVia user ids. ChatVia already enforces who may reach your agent (you, plus anyone you granted), so leaving this empty is the normal case, not an open door.

How it connects

The plugin dials out over TLS and holds the connection. There is no webhook and no inbound port, because OpenClaw runs on a personal machine with no public URL. Nothing needs forwarding and nothing needs a tunnel.

It carries no crypto. ChatVia encrypts and decrypts server-side for agents, so the message key never leaves the server and never lands on your machine.

What your agent may and may not do

ChatVia enforces all of this server-side, so a stolen token is bounded:

| | | |---|---| | Reply in a chat it is already in | yes | | Message you first | yes — 6 per hour, and you can switch it off | | Message anyone else first | no — the frame has no recipient field | | Post in a group unprompted | no — only within 10 minutes of an @-mention | | Read your chat history | no — it only sees messages sent while connected | | Change your profile, or delete anything | no |

If you revoke the token in Settings → Agents, the agent stops immediately. Being suspended or banned revokes it too.

Troubleshooting

"gateway port 18789 is still busy before restart"

Your agent is almost certainly fine. Check ChatVia first — if the agent shows as connected, the pairing worked and you can ignore this. Only the restart step failed, and a restart is not needed after a fresh install.

If you do need to restart it, the usual cause on Windows is WSL. WSL mirrors local ports into its virtual machine, and that mirror keeps hold of port 18789 even after OpenClaw stops, so the restart gives up waiting for the port. Run:

wsl --shutdown

then retry. If you would rather leave WSL alone, put OpenClaw on another port:

openclaw gateway --port 18790

A port has a separate IPv4 and IPv6 side. OpenClaw's gateway binds the IPv4 one (127.0.0.1:18789); WSL's relay, wslrelay.exe, binds the IPv6 one ([::1]:18789). OpenClaw lists busy ports with netstat -ano -p TCP, which reports IPv4 only — so it cannot see the WSL listener, cannot name it in the error, and cannot stop it. It just waits for a port that never frees.

Confirm it with:

netstat -ano | findstr 18789

Two LISTENING rows — one 127.0.0.1, one [::1] owned by a different PID — is this exact case. wsl --shutdown releases the second one.

Development

npm install
npm test

The tests run against a stub gateway and pin the wire protocol, the reconnect cursor, the pairing-code exchange, and the "do not retry a revoked token" rule. They do not prove integration with a real OpenClaw runtime — that needs OpenClaw installed and is a manual check.

Runs straight from TypeScript source with no build step, so the code avoids syntax Node's type-stripping cannot handle (notably constructor parameter properties).