🦐 PicoClaw is an ultra-lightweight personal AI Assistant inspired by 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!

📢 News

2026-02-16 🎉 PicoClaw hit 12K stars in one week! Thank you all for your support! PicoClaw is growing faster than we ever imagined. Given the high volume of PRs, we urgently need community maintainers. Our volunteer roles and roadmap are officially posted here —we can’t wait to have you on board!

2026-02-13 🎉 PicoClaw hit 5000 stars in 4days! Thank you for the community! There are so many PRs & issues coming in (during Chinese New Year holidays), we are finalizing the Project Roadmap and setting up the Developer Group to accelerate PicoClaw's development.
🚀 Call to Action: Please submit your feature requests in GitHub Discussions. We will review and prioritize them during our upcoming weekly meeting.

2026-02-09 🎉 PicoClaw Launched! Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 PicoClaw，Let's Go！

✨ 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, MIPS, and x86, One-click to Go!

🤖 AI-Bootstrapped: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement.

🦾 Demonstration

🛠️ Standard Assistant Workflows

📱 Run on old Android Phones

Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw. Quick Start:

1. Install Termux (Available on F-Droid or Google Play).
2. Execute cmds

# Note: Replace v0.1.1 with the latest version from the Releases page
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
chmod +x picoclaw-linux-arm64
pkg install proot
termux-chroot ./picoclaw-linux-arm64 onboard

And then follow the instructions in the "Quick Start" section to complete the configuration!

🐜 Innovative Low-Footprint Deploy

PicoClaw can be deployed on almost any Linux device!

• $9.9 LicheeRV-Nano E(Ethernet) or W(WiFi6) version, for Minimal Home Assistant
• $30~50 NanoKVM, or $100 NanoKVM-Pro for Automated Server Maintenance
• $50 MaixCAM or $100 MaixCAM2 for Smart Monitoring

🌟 More Deployment Cases Await！

📦 Install

Install with precompiled binary

Download the firmware for your platform from the release page.

Install from source (latest features, recommended for development)

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 for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
make build-pi-zero

# Build And Install
make install

Raspberry Pi Zero 2 W: Use the binary that matches your OS: 32-bit Raspberry Pi OS → make build-linux-arm (output: build/picoclaw-linux-arm); 64-bit → make build-linux-arm64 (output: build/picoclaw-linux-arm64). Or run make build-pi-zero to build both.

🐳 Docker Compose

You can also run PicoClaw using Docker Compose without installing anything locally.

# 1. Clone this repo
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw

# 2. First run — auto-generates docker/data/config.json then exits
docker compose -f docker/docker-compose.yml --profile gateway up
# The container prints "First-run setup complete." and stops.

# 3. Set your API keys
vim docker/data/config.json   # Set provider API keys, bot tokens, etc.

# 4. Start
docker compose -f docker/docker-compose.yml --profile gateway up -d

# 5. Check logs
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway

# 6. Stop
docker compose -f docker/docker-compose.yml --profile gateway down

Agent Mode (One-shot)

# Ask a question
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"

# Interactive mode
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent

Update

docker compose -f docker/docker-compose.yml pull
docker compose -f docker/docker-compose.yml --profile gateway up -d

🚀 Quick Start

1. Initialize

2. Configure (~/.picoclaw/config.json)

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt4",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "your-api-key",
      "request_timeout": 300
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "your-anthropic-key"
    }
  ],
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
      "tavily": {
        "enabled": false,
        "api_key": "YOUR_TAVILY_API_KEY",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "YOUR_PERPLEXITY_API_KEY",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://your-searxng-instance:8888",
        "max_results": 5
      }
    }
  }
}

New: The model_list configuration format allows zero-code provider addition. See Model Configuration for details. request_timeout is optional and uses seconds. If omitted or set to <= 0, PicoClaw uses the default timeout (120s).

3. Get API Keys

• LLM Provider: OpenRouter · Zhipu · Anthropic · OpenAI · Gemini
• Web Search (optional):
  • Brave Search - Paid ($5/1000 queries, ~$5-6/month)
  • Perplexity - AI-powered search with chat interface
  • SearXNG - Self-hosted metasearch engine (free, no API key needed)
  • Tavily - Optimized for AI Agents (1000 requests/month)
  • DuckDuckGo - Built-in fallback (no API key required)

Note: See config.example.json for a complete configuration template.

4. Chat

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, WhatsApp, DingTalk, LINE, or WeCom

Note: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (gateway.host:gateway.port, default 127.0.0.1:18790). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}

{
  "channels": {
    "discord": {
      "group_trigger": { "mention_only": true }
    }
  }
}

{
  "channels": {
    "discord": {
      "group_trigger": { "prefixes": ["!bot"] }
    }
  }
}

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": true,
      "session_store_path": "",
      "allow_from": []
    }
  }
}

{
  "channels": {
    "qq": {
      "enabled": true,
      "app_id": "YOUR_APP_ID",
      "app_secret": "YOUR_APP_SECRET",
      "allow_from": []
    }
  }
}

{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "allow_from": []
    }
  }
}

{
  "channels": {
    "line": {
      "enabled": true,
      "channel_secret": "YOUR_CHANNEL_SECRET",
      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
      "webhook_path": "/webhook/line",
      "allow_from": []
    }
  }
}

# Example with ngrok (gateway default port is 18790)
ngrok http 18790

{
  "channels": {
    "wecom": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
      "webhook_path": "/webhook/wecom",
      "allow_from": []
    }
  }
}

{
  "channels": {
    "wecom_app": {
      "enabled": true,
      "corp_id": "wwxxxxxxxxxxxxxxxx",
      "corp_secret": "YOUR_CORP_SECRET",
      "agent_id": 1000002,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-app",
      "allow_from": []
    }
  }
}

{
  "channels": {
    "wecom_aibot": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "Hello! How can I help you?"
    }
  }
}

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

⚙️ Configuration

Config file: ~/.picoclaw/config.json

Environment Variables

You can override default paths using environment variables. This is useful for portable installations, containerized deployments, or running picoclaw as a system service. These variables are independent and control different paths.

Examples:

# Run picoclaw using a specific config file
# The workspace path will be read from within that config file
PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway

# Run picoclaw with all its data stored in /opt/picoclaw
# Config will be loaded from the default ~/.picoclaw/config.json
# Workspace will be created at /opt/picoclaw/workspace
PICOCLAW_HOME=/opt/picoclaw picoclaw agent

# Use both for a fully customized setup
PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway

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)
├── state/            # Persistent state (last channel, etc.)
├── cron/             # Scheduled jobs database
├── skills/           # Custom skills
├── AGENTS.md         # Agent behavior guide
├── HEARTBEAT.md      # Periodic task prompts (checked every 30 min)
├── IDENTITY.md       # Agent identity
├── SOUL.md           # Agent soul
├── TOOLS.md          # Tool descriptions
└── USER.md           # User preferences

Skill Sources

By default, skills are loaded from:

1. ~/.picoclaw/workspace/skills (workspace)
2. ~/.picoclaw/skills (global)
3. <current-working-directory>/skills (builtin)

For advanced/test setups, you can override the builtin skills root with:

export PICOCLAW_BUILTIN_SKILLS=/path/to/skills

Unified Command Execution Policy

• Generic slash commands are executed through a single path in pkg/agent/loop.go via commands.Executor.
• Channel adapters no longer consume generic commands locally; they forward inbound text to the bus/agent path. Telegram still auto-registers supported commands at startup.
• Unknown slash command (for example /foo) passes through to normal LLM processing.
• Registered but unsupported command on the current channel (for example /show on WhatsApp) returns an explicit user-facing error and stops further processing.

🔒 Security Sandbox

PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace.

Default Configuration

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true
    }
  }
}

Protected Tools

When restrict_to_workspace: true, the following tools are sandboxed:

Additional Exec Protection

Even with restrict_to_workspace: false, the exec tool blocks these dangerous commands:

• rm -rf, del /f, rmdir /s — Bulk deletion
• format, mkfs, diskpart — Disk formatting
• dd if= — Disk imaging
• Writing to /dev/sd[a-z] — Direct disk writes
• shutdown, reboot, poweroff — System shutdown
• Fork bomb :(){ :|:& };:

Error Examples

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (path outside working dir)}

[ERROR] tool: Tool execution failed
{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}

Disabling Restrictions (Security Risk)

If you need the agent to access paths outside the workspace:

Method 1: Config file

{
  "agents": {
    "defaults": {
      "restrict_to_workspace": false
    }
  }
}

Method 2: Environment variable

export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false

⚠️ Warning: Disabling this restriction allows the agent to access any path on your system. Use with caution in controlled environments only.

Security Boundary Consistency

The restrict_to_workspace setting applies consistently across all execution paths:

All paths share the same workspace restriction — there's no way to bypass the security boundary through subagents or scheduled tasks.

Heartbeat (Periodic Tasks)

PicoClaw can perform periodic tasks automatically. Create a HEARTBEAT.md file in your workspace:

# Periodic Tasks

- Check my email for important messages
- Review my calendar for upcoming events
- Check the weather forecast

The agent will read this file every 30 minutes (configurable) and execute any tasks using available tools.

Async Tasks with Spawn

For long-running tasks (web search, API calls), use the spawn tool to create a subagent:

# Periodic Tasks

## Quick Tasks (respond directly)

- Report current time

## Long Tasks (use spawn for async)

- Search the web for AI news and summarize
- Check email and report important messages

Key behaviors:

How Subagent Communication Works

Heartbeat triggers
    ↓
Agent reads HEARTBEAT.md
    ↓
For long task: spawn subagent
    ↓                           ↓
Continue to next task      Subagent works independently
    ↓                           ↓
All tasks done            Subagent uses "message" tool
    ↓                           ↓
Respond HEARTBEAT_OK      User receives result directly

The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent.

Configuration:

{
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

Environment variables:

• PICOCLAW_HEARTBEAT_ENABLED=false to disable
• PICOCLAW_HEARTBEAT_INTERVAL=60 to change interval

Providers

Model Configuration (model_list)

What's New? PicoClaw now uses a model-centric configuration approach. Simply specify vendor/model format (e.g., zhipu/glm-4.7) to add new providers—zero code changes required!

This design also enables multi-agent support with flexible provider selection:

• Different agents, different providers: Each agent can use its own LLM provider
• Model fallbacks: Configure primary and fallback models for resilience
• Load balancing: Distribute requests across multiple endpoints
• Centralized configuration: Manage all providers in one place

📋 All Supported Vendors

Basic Configuration

{
  "model_list": [
    {
      "model_name": "gpt-5.2",
      "model": "openai/gpt-5.2",
      "api_key": "sk-your-openai-key"
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "sk-ant-your-key"
    },
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_key": "your-zhipu-key"
    }
  ],
  "agents": {
    "defaults": {
      "model": "gpt-5.2"
    }
  }
}

Vendor-Specific Examples

OpenAI

{
  "model_name": "gpt-5.2",
  "model": "openai/gpt-5.2",
  "api_key": "sk-..."
}

智谱 AI (GLM)

{
  "model_name": "glm-4.7",
  "model": "zhipu/glm-4.7",
  "api_key": "your-key"
}

DeepSeek

{
  "model_name": "deepseek-chat",
  "model": "deepseek/deepseek-chat",
  "api_key": "sk-..."
}

Anthropic (with API key)

{
  "model_name": "claude-sonnet-4.6",
  "model": "anthropic/claude-sonnet-4.6",
  "api_key": "sk-ant-your-key"
}

Run picoclaw auth login --provider anthropic to paste your API token.

Ollama (local)

{
  "model_name": "llama3",
  "model": "ollama/llama3"
}

Custom Proxy/API

{
  "model_name": "my-custom-model",
  "model": "openai/custom-model",
  "api_base": "https://my-proxy.com/v1",
  "api_key": "sk-...",
  "request_timeout": 300
}

LiteLLM Proxy

{
  "model_name": "lite-gpt4",
  "model": "litellm/lite-gpt4",
  "api_base": "http://localhost:4000/v1",
  "api_key": "sk-..."
}

PicoClaw strips only the outer litellm/ prefix before sending the request, so proxy aliases like litellm/lite-gpt4 send lite-gpt4, while litellm/openai/gpt-4o sends openai/gpt-4o.

Load Balancing

Configure multiple endpoints for the same model name—PicoClaw will automatically round-robin between them:

{
  "model_list": [
    {
      "model_name": "gpt-5.2",
      "model": "openai/gpt-5.2",
      "api_base": "https://api1.example.com/v1",
      "api_key": "sk-key1"
    },
    {
      "model_name": "gpt-5.2",
      "model": "openai/gpt-5.2",
      "api_base": "https://api2.example.com/v1",
      "api_key": "sk-key2"
    }
  ]
}

Migration from Legacy providers Config

The old providers configuration is deprecated but still supported for backward compatibility.

Old Config (deprecated):

{
  "providers": {
    "zhipu": {
      "api_key": "your-key",
      "api_base": "https://open.bigmodel.cn/api/paas/v4"
    }
  },
  "agents": {
    "defaults": {
      "provider": "zhipu",
      "model": "glm-4.7"
    }
  }
}

New Config (recommended):

{
  "model_list": [
    {
      "model_name": "glm-4.7",
      "model": "zhipu/glm-4.7",
      "api_key": "your-key"
    }
  ],
  "agents": {
    "defaults": {
      "model": "glm-4.7"
    }
  }
}

For detailed migration guide, see docs/migration/model-list-migration.md.

Provider Architecture

PicoClaw routes providers by protocol family:

• OpenAI-compatible protocol: OpenRouter, OpenAI-compatible gateways, Groq, Zhipu, and vLLM-style endpoints.
• Anthropic protocol: Claude-native API behavior.
• Codex/OAuth path: OpenAI OAuth/token authentication route.

This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (api_base + api_key).

{
  "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"
    }
  }
}

picoclaw agent -m "Hello"

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  },
  "session": {
    "dm_scope": "per-channel-peer",
    "backlog_limit": 20
  },
  "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,
      "bridge_url": "ws://localhost:3001",
      "use_native": false,
      "session_store_path": "",
      "allow_from": []
    },
    "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": {
      "brave": {
        "enabled": false,
        "api_key": "BSA...",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://localhost:8888",
        "max_results": 5
      }
    },
    "cron": {
      "exec_timeout_minutes": 5
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  }
}

CLI Reference

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. 🤗

See our full Community Roadmap.

Developer group building, join after your first merged PR!

User Groups:

discord: https://discord.gg/V4sAZ9XWpN

🐛 Troubleshooting

Web search says "API key configuration issue"

This is normal if you haven't configured a search API key yet. PicoClaw will provide helpful links for manual searching.

Search Provider Priority

PicoClaw automatically selects the best available search provider in this order:

1. Perplexity (if enabled and API key configured) - AI-powered search with citations
2. Brave Search (if enabled and API key configured) - Privacy-focused paid API ($5/1000 queries)
3. SearXNG (if enabled and base_url configured) - Self-hosted metasearch aggregating 70+ engines (free)
4. DuckDuckGo (if enabled, default fallback) - No API key required (free)

Web Search Configuration Options

Option 1 (Best Results): Perplexity AI Search

{
  "tools": {
    "web": {
      "perplexity": {
        "enabled": true,
        "api_key": "YOUR_PERPLEXITY_API_KEY",
        "max_results": 5
      }
    }
  }
}

Option 2 (Paid API): Get an API key at https://brave.com/search/api ($5/1000 queries, ~$5-6/month)

{
  "tools": {
    "web": {
      "brave": {
        "enabled": true,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      }
    }
  }
}

Option 3 (Self-Hosted): Deploy your own SearXNG instance

{
  "tools": {
    "web": {
      "searxng": {
        "enabled": true,
        "base_url": "http://your-server:8888",
        "max_results": 5
      }
    }
  }
}

Benefits of SearXNG:

• Zero cost: No API fees or rate limits
• Privacy-focused: Self-hosted, no tracking
• Aggregate results: Queries 70+ search engines simultaneously
• Perfect for cloud VMs: Solves datacenter IP blocking issues (Oracle Cloud, GCP, AWS, Azure)
• No API key needed: Just deploy and configure the base URL

Option 4 (No Setup Required): DuckDuckGo is enabled by default as fallback (no API key needed)

Add the key to ~/.picoclaw/config.json if using Brave:

{
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "YOUR_PERPLEXITY_API_KEY",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://your-searxng-instance:8888",
        "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