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

picoclaw skill — ingestion plan (local docs/code)

Snapshot:

• Source: picoclaw-main/
• Version basis: git describe returned 3488536 (no tags in this snapshot)
• Commit date: 2026-02-24

Queue (ingest one file/folder at a time)

Entry points

• [x] picoclaw-main/README.md
• [x] picoclaw-main/config/config.example.json
• [x] picoclaw-main/cmd/picoclaw/main.go (commands + version)

CLI commands

• [x] picoclaw-main/cmd/picoclaw/cmd_onboard.go
• [x] picoclaw-main/cmd/picoclaw/cmd_agent.go
• [x] picoclaw-main/cmd/picoclaw/cmd_gateway.go
• [x] picoclaw-main/cmd/picoclaw/cmd_status.go
• [x] picoclaw-main/cmd/picoclaw/cmd_auth.go
• [x] picoclaw-main/cmd/picoclaw/cmd_skills.go
• [x] picoclaw-main/cmd/picoclaw/cmd_cron.go
• [x] picoclaw-main/cmd/picoclaw/cmd_migrate.go

Docs: auth/providers/tools/migration

• [x] picoclaw-main/docs/tools_configuration.md
• [x] picoclaw-main/docs/ANTIGRAVITY_USAGE.md
• [x] picoclaw-main/docs/ANTIGRAVITY_AUTH.md
• [x] picoclaw-main/docs/migration/model-list-migration.md

Docs: channels

• [x] picoclaw-main/docs/wecom-app-configuration.md
• [x] picoclaw-main/docs/channels/\* (Telegram/Discord/QQ/WeCom/etc)

Finalization

• [x] Consistency pass (no conflicting commands/paths)
• [x] De-dup pass (merge overlapping reference notes)

Auth (OAuth / token store)

Credentials are stored in ~/.picoclaw/auth.json.

Commands

• Login:
• picoclaw auth login --provider openai
• picoclaw auth login --provider openai --device-code (headless)
• picoclaw auth login --provider anthropic (paste token)
• picoclaw auth login --provider google-antigravity

• Status:
• picoclaw auth status

• List Antigravity models:
• picoclaw auth models

• Logout:
• picoclaw auth logout --provider openai

Google Antigravity (headless note)

If browser redirect to localhost:51121 can’t be reached (remote/VPS), the documented flow is:

• Run login.
• Open the printed URL locally.
• After consent, copy the final redirect URL (even if it fails to load) and paste it back into the terminal.

What login updates

Auth commands may also patch ~/.picoclaw/config.json:

• Set providers.<name>.auth_method for backward compatibility.
• Add/update a model_list entry with auth_method.
• Update agents.defaults.model_name to a sensible default for that provider.

Troubleshooting

• auth status shows if tokens are expired or need refresh.
• If Antigravity returns empty/blocked responses, try a different model from auth models.

Channels

Channels are configured under channels in ~/.picoclaw/config.json and are started by picoclaw gateway.

General pattern:

1. Set channels.<name>.enabled=true 2. Fill required credentials/IDs 3. Optionally restrict who can trigger the bot via allow_from 4. Run picoclaw gateway

Common fields

• enabled: turns the channel on/off.
• allow_from: allowlist of peer IDs. Accepts strings or numbers.

Recent channel updates add voice-audio transcription echo behavior, so supported channels can reply with the recognized transcription of a voice message instead of treating voice as opaque input.

Recent v0.2.7-v0.2.8 changes also unify animated tool feedback across chat channels and Pico web/chat surfaces. If you built channel-specific workarounds for inconsistent tool-call visibility, re-test before keeping them.

WhatsApp

Config keys (from upstream config.example.json):

• channels.whatsapp.enabled
• channels.whatsapp.bridge_url (WebSocket URL for a bridge process)
• channels.whatsapp.use_native (use built-in native implementation)
• channels.whatsapp.session_store_path (where to store the native session state)
• channels.whatsapp.allow_from
• channels.whatsapp.reasoning_channel_id

Operational notes:

• If you set use_native=true, PicoClaw must be built with the whatsapp_native build tag.
• Upstream Makefile provides a helper target: make build-whatsapp-native.
• If you run a standard binary (no native tag), keep use_native=false and point bridge_url to your WhatsApp bridge.

Telegram

Config keys:

• channels.telegram.token
• channels.telegram.proxy (optional)
• channels.telegram.allow_from

Setup notes:

• Create a bot via @BotFather → /newbot → copy the HTTP API token.
• If you need an allowlist, you can obtain your Telegram numeric user ID (e.g. via a user-info bot) and put it into allow_from.

Discord

Config keys:

• channels.discord.token
• channels.discord.mention_only (only respond when mentioned)
• channels.discord.allow_from

Setup notes:

• Create an app in the Discord Developer Portal.
• Enable intents (at least Message Content Intent; some setups also require Server Members Intent).
• Invite the bot to your server with send/read permissions.

Discord channel behavior was updated to reply more cleanly when voice transcription echo is enabled.

Newer builds also support richer tool_calls/tool-feedback rendering in chat messages, which matters if your moderation or UX expectations depended on the older, less structured output.

Slack

Config keys:

• channels.slack.bot_token
• channels.slack.app_token

Setup notes:

• PicoClaw uses Slack Socket Mode (no public webhook endpoint required).
• Create a Slack app → enable Socket Mode → generate an app-level token (xapp-...).
• Install the app to your workspace and provide a bot token (xoxb-...).

Recent builds also improved Slack reply behavior when audio transcription echo is involved.

v0.2.9 adds a Slack webhook channel path. Use it when outbound webhook delivery is enough; keep Socket Mode when inbound Slack conversations and app-level event handling are required.

Late v0.2.9 channel notes

• Telegram media groups and SVG media handling were fixed. Re-test bots that receive grouped attachments or generated SVG/media replies.
• The stop command and queued voice follow-ups were tightened, which matters for voice-heavy channels where users need to cancel or interrupt pending work.
• MQTT channel stopping was fixed; if MQTT shutdown used to hang, retest before keeping wrapper-side cleanup scripts.

Teams Webhook (output-only, v0.2.6)

Config surface comes from the upstream teams_webhook channel type:

• channels.<name>.type = "teams_webhook"
• channels.<name>.settings.webhooks.default.webhook_url
• optional additional named webhook targets under webhooks.<target>
• optional target title per webhook

Operational notes:

• This is an output-only channel. It does not receive inbound chat events.
• Webhook URLs must use HTTPS, and a default target is required.
• Outbound ChatID selects the webhook target; unknown or empty targets fall back to default.
• PicoClaw renders rich notifications as Adaptive Cards and converts markdown tables into native Teams table elements when possible.

Feishu reply context (v0.2.6)

• Recent builds improved reply context for Feishu card and file replies.
• If follow-up replies used to lose thread context, re-test after upgrading before adding custom channel-side workarounds.

OneBot

Config keys:

• channels.onebot.ws_url
• channels.onebot.access_token
• channels.onebot.group_trigger_prefix

WeCom (two modes)

WeCom Bot (channels.wecom)

Intended for easier setup and group chats. Typical keys:

• token, encoding_aes_key
• webhook_url
• webhook_host, webhook_port, webhook_path

Setup notes:

• Add a group robot and copy its send webhook URL.
• If you want inbound messages, configure the callback URL + token + AES key in WeCom.

WeCom App (channels.wecom_app)

More features (incl. proactive messaging), but private chat only. Typical keys:

• corp_id, corp_secret, agent_id
• token, encoding_aes_key
• webhook_host, webhook_port (default 18792), webhook_path (default /webhook/wecom-app)

Setup notes:

• Create an internal app in the WeCom admin console and note CorpID, AgentId, and Secret.
• Configure “receive messages” callback to http://<host>:<port>/webhook/wecom-app.

Operational notes (from project docs):

• Callback URL validation requires the port to be reachable.
• If you see decrypt/padding errors for Chinese text, update PicoClaw (WeCom uses a 32-byte PKCS7 block size).

LINE

Config keys:

• channel_secret, channel_access_token
• webhook_host, webhook_port (default 18791), webhook_path

Config: ~/.picoclaw/config.json

picoclaw onboard creates the config file and a workspace directory (defaults to ~/.picoclaw/workspace).

Key sections

agents.defaults

Common fields:

• workspace: agent workspace root.
• restrict_to_workspace: when true, tools are expected to operate inside the workspace.
• model_name: the _alias_ you want to use (must match a model_list[].model_name).
• max_tokens, temperature, max_tool_iterations: generation limits.

Environment overrides exist for many fields (Go struct tags), e.g.:

• PICOCLAW_AGENTS_DEFAULTS_WORKSPACE
• PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME

agents.list and bindings (agent routing)

You can define multiple agents and route incoming messages to them by channel/account/context:

{
  "agents": {
    "defaults": { "workspace": "~/.picoclaw/workspace", "model_name": "gpt-4o-mini" },
    "list": [
      { "id": "main", "default": true, "name": "Main Assistant" },
      { "id": "support", "name": "Support Assistant" }
    ]
  },
  "bindings": [
    {
      "agent_id": "support",
      "match": { "channel": "telegram", "account_id": "*", "peer": { "kind": "direct", "id": "user123" } }
    }
  ]
}

Match priority: peer → parent_peer → guild_id → team_id → account_id (non-wildcard) → channel wildcard → default agent. Missing agent_id silently falls back to the default agent.

gateway.log_level

Controls gateway log verbosity. Default: warn. Supported: debug, info, warn, error, fatal. Override with PICOCLAW_LOG_LEVEL env var.

model_list (preferred)

Each entry describes _one way_ to call a model:

• model_name: user-facing alias (what you set in agents.defaults.model_name).
• model: protocol-prefixed identifier, e.g. openai/gpt-5.2, anthropic/claude-sonnet-4.6.
• api_key, api_base, proxy: HTTP settings.
• auth_method: oauth or token for some providers.

Notes:

• The model field format is typically [protocol/]model-id.
• Example: cerebras/llama-3.3-70b.
• If no prefix is specified, PicoClaw treats it as openai/.
• Recent releases add cleaner support for custom OpenAI-compatible endpoints in CLI/config flows. Prefer explicit api_base + auth settings per model_list entry instead of hiding provider differences behind one shared legacy provider block.
• Multiple entries can share the same model_name for round-robin load balancing.
• If you keep legacy providers, PicoClaw may auto-convert internally for backward compatibility.
• custom_headers can inject per-model HTTP headers and may override built-in headers; use it for provider-specific routing hints only when api_base/auth settings are not enough.
• Fallback evaluation now respects each fallback candidate's own provider settings, so keep fallback entries fully configured instead of assuming they inherit the primary provider behavior.

channels

Enable channels by setting channels.<name>.enabled=true and supplying tokens/IDs.

Important:

• allow_from accepts numbers or strings (it is parsed as a flexible string list).

tools

Tools are configured under tools.* (web search, exec, cron, skills registries). See: tools.md.

Recent builds also expose exec allow_remote support through web-facing settings. If you manage PicoClaw from the web UI/launcher, make sure remote-exec policy matches your CLI config instead of assuming the UI is read-only.

As of v0.2.3, cron command execution is also gated by exec settings. If a scheduled command stops running after upgrade, inspect tools.exec policy before debugging cron syntax.

Recent web config flows also track whether a change requires restart and surface save/restart prompts instead of silently writing config that will not be applied until later.

v0.2.9 adds MCP configuration coverage to the web UI and refreshes v3 config-format sync behavior. Treat web-edited MCP/server settings the same as manual config edits: save, note whether restart is required, then run a targeted status/test command.

gateway

• host, port control the health server bind address.
• If you bind to 127.0.0.1, endpoints are local-only.

heartbeat, devices

• heartbeat.enabled and heartbeat.interval start periodic tasks.
• devices.enabled and devices.monitor_usb manage device event monitoring.

.security.yml (sensitive data separation)

Store API keys and tokens in ~/.picoclaw/.security.yml separate from config.json:

model_list:
  gpt-5.4:
    api_keys:
      - "sk-proj-your-openai-key"
channels:
  telegram:
    token: "your-telegram-bot-token"

Values from .security.yml auto-map to config fields. If a field exists in both, .security.yml takes precedence. Set chmod 600 on the file.

voice (audio transcription)

voice.model_name lets you use any multimodal model for audio transcription instead of Groq Whisper:

{
  "voice": {
    "model_name": "voice-gemini",
    "echo_transcription": false
  }
}

If voice.model_name is unset, PicoClaw falls back to Groq when a Groq API key is available.

Workspace file hot-reload

AGENT.md, SOUL.md, USER.md, and memory/MEMORY.md are auto-detected via mtime tracking. No gateway restart needed after editing these files.

Recovery operations (v0.2.9)

• Factory reset support was added. Treat it as destructive recovery: export or back up config/workspace state first, then re-run onboarding/status checks.

Minimal config change checklist

• [ ] Set at least one model_list[].api_key (or configure OAuth via picoclaw auth login ...).
• [ ] Set agents.defaults.model_name to a model_list[].model_name you configured.
• [ ] If running gateway externally, decide whether gateway.host should be 127.0.0.1 or 0.0.0.0.

Cron (scheduled jobs)

Cron jobs are executed by the gateway’s cron service.

List jobs

• picoclaw cron list

Add a job

Two schedule styles:

1. Every N seconds

• picoclaw cron add --name "Ping" --every 60 --message "Say hi"

2. Cron expression

• picoclaw cron add --name "Daily" --cron "0 9 * * *" --message "Send a daily summary"

Delivery options:

• Add --deliver plus --channel and --to to route the result to a channel.

Execution policy note (v0.2.3)

Cron command execution is now gated through exec settings.

• If a cron task needs command execution, verify the relevant tools.exec policy first.
• Keep deny patterns enabled unless the environment is fully trusted.
• Use tools.cron.exec_timeout_minutes together with exec policy so scheduled commands stay bounded.

Enable/disable

• picoclaw cron disable <job_id>
• picoclaw cron enable <job_id>

Remove

• picoclaw cron remove <job_id>

Gateway operations

picoclaw gateway starts the long-running services that make PicoClaw feel like a “daemon”.

What gateway starts

• Agent loop
• Channel manager (only enabled channels are started)
• Cron service (jobs stored under workspace/cron/jobs.json)
• Heartbeat service (periodic prompts)
• Health server
• Optional device monitoring
• Optional voice transcription integration (Groq)

Health endpoints

When gateway is running:

• GET http://<host>:<port>/health
• GET http://<host>:<port>/ready

Bind address comes from gateway.host and gateway.port in config.

Recent releases also surface server.pid in health output, which is useful when supervising PicoClaw under service managers or wrapper scripts.

Debug logs

• picoclaw gateway --debug

Voice transcription (Groq)

If a Groq API key is configured, gateway can attach a Groq transcriber to supported channels (Telegram/Discord/Slack).

The key is detected from:

• legacy providers.groq.api_key, or
• a model_list entry whose model starts with groq/ and has api_key.

Common operational gotchas

• “No channels enabled”: set channels.<name>.enabled=true in config.
• Port conflicts: change gateway.port or channel webhook ports.
• External access: binding gateway.host=0.0.0.0 exposes health endpoints to the network.

v0.2.2 operational notes

• Gateway startup/path handling was tightened: prefer invoking the binary through the resolved gateway path and pass the config explicitly when you wrap PicoClaw in scripts or service managers.
• Empty-model errors are now clarified; if gateway fails early, verify agents.defaults.model_name against configured model_list entries before debugging channels.

v0.2.3 operational notes

• Web gateway hot reload and polling state sync improve operator feedback when config or runtime state changes through the web flow.
• WebSocket traffic can now proxy through the web-server port, which simplifies deployments that only expose one web-facing port.
• Gateway should no longer start if the underlying gateway server is not actually running; treat that as an early failure signal, not a partial-success state.

v0.2.6 operational notes

• Gateway PID handling now validates ownership/liveness more carefully and cleans stale pid files instead of treating every leftover pid as a live instance.
• If a wrapped/service-managed gateway still refuses to start, inspect the pid file and ownership first; manual pid deletion should be the last resort, not the first step.
• The web UI now derives the WebSocket URL from the browser location instead of backend assumptions, which is the safer behavior behind reverse proxies or browser-facing launchers.

v0.2.8 operational notes

• The web surface now gives clearer save/restart prompts and tracks which config changes require a restart before they take effect.
• Tool/model/channel/web-search restart requirements are surfaced more explicitly, which reduces the risk of “saved but not applied” operator confusion.
• Frontend file downloads and thought/tool-visibility toggles are more capable, so operator expectations around what the web UI can inspect/control should be updated.

v0.2.9 operational notes

• Runtime events planning and factory reset flows were added; use them for controlled recovery rather than deleting state by hand.
• Network-error retry and voice-media-store reload fixes reduce transient channel failures, but still keep gateway debug logs around reconnect/reload incidents.

Hook system

PicoClaw supports a hook system for intercepting and observing agent lifecycle events. Two mounting modes:

1. In-process hooks — Go code compiled into the binary 2. Out-of-process hooks — external processes via JSON-RPC over stdio

Supported hook types

Synchronous hook points: before_llm, after_llm, before_tool, after_tool, approve_tool. Everything else is exposed as read-only events.

Execution order

HookManager priority: in-process first → process hooks second → lower priority first → name order as tie-breaker.

Timeouts

Global defaults under hooks.defaults:

• observer_timeout_ms
• interceptor_timeout_ms
• approval_timeout_ms

Per-process-hook timeout_ms is not currently supported.

Config example (out-of-process)

{
  "hooks": {
    "enabled": true,
    "processes": {
      "py_review_gate": {
        "enabled": true,
        "priority": 100,
        "transport": "stdio",
        "command": ["python3", "/tmp/review_gate.py"],
        "observe": ["tool_exec_start", "tool_exec_end", "tool_exec_skipped"],
        "intercept": ["before_tool", "approve_tool"],
        "env": {
          "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log"
        }
      }
    }
  }
}

Common use cases

• Logging/auditing: observe all tool executions without modifying behavior
• Tool approval gate: require explicit approval for dangerous tools before execution
• LLM request/response filtering: modify prompts or responses in-flight
• Cost tracking: intercept LLM calls to log token usage

Direct tool responses (v0.2.6)

• before_tool hooks can now return action: "respond" with a final tool result payload.
• Use this for plugin-style tools implemented completely inside the hook process, result caching, or controlled mock responses during testing.
• respond skips the actual tool execution path and does not trigger after_tool, so treat it as a terminal decision for that tool call.
• The upstream JSON-RPC hook protocol documents the response envelope fields (for_llm, for_user, silent, is_error) explicitly; keep your hook output aligned with that structure.

Migration

OpenClaw → PicoClaw

Use the CLI migrator:

• picoclaw migrate (auto-detect + prompt)

Common flags:

• --dry-run (preview)
• --refresh (re-sync workspace)
• --config-only / --workspace-only
• --force
• --openclaw-home / --picoclaw-home

providers → model_list

model_list is the preferred model-centric config.

Benefits:

• Zero-code addition for OpenAI-compatible providers
• Load balancing (multiple entries with same model_name)
• Protocol-prefixed routing like openai/, anthropic/, antigravity/, openrouter/, groq/, deepseek/, cerebras/.

See also: config.md.

Quickstart (CLI + gateway)

Install options

Pick one:

1. Prebuilt binary (recommended for users)

• Download a release artifact for your OS/arch.
• Run picoclaw version to confirm it starts.

2. Build from source (good for dev)

• make deps
• make build (binary goes to picoclaw-main/build/)
• make install (installs to ~/.local/bin/picoclaw by default)

3. Docker Compose (gateway)

• Copy config and set tokens/keys.
• Start gateway profile.

First run

1. Initialize config and workspace templates:

• picoclaw onboard

2. Edit config:

• File: ~/.picoclaw/config.json
• Minimum: set an API key for at least one entry in model_list and select it via agents.defaults.model_name.

3. Sanity check:

• picoclaw status

Talk to the agent (CLI)

• One-shot:
• picoclaw agent -m "Hello"
• Interactive:
• picoclaw agent
• Override model for one call:
• picoclaw agent -m "Hello" --model <model_name>

Run gateway

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

Gateway brings up:

• Channels (if enabled)
• Cron service + heartbeat service
• Health server: http://<host>:<port>/health and /ready

Next

• See config details: config.md
• Enable a chat channel: channels.md
• Add a scheduled job: cron.md
• Configure auth (OAuth/token): auth.md

If you use the web frontend, v0.2.2 also improves launcher integration and adds agent-management UI, so upgrade first before troubleshooting mismatches between CLI state and the browser view.

Skills management

Skills live inside the workspace (default: ~/.picoclaw/workspace/skills).

List / show

• List installed:
• picoclaw skills list
• Show a skill:
• picoclaw skills show <skill-name>

Install

Two install paths are supported:

1. From GitHub repo slug (backward compatible)

• picoclaw skills install <owner>/<repo>/<skill-folder>
• Example: picoclaw skills install sipeed/picoclaw-skills/weather

2. From a registry (e.g. ClawHub)

• picoclaw skills install --registry <name> <slug>
• Example: picoclaw skills install --registry clawhub github

Registry endpoints are configured under tools.skills.registries.*.

Metadata parsing note (v0.2.2)

Skills loader markdown metadata parsing was refactored. If a custom skill suddenly stops loading after upgrade, validate its frontmatter/metadata formatting before blaming registry transport.

Remove

• picoclaw skills remove <skill-name>

Skill channel commands

From any chat channel, you can inspect and force skills:

• /list skills — shows installed skill names available to the current agent.
• /use <skill> <message> — forces a specific skill for a single request.
• /use <skill> — arms that skill for your next message in the same chat session.
• /use clear — cancels a pending skill override.

Built-in skills

• picoclaw skills install-builtin copies a small set of builtin skills (weather/news/stock/calculator) into the workspace.
• picoclaw skills list-builtin lists builtin skills from the global picoclaw directory.

Tools configuration

Tools are configured under tools in ~/.picoclaw/config.json.

Sections:

• tools.web: search/fetch
• tools.exec: shell execution guardrails
• tools.cron: scheduler limits
• tools.skills: skill registries (e.g. ClawHub)

MCP management (v0.2.8)

Recent PicoClaw builds add CLI-level MCP management commands for inspecting and operating configured servers:

• picoclaw mcp list
• picoclaw mcp show
• picoclaw mcp add
• picoclaw mcp edit
• picoclaw mcp remove
• picoclaw mcp test

Operational notes:

• Treat mcp test as the first-line check before blaming agent/tool routing.
• MCP init failures are surfaced to command handlers more clearly in the newer release line, so a failed test/init is now a meaningful signal rather than silent flakiness.
• Local stdio command paths are normalized and home-directory paths are expanded, which reduces config drift across machines.

MCP/tool feedback updates (v0.2.9)

• The config web UI has an MCP section, so operators can inspect or edit MCP-related settings without leaving the web flow.
• MCP streamable HTTP support and Gemini MCP schema sanitization were fixed; re-run picoclaw mcp test after upgrade before blaming server-side MCP schemas.
• tool_feedback defaults now include pretty_print and disable_escape_html. Review any UI/channel code that assumed raw escaped HTML or compact JSON output.
• Edit-file diff preview support improves generated-edit review. Prefer previewing changes before enabling tools that can modify files.

Web tools

Supported switches (from project docs):

• Brave: enabled, api_key, max_results
• DuckDuckGo: enabled, max_results
• Perplexity: enabled, api_key, max_results
• tools.web.proxy: proxy for web tools

Exec tool (dangerous command blocking)

Config keys:

• tools.exec.enable_deny_patterns (default true)
• tools.exec.custom_deny_patterns (regex list)
• allow_remote support is now surfaced in web settings, so remote-exec policy can be managed consistently across CLI and web flows.

Docs describe default blocked patterns including:

• destructive deletes (rm -rf, del /f/q, ...)
• format, mkfs, dd if=..., writes to /dev/sd*
• shutdown/reboot
• command substitution ($(), backticks)
• pipes to shell (| sh, | bash)
• privilege escalation (sudo, chmod, chown)
• remote ops (curl | sh, ssh)
• package managers and container commands

Security posture update (v0.2.2)

• PicoClaw hardened unauthenticated tool-exec paths.
• Treat remote execution as an explicit policy decision; do not rely on older implicit behavior.

Exec and subagent updates (v0.2.3)

• Exec controls are now used to gate cron command execution as well as direct command flows.
• Whitelist path checks are normalized for symlinked allowed roots, which reduces false negatives in workspace layouts that rely on symlinks.
• SpawnStatusTool is available for reporting subagent status back into the agent/tool surface.

Cron tool

• tools.cron.exec_timeout_minutes controls how long scheduled executions may run.
• Scheduled command execution now depends on exec policy, so review tools.exec when cron jobs need shell access.

Skills tool (registries)

Configure registries under:

• tools.skills.registries.<name>.*

Example registry in docs:

• clawhub: enabled, base_url, search_path, skills_path, download_path

Environment variable overrides

Docs define an override format for tools:

• PICOCLAW_TOOLS_<SECTION>_<KEY>

Example:

• PICOCLAW_TOOLS_WEB_DUCKDUCKGO_ENABLED=true

Note: array-type environment variables are not supported for tools; set those in the config file.

Serial hardware tool (v0.2.8)

PicoClaw now ships a cross-platform serial tool and wires it into runtime/dashboard flows.

• Treat serial access as an explicit operator capability; do not enable it casually on hosts where attached hardware should stay out of scope.
• Re-check exec/remote policy and agent permissions when exposing serial operations through gateway/web management surfaces.

Troubleshooting

“Config not found” / “Workspace not found”

• Run picoclaw onboard to create ~/.picoclaw/config.json and workspace templates.
• Check with picoclaw status.

“No channels enabled”

• Enable at least one channel: set channels.<name>.enabled=true and configure credentials.
• Start: picoclaw gateway.

Model not found

Error shape:

• model "xxx" not found in model_list or providers

Fix:

• Ensure agents.defaults.model_name matches an existing model_list[].model_name.

Auth issues

• picoclaw auth status shows whether tokens are expired.
• Re-login the provider if needed.

Gateway not reachable from host

• If running in Docker, binding to 127.0.0.1 may make endpoints unreachable externally.
• Set gateway.host=0.0.0.0 intentionally if you need remote access.

Exec tool blocks commands

PicoClaw has default deny patterns for dangerous commands (delete, pipes to shell, sudo, etc.). If something is blocked unexpectedly, adjust tools.exec.custom_deny_patterns or (carefully) disable defaults.

See also: tools.md.

Provider/tool schema issues after v0.2.9

• If Gemini-backed MCP tools fail schema validation, update first and re-run picoclaw mcp test; the release line includes Gemini MCP schema sanitization fixes.
• DeepSeek vision unsupported errors are clearer. Treat them as capability mismatch signals and switch model/tool routing instead of retrying the same vision request.
• For DeepSeek/Mimo reasoning-history replay issues, verify the current release before adding custom transcript rewriting.

WeCom callback validation fails

• Ensure the webhook port is reachable from WeCom.
• Confirm corp_id, token, encoding_aes_key.
• Check gateway logs (--debug).