Stop Managing AI Agents Blind: ClawPort Exposes Everything

Here's the dirty secret nobody talks about in AI engineering. You've got a dozen Claude Code agents running cron jobs, burning tokens, making decisions in the dark—and you're managing them through scattered terminal logs and prayer. No org chart. No cost visibility. No idea which agent just hallucinated its way through a production task. Sound familiar?

You're flying blind, and it's costing you.

Every day, engineering teams deploy AI agent teams without operational infrastructure. They build sophisticated multi-agent systems then monitor them like it's 2010—grep, tail, and hope. The result? Runaway API bills at 2 AM. Silent failures in scheduled pipelines. Team memory scattered across markdown files nobody reads. And when something breaks, you're archaeology-ing through ~/.openclaw/workspace like a digital Indiana Jones.

Enter ClawPort.

Built by John Rice with his own OpenClaw AI (meta, right?), ClawPort is the open-source dashboard that transforms your chaotic agent swarm into a visual command center. Org charts, live chat with vision and voice, kanban task boards, cron monitoring, cost tracking, memory browsing—all routing through your existing OpenClaw gateway with zero separate API keys. This isn't another SaaS dashboard trying to extract monthly rent from your infrastructure. This is your agents, your gateway, your data, fully visible.

The best part? Three commands and you're operational. But before we get to that—let me show you why this tool is already being whispered about in the AI engineering underground.

What Is ClawPort?

ClawPort is an open-source visual command center for OpenClaw AI agent teams. Born from the friction of managing Claude Code agents at scale, it connects directly to your local OpenClaw gateway and surfaces everything—hierarchy, conversations, costs, memory—in a unified Next.js interface.

The creator: John Rice, an ML engineer who apparently got tired of his own agents running amok. The project is actively maintained, ships with 781 passing tests across 32 Vitest suites, and carries zero TypeScript errors in production builds. That's not amateur hour—that's infrastructure-grade engineering.

Why it's trending now: The AI agent deployment wave has hit the "oh no, we need to operate this" phase. Teams are moving from "look, I made an agent!" to "wait, there are twelve of them and one just spent $47 on a cron job." ClawPort arrived at exactly this inflection point. While competitors pitch managed services with per-seat pricing, ClawPort offers full data sovereignty—everything stays in your infrastructure, routing through your gateway, readable from your filesystem.

The project's architecture reveals serious intent. Built on Next.js 16 with App Router and Turbopack, React 19, TypeScript 5, and Tailwind CSS 4, it leverages modern frontend patterns without compromise. The org chart visualization uses React Flow with auto-layout. The testing infrastructure runs Vitest 4. This isn't a weekend hack—it's production tooling that happens to be free.

Key Features That Eliminate Operational Darkness

Org Map — See Your Agent Hierarchy Instantly

ClawPort renders your entire agent team as an interactive org chart powered by React Flow. Hierarchy, cron status, and inter-agent relationships become visible at a glance. No more find ~/.openclaw -name "SOUL.md" | xargs grep to understand who reports to whom. The auto-layout engine handles complex team structures without manual positioning.

Chat — Direct Agent Communication with Multimodal Superpowers

Streaming text, image attachments with vision processing, voice messages with waveform playback, file attachments, clipboard paste, and drag-and-drop—all persisting locally. This isn't a wrapper around Claude's web interface. It's direct gateway communication with your agents, maintaining conversation context across sessions.

Kanban — Task Management Across Agent Boundaries

Drag-and-drop cards with agent assignment and embedded chat context. Finally, a way to visualize work distribution across your agent team without maintaining separate project management tools. The board syncs with agent state, not human assumptions.

Cron Monitor — Scheduled Job Observability

Live status of all scheduled jobs with 60-second auto-refresh. Filter by status, surface errors to the top, expand for execution details. The weekly heatmap visualization reveals patterns in agent workload that spreadsheets can't capture.

Cost Dashboard — Token Economics Exposed

Daily cost charts, per-job breakdowns, model distribution analytics, anomaly detection, week-over-week trends, and cache savings calculations. This is the financial transparency that prevents the dreaded "why is our Claude bill $2,400 this month?" conversation.

Activity Console & Live Logs — Historical and Streaming Observability

Browse historical events with JSON expansion, or pin the floating live stream widget that persists across page navigation. Click any log row to inspect raw JSON. The streaming widget uses Server-Sent Events through your OpenClaw gateway for real-time updates.

Memory Browser — Team Knowledge Accessible

Read team memory, long-term memory, and daily logs with markdown rendering, JSON syntax highlighting, search, and download capabilities. The categorized best practices guide helps onboard new team members to your agent conventions.

Five Themes — Instant Visual Adaptation

Dark, Glass, Color, Light, and System themes via CSS custom properties. Switch instantly without rebuild. All theming uses CSS tokens, making custom branding straightforward.

Use Cases Where ClawPort Transforms Chaos into Clarity

Scenario 1: The Midnight Cron Failure

Your orchestrator agent runs 47 scheduled jobs across sub-agents. At 3:47 AM, the data pipeline fails silently. Without ClawPort: you discover this at 9 AM via angry Slack messages, then spend 45 minutes tracing through log files. With ClawPort: the Cron Monitor surfaced the error within 60 seconds, the Activity Console shows the exact JSON response, and you fix it before your coffee cools.

Scenario 2: The Runaway Token Budget

New team member deploys an agent with overly verbose prompting. Token usage 10x's overnight. Without ClawPort: finance emails you Wednesday. With ClawPort: the Cost Dashboard's anomaly detection flagged the spike by Tuesday morning, the per-job breakdown identified the offending agent, and you implemented caching before significant spend accumulated.

Scenario 3: The Onboarding Knowledge Gap

Senior engineer leaves. Their agent team's operational knowledge was tribal—spread across SOUL.md files, shell history, and undocumented cron schedules. Without ClawPort: weeks of reverse engineering. With ClawPort: the Org Map reveals hierarchy instantly, Memory Browser surfaces conventions, and the Agent Detail pages expose tools, voice IDs, and configuration—turning weeks into hours.

Scenario 4: The Multi-Modal Debugging Session

Vision-enabled agent misclassifies production screenshots. Without ClawPort: ssh into server, locate image, manually test through CLI. With ClawPort: drag image into Chat panel, verify agent's vision interpretation in real-time, adjust prompt, re-test immediately—all within the dashboard.

Step-by-Step Installation & Setup Guide

Prerequisites

• Node.js 18+ with npm
• Running OpenClaw instance (gateway accessible)
• macOS, Linux, or WSL (Windows Subsystem for Linux)

Step 1: Install OpenClaw (If Not Present)

ClawPort requires a functioning OpenClaw gateway. If you're starting fresh:

# Install OpenClaw via official installer
curl -fsSL https://openclaw.ai/install.sh | bash

# Run onboarding wizard: configures workspace, gateway, and daemon
openclaw onboard --install-daemon

The --install-daemon flag ensures background service persistence. After completion, verify gateway health:

openclaw gateway status

Note your gateway URL (typically http://localhost:18789) and authentication token. ClawPort's setup command auto-detects custom ports, but verify accessibility before proceeding.

Step 2: Install ClawPort Globally

Critical naming note: The npm package is clawport-ui. The CLI command is clawport. Do not install the unrelated clawport package—it's a different project entirely.

npm install -g clawport-ui

For version pinning in production environments, specify the version badge shown in repository documentation.

Step 3: Auto-Configure Environment

# Detect OpenClaw configuration and write .env.local
clawport setup

This command probes your system for:

• WORKSPACE_PATH: Scans ~/.openclaw/agents/main/workspace (modern) or ~/.openclaw/workspace (legacy)
• OPENCLAW_BIN: Locates via which openclaw
• OPENCLAW_GATEWAY_TOKEN: Extracts from openclaw gateway status

If the global package directory lacks write permissions, setup gracefully falls back to ~/.config/clawport-ui/.env.local.

Step 4: Launch Development Server

clawport dev

Navigate to http://localhost:3000. The onboarding wizard guides through:

1. Portal naming (organizational identifier)
2. Theme selection (Dark recommended for extended monitoring sessions)
3. Operator identity configuration

Alternative: Install from Source

For contributors or those requiring latest commits:

git clone https://github.com/JohnRiceML/clawport-ui.git
cd clawport-ui
npm install
npm run setup
npm run dev

Production Deployment

clawport start  # Builds optimized production bundle, starts server

Verify configuration health anytime:

clawport status  # Gateway reachability and config validation

REAL Code Examples from the Repository

Example 1: OpenClaw Installation and Gateway Verification

The foundation of ClawPort operation is a healthy OpenClaw installation. The README provides the exact bootstrap sequence:

# Install OpenClaw via official installer script
curl -fsSL https://openclaw.ai/install.sh | bash

# Run the onboarding wizard (sets up workspace, gateway, and daemon)
openclaw onboard --install-daemon

After installation, verify gateway status before ClawPort connection:

# Check gateway URL and auth token availability
openclaw gateway status

Why this matters: ClawPort's entire value proposition depends on gateway connectivity. The openclaw gateway status command reveals the OPENCLAW_GATEWAY_TOKEN and endpoint that ClawPort consumes. Without this verification step, subsequent clawport setup calls fail cryptically. The --install-daemon flag is particularly crucial for production deployments—without background daemon persistence, gateway restarts require manual intervention, breaking ClawPort's continuous monitoring capabilities.

Example 2: ClawPort Installation and Launch Sequence

The three-command deployment that makes ClawPort remarkable:

# Install the dashboard globally
# NOTE: Package name 'clawport-ui' differs from CLI command 'clawport'
npm install -g clawport-ui

# Auto-detect OpenClaw configuration, write environment file
clawport setup

# Start development server with hot reload
clawport dev

Critical implementation detail: The package/CLI naming discrepancy (clawport-ui vs clawport) trips many first-time users. This isn't accidental sloppiness—it's npm namespace reality. The unrelated clawport package is a different project entirely. Installing the wrong package creates confusing failures where the clawport command remains unavailable.

The clawport setup command performs sophisticated environment detection: it parses shell configuration for OpenClaw paths, executes openclaw gateway status to extract tokens, and writes .env.local with discovered values. For global installations with permission constraints, it transparently redirects to ~/.config/clawport-ui/.env.local—a graceful degradation pattern that prevents setup failures in restricted environments.

Example 3: Source Installation for Development and Customization

For teams requiring fork modifications or bleeding-edge features:

# Clone repository with full git history
git clone https://github.com/JohnRiceML/clawport-ui.git
cd clawport-ui

# Install dependencies with lockfile respect
npm install

# Run repository-specific setup (differs from global CLI setup)
npm run setup

# Start development server with Turbopack
npm run dev

Development workflow insight: The npm run setup script in source installations performs additional steps beyond the global CLI's clawport setup—it likely initializes husky hooks, generates component catalog indices, or prepares documentation builds. The Turbopack-enabled dev server (Next.js 16 feature) provides sub-second hot module replacement, critical when iterating on React Flow org chart layouts or theme CSS custom properties.

Example 4: Environment Variable Configuration

For manual configuration or CI/CD pipelines, the README specifies exact variable requirements:

# Required: Path to OpenClaw workspace containing agent definitions
# Modern installations: ~/.openclaw/agents/main/workspace
# Legacy installations: ~/.openclaw/workspace
WORKSPACE_PATH=/path/to/workspace

# Required: Absolute path to openclaw binary for CLI operations
# Discover via: which openclaw
OPENCLAW_BIN=/usr/local/bin/openclaw

# Required: Gateway authentication token for API operations
# Discover via: openclaw gateway status
OPENCLAW_GATEWAY_TOKEN=your_token_here

# Optional: ElevenLabs integration for voice indicators on agent profiles
ELEVENLABS_API_KEY=your_elevenlabs_key

Operational security note: The OPENCLAW_GATEWAY_TOKEN grants full gateway access—equivalent to your Claude API key in scope. Never commit this to version control. The clawport setup command's auto-detection avoids manual token handling, reducing exposure risk. For containerized deployments, inject via orchestration secrets rather than environment files.

Example 5: Agent Discovery Architecture

ClawPort's zero-configuration agent discovery follows documented filesystem conventions:

$WORKSPACE_PATH/
├── SOUL.md                    # Root orchestrator definition
├── IDENTITY.md                # Root agent name and emoji
├── agents/
│   ├── orchestrator/
│   │   ├── SOUL.md            # Top-level agent personality
│   │   ├── sub-agents/
│   │   │   ├── researcher.md  # Flat sub-agent (must be .md)
│   │   │   └── writer.md
│   │   ├── members/
│   │   │   ├── analyst.md     # Team member definitions
│   │   │   └── reviewer.md
│   │   └── pipeline/          # Nested subdirectory agent
│   │       └── SOUL.md        # Requires SOUL.md for recognition
│   └── ...
└── memory/                    # Team memory storage
    ├── long-term/
    └── daily/

Discovery rules: ClawPort ignores directories lacking SOUL.md (enabling briefs/, data/ coexistence) and rejects non-.md files in sub-agents/ and members/ directories. For override control, create $WORKSPACE_PATH/clawport/agents.json with explicit name, color, hierarchy, and tool specifications—essential when filesystem conventions don't match operational reality.

Advanced Usage & Best Practices

Theme Customization for Team Branding

All five themes (Dark, Glass, Color, Light, System) use CSS custom properties. Override in globals.css or inject via clawport/agents.json for organizational consistency. The Glass theme particularly impresses stakeholders during demos—transparency effects signal "modern infrastructure."

Memory Browser as Knowledge Base

Structure memory/ with intentional hierarchy: long-term/ for architectural decisions, daily/ for operational logs, guides/ for onboarding. The markdown rendering and search capabilities transform agent memory into searchable team documentation.

Cost Dashboard Alerting

While ClawPort lacks native alerting, export cost data via the REST API (docs/API.md) to Prometheus/Grafana for threshold-based notifications. The anomaly detection algorithms identify statistical outliers—pair with PagerDuty for automated escalation.

Cron Monitor Optimization

The 60-second auto-refresh balances freshness with gateway load. For high-frequency cron environments, consider the live logs widget for sub-minute visibility, or implement custom WebSocket consumers via the API.

Agent Hierarchy Design

The Org Map's visual impact depends on thoughtful hierarchy. Avoid flat structures—nested SOUL.md relationships create compelling visual narratives that surface delegation patterns and potential bottlenecks.

Comparison with Alternatives

The decisive advantage: ClawPort occupies the unique intersection of zero-cost, full data control, and OpenClaw-native operation. Custom scripts eventually recreate ClawPort's feature set at 10x development cost. Managed SaaS solutions extract ongoing rent and expose sensitive agent operations to third parties. The Claude web interface wasn't designed for multi-agent operational monitoring.

FAQ

Is ClawPort production-ready?

Yes. 781 passing tests, zero TypeScript errors, production build validation, and MIT licensing for commercial use. The stack (Next.js 16, React 19, TypeScript 5) represents current stable releases, not experimental branches.

Does ClawPort require separate Claude API keys?

No. All AI operations route through your OpenClaw gateway using its existing token. This is architectural elegance—one authentication boundary, comprehensive visibility.

Can I use ClawPort without OpenClaw?

No. ClawPort is specifically designed for OpenClaw gateway integration. The agent discovery, chat routing, and cost tracking depend on OpenClaw's filesystem conventions and API surface.

How does ClawPort handle sensitive agent data?

All data remains local. ClawPort reads from your filesystem and communicates with your local gateway. No telemetry, no cloud dependencies, no data exfiltration vectors. The MIT license permits security auditing.

What's the performance impact with large agent teams?

The Org Map uses React Flow's virtualization for teams exceeding 50 agents. Memory Browser implements pagination for large log files. For teams exceeding 200 agents, consider the API for programmatic monitoring rather than continuous dashboard usage.

Can multiple operators use one ClawPort instance?

Currently designed for single-operator deployment. For team access, deploy behind reverse proxy with shared authentication, or run multiple instances pointing to the same OpenClaw gateway.

How do I customize agent appearance in the Org Map?

Create $WORKSPACE_PATH/clawport/agents.json with explicit name, color, hierarchy, and tool specifications. See SETUP.md for complete schema documentation.

Conclusion

The AI agent deployment revolution has an operations problem. We've made it trivial to spin up intelligent agents, but monitoring them remains stuck in terminal-era tooling. ClawPort solves this with surgical precision—native OpenClaw integration, comprehensive visibility, and zero additional infrastructure cost.

The three-command setup (npm install -g clawport-ui, clawport setup, clawport dev) transforms operational blindness into command center clarity. The org chart surfaces hierarchy. The cost dashboard prevents budget disasters. The memory browser preserves institutional knowledge. The multimodal chat enables direct intervention.

But here's what truly distinguishes ClawPort: it's not trying to become your AI platform. It's not extracting rent. It's not holding your data hostage. It's infrastructure that respects your existing choices—your OpenClaw gateway, your filesystem conventions, your operational patterns—while making them visible and manageable.

For teams running Claude Code agents in production, ClawPort isn't a nice-to-have. It's the difference between confident operations and anxious guesswork.

Ready to stop flying blind? Clone the repository, run those three commands, and see your agent team with clarity for the first time. Your 2 AM self will thank you.

Built with conviction by John Rice and Jarvis. MIT licensed. Community contributions welcome.