Quick Start

This guide will get you from zero to a working AI assistant in just a few minutes.

Prerequisites: Make sure you have installed PicoClaw before proceeding.

Overview

Getting started with PicoClaw is a simple 3-step process:

Initialize

Run the onboarding command to create your configuration

Configure API Keys

Add your LLM provider API key to the config file

Start Chatting

Talk to your AI assistant via CLI or chat apps

Step 1: Initialize

Run the onboarding command to set up your workspace and configuration:

picoclaw onboard

This creates:

~/.picoclaw/config.json — Main configuration file
~/.picoclaw/workspace/ — Working directory for the agent

You should see a success message indicating that the configuration was created.

Step 2: Configure API Keys

PicoClaw needs an LLM provider to function. Open the configuration file:

vim ~/.picoclaw/config.json
# Or use your preferred editor

Basic Configuration Structure

Here’s what the config file looks like:

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

Configuration Breakdown

agents.defaults — Core Settings

Field	Description	Default
`workspace`	Working directory for the agent	`~/.picoclaw/workspace`
`model_name`	Name reference for the model to use	`gpt4`
`max_tokens`	Maximum tokens per response	`8192`
`temperature`	Creativity level (0.0-1.0)	`0.7`
`max_tool_iterations`	Max tool calls per conversation turn	`20`

model_list — Provider Configuration

The model_list array defines available LLM models:

{
  "model_name": "gpt4",           // Friendly name to reference
  "model": "openai/gpt-5.2",      // Provider/model format
  "api_key": "your-api-key",      // API key for the provider
  "request_timeout": 300           // Optional: timeout in seconds
}

request_timeout is optional. If omitted or set to <= 0, PicoClaw uses the default timeout (120s).

tools.web — Search Configuration

Web search is optional but enhances the assistant’s capabilities:

Brave Search (recommended): Best results, 2000 free queries/month
Tavily: Optimized for AI agents, 1000 free queries/month
DuckDuckGo: No API key required, free fallback option

You can enable multiple search providers simultaneously.

Get API Keys

LLM Providers

Free Tier Options:

OpenRouter — 200K tokens/month, multiple models
Zhipu — 200K tokens/month, best for Chinese
Groq — Free tier, fast inference
Cerebras — Free tier available

Paid Options:

Anthropic — Claude models
OpenAI — GPT models
Gemini — Google’s models

Web Search (Optional)

Recommended:

Brave Search — 2000 queries/month
Tavily — 1000 queries/month

Free Fallback:

DuckDuckGo — No key required (enabled by default)

Example Configurations

{
  "model_list": [
    {
      "model_name": "claude-sonnet",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "sk-or-v1-your-openrouter-key"
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "claude-sonnet"
    }
  }
}

See config.example.json in the PicoClaw repository for a complete configuration template with all available options.

Step 3: Start Chatting

Once configured, you can start using PicoClaw immediately!

CLI Chat

# Ask a single question
picoclaw agent -m "What is 2+2?"

Expected Output

When you run your first command, you should see something like:

[INFO] agent: Starting agent
[INFO] agent: Using model: gpt4 (openai/gpt-5.2)
[INFO] agent: Loading workspace from ~/.picoclaw/workspace

> What is 2+2?

The answer is 4.

[INFO] agent: Conversation complete (1 turn, 2 tool calls)

Congratulations! Your PicoClaw AI assistant is now running.

Next Steps

Connect Chat Apps

PicoClaw can integrate with multiple chat platforms:

Easy setup with just a bot token

Discord

Simple bot token + intents configuration

Native QR scan or bridge URL

QQ

AppID + AppSecret

DingTalk

Client credentials setup

WeCom

Multiple integration modes

To enable a chat app, add its configuration to config.json. Example for Telegram:

Create a Bot

Open Telegram and message @BotFather:

/newbot

Follow the prompts and copy the bot token.

Get Your User ID

Message @userinfobot on Telegram to get your user ID.

Add to Config

Edit ~/.picoclaw/config.json:

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

Start Gateway

Run the gateway to connect to chat platforms:

picoclaw gateway

Now message your Telegram bot!

See the full Chat Apps Configuration guide for detailed setup instructions for all platforms.

Advanced Features

Scheduled Tasks

Set up periodic tasks and reminders with cron-like scheduling

Heartbeat

Automatic periodic task execution from HEARTBEAT.md

Custom Skills

Extend functionality with custom skill modules

Security Sandbox

Restrict agent access to specific directories

Common Commands

Command	Description
`picoclaw onboard`	Initialize config & workspace
`picoclaw agent -m "..."`	Chat with the agent (one-shot)
`picoclaw agent`	Interactive chat mode
`picoclaw gateway`	Start gateway for chat apps
`picoclaw status`	Show current status
`picoclaw cron list`	List scheduled jobs
`picoclaw cron add ...`	Add a scheduled job

Troubleshooting

"API key configuration issue"

This means you haven’t configured an LLM provider API key yet, or the key is invalid.Solution:

Get an API key from one of the supported providers
Add it to ~/.picoclaw/config.json in the model_list section
Make sure the model_name in agents.defaults matches an entry in model_list

"Web search says API key configuration issue"

This is normal if you haven’t configured a search API key. PicoClaw will provide helpful links for manual searching.To enable web search:

Get a free Brave Search API key (2000 queries/month)
Or enable DuckDuckGo (no key required):

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

"Content filtering errors"

Some providers (like Zhipu) have content filtering that may block certain queries.Solution:

Try rephrasing your query
Use a different model/provider
Check the provider’s content policy

Telegram bot: "Conflict: terminated by other getUpdates"

This happens when multiple instances of the bot are running.Solution:

Make sure only one picoclaw gateway is running at a time
Kill any existing gateway processes: pkill picoclaw

What’s Next?

Full Configuration Guide

Explore all configuration options and advanced features

Chat App Integration

Connect Telegram, Discord, WhatsApp, and more

CLI Reference

Complete command-line interface documentation

GitHub Repository

View source code and contribute

You’re all set! Enjoy your ultra-lightweight AI assistant.

Get Started

Core Concepts

Commands

Configuration

Chat Channels

Features

Deployment

Advanced

​Quick Start

​Overview

​Step 1: Initialize

​Step 2: Configure API Keys

​Basic Configuration Structure

​Configuration Breakdown

​Get API Keys

LLM Providers

Web Search (Optional)

​Example Configurations

​Step 3: Start Chatting

​CLI Chat

​Expected Output

​Next Steps

​Connect Chat Apps

Telegram

Discord

WhatsApp

QQ

DingTalk

WeCom

​Advanced Features

Scheduled Tasks

Heartbeat

Custom Skills

Security Sandbox

​Common Commands

​Troubleshooting

​What’s Next?

Full Configuration Guide

Chat App Integration

CLI Reference

GitHub Repository

Build docs developers (and LLMs) love

Quick Start

Overview

Step 1: Initialize

Step 2: Configure API Keys

Basic Configuration Structure

Configuration Breakdown

Get API Keys

Example Configurations

Step 3: Start Chatting

CLI Chat

Expected Output

Next Steps

Connect Chat Apps

Advanced Features

Common Commands

Troubleshooting

What’s Next?