<p align="center"> <img src="assets/LOGO_EN.png" width="400" alt="RivonClaw"> </p> <p align="center"> English | <a href="README.zh-CN.md">中文</a> </p>

Why RivonClaw?

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.

RivonClaw 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; RivonClaw 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: 20+ providers (OpenAI, Anthropic, Google Gemini, DeepSeek, Zhipu/Z.ai, Moonshot/Kimi, Qwen, Groq, Mistral, xAI, OpenRouter, MiniMax, Venice AI, Xiaomi/MiMo, Volcengine/Doubao, Amazon Bedrock, NVIDIA NIM, etc.) plus subscription/coding plans (Claude, Gemini, Zhipu Coding, Qwen Coding, Kimi Code, MiniMax Coding, Volcengine Coding) and Ollama for local models
OAuth & Subscription Plans: Sign in with Google for free-tier Gemini access or connect Claude/Anthropic subscription—no API key needed. Auto-detects or installs 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
Multi-Account Channels: Configure Telegram, WhatsApp, Discord, Slack, Google Chat, Signal, iMessage, Feishu/Lark, LINE, Matrix, Mattermost, Microsoft Teams, 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
Chat with Agent: Real-time WebSocket chat with markdown rendering, emoji picker, image attachments, model switching, and persistent conversation history
Skills Marketplace: Browse, search, and install community skills from a built-in marketplace; manage installed skills with one click
Auto-Update: Client update checker with static manifest hosting
Privacy-First Telemetry: Optional anonymous usage analytics—no PII collected

How File Permissions Work

RivonClaw 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 RivonClaw can cleanly pull upstream OpenClaw updates.

Prerequisites

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

Quick Start

# 1. Clone the repository
git clone https://github.com/nicepkg/rivonclaw.git
cd rivonclaw

# 2. Clone and build the vendored OpenClaw runtime (applies vendor patches automatically)
./scripts/setup-vendor.sh

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

# 4. Launch in dev mode
pnpm --filter @rivonclaw/desktop dev

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

Repository Structure

rivonclaw/
├── apps/
│   ├── desktop/          # Electron tray app (main process)
│   └── panel/            # React management UI (served by desktop)
├── 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/
│   ├── rivonclaw-policy/      # OpenClaw plugin shell for policy injection
│   ├── rivonclaw-tools/       # Owner-only custom tools plugin
│   ├── rivonclaw-file-permissions/  # OpenClaw plugin for file access control
│   └── rivonclaw-mobile-chat-channel/  # Mobile messaging relay plugin
├── scripts/
│   ├── test-local.sh             # Local test pipeline (build + unit + e2e tests)
│   ├── publish-release.sh        # Publish draft GitHub Release
│   └── rebuild-native.sh         # Prebuild better-sqlite3 for Node.js + Electron
└── vendor/
    └── openclaw/         # Vendored OpenClaw binary (gitignored)

Workspaces

The monorepo uses pnpm workspaces (apps/*, packages/*, extensions/*) with Turbo for build orchestration. All packages produce ESM output via tsdown.

Apps

| Package | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | @rivonclaw/desktop | Electron 40 tray app. Manages gateway lifecycle, hosts the panel server on port 3210, stores data in SQLite. | | @rivonclaw/panel | React 19 + Vite 6 SPA. Pages for chat, rules, providers, channels, permissions, STT, usage, skills marketplace, and a first-launch onboarding wizard. |

Extensions

| Package | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | @rivonclaw/rivonclaw-policy | Thin OpenClaw plugin shell that wires policy injection into the gateway's before_agent_start hook. | | @rivonclaw/rivonclaw-tools | Owner-only custom tools plugin (e.g. system control, desktop integration). | | @rivonclaw/file-permissions | OpenClaw plugin that enforces file access permissions by intercepting and validating tool calls before execution. | | @rivonclaw/rivonclaw-mobile-chat-channel | Mobile PWA messaging relay — bridges mobile chat clients to the gateway via WebSocket. |

Packages

| Package | Description | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | @rivonclaw/core | Zod-validated types: Rule, ChannelConfig, PermissionConfig, ModelConfig, LLM provider definitions (20+ providers including subscription/coding plans and Ollama), region-aware defaults. | | @rivonclaw/gateway | GatewayLauncher (spawn/stop/restart with exponential backoff), config writer, secret injection from system keychain, Gemini CLI OAuth flow, auth profile sync, skills directory watcher for hot reload. | | @rivonclaw/logger | tslog-based logger. Writes to ~/.rivonclaw/logs/. | | @rivonclaw/storage | SQLite via better-sqlite3. Repositories for rules, artifacts, channels, permissions, settings. Migration system included. DB at ~/.rivonclaw/rivonclaw.db. | | @rivonclaw/rules | Rule compilation, skill lifecycle (activate/deactivate), skill file writer that materializes rules as SKILL.md files for OpenClaw. | | @rivonclaw/secrets | Platform-aware secret storage. macOS Keychain, file-based fallback, in-memory for tests. | | @rivonclaw/updater | Checks update-manifest.json on the website, notifies user of new versions.

Rivonclaw

Install / Use

README