VelaClaw 🕷️

Protocol-driven autonomous AI agent runtime with intelligent model selection and multi-model negotiation.

English · 简体中文

Contributing · ai-lib migration (matrix & env)

Overview

VelaClaw is a Rust-first autonomous AI agent runtime that integrates with the ai-protocol ecosystem for intelligent, protocol-driven AI operations.

Key Features

Quick Start

Prerequisites

• Rust 1.70+ (2021 edition)
• A local ai-protocol checkout for provider manifests

Build

# Clone the repository
git clone https://github.com/ailib-official/velaclaw.git
cd velaclaw

# Build with default protocol support
cargo build

Cross-Compile for Raspberry Pi (aarch64)

# Install target
rustup target add aarch64-unknown-linux-gnu

# Build release binary
cargo build --release --target aarch64-unknown-linux-gnu

# Binary location
ls target/aarch64-unknown-linux-gnu/release/velaclaw

Run

# Enable smart model selection
cargo run --features smart-routing -- --smart

# Enable multi-model negotiation
cargo run --features multi-model -- --negotiate

# Run with the default protocol model id (openai/gpt-5.2)
cargo run -- agent -m "Hello"

Web Chat UI

With the gateway running (velaclaw daemon), open http://127.0.0.1:8080/chat in your browser for the local Web Chat UI.

1. Pair once: POST http://127.0.0.1:8080/pair with your pairing code, then paste the bearer token into the chat UI.
2. Select a model from the dropdown (requires BYOK credentials for providers in your ai-protocol checkout).
3. Messages stream over WebSocket (/ws) using the same agent loop as the CLI.

For frontend development, run npm ci && npm run dev inside ui-chat/ (Vite proxies API calls to the gateway).

Configuration

Environment Variables

# AI Protocol directory (for protocol-driven providers)
# Clone from: git clone https://github.com/ailib-official/ai-protocol
export AI_PROTOCOL_DIR=/path/to/ai-protocol

# Provider API keys declared by ai-protocol manifests
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

Config File

# ~/.velaclaw/config.toml
default_provider = "openai/gpt-5.2"
default_model = "openai/gpt-5.2"

Documentation

• User Guide (Chinese) - Complete user documentation
• Integration Guide - Developer integration guide
• Upstream Requirements - Requirements for ai-lib-rust and ai-protocol

User Guide Chapters

1. Getting Started
2. Basic Concepts
3. Chat with AI
4. Providers
5. Smart Routing
6. Channels
7. Telegram
8. Tools
9. Negotiation
10. Automation
11. Deployment
12. Remote Deployment
13. Security
14. Commands
15. Configuration
16. FAQ

Feature Flags

Dashboard

When running the gateway (velaclaw gateway), a monitoring dashboard is available at GET /dashboard:

• Status: Health and pairing state
• Cost: Session, daily, monthly costs and token usage (when [cost] enabled = true)
• Runtime: Component health snapshot

The dashboard auto-refreshes every 30 seconds.

Remote Deployment

VelaClaw supports controlled remote deployment via SSH with the --features remote-deploy flag.

Deploy Commands

# Deploy to a remote server
velaclaw deploy deploy --server <server-id>

# Check deployment status
velaclaw deploy status --server <server-id>

# Run health check
velaclaw deploy health-check --server <server-id>

# List configured deployment targets
velaclaw deploy list

# Rollback to previous deployment
velaclaw deploy rollback --server <server-id>

# Update to new version
velaclaw deploy update --server <server-id> --version <version>

# Sync configuration
velaclaw deploy sync-config --server <server-id>

Configuration

Configure deployment targets in your config.toml:

[deploy]
[[deploy.servers]]
id = "prod-001"
host = "192.168.1.100"
port = 22
user = "deploy"
ssh_key = "~/.ssh/id_ed25519"
labels = ["env:production", "region:us-west"]

[deploy.settings]
mode = "direct"  # Options: direct, docker, systemd
binary_path = "/usr/local/bin/velaclaw"
working_dir = "/opt/velaclaw"
auto_start = true
health_check_interval_secs = 30
restart_on_failure = true
max_restarts = 3

Architecture

VelaClaw uses a trait-driven, modular architecture:

• Providers: AI model backends (OpenAI, Anthropic, local models, etc.)
• Channels: Communication platforms (Telegram, Discord, Matrix, etc.)
• Tools: Extensible tool execution (shell, file, browser, etc.)
• Memory: Persistent storage backends (SQLite, PostgreSQL, etc.)
• Security: Policy enforcement and secret management

Upstream Dependencies

VelaClaw integrates with:

• ai-lib-rust - Protocol-driven AI API client (crates.io, enable with --features ai-protocol)
• ai-protocol - Provider YAML configs (clone and set AI_PROTOCOL_DIR)

Sync with Upstream

VelaClaw tracks velaclaw-labs/velaclaw for updates:

# List upstream changes
./sync-upstream.sh --list

# Preview merge
./sync-upstream.sh --dry-run

# Merge upstream
./sync-upstream.sh

# Cherry-pick specific commit
./sync-upstream.sh --cherry-pick <commit-hash>

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Author

Luqiang Wang

Acknowledgments

VelaClaw is a fork of VelaClaw with additional features:

• ai-protocol integration
• Provider scoring and smart routing
• Multi-model negotiation
• Parallel task execution
• Remote deployment