ClawX AI OS

The Next-Generation AI Operating System for Autonomous Agent Orchestration

Vision • Core Capabilities • Getting Started • Architecture • Telemetry • Development

English | 简体中文 | 日本語 | Русский

---

Vision

ClawX AI OS is not just a GUI; it is a full-scale AI Operating System designed to be the "Windows for AI Agents." It transforms the raw power of OpenClaw into a structured, hierarchical, and self-improving agent environment.

ClawX provides the foundation for building AI Teams, where agents aren't just chat bots, but specialized employees (CEOs, Planners, Researchers) working within isolated, persistent Workspaces.

Why an AI OS?

Concept	Traditional AI App	ClawX AI OS
Scope	Single Chat / Agent	Multi-agent Orchestration
Context	Temporary History	Persistent Knowledge Brain (Graph-based)
Logic	Flat List of Bots	Agent Hierarchy (Delegation & Supervision)
Performance	Basic Logs	Telemetry Engine (Latency, Cost, Success Rate)
Storage	Cloud-first	Local-first Architecture (Encrypted, Private)

For a full enterprise edition, dedicated service support, or tailored deployment guidance for your business scenario, contact us at public@valuecell.ai.

---

Screenshot

---

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
App updates	Startup update checks with a prompt before downloading or installing
Multiple AI providers	Unified provider configuration panel
Skill/plugin installation	Built-in skill marketplace and management

OpenClaw Inside

ClawX is built directly upon the official OpenClaw core. Instead of requiring a separate installation, we embed the runtime within the application to provide a seamless "battery-included" experience.

We are committed to maintaining strict alignment with the upstream OpenClaw project, ensuring that you always have access to the latest capabilities, stability improvements, and ecosystem compatibility provided by the official releases.

When Developer Mode is enabled, the sidebar also provides a native Dreams page for OpenClaw memory review, dream diary inspection, and basic maintenance actions. The full upstream OpenClaw Dreams UI remains available from that page when deeper diagnostics are needed.

---

Core Capabilities

🏢 Real AI Workspaces

Every workspace in ClawX acts as a mini-OS environment.

• Role-based Isolation: Assign agents as CEO, Planner, Researcher, or Executioner.
• Persistent Memory: Each workspace maintains its own local Vector DB and audit logs.
• Knowledge Brain: Native integration with Obsidian-like local knowledge graphs for relational memory.
• Filesystem Sandbox: Secure, local-first file access for agent operations.

🧠 Multi-Agent Orchestration (Agent Hierarchy)

Move beyond single-agent chats. ClawX implements a true hierarchy:

• Delegation: The CEO agent can delegate tasks to Planners or Researchers.
• Supervision: QA and Security agents audit the output of Execution agents before finalizing tasks.
• Execution Graphs: Visualize complex multi-turn reasoning and agent handovers in real-time.

📊 Agent Telemetry Engine

A self-improving system requires data. ClawX tracks every turn:

• Performance Metrics: Real-time tracking of latency (ms), token cost, and success rates.
• Hallucination Scoring: Automated feedback loops to detect and correct agent drift.
• Optimization: Over time, the system suggests the best model/agent pairing for specific task patterns.

🏠 Local-First & Local-Inference

ClawX is built for privacy and performance:

• Offline-First: Your memory and configurations stay on your machine.
• Encrypted Storage: All local memory and knowledge graphs are encrypted.
• Inference Integration: Seamless support for local model providers (Ollama, LM Studio) alongside Enterprise APIs.

⏰ Cron-Based Autonomous Operations

Schedule your "AI Employees" to work around the clock.

• Background Tasks: Auto-triggered monitoring, analysis, and reporting.
• Multi-Channel Delivery: Integrated delivery to Discord, Telegram, Feishu, and WhatsApp.

🧩 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. ClawX also pre-bundles full document-processing skills (pdf, xlsx, docx, pptx), deploys them automatically to the managed skills directory (default ~/.openclaw/skills) on startup, and enables them by default on first install. Additional bundled skills (find-skills, self-improving-agent, tavily-search) are also enabled by default; if required API keys are missing, OpenClaw will surface configuration errors in runtime. The Skills page can display skills discovered from multiple OpenClaw sources (managed dir, workspace, and extra skill dirs), and now shows each skill's actual location so you can open the real folder directly.

Environment variables for bundled search skills:

• TAVILY_API_KEY for tavily-search (OAuth may also be supported by upstream skill runtime)
• find-skills and self-improving-agent do not require API keys

🔐 Secure Provider Integration

Connect to multiple AI providers (OpenAI, Anthropic, and more) with credentials stored securely in your system's native keychain. OpenAI supports both API key and browser OAuth (Codex subscription) sign-in. For Custom providers used with OpenAI-compatible gateways, you can set a custom User-Agent in Settings → AI Providers → Edit Provider for compatibility-sensitive endpoints. When a compatible gateway rejects /models for non-auth reasons, ClawX automatically falls back to a lightweight /chat/completions or /responses probe during API key validation.

🌙 Adaptive Theming

Light mode, dark mode, or system-synchronized themes. ClawX adapts to your preferences automatically.

🚀 Startup Launch Control

In Settings → General, you can enable Launch at system startup so ClawX starts automatically after login.

🔔 Update Prompts

ClawX can automatically check for new versions on startup. When an update is available, it shows an in-app prompt; downloading and installing only happen after you choose the action.

---

Getting Started

System Requirements

• Operating System: macOS 11+, Windows 10+, or Linux (Ubuntu 20.04+)
• Memory: 4GB RAM minimum (8GB recommended)
• Storage: 1GB available disk space

Installation

Pre-built Releases (Recommended)

Download the latest release for your platform from the Releases page.

Build from Source

# Clone the repository
git clone https://github.com/ValueCell-ai/ClawX.git
cd ClawX

# Initialize the project
pnpm run 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 – Add providers with API keys or OAuth (for providers that support browser/device login)
3. Skill Bundles – Select pre-configured skills for common use cases
4. Verification – Test your configuration before entering the main interface

The wizard preselects your system language when it is supported, and falls back to English otherwise.

Note for Moonshot (Kimi): ClawX keeps Kimi web search enabled by default. When Moonshot is configured, ClawX also syncs Kimi web search to the China endpoint (https://api.moonshot.cn/v1) in OpenClaw config.

Proxy Settings

ClawX includes built-in proxy settings for environments where Electron, the OpenClaw Gateway, or channels such as Telegram need to reach the internet through a local proxy client.

Open Settings → Gateway → Proxy and configure:

• Proxy Server: the default proxy for all requests
• Bypass Rules: hosts that should connect directly, separated by semicolons, commas, or new lines
• In Developer Mode, you can optionally override:
  • HTTP Proxy
  • HTTPS Proxy
  • ALL_PROXY / SOCKS

Recommended local examples:

Proxy Server: http://127.0.0.1:7890

Notes:

• A bare host:port value is treated as HTTP.
• If advanced proxy fields are left empty, ClawX falls back to Proxy Server.
• Saving proxy settings reapplies Electron networking immediately and restarts the Gateway automatically.
• ClawX also syncs the proxy to OpenClaw's Telegram channel config when Telegram is enabled.
• Gateway restarts preserve an existing Telegram channel proxy if ClawX proxy is currently disabled.
• To explicitly clear Telegram channel proxy from OpenClaw config, save proxy settings with proxy disabled.
• In Settings → Advanced → Developer, you can run OpenClaw Doctor to execute openclaw doctor --json and inspect the diagnostic output without leaving the app.
• On packaged Windows builds, the bundled openclaw CLI/TUI runs via the shipped node.exe entrypoint to keep terminal input behavior stable.

---

Architecture

ClawX employs a dual-process architecture with a unified host API layer. The renderer talks to a single client abstraction, while Electron Main owns protocol selection and process lifecycle:

┌──────────────────────────────────────────────────────────────────┐
│                        ClawX AI OS Core                          │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              AI Orchestration Plane (Main)                 │  │
│  │  • Multi-Agent Hierarchy & Delegation                      │  │
│  │  • Telemetry Collection (Latency, Tokens, Cost)            │  │
│  │  • Local Memory Graph & Vector DB Manager                  │  │
│  │  • Secrets Vault & Identity Management                     │  │
│  └────────────────────────────────────────────────────────────┘  │
│                              │                                   │
│                              │ High-Performance IPC              │
│                              ▼                                   │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │              Command & Control (UI)                        │  │
│  │  • Real-time Execution Graph Visualization                │  │
│  │  • Workspace/Role Management Interface                     │  │
│  │  • Knowledge Brain (Markdown/Obsidian Preview)             │  │
│  │  • Telemetry Dashboards                                    │  │
│  └────────────────────────────────────────────────────────────┘  │
└──────────────────────────────┬───────────────────────────────────┘
                               │
                               │ OS-Level Transport Strategy
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│                     Autonomous Gateway                           │
│                                                                  │
│  • Multi-Channel I/O (Discord, WhatsApp, Telegram, etc.)         │
│  • Skill Runtime Isolation (Sandboxed Plugins)                │
│  • Distributed Inference Abstraction Layer                       │
└──────────────────────────────────────────────────────────────────┘

Design Principles

• Process Isolation: The AI runtime operates in a separate process, ensuring UI responsiveness even during heavy computation
• Single Entry for Frontend Calls: Renderer requests go through host-api/api-client; protocol details are hidden behind a stable interface
• Main-Process Transport Ownership: Electron Main controls WS/HTTP usage and fallback to IPC for reliability
• Graceful Recovery: Built-in reconnect, timeout, and backoff logic handles transient failures automatically
• Secure Storage: API keys and sensitive data leverage the operating system's native secure storage mechanisms
• CORS-Safe by Design: Local HTTP access is proxied by Main, preventing renderer-side CORS issues

Process Model & Gateway Troubleshooting

• ClawX is an Electron app, so one app instance normally appears as multiple OS processes (main/renderer/zygote/utility). This is expected.
• Single-instance protection uses Electron's lock plus a local process-file lock fallback, preventing duplicate app launch in environments where desktop IPC/session bus is unstable.
• During rolling upgrades, mixed old/new app versions can still have asymmetric protection behavior. For best reliability, upgrade all desktop clients to the same version.
• The OpenClaw Gateway listener should still be single-owner: only one process should listen on 127.0.0.1:18789.
• Gateway readiness is based on OpenClaw core signals such as system-presence, health, and status; memory, Dreams, or channel failures are shown as capability degradation instead of global Gateway failure.
• To verify the active listener:
  • macOS/Linux: lsof -nP -iTCP:18789 -sTCP:LISTEN
  • Windows (PowerShell): Get-NetTCPConnection -LocalPort 18789 -State Listen
• Clicking the window close button (X) hides ClawX to tray; it does not fully quit the app. Use tray menu Quit ClawX for complete shutdown.

---

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

Project Structure

├── electron/                 # Electron Main Process
│   ├── api/                 # Main-side API router and handlers
│   │   └── routes/          # RPC/HTTP proxy route modules
│   ├── services/            # Provider, secrets and runtime services
│   │   ├── providers/       # Provider/account model sync logic
│   │   └── secrets/         # OS keychain and secret storage
│   ├── shared/              # Shared provider schemas/constants
│   │   └── providers/
│   ├── main/                # App entry, windows, IPC registration
│   ├── gateway/             # OpenClaw Gateway process manager
│   ├── preload/             # Secure IPC bridge
│   └── utils/               # Utilities (storage, auth, paths)
├── src/                      # React Renderer Process
│   ├── lib/                 # Unified frontend API + error model
│   ├── stores/              # Zustand stores (settings/chat/gateway)
│   ├── components/          # Reusable UI components
│   ├── pages/               # Setup/Dashboard/Chat/Channels/Skills/Cron/Settings
│   ├── i18n/                # Localization resources
│   └── types/               # TypeScript type definitions
├── tests/
│   ├── e2e/                 # Playwright Electron end-to-end smoke tests
│   └── unit/                # Vitest unit/integration-like tests
├── resources/                # Static assets (icons/images)
└── scripts/                  # Build and utility scripts

Available Commands

# Development
pnpm run init             # Install dependencies + download uv
pnpm dev                  # Start with hot reload (auto-prepares bundled skills if missing)

# Quality
pnpm lint                 # Run ESLint
pnpm typecheck            # TypeScript validation

# Testing
pnpm test                 # Run unit tests
pnpm run test:e2e         # Run Electron E2E smoke tests with Playwright
pnpm run test:e2e:headed  # Run Electron E2E tests with a visible window
pnpm run comms:replay     # Compute communication replay metrics
pnpm run comms:baseline   # Refresh communication baseline snapshot
pnpm run comms:compare    # Compare replay metrics against baseline thresholds

# Build & Package
pnpm run build:vite       # Build frontend only
pnpm build                # Full production build (with packaging assets)
pnpm package              # Package for current platform (includes bundled preinstalled skills)
pnpm package:mac          # Package for macOS
pnpm package:win          # Package for Windows
pnpm package:linux        # Package for Linux

On headless Linux, run Electron tests under a display server such as xvfb-run -a pnpm run test:e2e.

Communication Regression Checks

When a PR changes communication paths (gateway events, chat runtime send/receive flow, channel delivery, or transport fallback), run:

pnpm run comms:replay
pnpm run comms:compare

comms-regression in CI enforces required scenarios and threshold checks.

Electron E2E Tests

The Playwright Electron suite launches the packaged renderer and main process from dist/ and dist-electron/, so it does not require manually running pnpm dev first.

pnpm run test:e2e automatically:

• builds the renderer and Electron bundles with pnpm run build:vite
• starts Electron in an isolated E2E mode with a temporary HOME
• uses a temporary ClawX userData directory
• skips heavy startup side effects such as gateway auto-start, bundled skill installation, tray creation, and CLI auto-install

The first two baseline specs cover:

• first-launch setup wizard visibility on a fresh profile
• skipping setup and navigating to the Models page inside the Electron app

Add future Electron flows under tests/e2e/ and reuse the shared fixture in tests/e2e/fixtures/electron.ts.

Tech Stack

Layer	Technology
Runtime	Electron 40+
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 – The AI agent runtime
• Electron – Cross-platform desktop framework
• React – UI component library
• shadcn/ui – Beautifully designed components
• Zustand – Lightweight state management

---

Community

Join our community to connect with other users, get support, and share your experiences.

Enterprise WeChat	Feishu Group	Discord

ClawX Partner Program 🚀

We're launching the ClawX Partner Program and looking for partners who can help introduce ClawX to more clients, especially those with custom AI agent or automation needs.

Partners help connect us with potential users and projects, while the ClawX team provides full technical support, customization, and integration.

If you work with clients interested in AI tools or automation, we'd love to collaborate.

DM us or email public@valuecell.ai to learn more.

---

Star History

---

License

ClawX is released under the MIT License. You're free to use, modify, and distribute this software.

---

_{Built with ❤️ by the ValueCell Team}