Tiny-OpenClaw is a highly extensible, asynchronous agentic AI framework designed to interact seamlessly via Telegram. Built around the powerful ReAct (Reasoning + Acting) paradigm, it acts as a robust runtime for Large Language Models (LLMs), giving them the ability to use custom tools, access long-term memory, and maintain session context across interactions.
This project was developed with a focus on scalability, reliability, and extensibility, serving as a blueprint for production-grade AI agents.
Tiny-OpenClaw is architected for high performance and clean separation of concerns.
At its core, the system utilizes a custom ReAct loop that interfaces with the Anthropic API (Claude Opus). Instead of static query-response pipelines, the agent can:
- Reason about the user's request.
- Act by invoking one or multiple loaded skills (tools).
- Observe the output and recursively iterate until the goal is met.
- Challenge: Initially, session histories and long-term user memories were persisted using local JSON files, which presented significant bottlenecks for concurrent access and horizontal scaling.
- Solution: I introduced Redis as the central data store for both
Memory(memory_store.py) andSessionManager(session_manager.py). - Impact: This transition eliminated file I/O locks, enabled atomic operations, and decoupled state from the application runtime, paving the way for multi-instance deployments.
The platform supports hot-loading of capabilities. Skills are distinct modules automatically discovered and loaded at runtime. This plugin-like architecture ensures that the core loop remains isolated from specific tool logic, following the Open-Closed Principle.
Current Built-in Skills:
browser_use: Empowers the agent to autonomously navigate the web, click elements, fill forms, and extract content using Playwright.datetime: Provides real-time temporal awareness.memory_work: Enables the agent to perform long-term recall and contextual note-taking.
Adding Future Skills:
Because of the modular design, adding new capabilities (like API integrations, database querying, or third-party webhooks) is as simple as dropping a new folder into the skills/ directory with a handler.py defining the tools and execution logic!
The entire application stack—from API calls (httpx) to Telegram webhook polling (python-telegram-bot) and file handling—utilizes Python's asyncio. This non-blocking architecture allows the bot to handle multiple users simultaneously without thread starvation.
To ensure zero-friction deployment and environment consistency, the application is fully containerized.
- Dockerized: The Python runtime is containerized using a slim base image for optimal footprint.
- Docker Compose: Orchestrates both the Tiny-OpenClaw agent container and the Redis datastore, handling networking and environment variable ingestion out of the box.
| Category | Technologies |
|---|---|
| Language & Concurrency | Python 3.11+, asyncio |
| AI / LLM Integration | Anthropic API (Claude), ReAct Pattern |
| Memory & Storage | Redis |
| Bot Framework | python-telegram-bot |
| Containerization | Docker, Docker Compose |
- Docker & Docker Compose
- Telegram Bot Token (from @BotFather)
- Anthropic API Key
-
Clone the repository:
git clone https://github.com/omer-here/tiny-openclaw.git cd tiny-openclaw -
Configure Environment:
cp .env.sample .env # Edit .env and add your ANTHROPIC_API_KEY and TELEGRAM_BOT_TOKEN -
Run via Docker Compose:
docker-compose up --build -d
-
Interact: Open Telegram and start messaging your bot!
- User: "What's on my schedule today, and remember that my favorite color is cyan."
- Agent Reason: I need to use the
datetimeskill to get the current date, and thememory_workskill to save the user's favorite color. - Agent Action:
- Calls
save_memory(key="favorite_color", value="cyan") - Calls
get_current_time()
- Calls
- Agent Response: "It's currently [Time]. I've also noted that your favorite color is cyan! What's next?"