picoclaw

PicoClaw

Overview

PicoClaw is an open-source (MIT) personal AI assistant from Sipeed, written in Go. It ships as a single binary that runs on small boards (Raspberry Pi, RISC-V, MIPS, even Android) with roughly 10-20 MB of RAM. It talks to 30+ LLM providers through a model_list in ~/.picoclaw/config.json, and bridges chats from Telegram, Discord, Slack, WhatsApp, Matrix, LINE and other channels through a gateway. It also supports MCP servers, installable skills, cron jobs and a heartbeat file. Current release at the time of writing: v0.3.1 (July 2026). The project is pre-1.0 and its config format has changed several times, so check picoclaw version and the docs at docs.picoclaw.io when something here does not match.

Instructions

1. Install PicoClaw

Prebuilt binary (simplest). Download picoclaw_Linux_x86_64.tar.gz (or the arm64, riscv64, macOS or Windows archive) from the GitHub Releases page together with picoclaw_<version>_checksums.txt, and verify before extracting:

grep Linux_x86_64 picoclaw_0.3.1_checksums.txt | sha256sum -c
tar xzf picoclaw_Linux_x86_64.tar.gz     # gives picoclaw and picoclaw-launcher

The archive contains picoclaw (CLI and gateway) and picoclaw-launcher (browser UI). The official download page is picoclaw.io; other picoclaw domains are not affiliated.

From source (Go 1.25+, Node 22+ and pnpm only needed for the web launcher):

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
make build      # core binary in build/
make install    # installs to ~/.local/bin

Docker Compose (the compose file lives in docker/, data in docker/data/):

git clone https://github.com/sipeed/picoclaw.git && cd picoclaw
docker compose -f docker/docker-compose.yml --profile launcher up   # first run writes docker/data/config.json, then exits
docker compose -f docker/docker-compose.yml --profile gateway up -d # long-running bot
docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Hello"

Profiles: launcher (web console on port 18800), gateway (bot only), agent (one-shot).

2. Initial setup

picoclaw onboard    # creates ~/.picoclaw/config.json, ~/.picoclaw/.security.yml and the workspace
picoclaw status     # shows config path, active model and which providers have keys

Alternatively run picoclaw-launcher and open http://localhost:18800 (add -public to listen on all interfaces). On first visit it asks you to create a dashboard password.

3. Configure an LLM provider

Models are declared in model_list; agents.defaults.model_name picks the default by its model_name. The older providers block was removed in the v2 config format (old files are migrated automatically).

{
  "agents": { "defaults": { "model_name": "claude-sonnet-4.6", "max_tool_iterations": 20 } },
  "model_list": [
    { "model_name": "claude-sonnet-4.6", "provider": "anthropic", "model": "claude-sonnet-4-6",
      "api_base": "https://api.anthropic.com/v1" }
  ]
}

Keep secrets out of config.json: onboard creates ~/.picoclaw/.security.yml, whose entries are mapped onto the config by name and override it. Keys must be arrays. Run chmod 600 on it and never commit it.

model_list:
  claude-sonnet-4.6:0:        # model_name plus ":0" for the first entry with that name
    api_keys:
      - "sk-ant-api03-REPLACE-WITH-YOUR-KEY"

Providers use the protocol/model form in the README (openai/, anthropic/, gemini/, openrouter/, deepseek/, groq/, zhipu/, ollama/, vllm/, bedrock/, azure/, ...). For a local model: { "model_name": "local-llama", "model": "ollama/llama3.1:8b", "api_base": "http://localhost:11434/v1" } (no key). Switch the default later with picoclaw model.

4. Chat with the agent

picoclaw agent -m "Summarize the Go 1.25 release notes"   # single query
picoclaw agent                                              # interactive mode

5. Set up a messaging gateway

Channels live under channel_list. Each has enabled, type and an allow_from list of user IDs (an empty list lets everyone in). Put the bot token in .security.yml:

{
  "channel_list": {
    "telegram": { "enabled": true, "type": "telegram", "allow_from": ["198234567"] }
  }
}

channel_list:
  telegram:
    settings:
      token: "7654321:AAF-REPLACE-WITH-BOTFATHER-TOKEN"

Create the Telegram bot with @BotFather and read your user ID from @userinfobot. Discord needs a bot from discord.com/developers/applications with MESSAGE CONTENT INTENT enabled; Slack uses Socket Mode with bot_token (xoxb-) and app_token (xapp-). Per-channel guides are in docs/channels/<name>/README.md. Start the gateway:

picoclaw gateway

The gateway listens on 127.0.0.1:18790 by default (PICOCLAW_GATEWAY_HOST=0.0.0.0 inside Docker). In chat, /list skills, /list mcp and /use <skill> <message> work as slash commands.

6. Web search

tools.web is enabled by default and Sogou search is on out of the box. Others: duckduckgo, brave, tavily, kagi, perplexity, searxng, gemini, glm_search, baidu_search. Enable one and put its key in .security.yml under web.<engine>.api_keys:

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

7. Skills and MCP servers

picoclaw skills search "web scraping"
picoclaw skills install web-scraper
picoclaw skills list
picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/pi/notes
picoclaw mcp list
picoclaw mcp test filesystem

picoclaw mcp only edits tools.mcp.servers in the config; it does not run the server. Set "tools": { "mcp": { "enabled": true } }. Skills load from ~/.picoclaw/workspace/skills, ~/.picoclaw/skills and the built-in set.

8. Scheduled tasks and heartbeat

Heartbeat reads ~/.picoclaw/workspace/HEARTBEAT.md every interval minutes (default 30, minimum 5) and runs the tasks in it:

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

## Quick Tasks
- Report current system uptime

## Long Tasks (use spawn for async)
- Search the web for security advisories and summarize

Cron jobs from the CLI are recurring only (--every <seconds> or --cron "<expr>"); one-time reminders are created by asking the agent ("remind me in 10 minutes"):

picoclaw cron add --name "Daily summary" --message "Summarize today's logs" --cron "0 18 * * *"
picoclaw cron add --name "Ping" --message "heartbeat" --every 300
picoclaw cron list
picoclaw cron disable a5c92bf87ec3b086
picoclaw cron remove a5c92bf87ec3b086

9. Workspace and security

The workspace (~/.picoclaw/workspace/) holds sessions/, memory/ (MEMORY.md), state/, cron/, skills/ and the markdown files AGENT.md, SOUL.md, USER.md, IDENTITY.md, HEARTBEAT.md. Edits to AGENT.md, SOUL.md, USER.md and MEMORY.md are picked up without a restart. PICOCLAW_HOME moves the whole data directory and PICOCLAW_CONFIG points at another config file.

agents.defaults.restrict_to_workspace is true by default: file tools and exec stay inside the workspace, and subagents and heartbeat tasks inherit this. Even with it off, exec blocks patterns such as rm -rf, mkfs, dd if=, shutdown and fork bombs (tools.exec.enable_deny_patterns). Extra read or write paths go in tools.allow_read_paths / tools.allow_write_paths.

Examples

Example 1: Deploy PicoClaw as a Telegram bot on a Raspberry Pi

User request: "Set up PicoClaw on my Raspberry Pi as a Telegram bot using Claude"

1. On the Pi (64-bit OS), download and verify the release, then initialise:

cd ~ && mkdir picoclaw-bin && cd picoclaw-bin
curl -LO https://github.com/sipeed/picoclaw/releases/download/v0.3.1/picoclaw_Linux_arm64.tar.gz
curl -LO https://github.com/sipeed/picoclaw/releases/download/v0.3.1/picoclaw_0.3.1_checksums.txt
grep Linux_arm64 picoclaw_0.3.1_checksums.txt | sha256sum -c
tar xzf picoclaw_Linux_arm64.tar.gz && ./picoclaw onboard

1. In ~/.picoclaw/config.json set agents.defaults.model_name to claude-sonnet-4.6, make sure that entry is in model_list, and enable Telegram with "allow_from": ["198234567"] under channel_list.telegram.
2. In ~/.picoclaw/.security.yml add the Anthropic key under model_list.claude-sonnet-4.6:0.api_keys and the BotFather token under channel_list.telegram.settings.token, then chmod 600 ~/.picoclaw/.security.yml.
3. Check and start:

./picoclaw status     # Model: claude-sonnet-4.6, Anthropic API: ✓
./picoclaw gateway

Result: the bot answers messages from user 198234567 in Telegram; other users are ignored.

Example 2: Run PicoClaw with Docker Compose and Discord

User request: "Run PicoClaw in Docker with Discord and send me a summary every evening"

git clone https://github.com/sipeed/picoclaw.git && cd picoclaw
docker compose -f docker/docker-compose.yml --profile launcher up   # generates docker/data/config.json

Edit docker/data/config.json (enable channel_list.discord with "allow_from": ["987654321012345678"], add a model), put the keys in docker/data/.security.yml, then:

docker compose -f docker/docker-compose.yml --profile gateway up -d
docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway

Then, in a Discord direct message from the allowed user, ask: "Every day at 18:00 summarize today's activity and send it to me". The agent creates the job with its cron tool; check it in the launcher or with picoclaw cron list against the same data directory.

Result: the gateway restarts with the container and the job is stored in the workspace under cron/.

Guidelines

• Always set allow_from to specific user IDs; an empty list lets anyone who finds the bot talk to an agent that can run commands.
• Only one gateway can use a bot token at a time; a second one causes Telegram "terminated by other getUpdates request" conflicts.
• PicoClaw is pre-1.0 and the project itself warns against production use with sensitive data. Recent builds can use 10-20 MB of RAM, not the 10 MB in older claims.
• Do not copy config snippets from older blog posts: providers, top-level channels and model fields written as anthropic/claude-sonnet-4-5-... belong to older formats. Use the files picoclaw onboard generates as the reference, and picoclaw update to upgrade the binary (picoclaw migrate imports data from OpenClaw-style projects).
• Command cron jobs can run shell commands. Leave tools.cron.command_allowed_remotes empty so chat users cannot schedule them, and never set it to "*".
• Groq-configured Whisper transcription turns voice messages from channels into text automatically.
• Environment variables override config values with the PICOCLAW_<SECTION>_<KEY> pattern, for example PICOCLAW_HEARTBEAT_INTERVAL=60 or PICOCLAW_LOG_LEVEL=info.
• Disabling restrict_to_workspace gives the agent access to your whole filesystem; do that only in a throwaway container.