299 lines
13 KiB
Markdown
299 lines
13 KiB
Markdown
|
||
<h1 align="center">ClawX</h1>
|
||
|
||
<p align="center">
|
||
<strong>The Desktop Interface for OpenClaw AI Agents</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="#features">Features</a> •
|
||
<a href="#why-clawx">Why ClawX</a> •
|
||
<a href="#getting-started">Getting Started</a> •
|
||
<a href="#architecture">Architecture</a> •
|
||
<a href="#development">Development</a> •
|
||
<a href="#contributing">Contributing</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue" alt="Platform" />
|
||
<img src="https://img.shields.io/badge/electron-33+-47848F?logo=electron" alt="Electron" />
|
||
<img src="https://img.shields.io/badge/react-19-61DAFB?logo=react" alt="React" />
|
||
<img src="https://img.shields.io/badge/typescript-5.7+-3178C6?logo=typescript" alt="TypeScript" />
|
||
<img src="https://img.shields.io/badge/license-MIT-green" alt="License" />
|
||
</p>
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
**ClawX** bridges the gap between powerful AI agents and everyday users. Built on top of [OpenClaw](https://github.com/OpenClaw), it transforms command-line AI orchestration into an accessible, beautiful desktop experience—no terminal required.
|
||
|
||
Whether you're automating workflows, managing AI-powered channels, or scheduling intelligent tasks, ClawX provides the interface you need to harness AI agents effectively.
|
||
|
||
---
|
||
|
||
## Why ClawX
|
||
|
||
Building AI agents shouldn't require mastering the command line. ClawX was designed with a simple philosophy: **powerful technology deserves an interface that respects your time.**
|
||
|
||
| Challenge | ClawX Solution |
|
||
|-----------|----------------|
|
||
| Complex CLI setup | One-click installation with guided setup wizard |
|
||
| Configuration files | Visual settings with real-time validation |
|
||
| Process management | Automatic gateway lifecycle management |
|
||
| Multiple AI providers | Unified provider configuration panel |
|
||
| Skill/plugin installation | Built-in skill marketplace and management |
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
### 🎯 Zero Configuration Barrier
|
||
Complete the entire setup—from installation to your first AI interaction—through an intuitive graphical interface. No terminal commands, no YAML files, no environment variable hunting.
|
||
|
||
### 💬 Intelligent Chat Interface
|
||
Communicate with AI agents through a modern chat experience. Support for multiple conversation contexts, message history, and rich content rendering with Markdown.
|
||
|
||
### 📡 Multi-Channel Management
|
||
Configure and monitor multiple AI channels simultaneously. Each channel operates independently, allowing you to run specialized agents for different tasks.
|
||
|
||
### ⏰ Cron-Based Automation
|
||
Schedule AI tasks to run automatically. Define triggers, set intervals, and let your AI agents work around the clock without manual intervention.
|
||
|
||
### 🧩 Extensible Skill System
|
||
Extend your AI agents with pre-built skills. Browse, install, and manage skills through the integrated skill panel—no package managers required.
|
||
|
||
### 🔐 Secure Provider Integration
|
||
Connect to multiple AI providers (OpenAI, Anthropic, and more) with credentials stored securely in your system's native keychain.
|
||
|
||
### 🌙 Adaptive Theming
|
||
Light mode, dark mode, or system-synchronized themes. ClawX adapts to your preferences automatically.
|
||
|
||
---
|
||
|
||
## Getting Started
|
||
|
||
### System Requirements
|
||
|
||
- **Operating System**: macOS 11+, Windows 10+, or Linux (Ubuntu 20.04+)
|
||
- **Memory**: 4GB RAM minimum (8GB recommended)
|
||
- **Storage**: 500MB available disk space
|
||
|
||
### Installation
|
||
|
||
#### Pre-built Releases (Recommended)
|
||
|
||
Download the latest release for your platform from the [Releases](https://github.com/ValueCell-ai/ClawX/releases) page.
|
||
|
||
#### Build from Source
|
||
|
||
```bash
|
||
# Clone the repository
|
||
git clone https://github.com/ValueCell-ai/ClawX.git
|
||
cd ClawX
|
||
|
||
# Install dependencies (pnpm recommended)
|
||
pnpm install
|
||
|
||
# Initialize OpenClaw submodule
|
||
pnpm openclaw:init
|
||
|
||
# Start in development mode
|
||
pnpm dev
|
||
```
|
||
|
||
### First Launch
|
||
|
||
When you launch ClawX for the first time, the **Setup Wizard** will guide you through:
|
||
|
||
1. **Language & Region** – Configure your preferred locale
|
||
2. **AI Provider** – Enter your API keys for supported providers
|
||
3. **Skill Bundles** – Select pre-configured skills for common use cases
|
||
4. **Verification** – Test your configuration before entering the main interface
|
||
|
||
---
|
||
|
||
## Architecture
|
||
|
||
ClawX employs a **dual-process architecture** that separates UI concerns from AI runtime operations:
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ ClawX Desktop App │
|
||
│ │
|
||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||
│ │ Electron Main Process │ │
|
||
│ │ • Window & application lifecycle management │ │
|
||
│ │ • Gateway process supervision │ │
|
||
│ │ • System integration (tray, notifications, keychain) │ │
|
||
│ │ • Auto-update orchestration │ │
|
||
│ └────────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ │ IPC │
|
||
│ ▼ │
|
||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||
│ │ React Renderer Process │ │
|
||
│ │ • Modern component-based UI (React 19) │ │
|
||
│ │ • State management with Zustand │ │
|
||
│ │ • Real-time WebSocket communication │ │
|
||
│ │ • Rich Markdown rendering │ │
|
||
│ └────────────────────────────────────────────────────────────┘ │
|
||
└──────────────────────────────┬──────────────────────────────────┘
|
||
│
|
||
│ WebSocket (JSON-RPC)
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ OpenClaw Gateway │
|
||
│ │
|
||
│ • AI agent runtime and orchestration │
|
||
│ • Message channel management │
|
||
│ • Skill/plugin execution environment │
|
||
│ • Provider abstraction layer │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Design Principles
|
||
|
||
- **Process Isolation**: The AI runtime operates in a separate process, ensuring UI responsiveness even during heavy computation
|
||
- **Graceful Recovery**: Built-in reconnection logic with exponential backoff handles transient failures automatically
|
||
- **Secure Storage**: API keys and sensitive data leverage the operating system's native secure storage mechanisms
|
||
- **Hot Reload**: Development mode supports instant UI updates without restarting the gateway
|
||
|
||
---
|
||
|
||
## Use Cases
|
||
|
||
### 🤖 Personal AI Assistant
|
||
Configure a general-purpose AI agent that can answer questions, draft emails, summarize documents, and help with everyday tasks—all from a clean desktop interface.
|
||
|
||
### 📊 Automated Monitoring
|
||
Set up scheduled agents to monitor news feeds, track prices, or watch for specific events. Results are delivered to your preferred notification channel.
|
||
|
||
### 💻 Developer Productivity
|
||
Integrate AI into your development workflow. Use agents to review code, generate documentation, or automate repetitive coding tasks.
|
||
|
||
### 🔄 Workflow Automation
|
||
Chain multiple skills together to create sophisticated automation pipelines. Process data, transform content, and trigger actions—all orchestrated visually.
|
||
|
||
---
|
||
|
||
## Development
|
||
|
||
### Prerequisites
|
||
|
||
- **Node.js**: 22+ (LTS recommended)
|
||
- **Package Manager**: pnpm 9+ (recommended) or npm
|
||
- **Git**: For submodule management
|
||
|
||
### Project Structure
|
||
|
||
```
|
||
ClawX/
|
||
├── electron/ # Electron main process
|
||
│ ├── main/ # Application entry, window management
|
||
│ ├── gateway/ # OpenClaw Gateway process manager
|
||
│ ├── preload/ # Secure IPC bridge scripts
|
||
│ └── utils/ # Utilities (storage, auth, paths)
|
||
├── src/ # React renderer process
|
||
│ ├── components/ # Reusable UI components
|
||
│ │ ├── ui/ # Base components (buttons, inputs)
|
||
│ │ ├── layout/ # Layout components (sidebar, header)
|
||
│ │ └── common/ # Shared components
|
||
│ ├── pages/ # Application pages
|
||
│ │ ├── Dashboard/ # Home dashboard
|
||
│ │ ├── Chat/ # AI chat interface
|
||
│ │ ├── Channels/ # Channel management
|
||
│ │ ├── Skills/ # Skill browser & manager
|
||
│ │ ├── Cron/ # Scheduled tasks
|
||
│ │ └── Settings/ # Configuration panels
|
||
│ ├── stores/ # Zustand state stores
|
||
│ └── types/ # TypeScript type definitions
|
||
├── openclaw/ # OpenClaw submodule
|
||
├── resources/ # Static assets (icons, images)
|
||
└── tests/ # Test suites
|
||
```
|
||
|
||
### Available Commands
|
||
|
||
```bash
|
||
# Development
|
||
pnpm dev # Start with hot reload
|
||
pnpm dev:electron # Launch Electron directly
|
||
|
||
# Quality
|
||
pnpm lint # Run ESLint
|
||
pnpm lint:fix # Auto-fix issues
|
||
pnpm typecheck # TypeScript validation
|
||
|
||
# Testing
|
||
pnpm test # Run unit tests
|
||
pnpm test:watch # Watch mode
|
||
pnpm test:coverage # Generate coverage report
|
||
pnpm test:e2e # Run Playwright E2E tests
|
||
|
||
# Build & Package
|
||
pnpm build # Full production build
|
||
pnpm package # Package for current platform
|
||
pnpm package:mac # Package for macOS
|
||
pnpm package:win # Package for Windows
|
||
pnpm package:linux # Package for Linux
|
||
```
|
||
|
||
### Tech Stack
|
||
|
||
| Layer | Technology |
|
||
|-------|------------|
|
||
| Runtime | Electron 33+ |
|
||
| UI Framework | React 19 + TypeScript |
|
||
| Styling | Tailwind CSS + shadcn/ui |
|
||
| State | Zustand |
|
||
| Build | Vite + electron-builder |
|
||
| Testing | Vitest + Playwright |
|
||
| Animation | Framer Motion |
|
||
| Icons | Lucide React |
|
||
|
||
---
|
||
|
||
## Contributing
|
||
|
||
We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or translations—every contribution helps make ClawX better.
|
||
|
||
### How to Contribute
|
||
|
||
1. **Fork** the repository
|
||
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
|
||
3. **Commit** your changes with clear messages
|
||
4. **Push** to your branch
|
||
5. **Open** a Pull Request
|
||
|
||
### Guidelines
|
||
|
||
- Follow the existing code style (ESLint + Prettier)
|
||
- Write tests for new functionality
|
||
- Update documentation as needed
|
||
- Keep commits atomic and descriptive
|
||
|
||
---
|
||
|
||
## Acknowledgments
|
||
|
||
ClawX is built on the shoulders of excellent open-source projects:
|
||
|
||
- [OpenClaw](https://github.com/OpenClaw) – The AI agent runtime
|
||
- [Electron](https://www.electronjs.org/) – Cross-platform desktop framework
|
||
- [React](https://react.dev/) – UI component library
|
||
- [shadcn/ui](https://ui.shadcn.com/) – Beautifully designed components
|
||
- [Zustand](https://github.com/pmndrs/zustand) – Lightweight state management
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
ClawX is released under the [MIT License](LICENSE). You're free to use, modify, and distribute this software.
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
<sub>Built with ❤️ by the ValueCell Team</sub>
|
||
</p>
|