# Picoclaw Agent > Configure, extend, debug, or contribute to PicoClaw itself. Use when the task is about PicoClaw CLI commands, config.json, gateway, auth, models, skills, MCP servers, cron, routing, sessions, self-evolution, built-in slash commands, or repository internals. Use PicoClaw-native workflows, terminology, paths, and configuration. - Skill: `sipeed/picoclaw-agent` (Agent Skill) - Install (CLI): `npx skillmds@latest add sipeed/picoclaw-agent` - Raw SKILL.md: https://api.skillmd.com/api/skills/sipeed/picoclaw-agent/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: sipeed (https://skillmd.com/u/sipeed) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/sipeed/picoclaw-agent --- # PicoClaw Agent PicoClaw is a lightweight personal AI assistant and agent framework with a native CLI, chat gateway, MCP integration, installable skills, session routing, scheduled jobs, and self-evolution. Use this skill when the job is about **PicoClaw itself**: onboarding, configuration, debugging, adding features, extending the CLI, changing routing/session behavior, working on skills or MCP support, or contributing to this repository. ## Operating Stance When this skill is active, stay fully subordinate to PicoClaw's real architecture: - Prefer PicoClaw commands, config keys, workspace layout, and docs. - Follow PicoClaw source and docs for behavior, naming, and workflows. - Treat repository code and checked-in docs as the source of truth. ## Quick Start ```bash # Initialize ~/.picoclaw/config.json and ~/.picoclaw/workspace picoclaw onboard # Authenticate a provider picoclaw auth login --provider openai # Inspect or switch the default model picoclaw model picoclaw model my-default-model # One-shot prompt picoclaw agent -m "Hello" # Interactive CLI chat picoclaw agent # Start the gateway for chat channels picoclaw gateway # Inspect runtime/config health picoclaw status # Explore installed skills and MCP servers picoclaw skills list picoclaw mcp list ``` ## Command Surface ### Core CLI ```bash picoclaw onboard picoclaw agent [-m MESSAGE] [--session KEY] [--model MODEL] [--debug] picoclaw gateway [--debug] [--no-truncate] [--allow-empty] [--host HOST] picoclaw status picoclaw version picoclaw migrate ``` ### Configuration and Models ```bash # Show or change the default configured model alias picoclaw model picoclaw model # Add a model from an OpenAI-compatible endpoint picoclaw model add --api-base URL --api-key KEY picoclaw model add -b http://localhost:8000/v1 -k dummy -m my-model -n local # Reset config to factory defaults (preserves sensitive keys) picoclaw config reset picoclaw config reset --force ``` Notes: - There is **no** general `picoclaw config edit` or `picoclaw config set`. - Advanced edits are usually done by editing `~/.picoclaw/config.json` directly. ### Authentication ```bash picoclaw auth login --provider openai picoclaw auth login --provider anthropic --setup-token picoclaw auth login --provider antigravity --device-code picoclaw auth models picoclaw auth status picoclaw auth logout --provider openai picoclaw auth weixin picoclaw auth wecom --timeout 10m ``` ### Skills ```bash picoclaw skills list picoclaw skills show picoclaw skills search "query" picoclaw skills install owner/repo/path picoclaw skills install --registry clawhub picoclaw skills remove picoclaw skills list-builtin picoclaw skills install-builtin ``` Skill loading priority is: 1. `~/.picoclaw/workspace/skills` 2. `~/.picoclaw/skills` 3. builtin embedded skills ### MCP ```bash picoclaw mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp picoclaw mcp add --deferred github --env-file .env.github -- npx -y @modelcontextprotocol/server-github picoclaw mcp list picoclaw mcp list --status picoclaw mcp show github picoclaw mcp test github picoclaw mcp edit picoclaw mcp remove github ``` Notes: - `picoclaw mcp` is a **configuration manager** for `tools.mcp.servers`. - It does **not** keep servers running by itself; the host/gateway loads them later. ### Cron ```bash picoclaw cron list picoclaw cron add --name "Daily summary" --message "Summarize today's logs" --cron "0 18 * * *" picoclaw cron add --name "Ping" --message "heartbeat" --every 300 --deliver picoclaw cron enable picoclaw cron disable picoclaw cron remove ``` Notes: - The current CLI `picoclaw cron add` supports recurring jobs only: `--every` or `--cron`. - One-shot `at_seconds` jobs exist in the cron system, but not as a first-class CLI flag today. ## Providers PicoClaw supports 30+ LLM providers through `model_list`. Credential patterns in PicoClaw are: - `model_list[].api_keys` for most hosted APIs - `picoclaw auth login --provider ...` for the built-in auth helper flows (`openai`, `anthropic`, `antigravity`) - local or self-hosted endpoints for providers like `ollama`, `lmstudio`, `vllm`, and `litellm` - external platform credentials for providers like `bedrock`, `azure`, and `github-copilot` `picoclaw auth login` does **not** cover every provider. For most providers, the normal path is adding a `model_list` entry with `provider`, `model`, and `api_keys`. ### Common Provider Matrix | Provider | `provider` value | Auth path in PicoClaw | | --- | --- | --- | | OpenAI | `openai` | OAuth helper via `picoclaw auth login --provider openai`, or `model_list[].api_keys` | | Anthropic | `anthropic` | API key in `model_list[].api_keys`, or helper flow via `picoclaw auth login --provider anthropic` | | Anthropic Messages API | `anthropic-messages` | API key in `model_list[].api_keys` | | Google Gemini | `gemini` | API key in `model_list[].api_keys` | | OpenRouter | `openrouter` | API key in `model_list[].api_keys` | | Zhipu / GLM | `zhipu` | API key in `model_list[].api_keys` | | DeepSeek | `deepseek` | API key in `model_list[].api_keys` | | VolcEngine / Doubao | `volcengine` | API key in `model_list[].api_keys` | | Qwen / DashScope | `qwen` | API key in `model_list[].api_keys` | | Moonshot / Kimi | `moonshot` | API key in `model_list[].api_keys` | | MiniMax | `minimax` | API key in `model_list[].api_keys` | | Mistral | `mistral` | API key in `model_list[].api_keys` | | Groq | `groq` | API key in `model_list[].api_keys` | | NVIDIA NIM | `nvidia` | API key in `model_list[].api_keys` | | Cerebras | `cerebras` | API key in `model_list[].api_keys` | | Azure OpenAI | `azure` | `api_key` in `model_list`, or Microsoft Entra ID if built with `azidentity` support | | AWS Bedrock | `bedrock` | AWS credentials plus Bedrock-enabled build (`go build -tags bedrock`) | | Antigravity | `antigravity` | OAuth helper via `picoclaw auth login --provider antigravity` | | GitHub Copilot | `github-copilot` | External Copilot gRPC endpoint, default `localhost:4321` | | Ollama | `ollama` | Local endpoint, no API key required | | LM Studio | `lmstudio` | Local endpoint, API key optional | | vLLM | `vllm` | Local OpenAI-compatible endpoint | | LiteLLM | `litellm` | Proxy endpoint and whichever credential model the proxy expects | | Claude CLI | `claude-cli` | Local Claude CLI provider, configured by workspace/runtime | | Codex CLI | `codex-cli` | Local Codex CLI provider, configured by workspace/runtime | ### Additional OpenAI-Compatible Vendors PicoClaw also carries first-class metadata or routing support for additional vendors such as: - `venice` - `vivgrid` - `longcat` - `modelscope` - `mimo` - `novita` - `byteplus` - `shengsuanyun` - `avian` - `zai-coding` - `gpt4free` For the full provider matrix, default API bases, protocol families, and vendor-specific examples, read `docs/guides/providers.md`. ## Built-in Tool Families PicoClaw tools are configured under `tools` in `config.json` and registered dynamically at runtime. Important activation rules: - most tools are enabled or disabled individually through `tools.*` - agent-level allowlists can further restrict tool visibility - `turn_profile.tools` can narrow tool exposure for a request or agent - deferred MCP tools can stay hidden until unlocked by tool discovery ### Runtime Tool Families | Family | Runtime tool names | What they provide | | --- | --- | --- | | Filesystem | `read_file`, `write_file`, `list_dir`, `edit_file`, `append_file` | Read, write, list, and patch workspace files | | Web | `web_search`, `web_fetch` | Search the web and fetch readable page content | | Command execution | `exec` | Shell command execution with deny-pattern guardrails | | Scheduling | `cron` | Scheduled jobs, reminders, recurring tasks, and command jobs | | Skills registry | `find_skills`, `install_skill` | Search and install skills from configured registries | | MCP | `mcp__` | Tools contributed by connected MCP servers | | MCP discovery | `tool_search_tool_bm25`, `tool_search_tool_regex` | Discover deferred hidden MCP tools on demand | | Hardware | `i2c`, `spi`, `serial` | Hardware access for supported devices and boards | | Messaging | `message`, `reaction` | Send outbound messages and reactions through channel integrations | | Media | `send_file`, `load_image`, `send_tts` | Send files, load local images into context, generate TTS output | | Subagents | `spawn`, `subagent`, `spawn_status`, `delegate` | Background tasks, synchronous sub-turns, task status, multi-agent delegation | ### Tool Registration Notes - `send_tts` is registered only when a TTS provider is available. - `spawn` and `spawn_status` require `subagent` support to be enabled. - `delegate` is auto-registered only when more than one agent exists. - MCP discovery tools are relevant only when deferred MCP discovery is enabled. - `message` can be configured for outbound media as well as plain text. For per-tool configuration, read `docs/reference/tools_configuration.md`. ## Specialized Subagents and Spawn PicoClaw has a first-class subagent model for long-running work, isolated subproblems, and multi-agent specialization. The core idea is: - use `spawn` for background work that should continue without blocking the current turn - use `subagent` for an isolated synchronous sub-task when the parent needs the result now - use `delegate` to hand a task to a specific peer agent with its own identity, model, workspace, and tools - use `spawn_status` or `/subagents` to inspect what is currently running ### Choosing the Right Subagent Tool | Tool | Execution style | Best use | | --- | --- | --- | | `spawn` | Async background task | Web research, API polling, long scans, work that can report back later | | `subagent` | Sync isolated sub-turn | Focused analysis, transformation, or verification that must return before the parent continues | | `delegate` | Sync handoff to named peer agent | Work that should run as a specialized agent rather than as a generic child turn | | `spawn_status` | Inspection/status only | Check running, completed, failed, or canceled spawned tasks | ### Specialized Peer Agents Specialized subagents are configured through the multi-agent system, not through ad hoc prompts alone. The two important layers are: - `config.json` defines which peer agents exist and which ones a given agent is allowed to spawn via `subagents.allow_agents` - each agent's `AGENT.md` defines the identity that makes that peer worth spawning: `name`, `description`, tools, skills, MCP servers, and optional model overrides Minimal shape: ```json { "agents": { "list": [ { "id": "main", "default": true, "subagents": { "allow_agents": ["research"] } }, { "id": "research" } ] } } ``` Example `AGENT.md` for a specialist: ```md --- name: Research Agent description: Specialist for deep web research, evidence gathering, and synthesis. tools: [web_search, web_fetch, message] skills: [deep-research] --- ``` ### Automatic Agent Discovery When an agent has the `spawn` tool and at least one allowed peer, PicoClaw injects a lightweight agent registry into the system prompt automatically. That means: - the model can see eligible peer agents without calling a separate `list_agents` tool - only spawnable peers are shown - the current agent is omitted - discovery uses the peer agent's stable `id`, `name`, and `description` In practice, this is what makes targeted `spawn(..., agent_id="research")` or `delegate(agent_id="research", ...)` reliable. ### Operational Behavior Subagent execution semantics that matter: - subagents run in isolated ephemeral session history, so their reasoning and intermediate steps do not pollute the parent conversation - `spawn` returns immediately and launches background work in a goroutine - `subagent` waits for completion and returns the result directly - `delegate` is synchronous and runs as the target peer agent instead of a generic child task - `spawn_status` is scoped to the current conversation when channel/chat context exists - all subagents still share the same workspace security boundary; they do not bypass sandbox or path restrictions Runtime limits and lifecycle rules: - nested sub-turn depth is limited to 3 - concurrency is limited to 5 sub-turns per parent turn - waiting for a concurrency slot times out after 30 seconds - spawned background tasks are marked critical so they can survive graceful parent completion - hard aborts still cascade to child and grandchild sub-turns ### Practical Patterns Use `spawn` when: - the task will take a while - the result can arrive later - the current turn should keep moving Use `subagent` when: - you need isolation from the parent context - you want an independent attempt at a bounded subproblem - the parent must wait for the answer before planning the next step Use `delegate` when: - a named peer agent is clearly better suited for the task - that peer has a narrower tool/skill/model setup - you want the task to run in the peer's own workspace/runtime identity ### Examples Background specialist research: ```text spawn( task="Search the web for the latest PicoClaw MCP integration patterns and summarize them.", label="mcp-research", agent_id="research" ) ``` Synchronous isolated check: ```text subagent( task="Review this config for risky tool exposure and return only the concrete findings." ) ``` Synchronous handoff to a named peer: ```text delegate( agent_id="research", task="Collect three primary-source references for current provider authentication behavior." ) ``` ### Observability For live visibility: - call `spawn_status` to inspect one task or list visible tasks in the current conversation - use `/subagents` in chat channels to show the active subagent tree for the current session ## Voice, Transcription, and TTS PicoClaw can transcribe inbound audio and synthesize outbound speech, but voice setup is model-driven like the rest of the runtime. The important pattern is: - ASR uses `voice.model_name` - TTS uses `voice.tts_model_name` - both resolve through named entries in `model_list` - secrets belong in `.security.yml`, not inline in `voice` ### STT (Voice -> Text) Voice and audio messages from supported channels can be transcribed automatically at the agent level. Recommended setup: 1. add an ASR-capable model entry to `model_list` 2. set `voice.model_name` to that entry's `model_name` 3. store the matching API key in `.security.yml` 4. optionally set `voice.echo_transcription` if you want the transcript echoed back in chat Example: ```json { "model_list": [ { "model_name": "voice-groq", "model": "groq/whisper-large-v3-turbo" } ], "voice": { "model_name": "voice-groq", "echo_transcription": true } } ``` ```yaml model_list: voice-groq: api_keys: - "gsk_your_groq_key" ``` ### Common ASR Routes | Route | Example model | Notes | | --- | --- | --- | | Groq Whisper | `groq/whisper-large-v3-turbo` | Fast OpenAI-compatible Whisper transcription and a common default choice | | OpenAI Whisper | `openai/whisper-1` | Standard Whisper transcription through the OpenAI-compatible audio endpoint | | ElevenLabs Scribe | `provider: elevenlabs`, `model: scribe_v1` | Uses PicoClaw's dedicated ElevenLabs transcription path | | Audio-capable chat models | `gemini/gemini-2.5-flash`, `openai/gpt-4o-audio-preview` | Multimodal audio transcription path; some model combinations are still evolving | Detection behavior that matters: - `voice.model_name` is the preferred and recommended path - if it resolves to an ElevenLabs model, PicoClaw uses the ElevenLabs transcriber - if it resolves to a Whisper-compatible model, PicoClaw uses the Whisper transcription path - if it resolves to an audio-capable multimodal model, PicoClaw can use audio-model transcription - if `voice.model_name` is omitted, PicoClaw still performs compatibility scanning across `model_list` for legacy auto-detected ASR entries ### TTS (Text -> Voice) Outbound speech is driven by `voice.tts_model_name` and exposed through `send_tts` when a provider is available. Recommended setup: 1. add a TTS-capable model entry to `model_list` 2. set `voice.tts_model_name` to that entry's `model_name` 3. store the API key in `.security.yml` 4. if the provider needs model-specific TTS fields, add them under `model_list[].extra_body` 5. enable `send_tts` in the tool configuration if you want the agent to emit speech files Example: ```json { "model_list": [ { "model_name": "openai-tts", "model": "openai/tts-1" } ], "voice": { "tts_model_name": "openai-tts" } } ``` ```yaml model_list: openai-tts: api_keys: - "sk-openai-your-key" ``` Example with OpenRouter MAI Voice 2: ```json { "model_list": [ { "model_name": "mai-voice-2", "provider": "openrouter", "model": "microsoft/mai-voice-2", "api_base": "https://openrouter.ai/api/v1", "extra_body": { "voice": "en-US-Harper:MAI-Voice-2", "response_format": "mp3" } } ], "voice": { "tts_model_name": "mai-voice-2" } } ``` ```yaml model_list: mai-voice-2: api_keys: - "sk-or-your-openrouter-key" ``` ### Current TTS Provider Paths | Provider path | Example model | Notes | | --- | --- | --- | | OpenAI-compatible speech | `openai/tts-1` | Best-supported path; PicoClaw sends an OpenAI-style `/audio/speech` request | | Xiaomi MiMo | `mimo/mimo-v2-tts` | Dedicated MiMo TTS provider path with MP3 output | Operational notes: - the preferred selection path is `voice.tts_model_name` - if that is missing, PicoClaw can still scan `model_list` for the first API-backed model whose ID contains `tts` - the current OpenAI-style TTS request defaults to `voice: alloy` and `response_format: opus` - you can override `voice` and `response_format` for a specific TTS model through `model_list[].extra_body` - if a provider rejects `response_format`, PicoClaw retries once without that field - `send_tts` is only registered when TTS detection succeeds ## In-Session Slash Commands PicoClaw's shared slash command registry lives under `pkg/commands`. Use these when helping users inside chat channels: ```text /start /help /show model /show channel /show agents /show mcp /list models /list channels /list agents /list skills /list mcp /subagents /use [message] /use clear /btw ``` Semantics that matter: - `/use ` forces one installed skill for a single request. - `/use ` arms that skill for the **next** message in the same chat session. - `/use clear` cancels the pending skill override. - `/btw ` asks an isolated side question without mutating the main session history. - `/subagents` shows the currently active subagent tree for the session. - Unknown slash commands pass through to normal LLM handling instead of hard-failing. Telegram auto-registers supported top-level commands like `/start`, `/help`, `/show`, `/list`, `/use`, and `/btw`. ## Key Paths and Environment ### Important Files ```text ~/.picoclaw/config.json Main config ~/.picoclaw/.security.yml Sensitive values stored outside config.json ~/.picoclaw/auth.json OAuth/token store ~/.picoclaw/workspace/ Default workspace ~/.picoclaw/workspace/skills/ Workspace skills ~/.picoclaw/workspace/sessions/ Session history ~/.picoclaw/workspace/cron/ Scheduled jobs store ``` Default workspace layout: ```text ~/.picoclaw/workspace/ ├── sessions/ ├── memory/ ├── state/ ├── cron/ ├── skills/ ├── AGENT.md ├── HEARTBEAT.md ├── IDENTITY.md ├── SOUL.md └── USER.md ``` ### Important Environment Variables ```bash PICOCLAW_CONFIG=/path/to/config.json PICOCLAW_HOME=/path/to/picoclaw-home PICOCLAW_BUILTIN_SKILLS=/path/to/custom-builtin-skills PICOCLAW_LOG_LEVEL=debug PICOCLAW_GATEWAY_HOST=0.0.0.0 ``` Use `PICOCLAW_CONFIG` when the user reports "wrong config file" behavior. Use `PICOCLAW_HOME` when the user wants a portable or service-managed install. ## PicoClaw-Native Concepts ### Model Configuration PicoClaw is model-centric. The key fields are: - `agents.defaults.model_name` - `model_list` - optional `provider` - runtime `model` Important behavior: - `agents.defaults.model_name` must match a `model_name` entry in `model_list`. - If `provider` is set, PicoClaw sends `model` to that provider unchanged. - If `provider` is omitted, legacy `provider/model` parsing is still supported. ### Sessions and Routing Session behavior is configured primarily through: - `session.dimensions` - `session.identity_links` - `agents.dispatch.rules[*].session_dimensions` Available dimensions: - `space` - `chat` - `topic` - `sender` Baseline separation still includes: - agent - channel - account So even a tiny `session.dimensions` list does **not** create one giant global memory across every platform. ### Skills Skills are plain directories with `SKILL.md`. The loader requires: - a valid lowercase-or-hyphen skill name - a non-empty description - a `SKILL.md` file in the skill directory Prefer this format: ```text workspace/skills//SKILL.md ``` PicoClaw only relies on `name` and `description` frontmatter fields for loading and matching. ### MCP Discovery PicoClaw supports always-loaded and deferred MCP tools. Use: - `--deferred` when tools should stay hidden until explicitly discovered - `picoclaw mcp show ` to inspect active tools - `/list mcp` and `/show mcp ` from chat channels when debugging live agents ### Self-Evolution The `evolution` block controls self-evolution: - `enabled` - `mode`: `observe`, `draft`, `apply` - `state_dir` - `min_task_count` - `min_success_ratio` - `cold_path_trigger` - `cold_path_times` Use `observe` first. Use `draft` when the team wants reviewable candidate skill changes. Use `apply` only when automatic workspace skill updates are acceptable. Notes: - `cold_path_trigger: manual` has no general user-facing CLI/API trigger yet. ## Debugging Workflow Start with the most PicoClaw-native path: 1. Check `picoclaw status`. 2. Confirm which config file is active. 3. Inspect `agents.defaults.model_name` and `model_list`. 4. Run `picoclaw gateway --debug` for runtime visibility. 5. Add `--no-truncate` only when full prompt or tool payload inspection is necessary. 6. For skill issues, inspect the skill directory and frontmatter. 7. For MCP issues, use `picoclaw mcp list`, `show`, and `test`. 8. For routing/session issues, inspect `session.dimensions` and `agents.dispatch.rules`. Useful runtime facts: - `--no-truncate` only works with `--debug`. - gateway health endpoints expose `/health`, `/ready`, and `/reload`. - `tool_feedback` can publish visible tool-execution notices directly into chats. ### Where to Find Logs For gateway and runtime debugging, PicoClaw writes logs under its home directory: ```text ~/.picoclaw/logs/gateway.log ~/.picoclaw/logs/gateway_panic.log ``` If `PICOCLAW_HOME` is overridden, use: ```text $PICOCLAW_HOME/logs/gateway.log $PICOCLAW_HOME/logs/gateway_panic.log ``` In practice, check these places first: - `~/.picoclaw/logs/` for persisted gateway logs - the terminal running `picoclaw gateway` or `picoclaw agent` - Docker stdout/stderr via `docker compose -f docker/docker-compose.yml logs -f` - launcher or service logs if PicoClaw is being run under another supervisor Useful controls: - `picoclaw gateway --debug` for detailed runtime logs - `picoclaw gateway --debug --no-truncate` for full prompt/tool payload inspection - `gateway.log_level` or `PICOCLAW_LOG_LEVEL` to raise verbosity to `debug` or `info` Special case: - the standalone `picoclaw agent` command uses console logging unless `PICOCLAW_LOG_FILE` is set explicitly - process hooks can write JSONL file logs when `PICOCLAW_HOOK_LOG_FILE` is set; this is hook-specific and separate from the main gateway log path ## Repository Map When contributing code, these paths matter most: - `cmd/picoclaw/main.go` — root CLI wiring - `cmd/picoclaw/internal/agent/` — direct CLI agent command - `cmd/picoclaw/internal/gateway/` — gateway startup and flags - `cmd/picoclaw/internal/auth/` — auth flows, QR onboarding - `cmd/picoclaw/internal/model/` — default model switching and `model add` - `cmd/picoclaw/internal/skills/` — install/list/show/remove/search commands - `cmd/picoclaw/internal/mcp/` — MCP CLI configuration manager - `cmd/picoclaw/internal/cron/` — cron CLI - `pkg/commands/` — shared slash command registry - `pkg/agent/` — prompt assembly, sessions, routing, tool execution, hooks - `pkg/skills/` — skill loading, metadata, registry installs - `pkg/mcp/` — MCP runtime integration - `pkg/config/` — config schema, defaults, migration, persistence - `docs/guides/configuration.md` — user-facing config reference - `docs/guides/session-guide.md` — session behavior recipes - `docs/reference/mcp-cli.md` — authoritative MCP CLI behavior - `docs/reference/cron.md` — cron behavior and limitations - `docs/operations/debug.md` — debugging workflow - `docs/operations/troubleshooting.md` — known misconfiguration patterns - `docs/architecture/agent-self-evolution.md` — evolution design and safety ## Contribution Rules When changing PicoClaw: - Prefer extending existing CLI groups and shared registries instead of adding parallel one-off flows. - Keep docs aligned with code for CLI flags, slash commands, and config behavior. - If you add or change a slash command, inspect `pkg/commands` and the chat-channel docs that mention command availability. - If you touch skills behavior, validate load order, naming rules, and frontmatter assumptions. - If you touch routing or session logic, re-check both `docs/guides/session-guide.md` and architecture docs so behavior and docs stay consistent. - If you touch MCP, remember the CLI manages config while the runtime host manages execution. ## Common Troubleshooting ### "model ... not found in model_list" Check that: - `agents.defaults.model_name` matches a configured `model_name` - the target `model_list` entry is enabled - the `provider` and `model` fields use PicoClaw's model-centric rules ### OpenRouter `free is not a valid model ID` Prefer explicit provider config: ```json { "provider": "openrouter", "model": "free" } ``` Not: ```json { "model": "free" } ``` ### Skill not appearing Check: - directory name is a valid skill name - `SKILL.md` exists - frontmatter `name` and `description` are present and sane - the skill lives under workspace, global, or builtin roots ### MCP server exists but tools do not show up Check: - `tools.mcp.enabled` is true - the server is enabled - deferred discovery settings match expectations - `picoclaw mcp test ` succeeds - `/show mcp ` or `picoclaw mcp show ` exposes tools ### Agent remembers too much or too little Check: - `session.dimensions` - any per-rule `session_dimensions` - whether the issue is really session isolation versus summarization ### Config edits do not seem to apply Check: - `PICOCLAW_CONFIG` - `PICOCLAW_HOME` - whether the user edited `config.json` or `.security.yml` - whether they are testing the CLI path, gateway path, or both ## Load These Docs Next Read these only when the task needs them: - `docs/guides/configuration.md` for config, routing, skills, turn profiles, and evolution - `docs/guides/session-guide.md` for session isolation recipes - `docs/reference/tools_configuration.md` for tool-specific config - `docs/reference/mcp-cli.md` for MCP CLI flags and storage behavior - `docs/reference/cron.md` for schedule types and security gates - `docs/operations/debug.md` for runtime inspection - `docs/operations/troubleshooting.md` for common provider/model mistakes If the task is code-level rather than user-facing, read the matching package under `cmd/picoclaw/internal/`, `pkg/commands/`, `pkg/agent/`, `pkg/skills/`, or `pkg/mcp/` before proposing behavior changes.