picoclaw-agent✓ ناجح

محتوى SKILL.md

---
name: picoclaw-agent
description: "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."
metadata: {"nanobot":{"emoji":"🦞"}}
---

# 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 <model_name>

# 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 <name>
picoclaw skills search "query"
picoclaw skills install owner/repo/path
picoclaw skills install --registry clawhub <slug>
picoclaw skills remove <name>
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 <job-id>
picoclaw cron disable <job-id>
picoclaw cron remove <job-id>
```

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_<server>_<tool>` | 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 <server>
/list models
/list channels
/list agents
/list skills
/list mcp
/subagents
/use <skill> [message]
/use clear
/btw <question>
```

Semantics that matter:

- `/use <skill> <message>` forces one installed skill for a single request.
- `/use <skill>` arms that skill for the **next** message in the same chat session.
- `/use clear` cancels the pending skill override.
- `/btw <question>` 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-name>/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 <name>` to inspect active tools
- `/list mcp` and `/show mcp <server>` 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 <name>` succeeds
- `/show mcp <server>` or `picoclaw mcp show <name>` 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.

الترخيص

الترخيص المُعلن: MIT

MIT License

Copyright (c) 2026 sipeed

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

عرض الترخيص في المستودع المصدري — النسخة المنشورة هناك هي المرجع.