The Problem

Managing dozens of OpenClaw agents across platforms (Feishu, Discord, etc.) forces operators to open multiple terminals, hunt through JSON files, and manually verify gateway health. There is no single view that shows which bot uses which model, its token consumption, or whether the underlying gateway is reachable.

What This Does

The repository ships a Next.js web UI that reads the local OpenClaw configuration (~/.openclaw/openclaw.json) and session files, then renders a dashboard with:

  • Bot cards – app/components/agent‑card.tsx shows name, emoji, model, platform, and health status.
  • Model list, session explorer, statistics charts, and an Alert Center – pages live under app/models/page.tsx, app/sessions/page.tsx, app/stats/page.tsx, and app/alerts/page.tsx.
  • Pixel Office – an animated office view built on the pixel‑office engine in lib/pixel-office/. Core types live in lib/pixel-office/types.ts; the renderer (lib/pixel-office/engine/renderer.ts) drives the canvas, while lib/pixel-office/engine/officeState.ts maintains the world state.

All data is fetched from the filesystem; no external database is required.

How It Is Wired

  1. Entry point – npm run dev starts Next.js, which loads app/layout.tsx and the route handlers under app/api/.
  2. API layer – each endpoint (e.g., app/api/agent-status/route.ts, app/api/pixel-office/layout/route.ts) imports helper functions from lib/. The most common helper is lib/openclaw-cli.ts, which invokes the OpenClaw CLI to read openclaw.json and session files.
  3. Data flow – an API request ultimately calls lib/config-cache.ts (caches the parsed JSON) → lib/openclaw-paths.ts (resolves file locations) → returns a plain JavaScript object to the route handler, which responds with JSON.
  4. UI consumption – client components (app/page.tsx, app/sidebar.tsx) use Next.js fetch to call /api/*. The data populates React state and drives the UI.
  5. Pixel Office rendering – the browser loads app/pixel-office/page.tsx, which instantiates new OfficeState() from lib/pixel-office/engine/officeState.ts. The state imports the hub module lib/pixel-office/types.ts (19 inbound imports) and passes sprite data from lib/pixel-office/sprites/spriteData.ts (1124 lines) to renderer.render(). The renderer imports 11 other engine modules, giving it the highest instability (1.0) in the import graph.
  6. Blast radius – changes to lib/pixel-office/types.ts affect 19 modules; modifications in the oversized officeState.ts ripple through the entire pixel‑office subsystem. The duplicated 6‑line blocks across 27 API routes (app/api/alerts/check/route.ts, app/api/pixel-office/idle-rank/route.ts, etc.) mean a bug fix in one place must be replicated manually.

No circular dependencies were detected, but the hub module and the oversized engine files are clear hotspots for future maintenance effort.

How To Use It

# Clone the exact repo
git clone https://github.com/moses-y/OpenClaw-bot-review.git
cd OpenClaw-bot-review

# Install Node dependencies (npm is defined in package.json)
npm install

# Development server
npm run dev          # starts Next.js on http://localhost:3000

# Optional: point at a custom OpenClaw config
export OPENCLAW_HOME=/opt/openclaw   # defaults to ~/.openclaw
npm run dev

Docker deployment

docker build -t openclaw-dashboard .
docker run -d -p 3000:3000 \
  -e OPENCLAW_HOME=/opt/openclaw \
  -v /path/to/openclaw:/opt/openclaw \
  openclaw-dashboard

The container image ships the same Next.js server; the only required runtime variable is OPENCLAW_HOME.

Real‑World Use

A DevOps team runs the dashboard inside their monitoring namespace. When a new Discord bot is added, they drop the updated openclaw.json into ~/.openclaw/. The dashboard instantly shows the new agent card, updates the pixel‑office animation, and triggers an alert if the gateway health endpoint (app/api/gateway-health/route.ts) reports a failure. No database migrations or additional configuration are needed.

Code Health & Issues

  • High – Cognitive load – lib/pixel-office/sprites/spriteData.ts, lib/pixel-office/engine/officeState.ts, lib/pixel-office/bugs/bugSystem.ts each exceed 1 000 lines. Split by responsibility.
  • Medium – Hub module – lib/pixel-office/types.ts is imported by 19 modules; keep its API stable, move volatile logic elsewhere.
  • High – Deep nesting – app/sidebar.tsx, app/components/agent-card.tsx, app/alerts/page.tsx reach 8 levels of indentation; refactor with early returns or helper functions.
  • High – Duplicated code – identical 6‑line blocks appear in 27 API route files; extract to a shared utility (e.g., lib/api/helpers.ts).
  • Medium – Branch density – lib/pixel-office/layout/* files contain 77 branch points over 269 lines; consider strategy tables.
  • Low – TODO/FIXME – nine markers remain in lib/pixel-office/engine/officeState.ts; resolve or file issues.
  • SDLC gap – No CI/CD configuration (.github/ or similar) is present; add a GitHub Actions workflow to run npm test and build the Docker image on push.
  • Tests – Nine test files exist, but coverage is unclear; consider expanding to cover the duplicated API logic and the pixel‑office engine.

The Bottom Line

The repo delivers a functional, zero‑database dashboard that visualizes OpenClaw agents and includes a novel pixel‑office animation. However, key modules are oversized, duplicated logic is widespread, and the project lacks automated CI. It is suitable for teams that need quick visibility and are comfortable refactoring the identified hotspots before scaling.