1. Clone and build the vendored OpenClaw runtime

<p align="center">
  <img src="assets/LOGO_EN_COMPACT.png" width="400" alt="EasyClaw">
</p>

<p align="center">
  English | <a href="README.zh-CN.md">中文</a>
</p>

## Why EasyClaw?

[OpenClaw](https://github.com/openclaw/openclaw) is a powerful agent runtime — but it's built for engineers. Setting it up means editing config files, managing processes, and juggling API keys from the terminal. For non-programmers (designers, operators, small business owners), that barrier is too high.

EasyClaw wraps OpenClaw into a desktop app that **anyone can use**: install, launch from the system tray, and manage everything through a local web panel. Write rules in plain language instead of code, configure LLM providers and messaging channels with a few clicks, and let the agent learn your preferences over time. No terminal required.

**In short:** OpenClaw is the engine; EasyClaw is the cockpit.

## Features

- **Natural Language Rules**: Write rules in plain language—they compile to policy, guards, or skills and take effect immediately (no restart)
- **Multi-Provider LLM Support**: 17+ providers (OpenAI, Anthropic, Google Gemini, DeepSeek, Zhipu/Z.ai, Moonshot, Qwen, Groq, Mistral, xAI, OpenRouter, MiniMax, Venice AI, Xiaomi, Volcengine/Doubao, Amazon Bedrock, etc.) with multi-key management and region-aware defaults
- **Gemini CLI OAuth**: Sign in with Google for free-tier Gemini access—no API key needed. Auto-detects or installs Gemini CLI credentials
- **Per-Provider Proxy Support**: Configure HTTP/SOCKS5 proxies per LLM provider or API key, with automatic routing and hot reload—essential for restricted regions
- **WeChat Messaging (WeCom)**: Chat with your agent from WeChat via a WeCom Customer Service relay. Open-source relay server included (`apps/wecom-relay`)
- **Multi-Account Channels**: Configure Telegram, Discord, Slack, WhatsApp, DingTalk, and more through UI with secure secret storage (Keychain/DPAPI)
- **Token Usage Tracking**: Real-time statistics by model and provider, auto-refreshed from OpenClaw session files
- **Speech-to-Text**: Region-aware STT integration for voice messages (Groq, Volcengine)
- **Visual Permissions**: Control file read/write access through UI
- **Zero-Restart Updates**: API key, proxy, and channel changes apply instantly via hot reload—no gateway restart needed
- **Local-First & Private**: All data stays on your machine; secrets never stored in plaintext
- **Auto-Update**: Client update checker with static manifest hosting
- **Privacy-First Telemetry**: Optional anonymous usage analytics—no PII collected

### How File Permissions Work

EasyClaw enforces file access permissions through an OpenClaw plugin that intercepts tool calls *before* they execute. Here's what's protected:

- **File access tools** (`read`, `write`, `edit`, `image`, `apply-patch`): Fully protected—paths are validated against your configured permissions
- **Command execution** (`exec`, `process`): Working directory is validated, but paths *inside* command strings (like `cat /etc/passwd`) cannot be inspected

**Coverage**: ~85-90% of file access scenarios. For maximum security, consider restricting or disabling `exec` tools through Rules.

**Technical note**: The file permissions plugin uses OpenClaw's `before_tool_call` hook—no vendor source code modifications needed, so EasyClaw can cleanly pull upstream OpenClaw updates.

## Prerequisites

| Tool    | Version    |
| ------- | ---------- |
| Node.js | >= 24      |
| pnpm    | 10.6.2     |

## Quick Start

```bash
# 1. Clone and build the vendored OpenClaw runtime
./scripts/setup-vendor.sh

# 2. Install workspace dependencies and build
pnpm install
pnpm build

# 3. Launch in dev mode
pnpm --filter @easyclaw/desktop dev
```

This starts the Electron tray app, which spawns the OpenClaw gateway and serves the management panel at `http://localhost:3210`.

## Repository Structure

```
easyclaw/
├── apps/
│   ├── desktop/          # Electron tray app (main process)
│   ├── panel/            # React management UI (served by desktop)
│   └── wecom-relay/      # WeCom Customer Service relay server (self-hosted)
├── packages/
│   ├── core/             # Shared types & Zod schemas
│   ├── device-id/        # Machine fingerprinting for device identity
│   ├── gateway/          # Gateway lifecycle, config writer, secret injection, OAuth flows
│   ├── logger/           # Structured logging (tslog)
│   ├── storage/          # SQLite persistence (better-sqlite3)
│   ├── rules/            # Rule compilation & skill file writer
│   ├── secrets/          # Keychain / DPAPI / file-based secret stores
│   ├── updater/          # Auto-update client
│   ├── stt/              # Speech-to-text abstraction (Groq, Volcengine)
│   ├── proxy-router/     # HTTP CONNECT proxy multiplexer for restricted regions
│   ├── telemetry/        # Privacy-first anonymous analytics client
│   └── policy/           # Policy injector & guard evaluator logic
├── extensions/
│   ├── dingtalk/         # DingTal

... (truncated)