Frequently Asked Questions

General Questions

What is PicoClaw?

PicoClaw is an ultra-lightweight personal AI assistant inspired by nanobot, refactored from the ground up in Go. It runs on $10 hardware with <10MB RAM, making it 99% less memory-hungry than OpenClaw and 98% cheaper than a Mac mini.Key features:

Ultra-lightweight (<10MB memory footprint)
Lightning fast (400X faster startup, boots in 1 second)
True portability (single binary across RISC-V, ARM, and x86)
AI-bootstrapped (95% agent-generated core)

How is PicoClaw different from OpenClaw and NanoBot?

Feature	OpenClaw	NanoBot	PicoClaw
Language	TypeScript	Python	Go
RAM	>1GB	>100MB	< 10MB
Startup (0.8GHz)	>500s	>30s	<1s
Cost	Mac Mini $599	Linux SBC ~$50	Any Linux Board ~$10

PicoClaw is designed for extreme resource efficiency, making it ideal for embedded devices and edge computing.

What hardware can run PicoClaw?

PicoClaw can run on:

Embedded Boards: LicheeRV-Nano ( $9.9), NanoKVM ($ 30-100), MaixCAM ($50-100)
Single Board Computers: Raspberry Pi (including Pi Zero 2 W)
Old Android Phones: Via Termux
Servers & Desktops: Any Linux, macOS, or Windows machine
Docker Containers: Portable deployment

Minimum requirements:

64MB RAM (target: <20MB)
Any architecture: x86_64, ARM64, ARM32, RISC-V

Is PicoClaw open source?

Yes! PicoClaw is open source under the MIT license. You can:

View the source code on GitHub
Contribute features, bug fixes, or documentation
Fork and customize for your needs
Use it commercially or personally

See our Contributing Guide to get started.

Was PicoClaw really built by AI?

Yes! PicoClaw was substantially developed with AI assistance through a self-bootstrapping process. The AI agent itself drove the architectural migration from Python to Go and code optimization.However, this doesn’t mean the code is unreviewed or low-quality:

All AI-generated code is reviewed and validated by humans
Contributors are responsible for understanding and testing code
The same quality standards apply to all contributions

We embrace responsible AI-assisted development and have built our contribution process around it.

Setup Questions

How do I install PicoClaw?

Precompiled Binary (Easiest)
From Source (Latest Features)
Docker
Android/Termux

Download from the releases page:

# Linux/macOS
chmod +x picoclaw-*
./picoclaw-* onboard

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
make build
./build/picoclaw onboard

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
docker compose -f docker/docker-compose.yml --profile gateway up
# Edit docker/data/config.json
docker compose -f docker/docker-compose.yml --profile gateway up -d

# Install Termux from F-Droid
pkg install proot
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
chmod +x picoclaw-linux-arm64
termux-chroot ./picoclaw-linux-arm64 onboard

What API keys do I need?

Required:

LLM Provider: Choose one:
- OpenRouter - Access to all models (200K tokens/month free)
- Zhipu - Best for Chinese users (200K tokens/month free)
- OpenAI - GPT models
- Anthropic - Claude models
- Gemini - Google models

Optional:

Web Search: Choose one:
- Brave Search - 2000 queries/month free
- Tavily - 1000 queries/month free, AI-optimized
- DuckDuckGo - Built-in fallback, no key needed
Voice Transcription: Groq - Free Whisper transcription

How do I configure PicoClaw?

After running picoclaw onboard, edit ~/.picoclaw/config.json:Basic Setup:

{
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "your-api-key"
    }
  ],
  "agents": {
    "defaults": {
      "model": "gpt4"
    }
  }
}

See config.example.json for a complete template.

Can I use PicoClaw without web search?

Yes! Web search is optional. If you don’t configure a search API key:

DuckDuckGo is used as an automatic fallback
The agent will provide helpful links for manual searching
All other features work normally

For the best experience, we recommend configuring Brave Search (2000 free queries/month).

How do I update PicoClaw?

Binary
From Source
Docker

Download the latest release and replace your existing binary:

wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw-linux-amd64
chmod +x picoclaw-linux-amd64

cd picoclaw
git pull
make deps
make build

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

Usage Questions

How do I chat with PicoClaw?

Command Line:

# One-shot message
picoclaw agent -m "What is 2+2?"

# Interactive mode
picoclaw agent

Chat Apps (after configuring channels):

picoclaw gateway
# Then message your bot on Telegram, Discord, WhatsApp, etc.

What can PicoClaw do?

PicoClaw is a full-featured AI assistant that can:File Operations:

Read, write, edit files
List directories
Search file contents

Web & Research:

Search the web
Fetch and analyze web pages
Stay updated on news and trends

Development:

Write and debug code
Execute shell commands
Manage git repositories

Planning & Memory:

Create and manage schedules
Set reminders and recurring tasks
Remember important information across sessions

Communication:

Respond on multiple chat platforms
Send messages to users
Handle group chats

How do I connect PicoClaw to Telegram/Discord/WhatsApp?

See our detailed channel guides:

Telegram Setup - Easiest, just a bot token
Discord Setup - Bot token + intents
WhatsApp Setup - QR scan or bridge
More Channels - QQ, LINE, WeCom, DingTalk, etc.

Quick Telegram Setup:

Message @BotFather on Telegram
Send /newbot and follow prompts
Copy the token to config.json:

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

Run picoclaw gateway

Can PicoClaw run scheduled tasks?

Yes! PicoClaw supports two types of scheduling:1. Heartbeat Tasks (periodic): Create ~/.picoclaw/workspace/HEARTBEAT.md:

# Periodic Tasks

- Check my email for important messages
- Review my calendar for upcoming events
- Search for AI news and summarize

The agent checks this file every 30 minutes (configurable).2. Cron Jobs (one-time or recurring):

# Via CLI
picoclaw cron add "Remind me to call mom" "in 1 hour"
picoclaw cron list

# Via chat
"Remind me in 10 minutes to check the oven"
"Remind me every day at 9am to review my schedule"

How does PicoClaw remember things?

PicoClaw has multiple memory mechanisms:Session Memory:

Stored in ~/.picoclaw/workspace/sessions/
Preserves conversation context
Separate sessions per channel/user

Long-term Memory:

MEMORY.md - Important facts and preferences
USER.md - User profile and preferences
IDENTITY.md - Agent identity and personality

State Persistence:

state/ - Last used channel, active sessions
cron/ - Scheduled tasks database

The agent automatically updates these files as it learns about you.

Is my data secure?

PicoClaw has multiple security features:Sandbox by Default:

restrict_to_workspace: true limits file access to workspace only
Dangerous commands (rm -rf, format, etc.) are blocked
No access to system files outside workspace

Channel Security:

allow_from restricts who can use your bot
Per-channel session isolation
No data leakage between users

API Key Protection:

Stored in local config file
Never logged or transmitted except to provider
Credentials redacted from logs

See our Roadmap for upcoming security enhancements.

Provider Questions

Which LLM provider should I use?

Best for Most Users: OpenRouter

Access to all major models (GPT, Claude, Gemini, Llama, etc.)
200K tokens/month free tier
Easy switching between models

Best for Chinese Users: Zhipu (智谱)

Optimized for Chinese language
200K tokens/month free tier
Fast response times in China

Best for Privacy: Local models via Ollama

Runs entirely on your hardware
No API keys needed
No data leaves your machine

Best for Speed: Groq or Cerebras

Ultra-fast inference
Free tier available
Great for simple tasks

Can I use local models?

Yes! PicoClaw supports local inference via:Ollama (Recommended):

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3

# Configure PicoClaw
{
  "model_list": [
    {
      "model_name": "local-llama",
      "model": "ollama/llama3"
    }
  ]
}

Other Options:

vLLM
LM Studio
LiteLLM Proxy

See Provider Configuration for details.

How do I switch between models?

Configure multiple models in model_list:

{
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "sk-..."
    },
    {
      "model_name": "claude",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "sk-ant-..."
    },
    {
      "model_name": "local",
      "model": "ollama/llama3"
    }
  ],
  "agents": {
    "defaults": {
      "model": "gpt4"  // Default model
    }
  }
}

Change the default model in agents.defaults.model to switch.

What if my API calls fail?

Load Balancing: Configure multiple endpoints for failover:

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

PicoClaw will automatically round-robin between endpoints.

How much does it cost to run PicoClaw?

Hardware Costs:

Embedded board: $10-50 (one-time)
Or use existing hardware: $0

API Costs (monthly):

OpenRouter: 200K tokens free, then ~$0.50-2/million tokens
Zhipu: 200K tokens free, then similar pricing
Local models (Ollama): $0, but uses your compute
Brave Search: 2000 queries free, then $5/1000 queries

Typical Usage:

Light user (<100 messages/day): Usually stays in free tier
Heavy user (>500 messages/day): ~$5-15/month

See our API Key Comparison.

Advanced Questions

Can I customize PicoClaw's personality?

Yes! Edit these files in your workspace:IDENTITY.md - Agent identity and name:

You are PicoClaw, a helpful AI assistant.
You are efficient, accurate, and friendly.

SOUL.md - Personality and behavior:

You respond concisely and professionally.
You prioritize user needs and ask clarifying questions.

AGENTS.md - Agent behavior guide:

When writing code, always include comments.
When searching, summarize findings concisely.

The agent reads these files on startup and follows the guidelines.

How do I add custom skills?

Create skill files in ~/.picoclaw/workspace/skills/:Example: email_checker.json

{
  "name": "check_email",
  "description": "Check email for important messages",
  "parameters": {
    "type": "object",
    "properties": {
      "filter": {
        "type": "string",
        "description": "Filter criteria (e.g., 'from:boss@company.com')"
      }
    }
  },
  "handler": "skills/email_checker.sh"
}

PicoClaw will automatically discover and use the skill.

Can I run multiple PicoClaw instances?

Yes! Each instance needs:Separate Config:

export PICOCLAW_CONFIG=/path/to/instance1/config.json
picoclaw gateway

Separate Workspace:

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace1"
    }
  }
}

Different Gateway Ports (if using webhooks):

{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18790  // Use different port for each instance
  }
}

See our Roadmap for upcoming “Swarm Mode” (multi-agent collaboration).

How do I contribute to PicoClaw?

We welcome all contributions! See our Contributing Guide.Quick Start:

Fork the repository
Create a feature branch
Make your changes
Run make check to verify
Open a Pull Request

What to Contribute:

Bug fixes
New features
Documentation improvements
New channel integrations
Provider support
Testing on new hardware

Community Channels:

GitHub Issues
GitHub Discussions
Discord
WeChat (after first merged PR)

What's on the roadmap?

See our full Roadmap for details. Highlights:Near-term:

Memory footprint reduction (<20MB target)
Security hardening (sandboxing, SSRF protection)
Protocol-first provider architecture
More channel integrations

Mid-term:

MCP (Model Context Protocol) support
Browser automation
Mobile device control
Multi-agent collaboration

Long-term:

Swarm mode (multiple PicoClaw instances)
Model routing (smart task distribution)
AIEOS (AI-native OS interaction)

Still Have Questions?

Troubleshooting

Common issues and solutions

GitHub Issues

Report bugs or request features

GitHub Discussions

Ask questions and share ideas

Discord

Join the community chat

​General Questions

​Setup Questions

​Usage Questions

​Provider Questions

​Advanced Questions

​Still Have Questions?