OptimClaw

OptimClaw

Your secure personal AI assistant, always on your side

License: MIT OR Apache-2.0 Telegram: @optimclawAI Reddit: r/optimclawAI gitcgr

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

Philosophy • Features • Mesh Cluster • Lazy Tools • Installation • Configuration • Security • Architecture

--- ## Philosophy OptimClaw is built on a simple principle: **your AI assistant should work for you, not against you**. In a world where AI systems are increasingly opaque about data handling and aligned with corporate interests, OptimClaw takes a different approach: - **Your data stays yours** - All information is stored locally, encrypted, and never leaves your control - **Transparency by design** - Open source, auditable, no hidden telemetry or data harvesting - **Self-expanding capabilities** - Build new tools on the fly without waiting for vendor updates - **Defense in depth** - Multiple security layers protect against prompt injection and data exfiltration OptimClaw is the AI assistant you can actually trust with your personal and professional life. ## Features ### Security First - **WASM Sandbox** - Untrusted tools run in isolated WebAssembly containers with capability-based permissions - **Credential Protection** - Secrets are never exposed to tools; injected at the host boundary with leak detection - **Prompt Injection Defense** - Pattern detection, content sanitization, and policy enforcement - **Endpoint Allowlisting** - HTTP requests only to explicitly approved hosts and paths ### Always Available - **Multi-channel** - REPL, HTTP webhooks, WASM channels (Telegram, Slack), and web gateway - **Docker Sandbox** - Isolated container execution with per-job tokens and orchestrator/worker pattern - **Web Gateway** - Browser UI with real-time SSE/WebSocket streaming - **Routines** - Cron schedules, event triggers, webhook handlers for background automation - **Heartbeat System** - Proactive background execution for monitoring and maintenance tasks - **Parallel Jobs** - Handle multiple requests concurrently with isolated contexts - **Self-repair** - Automatic detection and recovery of stuck operations ### Self-Expanding - **Dynamic Tool Building** - Describe what you need, and OptimClaw builds it as a WASM tool - **MCP Protocol** - Connect to Model Context Protocol servers for additional capabilities - **Plugin Architecture** - Drop in new WASM tools and channels without restarting ### Persistent Memory - **Hybrid Search** - Full-text + vector search using Reciprocal Rank Fusion - **Workspace Filesystem** - Flexible path-based storage for notes, logs, and context - **Identity Files** - Maintain consistent personality and preferences across sessions ## Mesh Cluster OptimClaw instances can form an **autonomous AI mesh network** where nodes discover each other automatically, coordinate via a gossip protocol, and route tasks intelligently across the cluster. Key highlights: - **Zero-config discovery** -- UDP beacon broadcast finds peers on the local network automatically - **Post-quantum encryption** -- ML-KEM-768 key exchange with AES-256-GCM authenticated encryption protects all inter-node traffic against both classical and quantum adversaries - **SWIM gossip membership** -- Reliable failure detection and cluster state convergence in O(log N) rounds - **Intelligent task routing** -- A scoring algorithm balances load, latency, capability match, session affinity, and region locality to pick the best node for each task - **Graceful degradation** -- Nodes operate independently if connectivity is lost; no split-brain data corruption Quick start (two nodes on one machine): ```bash # Terminal 1 export CLUSTER_ENABLED=true CLUSTER_SECRET="your-32-char-secret-here-change-me" CLUSTER_NODE_ID=node-a cargo run # Terminal 2 export CLUSTER_ENABLED=true CLUSTER_SECRET="your-32-char-secret-here-change-me" CLUSTER_NODE_ID=node-b CLUSTER_BIND_PORT=9410 cargo run ``` Monitor via `GET /api/mesh/status` and `GET /api/mesh/nodes`. See [docs/MESH_CLUSTER.md](docs/MESH_CLUSTER.md) for the full guide covering architecture, configuration reference, security model, and troubleshooting. ## Lazy Tools Lazy tool loading reduces the system prompt from approximately 13,000 tokens to approximately 4,000 tokens by deferring tool schemas that are not immediately needed. Enable it with: ```bash export OPTIMCLAW_LAZY_TOOLS=1 ``` When enabled, 12 core tools (echo, time, json, http, web_fetch, file_read, file_write, shell, memory_search, memory_write, message, tool_info) are loaded eagerly. All other tools -- including MCP, WASM, and skill tools -- are listed by name only. The LLM calls `tool_info` to load the full schema for any additional tool on demand. This is recommended for production deployments and cost-sensitive usage with expensive models. See [docs/LAZY_TOOLS.md](docs/LAZY_TOOLS.md) for the full guide. ## Installation ### Prerequisites - Rust 1.85+ - PostgreSQL 15+ with [pgvector](https://github.com/pgvector/pgvector) extension - NEAR AI account (authentication handled via setup wizard) ## Download or Build Visit [Releases page](https://github.com/nearai/optimclaw/releases/) to see the latest updates.
Install via Windows Installer (Windows) Download the [Windows Installer](https://github.com/nearai/optimclaw/releases/latest/download/optimclaw-x86_64-pc-windows-msvc.msi) and run it.
Install via powershell script (Windows) ```sh irm https://github.com/nearai/optimclaw/releases/latest/download/optimclaw-installer.ps1 | iex ```
Install via shell script (macOS, Linux, Windows/WSL) ```sh curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/optimclaw/releases/latest/download/optimclaw-installer.sh | sh ```
Install via Homebrew (macOS/Linux) ```sh brew install optimclaw ```
Compile the source code (Cargo on Windows, Linux, macOS) Install it with `cargo`, just make sure you have [Rust](https://rustup.rs) installed on your computer. ```bash # Clone the repository git clone https://github.com/nearai/optimclaw.git cd optimclaw # Build cargo build --release # Run tests cargo test ``` For **full release** (after modifying channel sources), run `./scripts/build-all.sh` to rebuild channels first.
### Database Setup ```bash # Create database createdb optimclaw # Enable pgvector psql optimclaw -c "CREATE EXTENSION IF NOT EXISTS vector;" ``` ## Configuration Run the setup wizard to configure OptimClaw: ```bash optimclaw onboard ``` The wizard handles database connection, NEAR AI authentication (via browser OAuth), and secrets encryption (using your system keychain). Settings are persisted in the connected database; bootstrap variables (e.g. `DATABASE_URL`, `LLM_BACKEND`) are written to `~/.optimclaw/.env` so they are available before the database connects. ### Alternative LLM Providers OptimClaw defaults to NEAR AI but supports many LLM providers out of the box. Built-in providers include **Anthropic**, **OpenAI**, **GitHub Copilot**, **Google Gemini**, **MiniMax**, **Mistral**, and **Ollama** (local). OpenAI-compatible services like **OpenRouter** (300+ models), **Together AI**, **Fireworks AI**, and self-hosted servers (**vLLM**, **LiteLLM**) are also supported. Select your provider in the wizard, or set environment variables directly: ```env # Example: MiniMax (built-in, 204K context) LLM_BACKEND=minimax MINIMAX_API_KEY=... # Example: OpenAI-compatible endpoint LLM_BACKEND=openai_compatible LLM_BASE_URL=https://openrouter.ai/api/v1 LLM_API_KEY=sk-or-... LLM_MODEL=anthropic/claude-sonnet-4 ``` See [docs/LLM_PROVIDERS.md](docs/LLM_PROVIDERS.md) for a full provider guide. ## Security OptimClaw implements defense in depth to protect your data and prevent misuse. ### WASM Sandbox All untrusted tools run in isolated WebAssembly containers: - **Capability-based permissions** - Explicit opt-in for HTTP, secrets, tool invocation - **Endpoint allowlisting** - HTTP requests only to approved hosts/paths - **Credential injection** - Secrets injected at host boundary, never exposed to WASM code - **Leak detection** - Scans requests and responses for secret exfiltration attempts - **Rate limiting** - Per-tool request limits to prevent abuse - **Resource limits** - Memory, CPU, and execution time constraints ``` WASM ──► Allowlist ──► Leak Scan ──► Credential ──► Execute ──► Leak Scan ──► WASM Validator (request) Injector Request (response) ``` ### Prompt Injection Defense External content passes through multiple security layers: - Pattern-based detection of injection attempts - Content sanitization and escaping - Policy rules with severity levels (Block/Warn/Review/Sanitize) - Tool output wrapping for safe LLM context injection ### Data Protection - All data stored locally in your PostgreSQL database - Secrets encrypted with AES-256-GCM - No telemetry, analytics, or data sharing - Full audit log of all tool executions ## Architecture ``` ┌────────────────────────────────────────────────────────────────┐ │ Channels │ │ ┌──────┐ ┌──────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ REPL │ │ HTTP │ │WASM Channels│ │ Web Gateway │ │ │ └──┬───┘ └──┬───┘ └──────┬──────┘ │ (SSE + WS) │ │ │ │ │ │ └──────┬──────┘ │ │ └─────────┴──────────────┴────────────────┘ │ │ │ │ │ ┌─────────▼─────────┐ │ │ │ Agent Loop │ Intent routing │ │ └────┬──────────┬───┘ │ │ │ │ │ │ ┌──────────▼────┐ ┌──▼───────────────┐ │ │ │ Scheduler │ │ Routines Engine │ │ │ │(parallel jobs)│ │(cron, event, wh) │ │ │ └──────┬────────┘ └────────┬─────────┘ │ │ │ │ │ │ ┌─────────────┼────────────────────┘ │ │ │ │ │ │ ┌───▼─────┐ ┌────▼────────────────┐ │ │ │ Local │ │ Orchestrator │ │ │ │Workers │ │ ┌───────────────┐ │ │ │ │(in-proc)│ │ │ Docker Sandbox│ │ │ │ └───┬─────┘ │ │ Containers │ │ │ │ │ │ │ ┌───────────┐ │ │ │ │ │ │ │ │Worker / CC│ │ │ │ │ │ │ │ └───────────┘ │ │ │ │ │ │ └───────────────┘ │ │ │ │ └─────────┬───────────┘ │ │ └──────────────────┤ │ │ │ │ │ ┌───────────▼──────────┐ │ │ │ Tool Registry │ │ │ │ Built-in, MCP, WASM │ │ │ └──────────────────────┘ │ └────────────────────────────────────────────────────────────────┘ ``` ### Core Components | Component | Purpose | |-----------|---------| | **Agent Loop** | Main message handling and job coordination | | **Router** | Classifies user intent (command, query, task) | | **Scheduler** | Manages parallel job execution with priorities | | **Worker** | Executes jobs with LLM reasoning and tool calls | | **Orchestrator** | Container lifecycle, LLM proxying, per-job auth | | **Web Gateway** | Browser UI with chat, memory, jobs, logs, extensions, routines | | **Routines Engine** | Scheduled (cron) and reactive (event, webhook) background tasks | | **Workspace** | Persistent memory with hybrid search | | **Safety Layer** | Prompt injection defense and content sanitization | ## Usage ```bash # First-time setup (configures database, auth, etc.) optimclaw onboard # Start interactive REPL cargo run # With debug logging RUST_LOG=optimclaw=debug cargo run ``` ## Development ```bash # Format code cargo fmt # Lint cargo clippy --all --benches --tests --examples --all-features # Run tests createdb optimclaw_test cargo test # Run specific test cargo test test_name ``` - **Telegram channel**: See [docs/TELEGRAM_SETUP.md](docs/TELEGRAM_SETUP.md) for setup and DM pairing. - **Changing channel sources**: Run `./channels-src/telegram/build.sh` before `cargo build` so the updated WASM is bundled. ## OpenClaw Heritage OptimClaw is a Rust reimplementation inspired by [OpenClaw](https://github.com/openclaw/openclaw). See [FEATURE_PARITY.md](FEATURE_PARITY.md) for the complete tracking matrix. Key differences: - **Rust vs TypeScript** - Native performance, memory safety, single binary - **WASM sandbox vs Docker** - Lightweight, capability-based security - **PostgreSQL vs SQLite** - Production-ready persistence - **Security-first design** - Multiple defense layers, credential protection ## License Licensed under either of: - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)) - MIT License ([LICENSE-MIT](LICENSE-MIT)) at your option.