ClawPort -- Developer Guide

ClawPort -- Developer Guide

Quick Reference

npm run setup        # Auto-detect OpenClaw config, write .env.local
npm run dev          # Start dev server (Turbopack, port 3000)
npm test             # Run all 781 tests via Vitest (32 suites)
npx tsc --noEmit     # Type-check (expect 0 errors)
npx next build       # Production build

CLI (global install)

The npm package is `clawport-ui`. The CLI command is `clawport`. The separate `clawport` npm package is unrelated.

npm install -g clawport-ui
clawport setup       # Auto-detect config, write .env.local into package dir
clawport dev         # Start dev server
clawport start       # Build + start production server
clawport status      # Check gateway reachability + env config
clawport help        # Show usage

The CLI resolves its own package root via `import.meta.url`, so all commands work regardless of the user's current working directory. Entry point: `bin/clawport.mjs`.

Project Overview

ClawPort is a Next.js 16 dashboard for managing OpenClaw AI agents. It provides an org chart (Org Map), direct agent chat with multimodal support, cron monitoring, a cost dashboard, an activity console with live log streaming, and memory browsing. All AI calls route through the OpenClaw gateway -- no separate API keys needed.

Tech Stack

undefined

Environment Variables

WORKSPACE_PATH       # Required -- path to .openclaw workspace (auto-detected)
OPENCLAW_BIN         # Required -- path to openclaw binary
OPENCLAW_GATEWAY_TOKEN  # Required -- gateway auth token
ELEVENLABS_API_KEY   # Optional -- voice indicators

Run `npm run setup` to auto-detect all required values from your local OpenClaw installation.

**Workspace detection order:** `~/.openclaw/agents/main/workspace` (current layout) → `~/.openclaw/workspace` (legacy). Falls back to manual prompt if neither exists.

**Global install:** When installed via `npm install -g clawport-ui`, `.env.local` may not be writable in the package directory. Setup falls back to `~/.config/clawport-ui/.env.local` (XDG-compliant). The CLI (`bin/clawport.mjs`) checks both locations when loading env vars.

Dev Server

`next.config.mjs` sets `allowedDevOrigins: ["*"]` so the dev server works over Tailscale, LAN, or any non-localhost origin without cross-origin errors.

Architecture

Agent Registry Resolution

loadRegistry() checks:
  1. $WORKSPACE_PATH/clawport/agents.json  (user override)
  2. Auto-discovered from $WORKSPACE_PATH   (agents/ directory scan)
  3. Bundled lib/agents.json               (default example)

`lib/agents-registry.ts` exports `loadRegistry()`. `lib/agents.ts` calls it to build the full agent list (merging in SOUL.md