A Complete Guide to Getting Started with PicoClaw: From Installation to Telegram Integration and Local AI Usage

PicoClaw is a lightweight personal AI assistant written in Go. It runs as a single binary with no external dependencies, making it perfect for low-spec boards like the Raspberry Pi. It starts up in less than a second and consumes less than 10MB of memory.

It is highly versatile. Beyond interactive use in the terminal, it can run as a resident bot for Telegram or Discord, or execute scheduled tasks via cron. Since you can customize agent behavior using Markdown files, you can tailor the assistant to your preferences without writing a single line of code.

This article covers everything you need to know, from installation to getting started.

Installation

PicoClaw can be installed simply by downloading the binary from GitHub Releases.

macOS

For Apple Silicon, download picoclaw-darwin-arm64; for Intel Macs, download picoclaw-darwin-amd64.

# Example for Apple Silicon
cd ~/Downloads
chmod +x picoclaw-darwin-arm64
mv picoclaw-darwin-arm64 ~/.local/bin/picoclaw

Once the PATH is set, you can use the picoclaw command.

Linux / Raspberry Pi

For arm64 environments like Raspberry Pi, use picoclaw-linux-arm64. For x86_64 environments, use picoclaw-linux-amd64.

chmod +x picoclaw-linux-arm64
sudo mv picoclaw-linux-arm64 /usr/local/bin/picoclaw

Windows

Download picoclaw-windows-amd64.exe and place it in a folder such as C:\picoclaw. It is convenient to rename the file to picoclaw.exe.

Initial Setup

Run the initialization command in the directory where you downloaded the binary.

picoclaw init

This will generate the workspace and configuration file. The default workspace is created at ~/.picoclaw/workspace/.

Configuring the Settings

To use PicoClaw, you need an LLM API key. The configuration file is located at ~/.picoclaw/workspace/config.json. Open it with a text editor to edit.

Using DeepSeek

{
  "api_key": "sk-your-api-key",
  "base_url": "https://api.deepseek.com",
  "model": "deepseek-chat",
  "language": "ja"
}

Using OpenAI

{
  "api_key": "sk-your-api-key",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-4o",
  "language": "ja"
}

Enter the API key obtained from your provider in api_key. Setting language to ja will ensure responses are in Japanese. You must restart PicoClaw after changing the settings.

Running PicoClaw

Once you have saved the configuration file, start the chat.

picoclaw run

When the > prompt appears, it is ready. Simply type your message and press Enter to have the AI respond.

> Tell me today's weather

To exit, press Ctrl + D.

Using with Local AI

If you want to avoid API costs or use it offline, combining it with Ollama is the easiest way. Ollama is a tool for running LLMs locally.

Setting up Ollama

1. Download and run the installer from ollama.com
2. Retrieve the model in your terminal

ollama run llama3

The chat will begin once the model download is complete. After verifying it works, exit with Ctrl + D. Ollama will continue to run in the background.

Changing PicoClaw Settings

Update config.json as follows:

{
  "api_key": "ollama",
  "base_url": "http://localhost:11434/v1",
  "model": "llama3",
  "language": "ja"
}

You can set api_key to ollama; no authentication is required. Specify the local Ollama address in base_url. Now, simply run picoclaw run as usual, and it will work with your local model, completely offline without needing a network connection.

Customizing Agents

PicoClaw is more than just a chatbot. You can change your agent's personality and skills simply by editing Markdown files in the workspace.

AGENTS.md

Write your agent's instructions in ~/.picoclaw/workspace/AGENTS.md.

# Agent: TechWriter
You are an expert in technical documentation. Please respond in concise and accurate Japanese.

## Skills
- Answering technical questions
- Code review
- Creating and proofreading documentation

## Constraints
- Do not answer based on speculation
- Explicitly state if there is no source

Save the file and restart PicoClaw to begin operating with the new persona.

SOUL.md

You can define the agent's fundamental behavior and values in SOUL.md. While AGENTS.md provides specific instructions, SOUL.md is the place for the underlying principles.

memory Directory

You can place long-term memory notes in ~/.picoclaw/workspace/memory/. These are notes the agent can reference during conversation, allowing it to utilize project information or your personal preferences based on context.

Using as a Telegram Bot

By running PicoClaw as a Telegram bot, you can chat with your AI assistant from your smartphone anytime. You can ask it to look things up on the go or summarize articles.

Creating the Bot

1. Search for and open BotFather in Telegram
2. Send the /newbot command
3. Enter the bot's name and username
4. Copy the generated token

Adding to config.json

{
  "api_key": "sk-your-api-key",
  "base_url": "https://api.deepseek.com",
  "model": "deepseek-chat",
  "language": "ja",
  "integrations": {
    "telegram": {
      "token": "your-telegram-bot-token",
      "allow_users": ["your_telegram_username"]
    }
  }
}

Enter only your own Telegram username in allow_users. If left empty, anyone could use your bot, leading to unexpected API costs.

After saving the settings, start with picoclaw run. Open the bot in Telegram and send a message to receive a response.

Using as a Discord Bot

Discord integration involves a few more steps than Telegram.

1. Create an application in the Discord Developer Portal
2. Select bot in OAuth2 Scopes and grant View Channels / Send Messages / Read Message History permissions
3. Enable MESSAGE CONTENT INTENT in the Bot settings
4. Invite the bot to your server
5. Get your User ID (enable Developer Mode and right-click your profile)

{
  "integrations": {
    "discord": {
      "token": "your-discord-bot-token",
      "application_id": "your-app-id"
    }
  }
}

Never expose tokens or API keys publicly. Committing config.json to git will cause your tokens to leak.

Scheduling Tasks with cron

PicoClaw includes a cron feature to automate tasks at set times.

# Execute every hour
picoclaw cron add --message "Summarize my inbox" --every 3600

# Execute at 9:00 AM on weekdays (cron expression)
picoclaw cron add --message "Organize today's tasks" --cron "0 9 * * 1-5"

# Execute once at a specific date and time
picoclaw cron add --message "Remind: Review meeting" --at "2026-03-01T09:00:00Z"

Management commands for cron jobs are also provided.

picoclaw cron list       # List registered jobs
picoclaw cron remove     # Delete a job
picoclaw cron toggle     # Enable/disable toggle
picoclaw cron run        # Run immediately

CLI Command List

Common commands summarized below:

Command	Description
picoclaw init	Initialize workspace and configuration file
picoclaw run	Start chat
picoclaw status	Check current configuration
picoclaw cron list	List registered cron jobs
picoclaw cron add	Add a cron job

Troubleshooting

If you don't get a response after setting the API key, check your settings first with picoclaw status. Also, look for typos in the base_url or model name. If using Ollama, ensure the Ollama process is running.

If you have corrupted your workspace files, you can delete ~/.picoclaw/workspace/ and re-run picoclaw init. Since this will erase your configuration file, be sure to take a backup beforehand.

---

PicoClaw's source code is published under the MIT License. For more information, please refer to GitHub or the official tutorial.