172 lines
4.6 KiB
Markdown
172 lines
4.6 KiB
Markdown
# Yonexus
|
|
|
|
Yonexus is a cross-instance communication system for OpenClaw built as **three separate repositories**:
|
|
|
|
| Repository | Role |
|
|
|---|---|
|
|
| `Yonexus` | Umbrella — architecture, planning, and coordination |
|
|
| `Yonexus.Server` | Central hub plugin — accepts client connections, handles pairing/authentication |
|
|
| `Yonexus.Client` | Client plugin — connects to server, manages local identity |
|
|
| `Yonexus.Protocol` | Shared protocol specification — referenced as a submodule by both Server and Client |
|
|
|
|
## Overview
|
|
|
|
### Yonexus.Server
|
|
Installed on the central OpenClaw instance.
|
|
|
|
Responsibilities:
|
|
- run the WebSocket server
|
|
- maintain the client registry
|
|
- handle pairing and authentication
|
|
- track heartbeat and liveness state
|
|
- relay messages to connected clients
|
|
- rewrite inbound client messages before rule dispatch
|
|
- notify a human administrator of pairing requests via Discord DM
|
|
|
|
### Yonexus.Client
|
|
Installed on follower OpenClaw instances.
|
|
|
|
Responsibilities:
|
|
- connect to `Yonexus.Server`
|
|
- manage local keypair and shared secret
|
|
- complete pairing with out-of-band pairing code
|
|
- authenticate on reconnect
|
|
- send periodic heartbeat
|
|
- send messages to server
|
|
- receive messages from server via rule dispatch
|
|
|
|
### Yonexus.Protocol
|
|
Shared protocol specification repository. Both `Yonexus.Server` and `Yonexus.Client` reference this as a submodule at `protocol/`.
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
Yonexus (umbrella)
|
|
├── Yonexus.Protocol ← shared protocol submodule
|
|
├── Yonexus.Server ← server plugin submodule
|
|
│ └── protocol/ ← points to Yonexus.Protocol
|
|
└── Yonexus.Client ← client plugin submodule
|
|
└── protocol/ ← points to Yonexus.Protocol
|
|
```
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
A Yonexus network contains:
|
|
- exactly one OpenClaw instance running `Yonexus.Server`
|
|
- one or more OpenClaw instances running `Yonexus.Client`
|
|
|
|
Topology rules:
|
|
- `Yonexus.Server` must be reachable via a stable address
|
|
- `Yonexus.Client` instances connect outbound to the server
|
|
- direct client-to-client sockets are not required in v1
|
|
- client-to-client communication, if needed, is relayed by the server
|
|
|
|
---
|
|
|
|
## Security Model
|
|
|
|
Pairing is intentionally **out-of-band**.
|
|
|
|
When a new client needs pairing:
|
|
- the server generates a pairing code
|
|
- the server sends that pairing code by Discord DM to a configured human admin
|
|
- the pairing code is **not** sent over the Yonexus WebSocket connection
|
|
- the human relays the code to the client side manually
|
|
- the client submits the code back through the protocol
|
|
|
|
After pairing:
|
|
- the server issues a shared secret
|
|
- the client stores its private key and secret locally
|
|
- reconnect authentication uses signed proof derived from `secret + nonce + timestamp`
|
|
|
|
---
|
|
|
|
## Current Repository Spec Files
|
|
|
|
### Umbrella (`Yonexus`)
|
|
- `PLAN.md` — project plan and architecture
|
|
- `ARCHITECTURE.md` — architecture overview and repository graph
|
|
- `FEAT.md` — implementation feature checklist
|
|
|
|
### Protocol (`Yonexus.Protocol`)
|
|
- `PROTOCOL.md` — shared communication protocol specification
|
|
|
|
### Server (`Yonexus.Server`)
|
|
- `PLAN.md` — server-specific implementation plan
|
|
- `protocol/` — submodule pointing to `Yonexus.Protocol`
|
|
|
|
### Client (`Yonexus.Client`)
|
|
- `PLAN.md` — client-specific implementation plan
|
|
- `protocol/` — submodule pointing to `Yonexus.Protocol`
|
|
|
|
---
|
|
|
|
## Planned TypeScript APIs
|
|
|
|
### Yonexus.Server
|
|
```ts
|
|
sendMessageToClient(identifier: string, message: string): Promise<void>
|
|
registerRule(rule: string, processor: (message: string) => unknown): void
|
|
```
|
|
|
|
### Yonexus.Client
|
|
```ts
|
|
sendMessageToServer(message: string): Promise<void>
|
|
registerRule(rule: string, processor: (message: string) => unknown): void
|
|
```
|
|
|
|
Message format:
|
|
```text
|
|
${rule_identifier}::${message_content}
|
|
```
|
|
|
|
Reserved rule: `builtin`
|
|
|
|
---
|
|
|
|
## Planned Server Config
|
|
|
|
```json
|
|
{
|
|
"followerIdentifiers": ["client-a", "client-b"],
|
|
"notifyBotToken": "<discord-bot-token>",
|
|
"adminUserId": "123456789012345678",
|
|
"listenHost": "0.0.0.0",
|
|
"listenPort": 8787,
|
|
"publicWsUrl": "wss://example.com/yonexus"
|
|
}
|
|
```
|
|
|
|
## Planned Client Config
|
|
|
|
```json
|
|
{
|
|
"mainHost": "wss://example.com/yonexus",
|
|
"identifier": "client-a",
|
|
"notifyBotToken": "<discord-bot-token>",
|
|
"adminUserId": "123456789012345678"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Status
|
|
|
|
- planning/specification stage
|
|
- split-plugin architecture defined
|
|
- protocol draft defined in `Yonexus.Protocol`
|
|
- implementation not started yet
|
|
|
|
---
|
|
|
|
## Repository URLs
|
|
|
|
- [Yonexus (umbrella)](https://git.hangman-lab.top/nav/Yonexus)
|
|
- [Yonexus.Server](https://git.hangman-lab.top/nav/Yonexus.Server)
|
|
- [Yonexus.Client](https://git.hangman-lab.top/nav/Yonexus.Client)
|
|
- [Yonexus.Protocol](https://git.hangman-lab.top/nav/Yonexus.Protocol)
|