122 lines
3.9 KiB
Markdown
122 lines
3.9 KiB
Markdown
# Hermes — OpenClaw Web Interface
|
|
|
|
**Prod:** `https://chat.jqxp.org` · `wss://chat.jqxp.org/ws`
|
|
**Dev:** `https://dev.jqxp.org`
|
|
|
|
---
|
|
|
|
## Stack
|
|
|
|
```
|
|
hermes/
|
|
backend/ Bun + TypeScript :3001 prod / :3003 dev
|
|
frontend/ Vue 3 + Vite :8443 dev / jqxp.org prod (static)
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Browser(s)
|
|
│ WebSocket /ws + HTTP /api/*
|
|
▼
|
|
server.ts (Bun.serve)
|
|
├── auth.ts token → user, session tokens
|
|
├── gateway.ts upstream WS → openclaw gateway :18789
|
|
├── session-sm.ts per-connection state machine
|
|
├── session-watcher.ts JSONL tail → WS events
|
|
├── hud-builder.ts HUD event factory, result builders, path helpers
|
|
├── message-filter.ts strip sensitive values from tool output
|
|
└── mcp/ MCP Streamable HTTP server
|
|
├── index.ts auth, routing, key management
|
|
├── dev.ts health, subscribe, push_state tools
|
|
├── events.ts in-memory event queue + long-poll
|
|
├── system.ts start/stop/restart/deploy tools
|
|
└── fs.ts remote file read/write/edit/grep
|
|
```
|
|
|
|
See [backend/README.md](backend/README.md) and [frontend/README.md](frontend/README.md) for details.
|
|
|
|
## Dev
|
|
|
|
### On openclaw VM (tmux sessions)
|
|
|
|
```bash
|
|
# Backend (auto-restarts on file change)
|
|
cd hermes/backend
|
|
PORT=3003 ~/.bun/bin/bun --watch run server.ts # tmux: hermes-bun
|
|
|
|
# Frontend (Vite HMR)
|
|
cd hermes/frontend
|
|
bun run dev # tmux: webchat-vite → :8443
|
|
```
|
|
|
|
### From Titan host (Claude Code workspace)
|
|
|
|
Local mirror: `D:/ClaudeCode/Titan/Openclaw/` ↔ `~/.openclaw/` on openclaw VM.
|
|
|
|
```bash
|
|
# Pull entire project
|
|
rsync -avz --exclude='node_modules' --exclude='dist' --exclude='.git' \
|
|
openclaw:~/.openclaw/workspace-titan/projects/hermes/ \
|
|
/d/ClaudeCode/Titan/Openclaw/workspace-titan/projects/hermes/
|
|
|
|
# Edit locally with Claude Code (Read/Edit tools — no shell escaping issues)
|
|
|
|
# Push backend (bun --watch auto-restarts)
|
|
rsync -avz --exclude='node_modules' --exclude='dist' --exclude='.git' \
|
|
/d/ClaudeCode/Titan/Openclaw/workspace-titan/projects/hermes/backend/ \
|
|
openclaw:~/.openclaw/workspace-titan/projects/hermes/backend/
|
|
|
|
# Push frontend (Vite HMR picks up instantly)
|
|
rsync -avz --exclude='node_modules' --exclude='dist' --exclude='.git' \
|
|
/d/ClaudeCode/Titan/Openclaw/workspace-titan/projects/hermes/frontend/ \
|
|
openclaw:~/.openclaw/workspace-titan/projects/hermes/frontend/
|
|
```
|
|
|
|
## Deploy
|
|
|
|
```bash
|
|
# Frontend → static hosting
|
|
cd hermes/frontend && npm run build
|
|
rsync -avz --delete dist/ u116526981@access1007204406.webspace-data.io:~/jqxp/
|
|
|
|
# Backend prod restart
|
|
sudo systemctl restart openclaw-web-gateway.service
|
|
curl https://chat.jqxp.org/health
|
|
```
|
|
|
|
## Ports
|
|
|
|
```
|
|
:3001 prod backend systemd: openclaw-web-gateway.service
|
|
:3003 dev backend tmux: hermes-bun
|
|
:8443 dev frontend tmux: webchat-vite
|
|
```
|
|
|
|
## Network
|
|
|
|
```
|
|
Browser → Cloudflare Tunnel → RouterVM → OpenClaw VM :3001 → gateway :18789
|
|
```
|
|
|
|
## Features (0.6.42)
|
|
|
|
- Multi-modal chat: text, images, PDFs, audio recording
|
|
- Audio STT via ElevenLabs Scribe v2 (mic → transcript → agent)
|
|
- TTS via ElevenLabs (speaker icon on assistant messages, player bar)
|
|
- Permanent sidebar rail with overlay expand, responsive
|
|
- Previous session history (server-fetched, load more)
|
|
- MCP server with 36+ tools (fs, system, deck, dev, takeover)
|
|
- Real-time MCP event loop (dev_subscribe + dev_push_state)
|
|
- Interactive dev tools: counter game, action picker, confetti
|
|
- Automated test runner via Nextcloud Deck + takeover bridge
|
|
- WebGL particle background (theme-aware)
|
|
- Deploy to prod via MCP (system_deploy_prod)
|
|
|
|
## Open
|
|
|
|
- [ ] Token management (tokens hardcoded in auth.ts)
|
|
- [ ] Room mode (shared session, multiple users)
|
|
- [ ] User message lifecycle (msgId-based updates, dedup)
|
|
- [ ] Rename project/domain
|