594 lines
16 KiB
Markdown
594 lines
16 KiB
Markdown
<div align="center">
|
||
<img src="assets/logo.jpg" alt="PicoClaw" width="512">
|
||
|
||
<h1>PicoClaw: Ultra-Efficient AI Assistant in Go</h1>
|
||
|
||
<h3>$10 Hardware · 10MB RAM · 1s Boot · 皮皮虾，我们走！</h3>
|
||
<h3></h3>
|
||
|
||
<p>
|
||
<img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
|
||
<img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20RISC--V-blue" alt="Hardware">
|
||
<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
|
||
</p>
|
||
|
||
[日本語](README.ja.md) | **English**
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
🦐 PicoClaw is an ultra-lightweight personal AI Assistant inspired by [nanobot](https://github.com/HKUDS/nanobot), refactored from the ground up in Go through a self-bootstrapping process, where the AI agent itself drove the entire architectural migration and code optimization.
|
||
|
||
⚡️ Runs on $10 hardware with <10MB RAM: That's 99% less memory than OpenClaw and 98% cheaper than a Mac mini!
|
||
|
||
<table align="center">
|
||
<tr align="center">
|
||
<td align="center" valign="top">
|
||
<p align="center">
|
||
<img src="assets/picoclaw_mem.gif" width="360" height="240">
|
||
</p>
|
||
</td>
|
||
<td align="center" valign="top">
|
||
<p align="center">
|
||
<img src="assets/licheervnano.png" width="400" height="240">
|
||
</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
## 📢 News
|
||
|
||
2026-02-09 🎉 PicoClaw Launched! Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 皮皮虾，我们走！
|
||
|
||
## ✨ Features
|
||
|
||
🪶 **Ultra-Lightweight**: <10MB Memory footprint — 99% smaller than Clawdbot - core functionality.
|
||
|
||
💰 **Minimal Cost**: Efficient enough to run on $10 Hardware — 98% cheaper than a Mac mini.
|
||
|
||
⚡️ **Lightning Fast**: 400X Faster startup time, boot in 1 second even in 0.6GHz single core.
|
||
|
||
🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, and x86, One-click to Go!
|
||
|
||
🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement.
|
||
|
||
| | OpenClaw | NanoBot | **PicoClaw** |
|
||
| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
|
||
| **Language** | TypeScript | Python | **Go** |
|
||
| **RAM** | >1GB | >100MB | **< 10MB** |
|
||
| **Startup**</br>(0.8GHz core) | >500s | >30s | **<1s** |
|
||
| **Cost** | Mac Mini 599$ | Most Linux SBC </br>~50$ | **Any Linux Board**</br>**As low as 10$** |
|
||
|
||
<img src="assets/compare.jpg" alt="PicoClaw" width="512">
|
||
|
||
## 🦾 Demonstration
|
||
|
||
### 🛠️ Standard Assistant Workflows
|
||
|
||
<table align="center">
|
||
<tr align="center">
|
||
<th><p align="center">🧩 Full-Stack Engineer</p></th>
|
||
<th><p align="center">🗂️ Logging & Planning Management</p></th>
|
||
<th><p align="center">🔎 Web Search & Learning</p></th>
|
||
</tr>
|
||
<tr>
|
||
<td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
|
||
<td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
|
||
<td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center">Develop • Deploy • Scale</td>
|
||
<td align="center">Schedule • Automate • Memory</td>
|
||
<td align="center">Discovery • Insights • Trends</td>
|
||
</tr>
|
||
</table>
|
||
|
||
### 🐜 Innovative Low-Footprint Deploy
|
||
|
||
PicoClaw can be deployed on almost any Linux device!
|
||
|
||
- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) version, for Minimal Home Assistant
|
||
- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) for Automated Server Maintenance
|
||
- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) for Smart Monitoring
|
||
|
||
<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
|
||
|
||
🌟 More Deployment Cases Await！
|
||
|
||
## 📦 Install
|
||
|
||
### Install with precompiled binary
|
||
|
||
Download the firmware for your platform from the [release](https://github.com/sipeed/picoclaw/releases) page.
|
||
|
||
### Install from source (latest features, recommended for development)
|
||
|
||
```bash
|
||
git clone https://github.com/sipeed/picoclaw.git
|
||
|
||
cd picoclaw
|
||
make deps
|
||
|
||
# Build, no need to install
|
||
make build
|
||
|
||
# Build for multiple platforms
|
||
make build-all
|
||
|
||
# Build And Install
|
||
make install
|
||
```
|
||
|
||
## 🐳 Docker Compose
|
||
|
||
You can also run PicoClaw using Docker Compose without installing anything locally.
|
||
|
||
```bash
|
||
# 1. Clone this repo
|
||
git clone https://github.com/sipeed/picoclaw.git
|
||
cd picoclaw
|
||
|
||
# 2. Set your API keys
|
||
cp config/config.example.json config/config.json
|
||
vim config/config.json # Set DISCORD_BOT_TOKEN, API keys, etc.
|
||
|
||
# 3. Build & Start
|
||
docker compose --profile gateway up -d
|
||
|
||
# 4. Check logs
|
||
docker compose logs -f picoclaw-gateway
|
||
|
||
# 5. Stop
|
||
docker compose --profile gateway down
|
||
```
|
||
|
||
### Agent Mode (One-shot)
|
||
|
||
```bash
|
||
# Ask a question
|
||
docker compose run --rm picoclaw-agent -m "What is 2+2?"
|
||
|
||
# Interactive mode
|
||
docker compose run --rm picoclaw-agent
|
||
```
|
||
|
||
### Rebuild
|
||
|
||
```bash
|
||
docker compose --profile gateway build --no-cache
|
||
docker compose --profile gateway up -d
|
||
```
|
||
|
||
### 🚀 Quick Start
|
||
|
||
> [!TIP]
|
||
> Set your API key in `~/.picoclaw/config.json`.
|
||
> Get API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
|
||
> Web search is **optional** - get free [Brave Search API](https://brave.com/search/api) (2000 free queries/month) or use built-in auto fallback.
|
||
|
||
**1. Initialize**
|
||
|
||
```bash
|
||
picoclaw onboard
|
||
```
|
||
|
||
**2. Configure** (`~/.picoclaw/config.json`)
|
||
|
||
```json
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"workspace": "~/.picoclaw/workspace",
|
||
"model": "glm-4.7",
|
||
"max_tokens": 8192,
|
||
"temperature": 0.7,
|
||
"max_tool_iterations": 20
|
||
}
|
||
},
|
||
"providers": {
|
||
"openrouter": {
|
||
"api_key": "xxx",
|
||
"api_base": "https://openrouter.ai/api/v1"
|
||
}
|
||
},
|
||
"tools": {
|
||
"web": {
|
||
"search": {
|
||
"api_key": "YOUR_BRAVE_API_KEY",
|
||
"max_results": 5
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**3. Get API Keys**
|
||
|
||
- **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
|
||
- **Web Search** (optional): [Brave Search](https://brave.com/search/api) - Free tier available (2000 requests/month)
|
||
|
||
> **Note**: See `config.example.json` for a complete configuration template.
|
||
|
||
**4. Chat**
|
||
|
||
```bash
|
||
picoclaw agent -m "What is 2+2?"
|
||
```
|
||
|
||
That's it! You have a working AI assistant in 2 minutes.
|
||
|
||
---
|
||
|
||
## 💬 Chat Apps
|
||
|
||
Talk to your picoclaw through Telegram, Discord, or DingTalk
|
||
|
||
| Channel | Setup |
|
||
| ------------ | -------------------------- |
|
||
| **Telegram** | Easy (just a token) |
|
||
| **Discord** | Easy (bot token + intents) |
|
||
| **QQ** | Easy (AppID + AppSecret) |
|
||
| **DingTalk** | Medium (app credentials) |
|
||
|
||
<details>
|
||
<summary><b>Telegram</b> (Recommended)</summary>
|
||
|
||
**1. Create a bot**
|
||
|
||
- Open Telegram, search `@BotFather`
|
||
- Send `/newbot`, follow prompts
|
||
- Copy the token
|
||
|
||
**2. Configure**
|
||
|
||
```json
|
||
{
|
||
"channels": {
|
||
"telegram": {
|
||
"enabled": true,
|
||
"token": "YOUR_BOT_TOKEN",
|
||
"allowFrom": ["YOUR_USER_ID"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> Get your user ID from `@userinfobot` on Telegram.
|
||
|
||
**3. Run**
|
||
|
||
```bash
|
||
picoclaw gateway
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Discord</b></summary>
|
||
|
||
**1. Create a bot**
|
||
|
||
- Go to <https://discord.com/developers/applications>
|
||
- Create an application → Bot → Add Bot
|
||
- Copy the bot token
|
||
|
||
**2. Enable intents**
|
||
|
||
- In the Bot settings, enable **MESSAGE CONTENT INTENT**
|
||
- (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data
|
||
|
||
**3. Get your User ID**
|
||
|
||
- Discord Settings → Advanced → enable **Developer Mode**
|
||
- Right-click your avatar → **Copy User ID**
|
||
|
||
**4. Configure**
|
||
|
||
```json
|
||
{
|
||
"channels": {
|
||
"discord": {
|
||
"enabled": true,
|
||
"token": "YOUR_BOT_TOKEN",
|
||
"allowFrom": ["YOUR_USER_ID"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**5. Invite the bot**
|
||
|
||
- OAuth2 → URL Generator
|
||
- Scopes: `bot`
|
||
- Bot Permissions: `Send Messages`, `Read Message History`
|
||
- Open the generated invite URL and add the bot to your server
|
||
|
||
**6. Run**
|
||
|
||
```bash
|
||
picoclaw gateway
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>QQ</b></summary>
|
||
|
||
**1. Create a bot**
|
||
|
||
- Go to [QQ Open Platform](https://connect.qq.com/)
|
||
- Create an application → Get **AppID** and **AppSecret**
|
||
|
||
**2. Configure**
|
||
|
||
```json
|
||
{
|
||
"channels": {
|
||
"qq": {
|
||
"enabled": true,
|
||
"app_id": "YOUR_APP_ID",
|
||
"app_secret": "YOUR_APP_SECRET",
|
||
"allow_from": []
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
|
||
|
||
**3. Run**
|
||
|
||
```bash
|
||
picoclaw gateway
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>DingTalk</b></summary>
|
||
|
||
**1. Create a bot**
|
||
|
||
- Go to [Open Platform](https://open.dingtalk.com/)
|
||
- Create an internal app
|
||
- Copy Client ID and Client Secret
|
||
|
||
**2. Configure**
|
||
|
||
```json
|
||
{
|
||
"channels": {
|
||
"dingtalk": {
|
||
"enabled": true,
|
||
"client_id": "YOUR_CLIENT_ID",
|
||
"client_secret": "YOUR_CLIENT_SECRET",
|
||
"allow_from": []
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
|
||
|
||
**3. Run**
|
||
|
||
```bash
|
||
picoclaw gateway
|
||
```
|
||
|
||
</details>
|
||
|
||
## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network
|
||
|
||
Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App.
|
||
|
||
**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)**
|
||
|
||
## ⚙️ Configuration
|
||
|
||
Config file: `~/.picoclaw/config.json`
|
||
|
||
### Workspace Layout
|
||
|
||
PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`):
|
||
|
||
```
|
||
~/.picoclaw/workspace/
|
||
├── sessions/ # Conversation sessions and history
|
||
├── memory/ # Long-term memory (MEMORY.md)
|
||
├── cron/ # Scheduled jobs database
|
||
├── skills/ # Custom skills
|
||
├── AGENTS.md # Agent behavior guide
|
||
├── IDENTITY.md # Agent identity
|
||
├── SOUL.md # Agent soul
|
||
├── TOOLS.md # Tool descriptions
|
||
└── USER.md # User preferences
|
||
```
|
||
|
||
### Providers
|
||
|
||
> [!NOTE]
|
||
> Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed.
|
||
|
||
| Provider | Purpose | Get API Key |
|
||
| -------------------------- | --------------------------------------- | ------------------------------------------------------ |
|
||
| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) |
|
||
| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](bigmodel.cn) |
|
||
| `openrouter(To be tested)` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) |
|
||
| `anthropic(To be tested)` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) |
|
||
| `openai(To be tested)` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) |
|
||
| `deepseek(To be tested)` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) |
|
||
| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) |
|
||
|
||
<details>
|
||
<summary><b>Zhipu</b></summary>
|
||
|
||
**1. Get API key and base URL**
|
||
|
||
- Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
|
||
|
||
**2. Configure**
|
||
|
||
```json
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"workspace": "~/.picoclaw/workspace",
|
||
"model": "glm-4.7",
|
||
"max_tokens": 8192,
|
||
"temperature": 0.7,
|
||
"max_tool_iterations": 20
|
||
}
|
||
},
|
||
"providers": {
|
||
"zhipu": {
|
||
"api_key": "Your API Key",
|
||
"api_base": "https://open.bigmodel.cn/api/paas/v4"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**3. Run**
|
||
|
||
```bash
|
||
picoclaw agent -m "Hello"
|
||
```
|
||
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>Full config example</b></summary>
|
||
|
||
```json
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"model": "anthropic/claude-opus-4-5"
|
||
}
|
||
},
|
||
"providers": {
|
||
"openrouter": {
|
||
"api_key": "sk-or-v1-xxx"
|
||
},
|
||
"groq": {
|
||
"api_key": "gsk_xxx"
|
||
}
|
||
},
|
||
"channels": {
|
||
"telegram": {
|
||
"enabled": true,
|
||
"token": "123456:ABC...",
|
||
"allow_from": ["123456789"]
|
||
},
|
||
"discord": {
|
||
"enabled": true,
|
||
"token": "",
|
||
"allow_from": [""]
|
||
},
|
||
"whatsapp": {
|
||
"enabled": false
|
||
},
|
||
"feishu": {
|
||
"enabled": false,
|
||
"app_id": "cli_xxx",
|
||
"app_secret": "xxx",
|
||
"encrypt_key": "",
|
||
"verification_token": "",
|
||
"allow_from": []
|
||
},
|
||
"qq": {
|
||
"enabled": false,
|
||
"app_id": "",
|
||
"app_secret": "",
|
||
"allow_from": []
|
||
}
|
||
},
|
||
"tools": {
|
||
"web": {
|
||
"search": {
|
||
"api_key": "BSA..."
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
</details>
|
||
|
||
## CLI Reference
|
||
|
||
| Command | Description |
|
||
| ------------------------- | ----------------------------- |
|
||
| `picoclaw onboard` | Initialize config & workspace |
|
||
| `picoclaw agent -m "..."` | Chat with the agent |
|
||
| `picoclaw agent` | Interactive chat mode |
|
||
| `picoclaw gateway` | Start the gateway |
|
||
| `picoclaw status` | Show status |
|
||
| `picoclaw cron list` | List all scheduled jobs |
|
||
| `picoclaw cron add ...` | Add a scheduled job |
|
||
|
||
### Scheduled Tasks / Reminders
|
||
|
||
PicoClaw supports scheduled reminders and recurring tasks through the `cron` tool:
|
||
|
||
- **One-time reminders**: "Remind me in 10 minutes" → triggers once after 10min
|
||
- **Recurring tasks**: "Remind me every 2 hours" → triggers every 2 hours
|
||
- **Cron expressions**: "Remind me at 9am daily" → uses cron expression
|
||
|
||
Jobs are stored in `~/.picoclaw/workspace/cron/` and processed automatically.
|
||
|
||
## 🤝 Contribute & Roadmap
|
||
|
||
PRs welcome! The codebase is intentionally small and readable. 🤗
|
||
|
||
discord: <https://discord.gg/V4sAZ9XWpN>
|
||
|
||
<img src="assets/wechat.png" alt="PicoClaw" width="512">
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
### Web search says "API 配置问题"
|
||
|
||
This is normal if you haven't configured a search API key yet. PicoClaw will provide helpful links for manual searching.
|
||
|
||
To enable web search:
|
||
|
||
1. **Option 1 (Recommended)**: Get a free API key at [https://brave.com/search/api](https://brave.com/search/api) (2000 free queries/month) for the best results.
|
||
2. **Option 2 (No Credit Card)**: If you don't have a key, we automatically fall back to **DuckDuckGo** (no key required).
|
||
|
||
Add the key to `~/.picoclaw/config.json` if using Brave:
|
||
|
||
```json
|
||
{
|
||
"tools": {
|
||
"web": {
|
||
"search": {
|
||
"api_key": "YOUR_BRAVE_API_KEY",
|
||
"max_results": 5
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Getting content filtering errors
|
||
|
||
Some providers (like Zhipu) have content filtering. Try rephrasing your query or use a different model.
|
||
|
||
### Telegram bot says "Conflict: terminated by other getUpdates"
|
||
|
||
This happens when another instance of the bot is running. Make sure only one `picoclaw gateway` is running at a time.
|
||
|
||
---
|
||
|
||
## 📝 API Key Comparison
|
||
|
||
| Service | Free Tier | Use Case |
|
||
| ---------------- | ------------------- | ------------------------------------- |
|
||
| **OpenRouter** | 200K tokens/month | Multiple models (Claude, GPT-4, etc.) |
|
||
| **Zhipu** | 200K tokens/month | Best for Chinese users |
|
||
| **Brave Search** | 2000 queries/month | Web search functionality |
|
||
| **Groq** | Free tier available | Fast inference (Llama, Mixtral) |
|