mirror of
https://github.com/dtzp555-max/odo.git
synced 2026-07-19 09:44:37 +00:00
taodeng
a1e7e66ae1
- Electron main process with tray icon and IPC setup - openclaw-manager.js server bridge - Architecture design document (ODO_ARCHITECTURE.md) - preload.js for renderer context bridge
26 KiB
26 KiB
ODO — OpenClaw Dashboard Orchestrator
Architecture Design Document
Version: Draft 1.0 Date: 2026-03-18 Status: Proposal — pending review
1. Product Overview
What is ODO?
ODO is the desktop app evolution of OCM (OpenClaw Manager). It is a cross-platform Electron application that lets users manage one or more OpenClaw instances — local or remote — from a single window.
One-line pitch
"Double-click to manage all your OpenClaw agents, on this machine or any other."
Who is ODO for?
- People already running OpenClaw who want visual control instead of hand-editing JSON
- People running OpenClaw on multiple machines (home server, VPS, NAS) who want one place to manage them all
- Power users who still want a built-in CLI but prefer a desktop app over a browser tab
Who is ODO not for?
- People who have never installed OpenClaw (ODO is not an installer)
- People who want a chat UI for talking to agents (that's ClawX / ClawUI territory)
- People who want a cloud-hosted SaaS dashboard
2. Competitive Positioning
| Product | Type | Focus | Weakness (ODO's opportunity) |
|---|---|---|---|
| ClawX | Desktop (Electron) | Chat client, talking to agents | No ops/config management |
| ClawUI | Desktop (Electron) | Chat + session inspection | No backup, no multi-instance |
| TenacitOS | Web dashboard | Cost analytics, monitoring | Web-only, no desktop, no remote |
| ClawBoard | Web dashboard | Agent management | Web-only, local only |
| VidClaw | Web dashboard | Kanban + file editing | Local only, no remote |
| Claworc | Web platform | Enterprise multi-instance | Requires Docker/K8s, overkill for individuals |
| ODO | Desktop (Electron) | Ops control + remote management | — |
ODO's unique value
- Multi-instance: manage local + remote OpenClaw from one window
- Ops-first: backup/restore, health, logs, gateway control — not just monitoring
- Configuration editor: visual tool/plugin management instead of JSON editing
- Disaster recovery: versioned config snapshots + remote backup
3. Feature Specification
3.1 Core Features (daily use)
Dashboard
- System health: CPU, RAM, disk gauges
- Gateway status: running/stopped, PID, uptime
- Agent overview: count, last activity, binding summary
- Quick actions: restart gateway, open logs
- Auto-refresh toggle (10s interval)
- NEW: Connection selector — switch between local and remote instances
Agents Console
- Agent tree: visual hierarchy of main agents and sub-agents
- Per-agent details: bound channels/groups/threads, model, workspace path
- Inline model switching (dropdown, save without rebuild)
- Workspace file browser: view and edit SOUL.md, MEMORY.md, config files
- EVOLVED: De-emphasize "Add Sub-Agent" wizard. The main use case is now:
- View current agent structure (read-heavy)
- Manually adjust model, tools, plugins per agent
- Edit personality/memory files
- Agent creation still available but no longer the hero flow
Stats (Token Cost Monitor)
- Parse session JSONL files for real token usage
- Breakdown: by model, by agent, by day
- Visual charts: daily bar chart, model pie chart
- Time range filter: 1d / 7d / 30d / 90d
- Custom model pricing (stored in local config)
- Borrow from TenacitOS: trend lines, cost prediction
3.2 Professional Features (when needed)
CLI Terminal
- Full-width terminal panel, expandable from bottom dock
- Real-time streaming output (chunked HTTP)
- Tab completion: OpenClaw subcommands + history + presets
- Saved favorites (user-defined frequent commands)
- Preset command library (15+ common operations)
- Keep as-is: this is a differentiator, power users love it
Log Viewer (NEW)
- Real-time gateway log streaming (tail -f style)
- Log level filter: ERROR / WARN / INFO / DEBUG
- Text search within logs
- Auto-scroll with pause-on-scroll
- Timestamp display (Brisbane timezone or user preference)
- Log file selector (gateway.log, agent session logs)
- Export / copy selected log range
Backup & Recovery
- Local backup: one-click snapshot of openclaw.json + agent configs to a local directory
- Remote backup: SFTP/SCP to a remote server (simplified from OCM's NAS module)
- Host, port, username, auth (password or SSH key)
- One-click test connection
- One-click backup now
- Scheduled backup (daily, via system scheduler integration)
- Config version history: every config change creates a timestamped snapshot
- Version list with diff view (before/after comparison)
- One-click rollback to any version
- Auto-cleanup: keep last 50 versions, older ones auto-pruned
- Remote backup simplification vs OCM:
- Remove: old NAS CBC cipher compatibility (too niche)
- Remove: SSH key generation UI (users should manage keys externally)
- Keep: password auth, key auth, test connection, backup now, scheduled backup
- Add: backup to any SSH-accessible server (not just NAS)
Routing (formerly Channels)
- View all channel bindings grouped by agent
- Expand/collapse per agent
- Add/remove bindings
- Support: Telegram groups, Discord channels/threads
- Agent filter (all agents / specific agent)
Models & Auth
- Primary model selector (from
openclaw models list) - Fallback chain editor
- Provider auth status overview
- Auth setup guides per provider (click-to-copy CLI commands)
3.3 Desktop App Capabilities (NEW)
System Tray
- App icon in system tray (macOS menu bar / Windows system tray / Linux indicator)
- Closing the window minimizes to tray (does not quit)
- Tray menu: Show Window, Gateway Status, Restart Gateway, Quit
- Status indicator: green dot (healthy) / red dot (gateway down)
Gateway Lifecycle Management
- On app launch: auto-start local OpenClaw gateway if not already running
- On app quit: optionally stop gateway (user preference)
- Gateway crash detection: notification + one-click restart
- Option: "Keep gateway running after ODO closes" (for server use)
Auto-Start
- Option to launch ODO on system login
- Uses: macOS Login Items / Windows Registry / Linux autostart
Auto-Update
- Check for updates on launch (GitHub Releases)
- Download + install in background
- Notification: "Update available — restart to apply"
- Uses: electron-updater
Multi-Instance Connection Manager (NEW — key differentiator)
- Connection list: save multiple OpenClaw instances
- Name (e.g., "Home Server", "VPS", "Local")
- Type: Local (filesystem) or Remote (WebSocket)
- For remote: host, port (18789), auth token
- Connection status indicator
- Switch between instances from the top bar
- All features work identically for local and remote instances
- Remote protocol: OpenClaw Gateway WebSocket API
- Connection security: token auth, optional SSH tunnel instructions
4. Technical Architecture
4.1 Stack
| Layer | Technology | Rationale |
|---|---|---|
| Desktop shell | Electron 33+ | Cross-platform, mature, largest ecosystem |
| Frontend | React 19 + TypeScript | Component-based, maintainable, huge community |
| UI framework | Tailwind CSS 4 | Utility-first, fast iteration, no custom CSS sprawl |
| Charts | Recharts | React-native charting, lightweight |
| Build tool | Vite | Fast dev server, HMR, clean builds |
| Packaging | electron-builder | .dmg / .exe / .AppImage in one command |
| Auto-update | electron-updater | GitHub Releases integration |
| Backend (main process) | Node.js (Electron built-in) | Reuse OCM server logic |
4.2 Process Architecture
┌──────────────────────────────────────────────┐
│ Electron │
│ │
│ ┌──────────────────┐ ┌───────────────────┐ │
│ │ Main Process │ │ Renderer Process │ │
│ │ (Node.js) │ │ (React App) │ │
│ │ │ │ │ │
│ │ - HTTP Server │◄─┤ - Dashboard │ │
│ │ - File I/O │ │ - Agents Console │ │
│ │ - child_process │ │ - Stats │ │
│ │ - Gateway mgmt │ │ - CLI Terminal │ │
│ │ - Backup engine │ │ - Log Viewer │ │
│ │ - Remote connect │ │ - Backup UI │ │
│ │ - System tray │ │ - Settings │ │
│ │ │ │ │ │
│ │ IPC Bridge ──────┤──┤── IPC Bridge │ │
│ └──────────────────┘ └───────────────────┘ │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ OpenClaw Gateway (child process or remote)│ │
│ └──────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
Main Process handles:
- All filesystem operations (read/write openclaw.json, logs, backups)
- Spawning OpenClaw CLI commands
- Gateway process lifecycle
- Remote WebSocket connections to other OpenClaw instances
- System tray management
- Auto-update checks
Renderer Process handles:
- All UI rendering (React components)
- User interactions
- Communicates with Main Process via Electron IPC
Why keep the HTTP server?
The existing OCM API layer (GET /api/dashboard, POST /api/agents, etc.) is well-tested. Rather than rewriting everything as IPC handlers from scratch, we wrap the existing HTTP API in the main process and call it from the renderer. This lets us:
- Reuse all existing backend logic
- Add IPC gradually (replace HTTP calls with IPC one module at a time)
- Keep the option of remote web access (start HTTP server on a port for LAN access)
4.3 IPC Communication
Renderer (React) Main Process (Node.js)
│ │
│── ipcRenderer.invoke('api', { │
│ method: 'GET', │
│ path: '/api/dashboard' │
│ }) │
│ │
│◄── { status: 200, data: {...} } ─────│
│ │
│── ipcRenderer.invoke('gateway', │
│ { action: 'restart' }) │
│ │
│◄── { ok: true, pid: 12345 } ────────│
IPC channels:
api— proxy to internal HTTP API (backward compatible with OCM)gateway— gateway lifecycle (start/stop/restart/status)backup— backup operations (snapshot/restore/remote-push)connection— remote instance management (connect/disconnect/list)system— app-level (auto-update, tray, preferences)cli— terminal command execution with streaming outputlogs— log file streaming (subscribe/unsubscribe)
4.4 Remote Connection Architecture
┌─────────────────┐ ┌──────────────────────────┐
│ ODO (Desktop) │ │ Remote Machine │
│ │ │ │
│ Connection Mgr │◄──WSS──┤ OpenClaw Gateway │
│ │ │ :18789│ (ws://127.0.0.1:18789) │
│ └─► Dashboard │ │ │
│ └─► Agents │ │ Accessed via: │
│ └─► Stats │ │ - Direct LAN/Tailscale │
│ └─► Logs │ │ - SSH tunnel │
│ │ │ │
└─────────────────┘ └──────────────────────────┘
For remote instances:
- ODO connects to the Gateway WebSocket API directly
- Auth: token-based (
gateway.remote.token) - Features available remotely: Dashboard, Agents (read), Stats, Logs, CLI (commands proxied)
- Features local-only: Backup to local disk, Gateway process management
5. Project Structure
odo/
├── package.json
├── electron-builder.yml # Build/packaging config
├── vite.config.ts # Vite config for renderer
├── tsconfig.json
│
├── src/
│ ├── main/ # Electron main process
│ │ ├── index.ts # App entry, window creation, tray
│ │ ├── ipc/ # IPC handlers
│ │ │ ├── api.ts # HTTP API proxy (from OCM)
│ │ │ ├── gateway.ts # Gateway lifecycle
│ │ │ ├── backup.ts # Backup engine
│ │ │ ├── connection.ts # Remote instance manager
│ │ │ ├── cli.ts # CLI command runner
│ │ │ └── logs.ts # Log streaming
│ │ ├── server/ # Migrated OCM backend
│ │ │ ├── api-routes.ts # All /api/* handlers
│ │ │ ├── openclaw-config.ts # openclaw.json reader/writer
│ │ │ ├── stats-parser.ts # Session JSONL parser
│ │ │ └── health.ts # openclaw doctor wrapper
│ │ ├── services/
│ │ │ ├── tray.ts # System tray
│ │ │ ├── auto-update.ts # electron-updater
│ │ │ ├── auto-launch.ts # Login item registration
│ │ │ └── gateway-manager.ts # Start/stop/monitor gateway
│ │ └── utils/
│ │ ├── paths.ts # OS-specific path resolution
│ │ ├── timestamp.ts # Brisbane timezone helper
│ │ └── backup-utils.ts # Snapshot/restore helpers
│ │
│ ├── renderer/ # React frontend
│ │ ├── index.html
│ │ ├── main.tsx # React entry
│ │ ├── App.tsx # Root component, routing
│ │ ├── api/ # IPC client wrappers
│ │ │ └── client.ts # invoke('api', ...) helper
│ │ ├── components/ # Shared UI components
│ │ │ ├── Layout.tsx # App shell: sidebar + header + main
│ │ │ ├── Sidebar.tsx # Navigation
│ │ │ ├── ConnectionPicker.tsx # Instance switcher (top bar)
│ │ │ ├── StatusBadge.tsx
│ │ │ └── Toast.tsx
│ │ ├── pages/
│ │ │ ├── Dashboard.tsx
│ │ │ ├── Agents.tsx
│ │ │ ├── Stats.tsx
│ │ │ ├── Logs.tsx # NEW
│ │ │ ├── CLI.tsx
│ │ │ ├── Routing.tsx
│ │ │ ├── ModelsAuth.tsx
│ │ │ ├── Backup.tsx
│ │ │ └── Settings.tsx # NEW: preferences, connections, auto-start
│ │ ├── hooks/
│ │ │ ├── useApi.ts # Data fetching hook
│ │ │ ├── useGateway.ts # Gateway status hook
│ │ │ └── useConnection.ts # Active connection hook
│ │ └── styles/
│ │ └── globals.css # Tailwind imports + dark theme vars
│ │
│ ├── shared/ # Types shared between main & renderer
│ │ ├── types.ts
│ │ └── constants.ts
│ │
│ └── preload/
│ └── index.ts # Electron preload script (IPC bridge)
│
├── resources/ # App icons, installer assets
│ ├── icon.icns # macOS
│ ├── icon.ico # Windows
│ └── icon.png # Linux
│
├── scripts/
│ └── migrate-ocm.ts # Helper: extract API logic from OCM single file
│
└── legacy/
└── openclaw-manager.js # Original OCM for reference during migration
6. UI Design Direction
Layout
┌──────────────────────────────────────────────────────┐
│ [ODO icon] [Connection: Local ▾] [🔴 Gateway] │
├────────┬─────────────────────────────────────────────┤
│ │ │
│ 🏠 │ Main Content Area │
│ Dashboard │
│ │ (selected page renders here) │
│ 🤖 │ │
│ Agents│ │
│ │ │
│ 📊 │ │
│ Stats │ │
│ │ │
│ 📋 │ │
│ Logs │ │
│ │ │
│ ⚙️ │ │
│ Routing │
│ │ │
│ 🔑 │ │
│ Auth │ │
│ │ │
│ 💾 │ │
│ Backup│ │
│ │ │
│ ⚙️ │ │
│ Settings │
│ │ │
├────────┴─────────────────────────────────────────────┤
│ [> _] CLI Terminal (expandable dock) │
└──────────────────────────────────────────────────────┘
Design principles
- Dark theme default — inherit OCM's dark palette (#0f1117 bg, #6c63ff accent)
- Sidebar navigation — always visible, icon + label, collapsible on narrow windows
- Top bar — connection picker (local/remote), gateway status badge
- Bottom dock — CLI terminal, click to expand, drag to resize
- Dense but readable — avoid excessive whitespace, show more data per screen
- No page reloads — SPA with client-side routing
7. Migration Strategy
Phase 0: Scaffolding (Week 1)
Goal: Empty Electron app that opens a window
- Initialize project:
npm create electron-vite@latest - Set up: TypeScript, React, Tailwind, Vite
- Create window with app shell (sidebar + empty main area)
- System tray with Quit option
- Build and package for macOS (.dmg)
- Verify: double-click .dmg → install → double-click app → window opens
Phase 1: Dashboard + Gateway (Week 2)
Goal: See system health and control gateway
- Migrate OCM's
/api/dashboardlogic to main process - Build Dashboard page (React): gauges, system info, gateway status
- IPC: gateway start/stop/restart
- Auto-start gateway on app launch
- Connection to local OpenClaw directory (auto-detect or setup wizard)
Phase 2: Agents + Workspace (Week 3)
Goal: View and configure agents
- Migrate OCM's agent tree rendering to React components
- Agent tree: collapsible, grouped by parent
- Per-agent: model selector, binding overview
- Workspace file browser: list files, view content, edit and save
- Migrate:
/api/agents,/api/workspaceendpoints
Phase 3: Stats + Logs (Week 4)
Goal: Monitor costs and debug issues
- Migrate OCM's stats parser (session JSONL)
- Stats page: charts (Recharts), filters, model breakdown
- NEW: Log viewer page
- Stream gateway.log via IPC
- Level filter, text search, auto-scroll
- Agent session log selector
Phase 4: CLI + Routing + Auth (Week 5)
Goal: Power user tools
- CLI terminal: command input, streaming output, tab completion, presets
- Routing page: binding list, add/remove, agent filter
- Models & Auth page: model selector, fallback chain, provider guides
Phase 5: Backup & Recovery (Week 6)
Goal: Disaster recovery
- Config version history: auto-snapshot on every change, diff viewer
- One-click rollback
- Local backup to user-specified directory
- Remote backup: SFTP/SCP with simplified setup
- Connection form: host, port, user, auth method, remote path
- Test connection, backup now, schedule (daily)
- Scheduled backup via OS scheduler (cron on macOS/Linux, Task Scheduler on Windows)
Phase 6: Remote Management (Week 7-8)
Goal: Manage OpenClaw on other machines
- Connection manager: add/edit/remove remote instances
- WebSocket client for OpenClaw Gateway API
- Auth: token-based
- Adapt all pages to work with remote data source
- Connection picker in top bar
- Handle disconnection gracefully (retry, notification)
Phase 7: Polish & Ship (Week 9-10)
Goal: Production-ready release
- Auto-update (electron-updater + GitHub Releases)
- Auto-start on login (optional)
- First-run setup wizard (detect OpenClaw dir, check health)
- Error handling and offline states
- Performance optimization (lazy loading pages, virtual scrolling for logs)
- Cross-platform testing: macOS, Windows, Linux
- Package: .dmg, .exe (NSIS), .AppImage
- README, screenshots, release notes
- Publish v1.0.0 on GitHub
8. Key Technical Decisions
Why Electron over Tauri?
- OCM's entire backend is Node.js — Electron includes Node.js, so migration is natural
- Tauri requires Rust for the backend, which means rewriting all server logic
- Electron's ecosystem for auto-update, packaging, and tray management is more mature
- The 150MB app size tradeoff is acceptable for a local developer tool
Why React over keeping vanilla JS?
- OCM's #1 recurring bug category is template literal escaping (documented 4+ times in DEVLOG)
- At 5000+ lines, a single-file vanilla JS app becomes unmaintainable
- React components isolate concerns: each page is independent, testable
- TypeScript catches bugs at compile time
- Massive ecosystem for UI components, hooks, state management
Why keep the HTTP API layer?
- OCM's API is well-tested and covers all needed operations
- Allows gradual migration: start with HTTP over IPC, replace with direct IPC later
- Keeps the door open for remote web access (serve HTTP for LAN users)
- Reduces initial migration risk
Why dark theme only (initially)?
- OCM already has a mature dark theme
- ODO's target users are developers/power users who prefer dark
- Adding light theme doubles CSS work for no immediate user value
- Can add light theme in v1.1 if demanded
9. Risk Assessment
| Risk | Impact | Mitigation |
|---|---|---|
| Electron app size too large | Low — dev tool, not consumer app | Accept 150MB, optimize later with electron-builder asar |
| Remote WebSocket auth issues | Medium — token handling across machines | Provide SSH tunnel instructions as fallback |
| Cross-platform CLI differences | Medium — child_process behavior varies | Test on all 3 platforms early in Phase 4 |
| Gateway auto-management conflicts | Medium — user may run gateway separately | Detect existing gateway, offer to attach instead of restart |
| React migration takes longer than estimated | High — 256KB of legacy code | Phase 0-1 focus on new code, legacy migration in later phases |
| OCM users confused by new product name | Low | Clear migration guide, same GitHub repo or redirect |
10. Success Metrics for v1.0
- Double-click to dashboard in under 3 seconds (cold start)
- All OCM features working in the Electron wrapper
- Remote management of at least one remote instance
- Backup + restore verified on all 3 platforms
- Auto-update working via GitHub Releases
- Zero template-literal escaping bugs (the React migration goal)
11. Resolved Decisions
- Product name: ODO (OpenClaw Dashboard Orchestrator) — confirmed
- GitHub repo: new repo
odo, separate fromocm - OCM maintenance: gradual sunset — keep OCM working but no new features; ODO is the future
- i18n: English only. No Chinese support planned.
- Cron: merged into Settings page (scheduled backup settings + auto-start toggle)
- App icon: TBD — needs design
12. Open Questions
- App icon: design needed — lobster/claw themed?
- Phase 0.5 (current): Electron shell wrapping existing OCM — ship as v0.1.0-alpha?
Appendix: Feature Comparison (OCM → ODO)
| Feature | OCM (current) | ODO (planned) |
|---|---|---|
| Launch method | bash start.sh → browser |
Double-click app icon |
| Dashboard | Browser tab | Native window |
| Agent management | Full CRUD wizard | Read-focused console + inline edit |
| Stats | Basic charts | Enhanced: trends, predictions |
| CLI Terminal | In-browser | In-app dock panel |
| Log Viewer | Partial (ops menu) | Full dedicated page |
| Backup (local) | Snapshots in .openclaw dir | Versioned history + diff viewer |
| Backup (remote) | NAS SSH (complex) | Any SSH server (simplified) |
| Cron management | System crontab UI | Simplified scheduled backup |
| Remote management | None | WebSocket to remote Gateway |
| System tray | None | Full tray with status indicator |
| Gateway management | Manual restart button | Auto-start/stop/crash recovery |
| Auto-update | None | GitHub Releases + electron-updater |
| Auto-start | None | OS login item option |
| Multi-instance | Single local dir | Multiple local + remote instances |
| Code structure | Single file (256KB) | React components + TypeScript |
| Dependencies | Zero | Electron + React + build tools |