DEV Community

TechLatest
TechLatest

Posted on • Originally published at Medium on

PicoClaw Agent Masterclass — Full Tutorial

#openclaw #aiassistant #picoclaw #agents

Everything you need to install, configure, and deploy PicoClaw — Sipeed’s ultra-lightweight Go AI assistant for $10 boards, old phones, and full desktops.

Official docs: docs.picoclaw.io · Download: picoclaw.io · Source: github.com/sipeed/picoclaw

What you’ll have at the end

  • PicoClaw running via WebUI launcher (http://localhost:18800) or CLI
  • LLM provider configured (OpenRouter, Ollama, Zhipu, OpenAI, …)
  • Telegram (or another channel) connected through the gateway
  • Workspace harness files understood (AGENTS.md, SOUL.md, USER.md)
  • Optional MCP , ClawHub skills , web search , and cron jobs

Introduction — AI on $10 hardware

PicoClaw is an independent open-source project by Sipeed , written in Go from scratch  — not a fork of OpenClaw, NanoBot, or ZeroClaw. It was AI-bootstrapped : ~95% of core code was agent-generated, human-refined.

The numbers from docs.picoclaw.io:

Recent builds may use 10–20MB during rapid development; optimization is on the roadmap.

Security notice: Official domains only —  picoclaw.io and sipeed.com. No official crypto tokens. Early-stage software — not production-hardened before v1.0.

Part 1 — Architecture

Components:

  • picoclaw-launcher  — browser UI for provider, channel, gateway config (Getting Started)
  • Gateway  — HTTP server for webhooks + channel orchestration (default 127.0.0.1:18790)
  • Agent  — tool loop with SubTurn, Hooks, EventBus (v0.2.4+)
  • Workspace  — sessions, memory, skills, harness Markdown files
  • .security.yml  — API keys separated from config.json (v1+ migration)

Part 2 — Install paths

Recommended: picoclaw.io download

Visit picoclaw.io — auto-detects the platform (Linux ARM/x86, macOS, Windows, Android APK).

GitHub releases 

wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_x86_64.tar.gz
tar xzf picoclaw_Linux_x86_64.tar.gz
Enter fullscreen mode Exit fullscreen mode

Build from source (Go 1.25+) 

git clone https://github.com/sipeed/picoclaw.git && cd picoclaw
make deps && make build && make build-launcher
Enter fullscreen mode Exit fullscreen mode

Docker 

git clone https://github.com/sipeed/picoclaw.git && cd picoclaw
docker compose -f docker/docker-compose.yml --profile launcher up -d
# http://localhost:18800
Enter fullscreen mode Exit fullscreen mode

Part 3 — WebUI quickstart (recommended) 

picoclaw-launcher
# Browser → http://localhost:18800
Enter fullscreen mode Exit fullscreen mode

Four steps in the UI:

  1. Configure Provider  — add LLM API key / pick model
  2. Configure Channel  — e.g., Telegram bot token
  3. Start Gateway
  4. Chat

Remote/Docker/VM access:

picoclaw-launcher -public
# or PICOCLAW_GATEWAY_HOST=0.0.0.0
Enter fullscreen mode Exit fullscreen mode

Full WebUI docs: docs.picoclaw.io

Part 4 — CLI path (onboard)

For headless / edge devices without launcher UI:

picoclaw onboard
Enter fullscreen mode Exit fullscreen mode

Creates ~/.picoclaw/config.json and workspace.

picoclaw agent -m "What is 2+2?"
picoclaw agent # interactive
picoclaw gateway # for chat apps
Enter fullscreen mode Exit fullscreen mode

Example config: examples/config.minimal.json

Part 5 — Configuration (config.json v2)

Config file: ~/.picoclaw/config.json  — schema version 2 (Configuration Overview).

Secrets go in .security.yml , not config.json — share config safely, keep keys in .gitignore.

Environment overrides: PICOCLAW_HOME, PICOCLAW_CONFIG, PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME, etc.

Part 6 — Providers (30+ LLMs)

Use protocol/model in model_list:

{
  "model_list": [
    {
      "model_name": "gpt-main",
      "model": "openai/gpt-5.4"
    },
    {
      "model_name": "local-llama",
      "model": "ollama/llama3.1:8b",
      "api_base": "http://localhost:11434/v1"
    }
  ],
  "agents": {
    "defaults": { "model_name": "gpt-main" }
  }
}
Enter fullscreen mode Exit fullscreen mode

Supported families (abbreviated): OpenAI, Anthropic, Gemini, OpenRouter, Zhipu, DeepSeek, Qwen, Groq, Ollama, vLLM, LiteLLM, GitHub Copilot OAuth, AWS Bedrock, Azure, and more — see upstream provider table.

Free-tier starting points (Getting Started API comparison):

Run PicoClaw completely offline using TechLatest’s Ollama + Open WebUI environment with DeepSeek, Llama, Qwen, Gemma, Mistral, and other open-source LLMs.

Prefer an OpenAI-compatible local endpoint? Deploy LocalAI with TechLatest and connect PicoClaw without changing your workflow.

Techlatest.net - LocalAI: Self-Hosted Alternative to OpenAI & Anthropic

Part 7 — Workspace harness files

Default workspace: ~/.picoclaw/workspace/


~/.picoclaw/workspace/
├── sessions/ # conversation history
├── memory/ # long-term MEMORY.md
├── cron/ # scheduled jobs DB
├── skills/ # custom SKILL.md files
├── AGENTS.md # behavior guide
├── SOUL.md # agent identity
├── USER.md # user preferences
├── TOOLS.md # tool descriptions
└── HEARTBEAT.md # periodic task prompts
Enter fullscreen mode Exit fullscreen mode

Same harness primitives as Harness Engineering — map-not-encyclopedia instructions on disk.

If you enjoy PicoClaw’s workspace-based AI assistant architecture, explore OpenClaw on TechLatest for larger-scale personal AI automation with additional skills, integrations, and workflow capabilities.

Techlatest.net - OpenClaw: AI Agent Automation Stack

Part 8 — Channels (19+ chat apps)

Talk to PicoClaw on the apps you already use:

Telegram example: examples/channel.telegram.json

//channel.telegram.json

{
  "channels": {
    "telegram": {
      "enabled": true,
      "bot_token": "STORE_IN_.security.yml",
      "allowed_user_ids": [123456789]
    }
  }
}

// Merge into ~/.picoclaw/config.json
// Put bot_token in ~/.picoclaw/.security.yml per docs:
// https://docs.picoclaw.io/docs/configuration
Enter fullscreen mode Exit fullscreen mode

Troubleshooting: Only one picoclaw gateway instance — "Conflict: terminated by other getUpdates" means a duplicate bot poller.

Gateway default: 127.0.0.1:18790. Webhook channels share one HTTP server.

Part 9 — Web search

Enable in tools.web — strongly recommended for real-world tasks (Getting Started)

Without search configured, you’ll see “API key configuration issue”  — expected until you add a key or use DuckDuckGo fallback.

Extend PicoClaw with Retrieval-Augmented Generation using RAGFlow to search PDFs, documentation, APIs, and knowledge bases.

Techlatest.net - Instant RAGFlow: Ready-to-Use AI Knowledge Retrieval Engine

Part 10 — MCP (Model Context Protocol)

Native MCP support — extend tools without forking core:

{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

CLI management:

picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp
picoclaw mcp list
picoclaw mcp test filesystem
Enter fullscreen mode Exit fullscreen mode

See examples/mcp.example.json and our MCP Visual Guide.

Web UI also supports MCP server management (v0.2.9+).

Part 11 — Skills (ClawHub)

Skills load from SKILL.md in workspace:

picoclaw skills search "web scraping"
picoclaw skills install <skill-name>
Enter fullscreen mode Exit fullscreen mode

Configure registries in tools.skills.registries (ClawHub, GitHub). Progressive capability extension — same pattern as OpenClaw skills and OpenCode Agent Skills.

Part 12 — Cron and heartbeat

Cron tool  — natural language scheduling:

  • “Remind me in 10 minutes”
  • “Remind me every 2 hours”
  • “Remind me at 9 am daily”

Jobs stored in ~/.picoclaw/workspace/cron/.

Heartbeat  — checks HEARTBEAT.md every ~30 minutes for periodic autonomous tasks. Configure in config.json → heartbeat section.

Part 13 — Vision pipeline

Send images and files to the agent — automatic base64 encoding for multimodal LLMs. Useful for MaixCam deployments and desktop chat.

Part 14 — Smart model routing

Rule-based routing sends simple queries to cheap/local models , complex ones to stronger APIs — saving cost on edge hardware with intermittent cloud access.

Configure via bindings And agent defaults in Configuration.

Part 15 — Edge and Android deployment

Hardware targets:

  • LicheeRV-Nano (~$10) — RISC-V Home Assistant
  • Raspberry Pi Zero 2 W  — make build-linux-arm or arm64
  • MaixCAM / NanoKVM  — camera and server ops
  • Android  — APK from picoclaw.io/download or Termux

PicoClaw’s pitch: give a decade-old phone a second life as your AI assistant.

Part 16 — PicoClaw vs OpenClaw vs ZeroClaw

PicoClaw wins when RAM and boot time matter. OpenClaw/ZeroClaw win when you need maximum channel depth and desktop integration on a full machine.

See OpenClaw masterclass · ZeroClaw masterclass.

Part 17 — Hands-on checklist 

# Desktop path
picoclaw-launcher
# WebUI: Provider → Channel → Gateway → Chat

# CLI path
picoclaw onboard
picoclaw agent -m "Summarize this project's README"
picoclaw gateway

# Extras
picoclaw mcp list
picoclaw skills search "calendar"
Enter fullscreen mode Exit fullscreen mode

Summary

PicoClaw proves agent harnesses don’t need gigabytes of RAM. A Go binary , a WebUI launcher , 30+ providers , 19+ channels , MCP, skills, and workspace harness files — all runnable on hardware that costs less than lunch.

Download from picoclaw.io, configure in the browser, start the gateway, and chat on Telegram. The model is swappable. The edge-native harness is the product.

Thank you so much for reading

Like | Follow | Subscribe to the newsletter.

Catch us on

Website: https://www.techlatest.net/

Newsletter: https://substack.com/@parvezmohammed

Twitter: https://twitter.com/TechlatestNet

LinkedIn: https://www.linkedin.com/in/techlatest-net/

YouTube:https://www.youtube.com/@techlatest_net/

Blogs: https://medium.com/@techlatest.net

Reddit Community: https://www.reddit.com/user/techlatest_net/

Top comments (0)