Skip to content

Commit 0b7f1c7

Browse files
arianachennn-designvcfgv
arianachennn-design
and
vcfgv
authored
Update README.md (#5)
Co-authored-by: Felix <24791380+vcfgv@users.noreply.github.com>
1 parent 4cd720a commit 0b7f1c7

File tree

1 file changed

+261
-87
lines changed

1 file changed

+261
-87
lines changed

‎README.md‎

Lines changed: 261 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,298 @@
1-
# ClawX
21

3-
> Graphical AI Assistant based on OpenClaw
2+
<h1 align="center">ClawX</h1>
43

5-
ClawX is a modern desktop application that provides a beautiful graphical interface for OpenClaw, making AI assistants accessible to everyone without command-line knowledge.
4+
<p align="center">
5+
<strong>The Desktop Interface for OpenClaw AI Agents</strong>
6+
</p>
7+
8+
<p align="center">
9+
<a href="#features">Features</a> •
10+
<a href="#why-clawx">Why ClawX</a> •
11+
<a href="#getting-started">Getting Started</a> •
12+
<a href="#architecture">Architecture</a> •
13+
<a href="#development">Development</a> •
14+
<a href="#contributing">Contributing</a>
15+
</p>
16+
17+
<p align="center">
18+
<img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-blue" alt="Platform" />
19+
<img src="https://img.shields.io/badge/electron-33+-47848F?logo=electron" alt="Electron" />
20+
<img src="https://img.shields.io/badge/react-19-61DAFB?logo=react" alt="React" />
21+
<img src="https://img.shields.io/badge/typescript-5.7+-3178C6?logo=typescript" alt="TypeScript" />
22+
<img src="https://img.shields.io/badge/license-MIT-green" alt="License" />
23+
</p>
24+
25+
---
26+
27+
## Overview
28+
29+
**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.
30+
31+
Whether you're automating workflows, managing AI-powered channels, or scheduling intelligent tasks, ClawX provides the interface you need to harness AI agents effectively.
32+
33+
---
34+
35+
## Why ClawX
36+
37+
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.**
38+
39+
| Challenge | ClawX Solution |
40+
|-----------|----------------|
41+
| Complex CLI setup | One-click installation with guided setup wizard |
42+
| Configuration files | Visual settings with real-time validation |
43+
| Process management | Automatic gateway lifecycle management |
44+
| Multiple AI providers | Unified provider configuration panel |
45+
| Skill/plugin installation | Built-in skill marketplace and management |
46+
47+
---
648

749
## Features
850

9-
- 🎯 **Zero CLI Required** - Complete all installation, configuration, and usage through GUI
10-
- 🎨 **Modern UI** - Beautiful, intuitive desktop application interface
11-
- 📦 **Ready to Use** - Pre-installed skill bundles, ready immediately
12-
- 🖥️ **Cross-Platform** - Unified experience on macOS / Windows / Linux
13-
- 🔄 **Seamless Integration** - Fully compatible with OpenClaw ecosystem
51+
### 🎯 Zero Configuration Barrier
52+
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.
1453

15-
## Tech Stack
54+
### 💬 Intelligent Chat Interface
55+
Communicate with AI agents through a modern chat experience. Support for multiple conversation contexts, message history, and rich content rendering with Markdown.
1656

17-
- **Runtime**: Electron 33+
18-
- **Frontend**: React 19 + TypeScript
19-
- **UI Components**: shadcn/ui + Tailwind CSS
20-
- **State Management**: Zustand
21-
- **Build Tools**: Vite + electron-builder
22-
- **Testing**: Vitest + Playwright
57+
### 📡 Multi-Channel Management
58+
Configure and monitor multiple AI channels simultaneously. Each channel operates independently, allowing you to run specialized agents for different tasks.
2359

24-
## Development
60+
### ⏰ Cron-Based Automation
61+
Schedule AI tasks to run automatically. Define triggers, set intervals, and let your AI agents work around the clock without manual intervention.
2562

26-
### Prerequisites
63+
### 🧩 Extensible Skill System
64+
Extend your AI agents with pre-built skills. Browse, install, and manage skills through the integrated skill panel—no package managers required.
65+
66+
### 🔐 Secure Provider Integration
67+
Connect to multiple AI providers (OpenAI, Anthropic, and more) with credentials stored securely in your system's native keychain.
68+
69+
### 🌙 Adaptive Theming
70+
Light mode, dark mode, or system-synchronized themes. ClawX adapts to your preferences automatically.
71+
72+
---
73+
74+
## Getting Started
2775

28-
- Node.js 22+
29-
- pnpm (recommended) or npm
76+
### System Requirements
3077

31-
### Setup
78+
- **Operating System**: macOS 11+, Windows 10+, or Linux (Ubuntu 20.04+)
79+
- **Memory**: 4GB RAM minimum (8GB recommended)
80+
- **Storage**: 500MB available disk space
81+
82+
### Installation
83+
84+
#### Pre-built Releases (Recommended)
85+
86+
Download the latest release for your platform from the [Releases](https://github.com/ValueCell-ai/ClawX/releases) page.
87+
88+
#### Build from Source
3289

3390
```bash
3491
# Clone the repository
3592
git clone https://github.com/ValueCell-ai/ClawX.git
36-
cd clawx
93+
cd ClawX
3794

38-
# Install dependencies
95+
# Install dependencies (pnpm recommended)
3996
pnpm install
4097

41-
# Start development server
98+
# Initialize OpenClaw submodule
99+
pnpm openclaw:init
100+
101+
# Start in development mode
42102
pnpm dev
43103
```
44104

105+
### First Launch
106+
107+
When you launch ClawX for the first time, the **Setup Wizard** will guide you through:
108+
109+
1. **Language & Region** – Configure your preferred locale
110+
2. **AI Provider** – Enter your API keys for supported providers
111+
3. **Skill Bundles** – Select pre-configured skills for common use cases
112+
4. **Verification** – Test your configuration before entering the main interface
113+
114+
---
115+
116+
## Architecture
117+
118+
ClawX employs a **dual-process architecture** that separates UI concerns from AI runtime operations:
119+
120+
```
121+
┌─────────────────────────────────────────────────────────────────┐
122+
│ ClawX Desktop App │
123+
│ │
124+
│ ┌────────────────────────────────────────────────────────────┐ │
125+
│ │ Electron Main Process │ │
126+
│ │ • Window & application lifecycle management │ │
127+
│ │ • Gateway process supervision │ │
128+
│ │ • System integration (tray, notifications, keychain) │ │
129+
│ │ • Auto-update orchestration │ │
130+
│ └────────────────────────────────────────────────────────────┘ │
131+
│ │ │
132+
│ │ IPC │
133+
│ ▼ │
134+
│ ┌────────────────────────────────────────────────────────────┐ │
135+
│ │ React Renderer Process │ │
136+
│ │ • Modern component-based UI (React 19) │ │
137+
│ │ • State management with Zustand │ │
138+
│ │ • Real-time WebSocket communication │ │
139+
│ │ • Rich Markdown rendering │ │
140+
│ └────────────────────────────────────────────────────────────┘ │
141+
└──────────────────────────────┬──────────────────────────────────┘
142+
│
143+
│ WebSocket (JSON-RPC)
144+
▼
145+
┌─────────────────────────────────────────────────────────────────┐
146+
│ OpenClaw Gateway │
147+
│ │
148+
│ • AI agent runtime and orchestration │
149+
│ • Message channel management │
150+
│ • Skill/plugin execution environment │
151+
│ • Provider abstraction layer │
152+
└─────────────────────────────────────────────────────────────────┘
153+
```
154+
155+
### Design Principles
156+
157+
- **Process Isolation**: The AI runtime operates in a separate process, ensuring UI responsiveness even during heavy computation
158+
- **Graceful Recovery**: Built-in reconnection logic with exponential backoff handles transient failures automatically
159+
- **Secure Storage**: API keys and sensitive data leverage the operating system's native secure storage mechanisms
160+
- **Hot Reload**: Development mode supports instant UI updates without restarting the gateway
161+
162+
---
163+
164+
## Use Cases
165+
166+
### 🤖 Personal AI Assistant
167+
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.
168+
169+
### 📊 Automated Monitoring
170+
Set up scheduled agents to monitor news feeds, track prices, or watch for specific events. Results are delivered to your preferred notification channel.
171+
172+
### 💻 Developer Productivity
173+
Integrate AI into your development workflow. Use agents to review code, generate documentation, or automate repetitive coding tasks.
174+
175+
### 🔄 Workflow Automation
176+
Chain multiple skills together to create sophisticated automation pipelines. Process data, transform content, and trigger actions—all orchestrated visually.
177+
178+
---
179+
180+
## Development
181+
182+
### Prerequisites
183+
184+
- **Node.js**: 22+ (LTS recommended)
185+
- **Package Manager**: pnpm 9+ (recommended) or npm
186+
- **Git**: For submodule management
187+
188+
### Project Structure
189+
190+
```
191+
ClawX/
192+
├── electron/ # Electron main process
193+
│ ├── main/ # Application entry, window management
194+
│ ├── gateway/ # OpenClaw Gateway process manager
195+
│ ├── preload/ # Secure IPC bridge scripts
196+
│ └── utils/ # Utilities (storage, auth, paths)
197+
├── src/ # React renderer process
198+
│ ├── components/ # Reusable UI components
199+
│ │ ├── ui/ # Base components (buttons, inputs)
200+
│ │ ├── layout/ # Layout components (sidebar, header)
201+
│ │ └── common/ # Shared components
202+
│ ├── pages/ # Application pages
203+
│ │ ├── Dashboard/ # Home dashboard
204+
│ │ ├── Chat/ # AI chat interface
205+
│ │ ├── Channels/ # Channel management
206+
│ │ ├── Skills/ # Skill browser & manager
207+
│ │ ├── Cron/ # Scheduled tasks
208+
│ │ └── Settings/ # Configuration panels
209+
│ ├── stores/ # Zustand state stores
210+
│ └── types/ # TypeScript type definitions
211+
├── openclaw/ # OpenClaw submodule
212+
├── resources/ # Static assets (icons, images)
213+
└── tests/ # Test suites
214+
```
215+
45216
### Available Commands
46217

47218
```bash
48219
# Development
49-
pnpm dev # Start development server with hot reload
50-
pnpm build # Build for production
220+
pnpm dev # Start with hot reload
221+
pnpm dev:electron # Launch Electron directly
222+
223+
# Quality
224+
pnpm lint # Run ESLint
225+
pnpm lint:fix # Auto-fix issues
226+
pnpm typecheck # TypeScript validation
51227

52228
# Testing
53-
pnpm test # Run unit tests
54-
pnpm test:e2e # Run E2E tests
55-
pnpm test:coverage # Generate coverage report
56-
57-
# Code Quality
58-
pnpm lint # Run ESLint
59-
pnpm lint:fix # Fix linting issues
60-
pnpm typecheck # TypeScript type checking
61-
62-
# Packaging
63-
pnpm package # Package for current platform
64-
pnpm package:mac # Package for macOS
65-
pnpm package:win # Package for Windows
66-
pnpm package:linux # Package for Linux
229+
pnpm test # Run unit tests
230+
pnpm test:watch # Watch mode
231+
pnpm test:coverage # Generate coverage report
232+
pnpm test:e2e # Run Playwright E2E tests
233+
234+
# Build & Package
235+
pnpm build # Full production build
236+
pnpm package # Package for current platform
237+
pnpm package:mac # Package for macOS
238+
pnpm package:win # Package for Windows
239+
pnpm package:linux # Package for Linux
67240
```
68241

69-
## Project Structure
242+
### Tech Stack
70243

71-
```
72-
clawx/
73-
├── electron/ # Electron main process
74-
│ ├── main/ # Main process entry and handlers
75-
│ ├── gateway/ # Gateway process management
76-
│ ├── preload/ # Preload scripts
77-
│ └── utils/ # Utilities
78-
├── src/ # React renderer process
79-
│ ├── components/ # React components
80-
│ ├── pages/ # Page components
81-
│ ├── stores/ # Zustand state stores
82-
│ ├── hooks/ # Custom React hooks
83-
│ ├── types/ # TypeScript types
84-
│ └── styles/ # Global styles
85-
├── resources/ # Static resources
86-
├── tests/ # Test files
87-
└── build_process/ # Build documentation
88-
```
244+
| Layer | Technology |
245+
|-------|------------|
246+
| Runtime | Electron 33+ |
247+
| UI Framework | React 19 + TypeScript |
248+
| Styling | Tailwind CSS + shadcn/ui |
249+
| State | Zustand |
250+
| Build | Vite + electron-builder |
251+
| Testing | Vitest + Playwright |
252+
| Animation | Framer Motion |
253+
| Icons | Lucide React |
89254

90-
## Architecture
255+
---
91256

92-
ClawX follows a dual-port architecture:
257+
## Contributing
93258

94-
- **Port 23333**: ClawX GUI (default interface)
95-
- **Port 18789**: OpenClaw Gateway (native management)
259+
We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or translations—every contribution helps make ClawX better.
96260

97-
```
98-
┌─────────────────────────────────┐
99-
│ ClawX App │
100-
│ ┌───────────────────────────┐ │
101-
│ │ Electron Main Process │ │
102-
│ │ - Window management │ │
103-
│ │ - Gateway lifecycle │ │
104-
│ │ - System integration │ │
105-
│ └───────────────────────────┘ │
106-
│ ┌───────────────────────────┐ │
107-
│ │ React Renderer Process │ │
108-
│ │ - Modern UI │ │
109-
│ │ - WebSocket communication │ │
110-
│ └───────────────────────────┘ │
111-
└───────────────┬─────────────────┘
112-
│ WebSocket (JSON-RPC)
113-
▼
114-
┌─────────────────────────────────┐
115-
│ OpenClaw Gateway │
116-
│ - Message channel management │
117-
│ - AI Agent runtime │
118-
│ - Skills/plugins system │
119-
└─────────────────────────────────┘
120-
```
261+
### How to Contribute
262+
263+
1. **Fork** the repository
264+
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
265+
3. **Commit** your changes with clear messages
266+
4. **Push** to your branch
267+
5. **Open** a Pull Request
268+
269+
### Guidelines
270+
271+
- Follow the existing code style (ESLint + Prettier)
272+
- Write tests for new functionality
273+
- Update documentation as needed
274+
- Keep commits atomic and descriptive
275+
276+
---
277+
278+
## Acknowledgments
279+
280+
ClawX is built on the shoulders of excellent open-source projects:
281+
282+
- [OpenClaw](https://github.com/OpenClaw) – The AI agent runtime
283+
- [Electron](https://www.electronjs.org/) – Cross-platform desktop framework
284+
- [React](https://react.dev/) – UI component library
285+
- [shadcn/ui](https://ui.shadcn.com/) – Beautifully designed components
286+
- [Zustand](https://github.com/pmndrs/zustand) – Lightweight state management
287+
288+
---
121289

122290
## License
123291

124-
MIT
292+
ClawX is released under the [MIT License](LICENSE). You're free to use, modify, and distribute this software.
293+
294+
---
295+
296+
<p align="center">
297+
<sub>Built with ❤️ by the ValueCell Team</sub>
298+
</p>

0 commit comments

Comments
 (0)