mirror of
https://github.com/JohnRiceML/clawport-ui.git
synced 2026-08-14 00:47:50 +00:00
docs: comprehensive documentation overhaul
- README.md: full rewrite with badges, OpenClaw quick start walkthrough, feature highlights, architecture diagram, agent discovery docs, and documentation index - SETUP.md: added "Setting Up OpenClaw" section (install, onboard, gateway, key concepts) before ClawPort-specific steps - CONTRIBUTING.md: new file — dev setup, code style, testing, PR process - CHANGELOG.md: new file — full version history from 0.1.0 to 0.5.4 - SECURITY.md: new file — security model, token handling, data storage, vulnerability reporting Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
JohnRiceML
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
09a85f1711
commit
33112c8b4a
+182
@@ -0,0 +1,182 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to [clawport-ui](https://www.npmjs.com/package/clawport-ui) will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [0.5.3] - 2026-03-05
|
||||
|
||||
### Changed
|
||||
|
||||
- Added clawport.dev link to README header.
|
||||
|
||||
## [0.5.2] - 2026-03-04
|
||||
|
||||
### Fixed
|
||||
|
||||
- Agent discovery now uses SOUL.md-driven scanning for subdirectory agents, replacing fragile directory-name matching.
|
||||
|
||||
## [0.5.1] - 2026-03-03
|
||||
|
||||
### Changed
|
||||
|
||||
- Rewrote CLI discovery to use real `openclaw agents list` output format.
|
||||
|
||||
## [0.5.0] - 2026-03-02
|
||||
|
||||
### Added
|
||||
|
||||
- CLI-based agent discovery via `openclaw agents list`.
|
||||
- Dagre-powered org map with team-column layout.
|
||||
|
||||
### Fixed
|
||||
|
||||
- Deduplicated root agent when `agents/` directory name matches root ID.
|
||||
|
||||
## [0.4.6] - 2026-02-28
|
||||
|
||||
### Added
|
||||
|
||||
- Setup detection module with comprehensive setup scenario tests.
|
||||
|
||||
## [0.4.5] - 2026-02-27
|
||||
|
||||
### Fixed
|
||||
|
||||
- Handle `{ crons, pipelines }` response format in all consumers.
|
||||
|
||||
## [0.4.4] - 2026-02-26
|
||||
|
||||
### Fixed
|
||||
|
||||
- Split cron-pipelines module to avoid `fs` import in client bundle.
|
||||
|
||||
## [0.4.3] - 2026-02-25
|
||||
|
||||
### Added
|
||||
|
||||
- Rebuilt Memory page as 3-tab dashboard with live config viewer.
|
||||
|
||||
### Changed
|
||||
|
||||
- Documentation: added 405 troubleshooting, auto-discovery info, fixed clone URL.
|
||||
|
||||
### Fixed
|
||||
|
||||
- Detect and auto-enable gateway HTTP endpoint during setup.
|
||||
- Rewrote agent auto-discovery to handle all OpenClaw heading formats.
|
||||
|
||||
## [0.4.2] - 2026-02-24
|
||||
|
||||
### Added
|
||||
|
||||
- Auto-discover agents from OpenClaw workspace.
|
||||
- Kanban board hardening.
|
||||
|
||||
### Changed
|
||||
|
||||
- Default accent color to red; clarified package vs CLI naming.
|
||||
|
||||
## [0.4.1] - 2026-02-23
|
||||
|
||||
### Fixed
|
||||
|
||||
- Set `turbopack.root` to package directory for global installs.
|
||||
- Moved Next.js build dependencies to `dependencies` for global installs.
|
||||
- Converted `next.config.ts` to `next.config.mjs` for global installs.
|
||||
- Use package-local `next` binary instead of `npx` in CLI.
|
||||
|
||||
## [0.2.0] - 2026-02-20
|
||||
|
||||
### Added
|
||||
|
||||
- CLI entry point (`bin/clawport.mjs`) with `clawport dev`, `clawport setup`, `clawport start`, `clawport status`, and `clawport help` commands.
|
||||
- Published `clawport-ui` to npm with default lobster emoji.
|
||||
- MIT LICENSE file and repository URLs for open-source readiness.
|
||||
- Lucide icons on all action buttons with dynamic accent contrast.
|
||||
- Onboarding wizard (5-step first-run setup: name, theme, accent, mic, overview).
|
||||
|
||||
### Changed
|
||||
|
||||
- Rebranded from Agent Claw / Manor UI to ClawPort throughout the codebase.
|
||||
- Renamed ManorMap component and stripped voice IDs.
|
||||
|
||||
## [0.1.3] - 2026-02-17
|
||||
|
||||
### Added
|
||||
|
||||
- Kanban board with agent automation (V2).
|
||||
|
||||
### Changed
|
||||
|
||||
- Comprehensive README, CLAUDE.md, and `.env.example` update.
|
||||
|
||||
### Removed
|
||||
|
||||
- Voice recording and audio playback from chat.
|
||||
|
||||
### Fixed
|
||||
|
||||
- `sendViaOpenClaw` uses send-then-poll pattern for `chat.send`.
|
||||
- Image pipeline: resize client-side, use CLI `execFile`, check only latest message.
|
||||
|
||||
## [0.1.2] - 2026-02-14
|
||||
|
||||
### Added
|
||||
|
||||
- Route image messages through OpenClaw `chat.send` pipeline.
|
||||
- TDD coverage for multimodal, validation, and audio-recorder modules.
|
||||
- Multimodal chat with vision and file support, plus TTS listen button.
|
||||
- Voice messages, file attachments, and enhanced media input.
|
||||
|
||||
### Fixed
|
||||
|
||||
- Use WebSocket for image messages instead of CLI (fixes E2BIG).
|
||||
- Return plain string for audio-only messages in `buildApiContent`.
|
||||
|
||||
## [0.1.1] - 2026-02-11
|
||||
|
||||
### Added
|
||||
|
||||
- Complete Apple-quality UI/UX remake.
|
||||
- Security hardening and test infrastructure.
|
||||
- Messenger-style chat with avatars, name labels, and markdown formatting.
|
||||
- Full Messenger rebuild with persistent threads, all agents, and media support.
|
||||
- 5-theme system (Dark, Glass, Color, Light, System) with visible map connectors.
|
||||
|
||||
### Fixed
|
||||
|
||||
- Removed hardcoded OpenClaw gateway token.
|
||||
- Chat via OpenClaw gateway using `claude-sonnet-4-6` (no separate API key required).
|
||||
|
||||
### Changed
|
||||
|
||||
- Apple dark mode full pass: glass chat, line numbers, gold gradients, animated states.
|
||||
|
||||
## [0.1.0] - 2026-02-07
|
||||
|
||||
### Added
|
||||
|
||||
- Initial release.
|
||||
- Agent org map with React Flow.
|
||||
- Call box for direct agent chat.
|
||||
- Cron monitor dashboard.
|
||||
- Memory browser.
|
||||
- Next.js 16 App Router with Turbopack.
|
||||
|
||||
[0.5.3]: https://github.com/JohnRiceML/clawport-ui/compare/v0.5.2...v0.5.3
|
||||
[0.5.2]: https://github.com/JohnRiceML/clawport-ui/compare/v0.5.1...v0.5.2
|
||||
[0.5.1]: https://github.com/JohnRiceML/clawport-ui/compare/v0.5.0...v0.5.1
|
||||
[0.5.0]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.6...v0.5.0
|
||||
[0.4.6]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.5...v0.4.6
|
||||
[0.4.5]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.4...v0.4.5
|
||||
[0.4.4]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.3...v0.4.4
|
||||
[0.4.3]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.2...v0.4.3
|
||||
[0.4.2]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.1...v0.4.2
|
||||
[0.4.1]: https://github.com/JohnRiceML/clawport-ui/compare/v0.2.0...v0.4.1
|
||||
[0.2.0]: https://github.com/JohnRiceML/clawport-ui/compare/v0.1.3...v0.2.0
|
||||
[0.1.3]: https://github.com/JohnRiceML/clawport-ui/compare/v0.1.2...v0.1.3
|
||||
[0.1.2]: https://github.com/JohnRiceML/clawport-ui/compare/v0.1.1...v0.1.2
|
||||
[0.1.1]: https://github.com/JohnRiceML/clawport-ui/compare/v0.1.0...v0.1.1
|
||||
[0.1.0]: https://github.com/JohnRiceML/clawport-ui/releases/tag/v0.1.0
|
||||
+116
@@ -0,0 +1,116 @@
|
||||
# Contributing to ClawPort
|
||||
|
||||
Thank you for your interest in contributing to ClawPort. Whether you are fixing a bug, improving documentation, or adding a feature, your help is welcome and appreciated.
|
||||
|
||||
This guide covers the conventions and process we follow so that contributions stay consistent and easy to review.
|
||||
|
||||
## Development Setup
|
||||
|
||||
1. Fork and clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/<your-username>/clawport-ui.git
|
||||
cd clawport-ui
|
||||
```
|
||||
|
||||
2. Install dependencies (Node 22+):
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. Run the setup script to auto-detect your local OpenClaw installation and generate `.env.local`:
|
||||
```bash
|
||||
npm run setup
|
||||
```
|
||||
|
||||
4. Start the dev server (Turbopack, port 3000):
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Code Style
|
||||
|
||||
ClawPort follows a small set of conventions that keep the codebase consistent. Please follow these when writing new code:
|
||||
|
||||
- **TypeScript strict mode.** No `any` escapes without a comment explaining why.
|
||||
- **Tailwind CSS custom properties for theming.** Use `var(--text-primary)`, `var(--bg)`, etc. instead of Tailwind color utility classes like `text-gray-500`. Theme tokens are defined in `app/globals.css`.
|
||||
- **No external charting or media libraries.** Use native Web APIs (Canvas, SVG, MediaRecorder, AudioContext) and custom components.
|
||||
- **Base64 data URLs for persisted media.** Blob URLs do not survive page reloads. Always convert to base64 before storing.
|
||||
- **Call `requireEnv()` inside functions, not at module top level.** Top-level calls crash imports during `next build` and test runs when env vars are absent. See `lib/env.ts` for the helper.
|
||||
|
||||
## Testing
|
||||
|
||||
All tests live alongside their source files: `lib/foo.ts` has `lib/foo.test.ts`.
|
||||
|
||||
Before opening a PR, make sure both of these pass:
|
||||
|
||||
```bash
|
||||
npm test # Vitest -- all tests must pass
|
||||
npx tsc --noEmit # Type-check -- zero errors expected
|
||||
```
|
||||
|
||||
### Writing Tests
|
||||
|
||||
- Write tests for every new feature or bug fix.
|
||||
- Use the patterns already established in the codebase:
|
||||
- `vi.mock('child_process')` for CLI-dependent code
|
||||
- `vi.stubEnv('VAR_NAME', 'value')` for environment variables
|
||||
- `vi.useFakeTimers({ shouldAdvanceTime: true })` for polling or time-dependent logic
|
||||
- Keep tests focused. One behavior per test case.
|
||||
|
||||
## Pull Request Process
|
||||
|
||||
1. **Fork** the repo and create a feature branch from `main`:
|
||||
```bash
|
||||
git checkout -b fix/agent-discovery-crash
|
||||
```
|
||||
|
||||
2. **Make your changes.** Commit with clear messages (see below).
|
||||
|
||||
3. **Push** your branch and open a pull request against `main`.
|
||||
|
||||
4. In the PR description, explain **what** the change does and **why** it is needed. Link to a related issue if one exists.
|
||||
|
||||
5. A maintainer will review your PR. Be open to feedback -- we may suggest changes before merging.
|
||||
|
||||
## Commit Messages
|
||||
|
||||
Use imperative mood with a short subject line. A longer body is optional but welcome for non-trivial changes.
|
||||
|
||||
Examples from the project history:
|
||||
|
||||
```
|
||||
Fix agent discovery: SOUL.md-driven scanning
|
||||
Add CLI-based agent discovery
|
||||
feat: auto-discover agents from OpenClaw workspace
|
||||
```
|
||||
|
||||
Keep the subject under 72 characters. If you need to elaborate, leave a blank line after the subject and write a body paragraph.
|
||||
|
||||
## What Makes a Good PR
|
||||
|
||||
- **One concern per PR.** A bug fix, a feature, or a refactor -- not all three at once.
|
||||
- **Tests included.** New behavior should have corresponding tests. Bug fixes should include a test that would have caught the bug.
|
||||
- **No unrelated changes.** Resist the urge to fix formatting or rename variables in files you are not otherwise touching. Those are welcome as separate PRs.
|
||||
|
||||
## Reporting Bugs
|
||||
|
||||
Open a [GitHub Issue](https://github.com/JohnRiceML/clawport-ui/issues) with:
|
||||
|
||||
- A clear title describing the problem.
|
||||
- Steps to reproduce (commands, configuration, browser/OS if relevant).
|
||||
- Expected behavior vs. actual behavior.
|
||||
- Relevant error messages, logs, or screenshots.
|
||||
|
||||
## Feature Requests
|
||||
|
||||
Open a [GitHub Issue](https://github.com/JohnRiceML/clawport-ui/issues) and describe:
|
||||
|
||||
- The problem you are trying to solve (not just the solution you have in mind).
|
||||
- Why this matters for your workflow.
|
||||
- Any alternatives you have considered.
|
||||
|
||||
Good feature requests focus on the "why" and leave room for the maintainers and community to collaborate on the "how."
|
||||
|
||||
## License
|
||||
|
||||
By contributing to ClawPort, you agree that your contributions will be licensed under the [MIT License](LICENSE).
|
||||
@@ -1,84 +1,114 @@
|
||||
<div align="center">
|
||||
|
||||
# ClawPort
|
||||
|
||||
**[clawport.dev](https://clawport.dev)** | A visual command centre for your AI agent team.
|
||||
**A visual command centre for your AI agent team.**
|
||||
|
||||
ClawPort is an open-source dashboard for managing, monitoring, and talking directly to your [OpenClaw](https://openclaw.ai) AI agents. Built with Next.js 16, React 19, and a dark command-centre aesthetic with five themes.
|
||||
[](https://www.npmjs.com/package/clawport-ui)
|
||||
[](LICENSE)
|
||||
[](#testing)
|
||||
|
||||
[Website](https://clawport.dev) | [Setup Guide](SETUP.md) | [API Docs](docs/API.md) | [npm](https://www.npmjs.com/package/clawport-ui)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
ClawPort is an open-source dashboard for managing, monitoring, and talking directly to your [OpenClaw](https://openclaw.ai) AI agents. It connects to your local OpenClaw gateway and gives you an org chart, direct agent chat with vision and voice, a kanban board, cron monitoring, and a memory browser -- all in one place.
|
||||
|
||||
### Prerequisites
|
||||
No separate AI API keys needed. Everything routes through your OpenClaw gateway.
|
||||
|
||||
- [Node.js 22+](https://nodejs.org) (LTS recommended)
|
||||
- [OpenClaw](https://openclaw.ai) installed and running
|
||||
- OpenClaw gateway started (`openclaw gateway run`)
|
||||
---
|
||||
|
||||
### Quick Start (npm)
|
||||
## Quick Start
|
||||
|
||||
### 1. Install OpenClaw
|
||||
|
||||
ClawPort requires a running [OpenClaw](https://openclaw.ai) instance. If you don't have one yet:
|
||||
|
||||
```bash
|
||||
# Install OpenClaw
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
|
||||
# Run the onboarding wizard (sets up workspace, gateway, and daemon)
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
After onboarding, verify the gateway is running:
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
```
|
||||
|
||||
You should see your gateway URL (`localhost:18789`) and auth token. See the [OpenClaw docs](https://docs.openclaw.ai/getting-started) for more detail.
|
||||
|
||||
### 2. Install ClawPort
|
||||
|
||||
> **Note:** The npm package is `clawport-ui`. The CLI command is `clawport`.
|
||||
> Do not install the unrelated `clawport` package.
|
||||
|
||||
```bash
|
||||
# Install globally (package: clawport-ui, command: clawport)
|
||||
npm install -g clawport-ui
|
||||
```
|
||||
|
||||
# Auto-detect your OpenClaw config
|
||||
### 3. Connect and Launch
|
||||
|
||||
```bash
|
||||
# Auto-detect your OpenClaw config and write .env.local
|
||||
clawport setup
|
||||
|
||||
# Start the dev server
|
||||
# Start the dashboard
|
||||
clawport dev
|
||||
```
|
||||
|
||||
### Quick Start (from source)
|
||||
Open [http://localhost:3000](http://localhost:3000). The onboarding wizard walks you through naming your portal, picking a theme, and setting up your operator identity.
|
||||
|
||||
<details>
|
||||
<summary><strong>Install from source instead</strong></summary>
|
||||
|
||||
```bash
|
||||
git clone https://github.com/JohnRiceML/clawport-ui.git
|
||||
cd clawport-ui
|
||||
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](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.
|
||||
|
||||
See [SETUP.md](SETUP.md) for detailed environment configuration and troubleshooting.
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Org Map
|
||||
Interactive org chart of your entire agent team. Nodes show hierarchy, cron status, voice capabilities, and relationships at a glance. Powered by React Flow with BFS-based auto-layout.
|
||||
- **Org Map** -- Interactive org chart of your entire agent team. Hierarchy, cron status, and relationships at a glance. Powered by React Flow with auto-layout.
|
||||
- **Chat** -- Streaming text chat, image attachments with vision, voice messages with waveform playback, file attachments, clipboard paste and drag-and-drop. Conversations persist locally.
|
||||
- **Kanban** -- Task board for managing work across agents. Drag-and-drop cards with agent assignment and chat context.
|
||||
- **Cron Monitor** -- Live status of all scheduled jobs. Filter by status, sort errors to top, expand for details. Auto-refreshes every 60 seconds.
|
||||
- **Memory Browser** -- Read team memory, long-term memory, and daily logs. Markdown rendering, JSON syntax highlighting, search, and download.
|
||||
- **Agent Detail** -- Full profile per agent: SOUL.md viewer, tools, hierarchy, crons, voice ID, and direct chat link.
|
||||
- **Five Themes** -- Dark, Glass, Color, Light, and System. All CSS custom properties -- switch instantly.
|
||||
- **Auto-Discovery** -- Automatically finds agents from your OpenClaw workspace. No config file needed.
|
||||
|
||||
### Chat (Call Box)
|
||||
Full-featured messenger for direct agent conversations:
|
||||
- **Streaming text chat** via Claude (through the OpenClaw gateway)
|
||||
- **Image attachments** with vision -- agents can see and describe images
|
||||
- **Voice messages** -- hold-to-record with waveform playback
|
||||
- **File attachments** -- PDFs, docs, text files with type-aware rendering
|
||||
- **Clipboard paste and drag-and-drop** for images
|
||||
- **Clear chat** per agent
|
||||
- Conversations persist to localStorage
|
||||
---
|
||||
|
||||
### Agent Detail
|
||||
Full profile: SOUL.md viewer, tool list, hierarchy, associated crons, voice ID, and direct chat link.
|
||||
## How It Works
|
||||
|
||||
### Kanban
|
||||
Task board for managing work across your agent team. Drag-and-drop cards with agent assignment and chat context.
|
||||
ClawPort reads your OpenClaw workspace to discover agents, then connects to the gateway for all AI operations:
|
||||
|
||||
### Cron Monitor
|
||||
Live status of all scheduled jobs. Filter by status (all/ok/error/idle), sort errors to top, expand for error details. Auto-refreshes every 60 seconds.
|
||||
```
|
||||
Browser --> ClawPort (Next.js) --> OpenClaw Gateway (localhost:18789) --> Claude
|
||||
| |
|
||||
| Text: /v1/chat/completions (streaming SSE)
|
||||
| Vision: openclaw gateway call chat.send (CLI)
|
||||
| Audio: /v1/audio/transcriptions (Whisper)
|
||||
|
|
||||
Reads from:
|
||||
$WORKSPACE_PATH/agents/ (agent SOUL.md files)
|
||||
$WORKSPACE_PATH/memory/ (team memory)
|
||||
openclaw cron list (scheduled jobs)
|
||||
```
|
||||
|
||||
### Memory Browser
|
||||
Read team memory, long-term memory, and daily logs. Markdown rendering and JSON syntax highlighting built-in. Search, copy, and download support.
|
||||
|
||||
### Settings
|
||||
Personalize your portal: custom name, subtitle, logo/emoji, accent color, agent avatar overrides, and theme selection. All settings persist in your browser.
|
||||
All AI calls -- chat, vision, TTS, transcription -- route through the gateway. One token, no separate API keys.
|
||||
|
||||
---
|
||||
|
||||
@@ -86,211 +116,99 @@ Personalize your portal: custom name, subtitle, logo/emoji, accent color, agent
|
||||
|
||||
### Required Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `WORKSPACE_PATH` | Path to your OpenClaw workspace directory (default: `~/.openclaw/workspace`) |
|
||||
| `OPENCLAW_BIN` | Path to the `openclaw` CLI binary |
|
||||
| `OPENCLAW_GATEWAY_TOKEN` | Token that authenticates all API calls to the gateway |
|
||||
| Variable | Description | How to find it |
|
||||
|----------|-------------|----------------|
|
||||
| `WORKSPACE_PATH` | Path to your OpenClaw workspace | Default: `~/.openclaw/workspace` |
|
||||
| `OPENCLAW_BIN` | Path to the `openclaw` binary | Run `which openclaw` |
|
||||
| `OPENCLAW_GATEWAY_TOKEN` | Gateway auth token | Run `openclaw gateway status` |
|
||||
|
||||
### Optional Environment Variables
|
||||
### Optional
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `ELEVENLABS_API_KEY` | ElevenLabs API key for voice/TTS indicators on agent profiles |
|
||||
| `ELEVENLABS_API_KEY` | ElevenLabs API key for voice indicators on agent profiles |
|
||||
|
||||
No separate AI API keys are needed. All AI calls (chat, vision, TTS, transcription) route through the OpenClaw gateway.
|
||||
|
||||
See [SETUP.md](SETUP.md) for how to find each value.
|
||||
Running `clawport setup` auto-detects all required values and writes `.env.local`. See [SETUP.md](SETUP.md) for manual configuration, agent customization, and troubleshooting.
|
||||
|
||||
---
|
||||
|
||||
## Agent Customization
|
||||
## Agent Discovery
|
||||
|
||||
ClawPort ships with a bundled agent registry (`lib/agents.json`) as a working example. To use your own agents, create a file at:
|
||||
ClawPort automatically discovers agents from your OpenClaw workspace. No configuration file needed.
|
||||
|
||||
```
|
||||
$WORKSPACE_PATH/clawport/agents.json
|
||||
```
|
||||
**What it scans:**
|
||||
- `$WORKSPACE_PATH/SOUL.md` -- root orchestrator
|
||||
- `$WORKSPACE_PATH/IDENTITY.md` -- root agent name and emoji
|
||||
- `agents/<name>/SOUL.md` -- top-level agents
|
||||
- `agents/<name>/sub-agents/*.md` -- flat sub-agent files
|
||||
- `agents/<name>/members/*.md` -- team member files
|
||||
- `agents/<name>/<subdir>/SOUL.md` -- nested subdirectory agents
|
||||
|
||||
ClawPort checks for this file on every request. If it exists, it takes priority over the bundled registry. If it's missing or malformed, the bundled default is used as a fallback.
|
||||
**What it ignores:**
|
||||
- Directories without `SOUL.md` (e.g., `briefs/`, data files)
|
||||
- Non-`.md` files in `sub-agents/` and `members/`
|
||||
|
||||
Each agent entry looks like this:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "my-agent",
|
||||
"name": "My Agent",
|
||||
"title": "What they do",
|
||||
"reportsTo": "parent-agent-id",
|
||||
"directReports": [],
|
||||
"soulPath": "agents/my-agent/SOUL.md",
|
||||
"voiceId": null,
|
||||
"color": "#06b6d4",
|
||||
"emoji": "🤖",
|
||||
"tools": ["read", "write"],
|
||||
"memoryPath": null,
|
||||
"description": "One-liner description of this agent."
|
||||
}
|
||||
```
|
||||
|
||||
See [SETUP.md](SETUP.md) for the full field reference and examples.
|
||||
For full control over names, colors, hierarchy, and tools, create `$WORKSPACE_PATH/clawport/agents.json`. See [SETUP.md](SETUP.md) for the schema and examples.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### How Chat Works
|
||||
|
||||
Text messages go through the OpenClaw gateway's OpenAI-compatible endpoint (`/v1/chat/completions`) for streaming responses.
|
||||
|
||||
Image messages use a different pipeline because the gateway's HTTP endpoint strips image data. Instead, ClawPort uses the same path as Discord/Telegram channels:
|
||||
## CLI
|
||||
|
||||
```bash
|
||||
clawport dev # Start the development server
|
||||
clawport start # Build and start production server
|
||||
clawport setup # Auto-detect OpenClaw config, write .env.local
|
||||
clawport status # Check gateway reachability and config
|
||||
clawport help # Show usage
|
||||
```
|
||||
User attaches image
|
||||
→ Client resizes to 1200px max (fits within OS arg limits)
|
||||
→ Client converts to base64 data URL
|
||||
→ POST /api/chat/[id] detects image in latest message
|
||||
→ Server calls `openclaw gateway call chat.send` via CLI
|
||||
→ Server polls `openclaw gateway call chat.history` every 2s
|
||||
→ Agent processes image + text through Anthropic vision API
|
||||
→ Response returned to client as SSE
|
||||
```
|
||||
|
||||
Voice messages are recorded in-browser using the MediaRecorder API, transcribed server-side via Whisper (through the gateway's `/v1/audio/transcriptions` endpoint), and sent as text with the audio waveform preserved for playback.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
app/
|
||||
page.tsx — Org Map (React Flow org chart)
|
||||
chat/page.tsx — Multi-agent messenger
|
||||
agents/[id]/page.tsx — Agent detail profile
|
||||
kanban/page.tsx — Task board
|
||||
crons/page.tsx — Cron job monitor
|
||||
memory/page.tsx — Memory file browser
|
||||
settings/page.tsx — ClawPort personalization
|
||||
api/
|
||||
agents/route.ts — GET agents from registry
|
||||
chat/[id]/route.ts — POST chat (text + vision)
|
||||
crons/route.ts — GET crons via CLI
|
||||
memory/route.ts — GET memory files
|
||||
tts/route.ts — POST text-to-speech
|
||||
transcribe/route.ts — POST audio transcription
|
||||
|
||||
components/
|
||||
OrgMap.tsx — React Flow graph with auto-layout
|
||||
AgentNode.tsx — Custom node for the org chart
|
||||
Sidebar.tsx — Desktop navigation sidebar
|
||||
MobileSidebar.tsx — Mobile hamburger menu
|
||||
ThemeToggle.tsx — Theme switcher (5 themes)
|
||||
GlobalSearch.tsx — Cmd+K agent search
|
||||
chat/
|
||||
ConversationView.tsx — Message history + input with media
|
||||
AgentList.tsx — Agent sidebar for chat
|
||||
VoiceMessage.tsx — Waveform playback component
|
||||
FileAttachment.tsx — File bubble with icon + download
|
||||
MediaPreview.tsx — Pre-send attachment strip
|
||||
|
||||
lib/
|
||||
agents.ts — Agent registry + SOUL.md reader
|
||||
agents-registry.ts — Registry loader (workspace override or bundled)
|
||||
agents.json — Bundled default agent registry
|
||||
anthropic.ts — OpenClaw vision pipeline (chat.send + poll)
|
||||
audio-recorder.ts — MediaRecorder + waveform extraction
|
||||
conversations.ts — Client-side conversation store (localStorage)
|
||||
crons.ts — Cron data via openclaw CLI
|
||||
env.ts — Environment variable helper
|
||||
memory.ts — Memory file reader
|
||||
multimodal.ts — Message → API content format converter
|
||||
sanitize.ts — HTML/markdown sanitization
|
||||
settings.ts — ClawPort settings (localStorage)
|
||||
transcribe.ts — Whisper transcription with fallback
|
||||
validation.ts — Chat message validation
|
||||
types.ts — Shared TypeScript types
|
||||
themes.ts — Theme definitions
|
||||
styles.ts — Semantic style constants
|
||||
utils.ts — Tailwind merge utility
|
||||
```
|
||||
|
||||
### Key Design Decisions
|
||||
|
||||
- **No separate API keys** -- All AI calls (chat, vision, TTS, transcription) route through the OpenClaw gateway. One subscription, one token.
|
||||
- **No external charting/media libraries** -- Voice waveforms use plain div bars (not canvas), images resize via native Canvas API, all CSS uses Tailwind custom properties.
|
||||
- **Client-side persistence** -- Conversations stored in localStorage with base64 data URLs. Blob URLs don't survive page reload; data URLs do.
|
||||
- **Image resize before send** -- Images are resized client-side to max 1200px longest side before base64 encoding. This keeps the CLI argument payload under macOS's 1MB `ARG_MAX` limit.
|
||||
- **Send-then-poll for vision** -- The gateway's `chat.send` is async (returns immediately). We poll `chat.history` every 2 seconds until the assistant response appears, matched by timestamp.
|
||||
|
||||
---
|
||||
|
||||
## Themes
|
||||
## Testing
|
||||
|
||||
Five built-in themes, toggled via the sidebar button:
|
||||
|
||||
| Theme | Description |
|
||||
|-------|-------------|
|
||||
| **Dark** | Apple Dark Mode with warm blacks, red accent |
|
||||
| **Glass** | Frosted translucent panels on deep blue-black |
|
||||
| **Color** | Vibrant purple-indigo gradients |
|
||||
| **Light** | Apple Light Mode, clean whites |
|
||||
| **System** | Follows OS preference |
|
||||
|
||||
All themes use CSS custom properties. Components reference semantic tokens (`--bg`, `--text-primary`, `--accent`, etc.) so every theme is automatic.
|
||||
```bash
|
||||
npm test # 442 tests across 21 suites (Vitest)
|
||||
npx tsc --noEmit # Type-check (zero errors)
|
||||
npx next build # Production build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stack
|
||||
|
||||
- [Next.js 16](https://nextjs.org) (App Router, Turbopack)
|
||||
- [React 19](https://react.dev)
|
||||
- [TypeScript 5](https://typescriptlang.org)
|
||||
- [React 19](https://react.dev) / [TypeScript 5](https://typescriptlang.org)
|
||||
- [Tailwind CSS 4](https://tailwindcss.com)
|
||||
- [React Flow (@xyflow/react)](https://reactflow.dev) -- Org chart
|
||||
- [OpenAI SDK](https://github.com/openai/openai-node) -- Gateway client (routed to Claude via OpenClaw)
|
||||
- [Vitest 4](https://vitest.dev) -- Test runner
|
||||
- [OpenClaw](https://openclaw.ai) -- AI gateway, agent runtime, vision pipeline
|
||||
- [React Flow](https://reactflow.dev) -- org chart
|
||||
- [Vitest 4](https://vitest.dev) -- testing
|
||||
- [OpenClaw](https://openclaw.ai) -- AI gateway and agent runtime
|
||||
|
||||
---
|
||||
|
||||
## Development
|
||||
## Documentation
|
||||
|
||||
See [CLAUDE.md](CLAUDE.md) for the full developer guide: architecture deep-dives, test patterns, common tasks, and contribution conventions.
|
||||
|
||||
```bash
|
||||
npm run dev # Start dev server (Turbopack, port 3000)
|
||||
npm test # Run all tests via Vitest
|
||||
npx tsc --noEmit # Type-check (expect 0 errors)
|
||||
npx next build # Production build
|
||||
```
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [SETUP.md](SETUP.md) | Full setup guide, agent customization, troubleshooting |
|
||||
| [docs/API.md](docs/API.md) | REST API reference for all endpoints |
|
||||
| [docs/COMPONENTS.md](docs/COMPONENTS.md) | UI component catalog (50+ components) |
|
||||
| [docs/THEMING.md](docs/THEMING.md) | Theme system, CSS tokens, settings API |
|
||||
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
|
||||
| [CHANGELOG.md](CHANGELOG.md) | Version history |
|
||||
| [CLAUDE.md](CLAUDE.md) | Developer architecture guide |
|
||||
|
||||
---
|
||||
|
||||
## Built by
|
||||
## Contributing
|
||||
|
||||
[John Rice](https://github.com/johnrice) with [Jarvis](https://openclaw.ai) (OpenClaw AI)
|
||||
|
||||
---
|
||||
|
||||
## npm
|
||||
|
||||
```bash
|
||||
npm install -g clawport-ui
|
||||
clawport help
|
||||
```
|
||||
|
||||
Published as [`clawport-ui`](https://www.npmjs.com/package/clawport-ui) on npm. The CLI command is `clawport` (not `clawport-ui`). The separate `clawport` npm package is unrelated and not affiliated with this project.
|
||||
|
||||
### CLI Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `clawport dev` | Start the development server |
|
||||
| `clawport start` | Build and start the production server |
|
||||
| `clawport setup` | Auto-detect OpenClaw config and write `.env.local` |
|
||||
| `clawport status` | Check gateway reachability and current config |
|
||||
| `clawport help` | Show usage |
|
||||
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines.
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
[MIT](LICENSE)
|
||||
|
||||
---
|
||||
|
||||
Built by [John Rice](https://github.com/JohnRiceML) with [Jarvis](https://openclaw.ai) (OpenClaw AI).
|
||||
|
||||
+64
@@ -0,0 +1,64 @@
|
||||
# Security Policy
|
||||
|
||||
## Supported Versions
|
||||
|
||||
| Version | Supported |
|
||||
| ------- | --------- |
|
||||
| 0.5.x | Yes |
|
||||
| < 0.5 | No |
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
If you discover a security vulnerability in ClawPort, please report it responsibly.
|
||||
|
||||
- **Email:** security@clawport.dev
|
||||
- **GitHub:** Use [GitHub Security Advisories](https://github.com/JohnRiceML/clawport-ui/security/advisories/new) to report vulnerabilities privately.
|
||||
|
||||
Please include steps to reproduce, affected versions, and potential impact. You should receive an acknowledgment within 72 hours. We will not pursue legal action against good-faith reporters.
|
||||
|
||||
## Security Model
|
||||
|
||||
ClawPort is a **local-first, single-operator tool**. It is designed to run on a developer's own machine or a trusted server. There is no user authentication system, no multi-tenant isolation, and no public-facing deployment expected.
|
||||
|
||||
The trust boundary is the local machine. If an attacker has access to the machine running ClawPort, the application is not the appropriate layer of defense.
|
||||
|
||||
## Token Handling
|
||||
|
||||
ClawPort authenticates with the OpenClaw gateway using `OPENCLAW_GATEWAY_TOKEN`, stored in `.env.local` (gitignored). This token is:
|
||||
|
||||
- Read server-side only via Next.js server actions and API routes.
|
||||
- Never exposed to the browser or included in client-side bundles.
|
||||
- Never logged or written to disk at runtime.
|
||||
|
||||
No direct API keys for AI providers (OpenAI, Anthropic, etc.) are used. All AI calls route through the local OpenClaw gateway.
|
||||
|
||||
## Data Storage
|
||||
|
||||
- **Conversations** are stored in the browser's `localStorage` as base64 data URLs. They are not encrypted and are cleared when the user clears browser data.
|
||||
- **Settings** are also stored in `localStorage`.
|
||||
- No data is sent to external servers. There is no database.
|
||||
|
||||
Users should be aware that anyone with access to their browser profile can read stored conversations and settings.
|
||||
|
||||
## Filesystem Access
|
||||
|
||||
ClawPort reads files from the path specified by `WORKSPACE_PATH` and executes the OpenClaw CLI binary specified by `OPENCLAW_BIN` via `child_process.execFile`.
|
||||
|
||||
- `execFile` is used instead of `exec` to avoid shell injection.
|
||||
- Both `WORKSPACE_PATH` and `OPENCLAW_BIN` are configured via server-side environment variables, not user input.
|
||||
- Access is bounded by the OS-level permissions of the process running ClawPort.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
The following are not considered vulnerabilities in ClawPort:
|
||||
|
||||
- Denial of service against localhost services.
|
||||
- Social engineering attacks.
|
||||
- Physical access to the host machine.
|
||||
- Vulnerabilities in OpenClaw, the gateway, or upstream AI providers (report those to their respective maintainers).
|
||||
- Missing authentication or authorization (by design -- this is a single-operator tool).
|
||||
- Data readable in `localStorage` by same-origin scripts (expected browser behavior).
|
||||
|
||||
## Dependencies
|
||||
|
||||
Dependencies are kept minimal. We run `npm audit` regularly and update vulnerable packages promptly. If you identify a dependency-level vulnerability that affects ClawPort specifically, please report it through the channels above.
|
||||
@@ -6,9 +6,73 @@ This guide walks you through getting ClawPort running against your own OpenClaw
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Node.js 22+** -- [Download](https://nodejs.org). Verify with `node -v`.
|
||||
2. **OpenClaw** -- [Install OpenClaw](https://openclaw.ai) and make sure the CLI works: `openclaw --version`.
|
||||
3. **OpenClaw gateway running** -- ClawPort talks to the gateway at `localhost:18789`. Start it before launching the UI.
|
||||
- **Node.js 22+** -- [Download](https://nodejs.org). Verify with `node -v`.
|
||||
- **OpenClaw** -- installed and running (see below)
|
||||
|
||||
---
|
||||
|
||||
## 0. Setting Up OpenClaw
|
||||
|
||||
ClawPort connects to [OpenClaw](https://openclaw.ai), an open-source, self-hosted AI assistant that runs locally on your machine. If you already have OpenClaw running, skip to [step 1](#1-install-clawport).
|
||||
|
||||
### Install OpenClaw
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
|
||||
# Or via npm (requires Node 22+)
|
||||
npm install -g openclaw
|
||||
```
|
||||
|
||||
Windows: `iwr -useb https://openclaw.ai/install.ps1 | iex`
|
||||
|
||||
Verify the install:
|
||||
|
||||
```bash
|
||||
openclaw --version
|
||||
```
|
||||
|
||||
### Run the Onboarding Wizard
|
||||
|
||||
The onboarding wizard sets up your workspace, configures the gateway, and installs it as a background daemon:
|
||||
|
||||
```bash
|
||||
openclaw onboard --install-daemon
|
||||
```
|
||||
|
||||
This creates:
|
||||
|
||||
| What | Where |
|
||||
|------|-------|
|
||||
| Config file | `~/.openclaw/openclaw.json` |
|
||||
| Workspace | `~/.openclaw/workspace/` |
|
||||
| Agent SOUL files | `~/.openclaw/workspace/agents/` |
|
||||
| Memory | `~/.openclaw/workspace/memory/` |
|
||||
| Credentials | `~/.openclaw/credentials/` |
|
||||
|
||||
### Verify the Gateway
|
||||
|
||||
The gateway is the local server that handles all AI operations. ClawPort talks to it at `localhost:18789`.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
```
|
||||
|
||||
You should see the gateway URL, port, and auth token. If the gateway isn't running:
|
||||
|
||||
```bash
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
### Key Concepts
|
||||
|
||||
- **Workspace** -- the directory where OpenClaw stores agent files, memory, and configuration. Default: `~/.openclaw/workspace`.
|
||||
- **Gateway** -- local server at `localhost:18789` that routes AI calls to Claude, GPT, or local models. Exposes an OpenAI-compatible HTTP endpoint and a WebSocket control plane.
|
||||
- **Agents** -- each agent has a `SOUL.md` defining its persona and a directory under `agents/` in your workspace.
|
||||
- **SOUL.md** -- the identity file for an agent. Contains its name, role, personality, and operating rules. ClawPort reads these to build the dashboard.
|
||||
|
||||
For more detail, see the [OpenClaw documentation](https://docs.openclaw.ai/getting-started).
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "clawport-ui",
|
||||
"version": "0.5.3",
|
||||
"version": "0.5.4",
|
||||
"description": "Open-source dashboard for managing, monitoring, and chatting with your OpenClaw AI agents.",
|
||||
"homepage": "https://clawport.dev",
|
||||
"repository": {
|
||||
|
||||
Reference in New Issue
Block a user