diff --git a/README.md b/README.md index a3e970d97..00fb0fd68 100644 --- a/README.md +++ b/README.md @@ -208,653 +208,6 @@ Connect Picoclaw to the Agent Social Network simply by sending a single message **Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)** ## ๐Ÿ–ฅ๏ธ CLI Reference -## โš™๏ธ Configuration - -Config file: `~/.picoclaw/config.json` - -### Environment Variables - -You can override default paths using environment variables. This is useful for portable installations, containerized deployments, or running picoclaw as a system service. These variables are independent and control different paths. - -| Variable | Description | Default Path | -|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------| -| `PICOCLAW_CONFIG` | Overrides the path to the configuration file. This directly tells picoclaw which `config.json` to load, ignoring all other locations. | `~/.picoclaw/config.json` | -| `PICOCLAW_HOME` | Overrides the root directory for picoclaw data. This changes the default location of the `workspace` and other data directories. | `~/.picoclaw` | - -**Examples:** - -```bash -# Run picoclaw using a specific config file -# The workspace path will be read from within that config file -PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway - -# Run picoclaw with all its data stored in /opt/picoclaw -# Config will be loaded from the default ~/.picoclaw/config.json -# Workspace will be created at /opt/picoclaw/workspace -PICOCLAW_HOME=/opt/picoclaw picoclaw agent - -# Use both for a fully customized setup -PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway -``` - -### Workspace Layout - -PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`): - -``` -~/.picoclaw/workspace/ -โ”œโ”€โ”€ sessions/ # Conversation sessions and history -โ”œโ”€โ”€ memory/ # Long-term memory (MEMORY.md) -โ”œโ”€โ”€ state/ # Persistent state (last channel, etc.) -โ”œโ”€โ”€ cron/ # Scheduled jobs database -โ”œโ”€โ”€ skills/ # Custom skills -โ”œโ”€โ”€ AGENTS.md # Agent behavior guide -โ”œโ”€โ”€ HEARTBEAT.md # Periodic task prompts (checked every 30 min) -โ”œโ”€โ”€ IDENTITY.md # Agent identity -โ”œโ”€โ”€ SOUL.md # Agent soul -โ””โ”€โ”€ USER.md # User preferences -``` - -### Skill Sources - -By default, skills are loaded from: - -1. `~/.picoclaw/workspace/skills` (workspace) -2. `~/.picoclaw/skills` (global) -3. `/skills` (builtin) - -For advanced/test setups, you can override the builtin skills root with: - -```bash -export PICOCLAW_BUILTIN_SKILLS=/path/to/skills -``` - -### Unified Command Execution Policy - -- Generic slash commands are executed through a single path in `pkg/agent/loop.go` via `commands.Executor`. -- Channel adapters no longer consume generic commands locally; they forward inbound text to the bus/agent path. Telegram still auto-registers supported commands at startup. -- Unknown slash command (for example `/foo`) passes through to normal LLM processing. -- Registered but unsupported command on the current channel (for example `/show` on WhatsApp) returns an explicit user-facing error and stops further processing. -### ๐Ÿ”’ Security Sandbox - -PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace. - -#### Default Configuration - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "restrict_to_workspace": true - } - } -} -``` - -| Option | Default | Description | -| ----------------------- | ----------------------- | ----------------------------------------- | -| `workspace` | `~/.picoclaw/workspace` | Working directory for the agent | -| `restrict_to_workspace` | `true` | Restrict file/command access to workspace | - -#### Protected Tools - -When `restrict_to_workspace: true`, the following tools are sandboxed: - -| Tool | Function | Restriction | -| ------------- | ---------------- | -------------------------------------- | -| `read_file` | Read files | Only files within workspace | -| `write_file` | Write files | Only files within workspace | -| `list_dir` | List directories | Only directories within workspace | -| `edit_file` | Edit files | Only files within workspace | -| `append_file` | Append to files | Only files within workspace | -| `exec` | Execute commands | Command paths must be within workspace | - -#### Additional Exec Protection - -Even with `restrict_to_workspace: false`, the `exec` tool blocks these dangerous commands: - -* `rm -rf`, `del /f`, `rmdir /s` โ€” Bulk deletion -* `format`, `mkfs`, `diskpart` โ€” Disk formatting -* `dd if=` โ€” Disk imaging -* Writing to `/dev/sd[a-z]` โ€” Direct disk writes -* `shutdown`, `reboot`, `poweroff` โ€” System shutdown -* Fork bomb `:(){ :|:& };:` - -#### Error Examples - -``` -[ERROR] tool: Tool execution failed -{tool=exec, error=Command blocked by safety guard (path outside working dir)} -``` - -``` -[ERROR] tool: Tool execution failed -{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)} -``` - -#### Disabling Restrictions (Security Risk) - -If you need the agent to access paths outside the workspace: - -**Method 1: Config file** - -```json -{ - "agents": { - "defaults": { - "restrict_to_workspace": false - } - } -} -``` - -**Method 2: Environment variable** - -```bash -export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false -``` - -> โš ๏ธ **Warning**: Disabling this restriction allows the agent to access any path on your system. Use with caution in controlled environments only. - -#### Security Boundary Consistency - -The `restrict_to_workspace` setting applies consistently across all execution paths: - -| Execution Path | Security Boundary | -| ---------------- | ---------------------------- | -| Main Agent | `restrict_to_workspace` โœ… | -| Subagent / Spawn | Inherits same restriction โœ… | -| Heartbeat tasks | Inherits same restriction โœ… | - -All paths share the same workspace restriction โ€” there's no way to bypass the security boundary through subagents or scheduled tasks. - -### Heartbeat (Periodic Tasks) - -PicoClaw can perform periodic tasks automatically. Create a `HEARTBEAT.md` file in your workspace: - -```markdown -# Periodic Tasks - -- Check my email for important messages -- Review my calendar for upcoming events -- Check the weather forecast -``` - -The agent will read this file every 30 minutes (configurable) and execute any tasks using available tools. - -#### Async Tasks with Spawn - -For long-running tasks (web search, API calls), use the `spawn` tool to create a **subagent**: - -```markdown -# Periodic Tasks - -## Quick Tasks (respond directly) - -- Report current time - -## Long Tasks (use spawn for async) - -- Search the web for AI news and summarize -- Check email and report important messages -``` - -**Key behaviors:** - -| Feature | Description | -| ----------------------- | --------------------------------------------------------- | -| **spawn** | Creates async subagent, doesn't block heartbeat | -| **Independent context** | Subagent has its own context, no session history | -| **message tool** | Subagent communicates with user directly via message tool | -| **Non-blocking** | After spawning, heartbeat continues to next task | - -#### How Subagent Communication Works - -``` -Heartbeat triggers - โ†“ -Agent reads HEARTBEAT.md - โ†“ -For long task: spawn subagent - โ†“ โ†“ -Continue to next task Subagent works independently - โ†“ โ†“ -All tasks done Subagent uses "message" tool - โ†“ โ†“ -Respond HEARTBEAT_OK User receives result directly -``` - -The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent. - -**Configuration:** - -```json -{ - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -| Option | Default | Description | -| ---------- | ------- | ---------------------------------- | -| `enabled` | `true` | Enable/disable heartbeat | -| `interval` | `30` | Check interval in minutes (min: 5) | - -**Environment variables:** - -* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable -* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval - -### Providers - -> [!NOTE] -> Groq provides free voice transcription via Whisper. If configured, audio messages from any channel will be automatically transcribed at the agent level. - -| Provider | Purpose | Get API Key | -| ------------ | --------------------------------------- | ------------------------------------------------------------ | -| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | -| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](https://bigmodel.cn) | -| `volcengine` | LLM(Volcengine direct) | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | -| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) | -| `anthropic` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | -| `openai` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | -| `deepseek` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | -| `qwen` | LLM (Qwen direct) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) | -| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) | -| `cerebras` | LLM (Cerebras direct) | [cerebras.ai](https://cerebras.ai) | -| `vivgrid` | LLM (Vivgrid direct) | [vivgrid.com](https://vivgrid.com) | -| `azure` | LLM (Azure OpenAI) | [portal.azure.com](https://portal.azure.com) | - -### Model Configuration (model_list) - -> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providersโ€”**zero code changes required!** - -This design also enables **multi-agent support** with flexible provider selection: - -- **Different agents, different providers**: Each agent can use its own LLM provider -- **Model fallbacks**: Configure primary and fallback models for resilience -- **Load balancing**: Distribute requests across multiple endpoints -- **Centralized configuration**: Manage all providers in one place - -#### ๐Ÿ“‹ All Supported Vendors - -| Vendor | `model` Prefix | Default API Base | Protocol | API Key | -| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- | -| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Get Key](https://platform.openai.com) | -| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Get Key](https://console.anthropic.com) | -| **ๆ™บ่ฐฑ AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | -| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Get Key](https://platform.deepseek.com) | -| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Get Key](https://aistudio.google.com/api-keys) | -| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Get Key](https://console.groq.com) | -| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Get Key](https://platform.moonshot.cn) | -| **้€šไน‰ๅƒ้—ฎ (Qwen)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Get Key](https://dashscope.console.aliyun.com) | -| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Get Key](https://build.nvidia.com) | -| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (no key needed) | -| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Get Key](https://openrouter.ai/keys) | -| **LiteLLM Proxy** | `litellm/` | `http://localhost:4000/v1` | OpenAI | Your LiteLLM proxy key | -| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local | -| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Get Key](https://cerebras.ai) | -| **VolcEngine (Doubao)** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) | -| **็ฅž็ฎ—ไบ‘** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - | -| **BytePlus** | `byteplus/` | `https://ark.ap-southeast.bytepluses.com/api/v3` | OpenAI | [Get Key](https://www.byteplus.com) | -| **Vivgrid** | `vivgrid/` | `https://api.vivgrid.com/v1` | OpenAI | [Get Key](https://vivgrid.com) | -| **LongCat** | `longcat/` | `https://api.longcat.chat/openai` | OpenAI | [Get Key](https://longcat.chat/platform) | -| **ModelScope (้ญ”ๆญ)**| `modelscope/` | `https://api-inference.modelscope.cn/v1` | OpenAI | [Get Token](https://modelscope.cn/my/tokens) | -| **Azure OpenAI** | `azure/` | `https://{resource}.openai.azure.com` | Azure | [Get Key](https://portal.azure.com) | -| **Novita** | `novita/` | `https://api.novita.ai/openai` | OpenAI | [Get Key](https://novita.ai) | -| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth only | -| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - | - -#### Basic Configuration - -```json -{ - "model_list": [ - { - "model_name": "ark-code-latest", - "model": "volcengine/ark-code-latest", - "api_key": "sk-your-api-key" - }, - { - "model_name": "gpt-5.4", - "model": "openai/gpt-5.4", - "api_key": "sk-your-openai-key" - }, - { - "model_name": "claude-sonnet-4.6", - "model": "anthropic/claude-sonnet-4.6", - "api_key": "sk-ant-your-key" - }, - { - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-zhipu-key" - } - ], - "agents": { - "defaults": { - "model": "gpt-5.4" - } - } -} -``` - -#### Vendor-Specific Examples - -**OpenAI** - -```json -{ - "model_name": "gpt-5.4", - "model": "openai/gpt-5.4", - "api_key": "sk-..." -} -``` - -**VolcEngine (Doubao)** - -```json -{ - "model_name": "ark-code-latest", - "model": "volcengine/ark-code-latest", - "api_key": "sk-..." -} -``` - -**ๆ™บ่ฐฑ AI (GLM)** - -```json -{ - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" -} -``` - -**DeepSeek** - -```json -{ - "model_name": "deepseek-chat", - "model": "deepseek/deepseek-chat", - "api_key": "sk-..." -} -``` - -**Anthropic (with API key)** - -```json -{ - "model_name": "claude-sonnet-4.6", - "model": "anthropic/claude-sonnet-4.6", - "api_key": "sk-ant-your-key" -} -``` - -> Run `picoclaw auth login --provider anthropic` to paste your API token. - -**Anthropic Messages API (native format)** - -For direct Anthropic API access or custom endpoints that only support Anthropic's native message format: - -```json -{ - "model_name": "claude-opus-4-6", - "model": "anthropic-messages/claude-opus-4-6", - "api_key": "sk-ant-your-key", - "api_base": "https://api.anthropic.com" -} -``` - -> Use `anthropic-messages` protocol when: -> - Using third-party proxies that only support Anthropic's native `/v1/messages` endpoint (not OpenAI-compatible `/v1/chat/completions`) -> - Connecting to services like MiniMax, Synthetic that require Anthropic's native message format -> - The existing `anthropic` protocol returns 404 errors (indicating the endpoint doesn't support OpenAI-compatible format) -> -> **Note:** The `anthropic` protocol uses OpenAI-compatible format (`/v1/chat/completions`), while `anthropic-messages` uses Anthropic's native format (`/v1/messages`). Choose based on your endpoint's supported format. - -**Ollama (local)** - -```json -{ - "model_name": "llama3", - "model": "ollama/llama3" -} -``` - -**Custom Proxy/API** - -```json -{ - "model_name": "my-custom-model", - "model": "openai/custom-model", - "api_base": "https://my-proxy.com/v1", - "api_key": "sk-...", - "request_timeout": 300 -} -``` - -**LiteLLM Proxy** - -```json -{ - "model_name": "lite-gpt4", - "model": "litellm/lite-gpt4", - "api_base": "http://localhost:4000/v1", - "api_key": "sk-..." -} -``` - -PicoClaw strips only the outer `litellm/` prefix before sending the request, so proxy aliases like `litellm/lite-gpt4` send `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`. - -#### Load Balancing - -Configure multiple endpoints for the same model nameโ€”PicoClaw will automatically round-robin between them: - -```json -{ - "model_list": [ - { - "model_name": "gpt-5.4", - "model": "openai/gpt-5.4", - "api_base": "https://api1.example.com/v1", - "api_key": "sk-key1" - }, - { - "model_name": "gpt-5.4", - "model": "openai/gpt-5.4", - "api_base": "https://api2.example.com/v1", - "api_key": "sk-key2" - } - ] -} -``` - -#### Migration from Legacy `providers` Config - -The old `providers` configuration is **deprecated** but still supported for backward compatibility. - -**Old Config (deprecated):** - -```json -{ - "providers": { - "zhipu": { - "api_key": "your-key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - }, - "agents": { - "defaults": { - "provider": "zhipu", - "model": "glm-4.7" - } - } -} -``` - -**New Config (recommended):** - -```json -{ - "model_list": [ - { - "model_name": "glm-4.7", - "model": "zhipu/glm-4.7", - "api_key": "your-key" - } - ], - "agents": { - "defaults": { - "model": "glm-4.7" - } - } -} -``` - -For detailed migration guide, see [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md). - -### Provider Architecture - -PicoClaw routes providers by protocol family: - -- OpenAI-compatible protocol: OpenRouter, OpenAI-compatible gateways, Groq, Zhipu, and vLLM-style endpoints. -- Anthropic protocol: Claude-native API behavior. -- Codex/OAuth path: OpenAI OAuth/token authentication route. - -This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`). - -
-Zhipu - -**1. Get API key and base URL** - -* Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) - -**2. Configure** - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.picoclaw/workspace", - "model": "glm-4.7", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "providers": { - "zhipu": { - "api_key": "Your API Key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - } - } -} -``` - -**3. Run** - -```bash -picoclaw agent -m "Hello" -``` - -
- -
-Full config example - -```json -{ - "agents": { - "defaults": { - "model": "anthropic/claude-opus-4-5" - } - }, - "session": { - "dm_scope": "per-channel-peer", - "backlog_limit": 20 - }, - "providers": { - "openrouter": { - "api_key": "sk-or-v1-xxx" - }, - "groq": { - "api_key": "gsk_xxx" - } - }, - "channels": { - "telegram": { - "enabled": true, - "token": "123456:ABC...", - "allow_from": ["123456789"] - }, - "discord": { - "enabled": true, - "token": "", - "allow_from": [""] - }, - "whatsapp": { - "enabled": false, - "bridge_url": "ws://localhost:3001", - "use_native": false, - "session_store_path": "", - "allow_from": [] - }, - "feishu": { - "enabled": false, - "app_id": "cli_xxx", - "app_secret": "xxx", - "encrypt_key": "", - "verification_token": "", - "allow_from": [] - }, - "qq": { - "enabled": false, - "app_id": "", - "app_secret": "", - "allow_from": [] - } - }, - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "BSA...", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - }, - "perplexity": { - "enabled": false, - "api_key": "", - "max_results": 5 - }, - "searxng": { - "enabled": false, - "base_url": "http://localhost:8888", - "max_results": 5 - } - }, - "cron": { - "exec_timeout_minutes": 5 - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -
- -## CLI Reference | Command | Description | | ------------------------- | ----------------------------- |