PicoClaw

PicoClaw is an ultra-lightweight AI assistant written in Go. This skill is a practical operator playbook for running the CLI, configuring ~/.picoclaw/config.json, and operating gateway + channels.

Quick navigation

Getting started + common commands: references/quickstart.md
Config (model_list, tools, gateway, channels): references/config.md
Tools (web search, exec guardrails, registries): references/tools.md
Auth flows (OpenAI OAuth, Google Antigravity OAuth, token): references/auth.md
Gateway operations (health/ready, cron, heartbeat, voice): references/gateway.md
Channels (Telegram/Discord/WeCom/OneBot/etc): references/channels.md
Skills management (install/list/remove, registries): references/skills.md
Cron scheduling via CLI: references/cron.md
Migration notes: references/migration.md
Troubleshooting: references/troubleshooting.md

When to use

Use when you need to:

Bootstrap PicoClaw on a host (onboard → config → run)
Switch providers/models via model_list
Run the agent in CLI mode or operate gateway
Enable chat channels (Telegram/Discord/Slack/WeCom/...)
Configure tools (web search, exec deny patterns, skills registries)
Install/remove skills into the workspace
Schedule recurring jobs (cron)

Recipes

1) Initialize + verify

Create initial config and workspace templates:
- picoclaw onboard
Verify what’s configured:
- picoclaw status

2) Chat from CLI

One-shot:
- picoclaw agent -m "Hello"
Interactive:
- picoclaw agent

3) Run gateway (channels + cron + health)

Start gateway:
- picoclaw gateway
Debug logs:
- picoclaw gateway --debug

4) Manage auth

OpenAI OAuth (optionally device-code for headless):
- picoclaw auth login --provider openai
- picoclaw auth login --provider openai --device-code
Google Antigravity OAuth:
- picoclaw auth login --provider google-antigravity
Check status / list models:
- picoclaw auth status
- picoclaw auth models

5) Install skills

List installed skills:
- picoclaw skills list
Install from GitHub repo slug:
- picoclaw skills install sipeed/picoclaw-skills/weather
Install from registry:
- picoclaw skills install --registry clawhub github

6) Add a scheduled job

Create a cron job:
- picoclaw cron add --name "Daily report" --cron "0 9 * * *" --message "Summarize my inbox"
List jobs:
- picoclaw cron list

Critical safety notes

Do not commit real API keys or OAuth tokens into a repo; keep them in ~/.picoclaw/ only.
Be cautious enabling the exec tool; keep deny patterns enabled unless you fully trust the environment.
Exposing gateway to 0.0.0.0 makes health endpoints reachable from the network; do that only intentionally.

picoclaw