LightClaw

LightClaw is a self-hosted Telegram AI agent inspired by OpenClaw: a Python codebase with persistent local memory, multi-provider LLM routing, skills, and local multi-agent delegation.

If you are searching for an OpenClaw alternative, OpenClaw in Python, or a Telegram AI bot with memory, this project is built for that workflow.

Security Disclaimer

LightClaw can execute impactful actions (file edits and delegated local agent runs). It fails closed unless numeric TELEGRAM_ALLOWED_USERS are configured; public access requires the explicit LIGHTCLAW_PUBLIC_BOT_ACK=yes override. Use least-privilege credentials and review installed skills.

Read the security policy and threat model before exposing a bot.

Why LightClaw

• Lightweight and forkable: understand the core quickly and customize without framework overhead.
• Practical for solo builders: run on small VPS machines with minimal setup.
• Built for real usage: memory recall, file operations, skills, and delegated coding agents.

Core Features

• Persistent SQLite memory with local lexical recall.
• 6 LLM providers: OpenAI, xAI, Anthropic, Gemini, DeepSeek, Z-AI.
• Telegram-first experience with command-driven workflow.
• Local terminal chat mode (lightclaw chat) using the same runtime stack.
• Skills system (hub + local skills).
• Local agent delegation (codex, claude) for large coding tasks.
• Smart multi-agent orchestration with auto-planning, dependencies, and confirmation flow.
• Workspace-native code generation/editing with compact delta reports.
• Optional voice transcription with Groq Whisper.

Quick Start

1) One-command setup (recommended)

git clone https://github.com/OthmaneBlial/lightclaw.git && cd lightclaw && bash setup.sh

setup.sh does everything automatically:

• Installs the lightclaw command at ~/.local/bin/lightclaw
• Writes private app config to ~/.config/lightclaw/config.env
• Creates runtime files in ~/.lightclaw

Then run:

lightclaw run

If your shell has not reloaded PATH yet, use:

~/.local/bin/lightclaw run

2) Manual setup

git clone https://github.com/OthmaneBlial/lightclaw.git
cd lightclaw
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
lightclaw onboard

Then edit ~/.config/lightclaw/config.env and start:

lightclaw run

Minimal App Config Example

# Provider selection
LLM_PROVIDER=openai
LLM_MODEL=latest

# Provider keys (fill what you use)
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
ANTHROPIC_AUTH_TOKEN=
ANTHROPIC_BASE_URL=
DEEPSEEK_API_KEY=

# Telegram
TELEGRAM_BOT_TOKEN=
TELEGRAM_ALLOWED_USERS=123456789
LIGHTCLAW_PUBLIC_BOT_ACK=no

# Optional generation tuning
MAX_OUTPUT_TOKENS=12000

# Local delegated agents
LOCAL_AGENT_TIMEOUT_SEC=1800
LOCAL_AGENT_PROGRESS_INTERVAL_SEC=30
LOCAL_AGENT_MULTI_DEFAULT_AGENTS=claude,codex
LOCAL_AGENT_MULTI_AUTO_CONTINUE=no
LOCAL_AGENT_MULTI_REPAIR_ATTEMPTS=1
LOCAL_AGENT_SAFETY_MODE=strict
LOCAL_AGENT_CAPABILITY_PROFILE=workspace-write
LOCAL_AGENT_DENY_PATTERNS=

# Skills
SKILLS_HUB_BASE_URL=https://clawhub.ai
SKILLS_STATE_PATH=.lightclaw/skills_state.json

CLI Commands

lightclaw onboard
lightclaw onboard --reset-env
lightclaw onboard --configure
lightclaw doctor
lightclaw doctor --json
lightclaw run
lightclaw run --provider deepseek --model deepseek-chat
lightclaw chat
lightclaw undo <task-workspace-label>
lightclaw uninstall --dry-run

See the complete install, upgrade, undo, and uninstall guide.

Telegram / Chat Commands

Smart Multi-Agent Mode

Full guide with many usage examples: MULTI_AGENT.md

/agent multi supports three ways to define worker assignment:

1. Auto mode:

/agent multi build a full stack todo app

1. Preferred agents (no labels):

/agent multi @claude @codex build a full stack todo app

1. Explicit roster override (backward compatible):

/agent multi --agent backend=codex --agent frontend=claude --agent docs=codex build a full stack todo app

You can also declare explicit dependencies in the DAG:

/agent multi --agent backend=codex --agent frontend=claude --agent integration=claude --depends-on integration=backend,frontend build the app

With explicit rosters, dependency hints in the goal are still respected when you do not pass --depends-on. Example:

/agent multi --agent backend=codex --agent frontend=claude --agent integration=claude build the app, keep backend and frontend parallel, and make integration wait for backend and frontend

How it runs:

• Plan is generated and shown first.
• Confirmation is required by default (confirm, yes) unless LOCAL_AGENT_MULTI_AUTO_CONTINUE=yes.
• edit lets you iterate the plan before execution.
• cancel or no clears the pending plan.
• Execution now follows true DAG scheduling, so downstream lanes can start as soon as their own dependencies finish.
• Each worker gets owned paths, must write handoff/<lane>.md plus handoff/<lane>.json, and is checked against lightweight acceptance rules.
• The same contract system now handles non-coding lanes too, including research, analysis, authoring, and review/validation roles.
• Acceptance can now run small bounded repo-local commands when a lane declares command_succeeds.
• Backend/frontend lanes also get automatic handoff JSON field checks, so outputs.endpoints and outputs.api_calls must actually be populated.
• Docs/authoring lanes now get the same treatment via outputs.deliverables, so non-code artifacts are tracked in a machine-readable way too.
• Research/review and docs/authoring runs now also get lightweight cross-lane findings/deliverables audits in the final report.
• Backend/frontend runs also get a lightweight cross-lane API audit from handoff JSON, so method/path mismatches are surfaced in the final report.
• Failed lanes can get a small self-repair pass controlled by LOCAL_AGENT_MULTI_REPAIR_ATTEMPTS (clamped to 0..2).

Supported Providers

Quick provider check:

python scripts/provider_smoke_test.py

Skills (Hub + Local)

Examples:

/skills search sonos
/skills add sonoscli
/skills use sonoscli
/skills off sonoscli
/skills create my_custom_skill "My private workflow"

Paths:

• Hub skills: ~/.lightclaw/skills/hub/<slug>/SKILL.md
• Local skills: ~/.lightclaw/skills/local/<name>/SKILL.md

Architecture (Short)

Telegram or terminal chat
  -> memory recall (SQLite + semantic search)
  -> provider routing (OpenAI/xAI/Claude/Gemini/DeepSeek/Z-AI)
  -> response + optional file operations in ~/.lightclaw/workspace
  -> optional delegated local agents (single or multi-worker)

OpenClaw and LightClaw

• OpenClaw: larger TypeScript platform for broad, multi-app orchestration.
• LightClaw: focused Python core for fast local customization and Telegram-first workflows.

OpenClaw links:

• https://github.com/openclaw/openclaw
• https://docs.openclaw.ai/

Requirements

• Python 3.10+
• Telegram bot token from @BotFather
• API credentials for at least one supported LLM provider
• Optional: Groq API key for voice transcription

License

MIT

LightClaw is intentionally small: easy to read, easy to fork, and fast to ship.