Picoclaw

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.

Links

• Documentation
• Releases
• GitHub

Quick navigation

• Getting started + common commands: references/quickstart.md
• Config (model_list, tools, gateway, channels, bindings): 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/Feishu/OneBot/etc): references/channels.md
• Skills management (install/list/remove, channel commands): references/skills.md
• Hook system (observers, interceptors, approvers): references/hooks.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/...)
• Send outbound notifications to Microsoft Teams via webhook targets
• Configure tools (web search, exec deny patterns, skills registries)
• Install/remove skills into the workspace
• Use skill channel commands (/list skills, /use <skill>)
• Configure hook system (observers, interceptors, approvers)
• Configure agent bindings (route messages to different agents)
• 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.

Release Highlights (v0.2.8)

• MCP operations: PicoClaw now exposes first-class MCP management commands (show, add, list, remove, test, edit) and surfaces init/lifecycle failures more clearly.
• Custom endpoints + tools: CLI/config flows add better support for custom OpenAI-compatible endpoints and a cross-platform serial hardware tool.
• Chat/web feedback: tool-call visibility, animated tool feedback, restart prompts, and reasoning visibility are more consistent across Pico web/chat surfaces and channels.

Release Highlights (v0.2.9)

• MCP and config UI: the config web UI adds an MCP section, MCP streamable HTTP support is fixed, Gemini MCP schema sanitization is hardened, and v3 config format sync docs/flows were refreshed.
• Tool feedback and edit UX: tool_feedback defaults add pretty_print and disable_escape_html, parent-session tool feedback cleanup is fixed, and edit-file diff previews improve review before applying generated edits.
• Channels and voice: Slack webhook channel support lands, Telegram media groups/SVG media handling improves, queued voice follow-ups and voice media store reload behavior are fixed, and stop command / MQTT channel handling are tightened.
• Provider/runtime fixes: Bedrock streaming, DeepSeek vision unsupported errors, DeepSeek/Mimo reasoning replay, network-error retry, and factory reset flows were improved.

Release Highlights (v0.2.6)

• Hooks respond action: before_tool hooks can now return a final tool result directly, which is useful for plugin-style tools, caching, or policy-controlled mocks without registering a native tool implementation.
• Teams outbound channel: teams_webhook adds an output-only Microsoft Teams path with named webhook targets and Adaptive Card rendering for richer notifications.
• Provider request shaping: model_list[].custom_headers lets you inject extra HTTP headers per model entry, and fallback resolution now uses each fallback candidate's own provider settings.
• Gateway/web reliability: PID ownership/stale-pid handling was hardened, and the web UI now derives its WebSocket endpoint from the browser-visible location instead of backend assumptions.
• Channel polish: Feishu reply context was improved for card/file replies, reducing broken follow-up threading in that connector.

Release Highlights (v0.2.4)

• Hook system: in-process and out-of-process hooks (JSON-RPC over stdio) with observer, LLM interceptor, tool interceptor, and tool approver stages. Configurable via hooks in config.
• Agent bindings: route incoming messages to different agents by channel/account/context via bindings config section.
• Skill channel commands: /list skills, /use <skill> <message>, /use <skill> (arm for next message), /use clear.
• Configurable log level: gateway.log_level (debug/info/warn/error/fatal) in config or PICOCLAW_LOG_LEVEL env var.
• Voice transcription model: voice.model_name lets you use any multimodal model for audio transcription; Groq Whisper remains as fallback.
• Security config separation: .security.yml file for storing API keys/tokens separate from config.json.
• Workspace file hot-reload: AGENT.md, SOUL.md, USER.md, MEMORY.md are auto-detected via mtime tracking — no restart needed.
• SubTurn error handling and logging improved. Security config precedence fixed during migration.

Links

• Upstream repo (for releases/issues): https://github.com/sipeed/picoclaw