ClawPort UI reads your OpenClaw workspace as a filesystem database

The npm package and the CLI command carry different names

The npm package is `clawport-ui`. The command it puts on your PATH is `clawport`, mapped in package.json to `./bin/clawport.mjs`. Those two names are far enough apart that the README puts a warning on them, telling you not to install the unrelated `clawport` package that already exists on npm. Nothing in the code stops you from installing it. A global install resolves one name and the wrong binary is what ends up on your PATH.

Only the package ships. The `files` array in package.json lists what npm publishes:

npm install -g clawport-ui

It includes `app/`, `bin/`, `components/`, `docs/`, `lib/`, `public/`, `scripts/`, `next.config.mjs`, `postcss.config.mjs`, `tsconfig.json` and `.env.example`. What it does not include is worth reading closely: no `SETUP.md`, no `CONTRIBUTING.md`, no `SECURITY.md`, no `CHANGELOG.md`, no `CLAUDE.md`, no `BRANDING.md`, no `components.json`, no `vitest.config.ts`, no `package-lock.json`, and no `clawport-logo.png` despite the logo file being named there. The README links all four of those markdown files at the top of the page and tells you to read SETUP.md for the `agents.json` schema, for manual configuration, for agent customization and for troubleshooting. None of that documentation reaches an npm install. A global install leaves you with the schema undocumented and troubleshooting unsourced.

Agent discovery is a filename scan, not a config file

There is no agent manifest to author by default. ClawPort walks your workspace and treats the presence of specific files as the structure of your org chart:

$WORKSPACE_PATH/SOUL.md
$WORKSPACE_PATH/IDENTITY.md
agents/<name>/SOUL.md
agents/<name>/sub-agents/*.md
agents/<name>/members/*.md
agents/<name>/<subdir>/SOUL.md

Two names come straight off the filesystem. The root orchestrator is whatever sits at `SOUL.md` in the workspace root, and the root agent's display name and emoji come from `IDENTITY.md` sitting next to it. Rename either file and the node changes or loses its label; there is no fallback list.

The discovery rules are also an implicit naming convention for your agents. Anything under `sub-agents/` or `members/` that is not a `.md` file is skipped, and any directory without its own `SOUL.md` is skipped entirely, which is how `briefs/` and data directories stay out of the chart. A nested agent one directory deeper still needs `SOUL.md` at that depth to count, so the depth you actually use is not fixed by the code.

The escape hatch is one file: `$WORKSPACE_PATH/clawport/agents.json`, which is where names, colors, hierarchy and tools are controlled by hand. Its schema lives in SETUP.md, and SETUP.md is not in the npm tarball, so the override path is documented only for people working from a clone.

One token, three different gateway routes

The dashboard claims no separate AI API keys are needed, and every AI call routes through your gateway. The claim holds, but the routes are not uniform. The diagram in the README splits them three ways: text goes to `/v1/chat/completions` over streaming SSE, audio goes to `/v1/audio/transcriptions` for Whisper, and vision does not use the HTTP API at all. Vision shells out to `openclaw gateway call chat.send` through the CLI, which means it needs a working binary on PATH, not just a reachable port.

That is what makes `OPENCLAW_BIN` a required variable alongside `WORKSPACE_PATH` and `OPENCLAW_GATEWAY_TOKEN`, and it is also the least obvious of the three. The other two are values you look up and paste. A stale path to a binary that has been moved or upgraded breaks image input while text chat keeps working, which is a confusing failure to debug from the browser.

One optional key changes what a profile shows. `ELEVENLABS_API_KEY` turns on voice indicators on agent profiles, so the same dashboard renders differently depending on whether a key is present, with no warning when it is blank. The `.env.example` lists it as commented out with the note that you can leave it or remove the line, while `openai` sits in dependencies with no indication of what else consumes it.

The cron monitor polls on a fixed 60 second timer

Scheduled jobs come from the CLI, not from a file. The README lists `openclaw cron list` under the paths ClawPort reads, alongside `$WORKSPACE_PATH/agents/` and `$WORKSPACE_PATH/memory/`. ClawPort never asks the gateway for the schedule directly.

The cron monitor auto-refreshes every 60 seconds. The cost dashboard sits on top of that same job list and adds token usage, per-job breakdown, model distribution, anomaly detection, week-over-week comparison and cache savings. Anomaly detection implies baselines, and nothing in the repository says where a baseline is stored, what window it uses, or how it treats a job that has been failing for a week.

The 60 second cadence is the part to reason about. A cron screen that a human watches can be a minute stale and still be fine. A cost dashboard that a human acts on cannot, especially when it is the surface that claims to have spotted an anomaly. The refresh is a fixed interval with no live stream behind it, which is an odd split in a project that also ships a live log streaming widget, where clicking a row in the activity console expands the raw JSON of that event. Event logs stream, and job status polls. Cost numbers derive from the polling side.

setup writes to ~/.config when npm owns the package directory

Running `clawport setup` auto-detects the three required values and writes `.env.local`. Where it writes depends on file ownership rather than on a flag:

clawport setup
clawport dev

After a global install, if the package directory is not writable, setup writes to `~/.config/clawport-ui/.env.local` instead. Both locations hold a gateway auth token in plaintext, and which one your install used is not something the CLI tells you. The variable to fix that is `OPENCLAW_GATEWAY_TOKEN`, and every AI call in the project uses it: chat, vision, transcription and speech all present the same token to the local gateway. Treat the file that holds it as local root-equivalent material, and check its permissions before you check anything else in this setup.

Port detection is described as automatic. `clawport setup` finds a custom port if you changed one, and the default is `localhost:18789`, which `openclaw gateway status` prints together with the auth token. `.env.example` confirms 18789 but adds that the port lives in `openclaw.json` under `gateway.http.port`, so the value has to be edited in a file ClawPort does not manage.

Version 0.8.9 with no releases to compare it against

`package.json` says 0.8.9. The repository has no GitHub releases at all, and its version number is sitting in the 0.x series, which under npm semver rules means the project has not committed to a stable public API. You install 0.8.9 and nothing in the repository tells you whether it came after or before a breaking change, because the usual markers for that are the release notes and the tags, and there are none to read. The published tarball is the only artifact, so the upgrade path written down anywhere is reinstalling the global package and hoping the workspace format stayed compatible.

The last push on the repository was 2026-03-24, and the package itself is the install path: the README points at the npm package from the header, so a user who never visits GitHub has no way to see the commit history, the issues, or the pull requests at all.

The stack is pinned tightly. Node has to be 22 or newer per the `engines` field, Next.js is `16.1.6` exactly rather than a range, React and React DOM are pinned to `19.2.3`, and the only OpenClaw dependency is the external `openai` package at `^6.25.0`. The graph layout runs on `@dagrejs/dagre` with `@xyflow/react` doing the drawing, and Tailwind sits at version 4 with `tw-animate-css` beside it. `prepublishOnly` runs `npx tsc --noEmit && vitest run`, so a publish is type-checked and tested, but only against whatever is in that clone.

The CLI reference stops mid-command

The command list at the end of the README breaks in the middle of a line. Three entries are complete:

clawport dev      # Start the development server
clawport start    # Build and start production server
clawport setup    # Auto-detect OpenClaw config, write .env.local
clawport status   # C

The fourth line ends after the letter C, mid-comment. Nothing follows it: the rest of the command table and every section after it are absent, so the documentation stops at the point where it would start describing commands you have not been shown. That boundary is where this article stops too, because everything past it is genuinely not there.

What can be read from the three complete entries and from `scripts` in package.json is still useful. `clawport dev` is the development server and `clawport start` builds and serves production, which map onto the `next dev` and `next build` plus `next start` scripts. The two things package.json adds that the README command list never gets to mention are `npm test`, which is `vitest run` with `@vitejs/plugin-react` and `jsdom` configured, and `npm run setup`, which is `node scripts/setup.mjs`, the source install path for people working from a clone.

Editorial conclusion

ClawPort fits operators who already run an OpenClaw gateway and accept a dashboard that reads the workspace directly, polls cron on a fixed 60 second timer, and discovers agents purely by markdown filename. Before adopting it, confirm which ClawPort version your install resolves, since the project ships tagged npm builds while its repository has no GitHub releases, so the only upgrade path written down is reinstalling the global package. Treat the two tokens it reads as a local privilege escalation surface, and check the gateway port yourself rather than trusting the documented default.

Frequently asked questions

Official sources

1. Issues
2. JohnRiceML/clawport-ui on GitHub
3. License: MIT
4. Project website
5. README