ClawPort Command Centre
🚀
Getting Started
Setup, prerequisites, env vars

Getting Started

This guide walks you through getting ClawPort running against your own OpenClaw instance. ClawPort is a Next.js 16 dashboard for managing, monitoring, and talking directly to your OpenClaw AI agents.

Prerequisites

  • Node.js 22+ -- verify with node -v
  • OpenClaw -- installed and working: openclaw --version
  • OpenClaw gateway running -- ClawPort talks to the gateway at localhost:18789

Quick Start (npm)

Note
The npm package is clawport-ui. The CLI command is clawport. Do not install the unrelated clawport package.
terminal
# Install globally (package: clawport-ui, command: clawport)
npm install -g clawport-ui

# Run the setup wizard (auto-detects your OpenClaw config)
clawport setup

# Start the dev server
clawport dev
Warning
If you get EACCES: permission denied or EEXIST errors during install, your npm cache has broken permissions (usually from a previous sudo npm install). Fix it with: sudo chown -R $(whoami) ~/.npm then retry. See the Troubleshooting section for full details.

Quick Start (from source)

terminal
# Clone the repo
git clone https://github.com/JohnRiceML/clawport-ui.git
cd clawport-ui

# Install dependencies
npm install

# Auto-detect your OpenClaw config and write .env.local
npm run setup

# Start the dev server
npm run dev

Open http://localhost:3000. On first launch you'll see the onboarding wizard which walks you through naming your portal, choosing a theme, and personalizing agent avatars.

Environment Variables

The fastest way to configure is the auto-setup script: npm run setup. It auto-detects your WORKSPACE_PATH, OPENCLAW_BIN, and gateway token from your local OpenClaw installation.

To configure manually, copy the template and edit:

cp .env.example .env.local
VariableRequiredDescription
WORKSPACE_PATHYesPath to your OpenClaw workspace directory (default: ~/.openclaw/workspace)
OPENCLAW_BINYesAbsolute path to the openclaw CLI binary
OPENCLAW_GATEWAY_TOKENYesToken that authenticates all API calls to the gateway
ELEVENLABS_API_KEYNoElevenLabs API key for voice/TTS indicators on agent profiles
Tip
No separate AI API keys are needed. All AI calls (chat, vision, TTS, transcription) route through the OpenClaw gateway. One subscription, one token.

Finding Your Values

  1. WORKSPACE_PATH: Run ls ~/.openclaw/workspace to verify. You should see files like SOUL.md, an agents/ directory, and a memory/ directory.
  2. OPENCLAW_BIN: Run which openclaw and use the full path.
  3. OPENCLAW_GATEWAY_TOKEN: Run openclaw gateway status to view your gateway configuration including the token.

Start the Gateway

ClawPort expects the OpenClaw gateway running at localhost:18789. Start it in a separate terminal:

openclaw gateway run
Warning
The gateway's HTTP chat completions endpoint is disabled by default. Running clawport setup will detect this and offer to enable it automatically. If chat returns a 405 error, see the Troubleshooting section.

First-Run Onboarding

On your first visit, ClawPort launches the onboarding wizard (5 steps):

  1. Naming your portal -- give your command centre a custom name and subtitle
  2. Choosing a theme -- pick from Dark, Glass, Color, Light, or System
  3. Setting an accent color -- personalize the UI highlight color
  4. Voice chat -- optional microphone permission test
  5. Overview -- feature summary of all pages

All of these can be changed later in the Settings page.

Production Build

terminal
npx next build
npm start

The production server runs on port 3000 by default. The gateway still needs to be running.