PicoClaw

https://docs.picoclaw.io
Admin
PicoClaw is an ultra-lightweight AI assistant written in Go that runs on minimal hardware (under...
Tokens:68,730
Snippets:985
Trust Score:6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Docker Compose Setup for PicoClaw

Source: https://docs.picoclaw.io/docs/docker

Steps to clone the repository, perform the initial setup which auto-generates configuration, set API keys, and start the PicoClaw service using Docker Compose.

```bash
# 1. Clone the repo  

git clone https://github.com/sipeed/picoclaw.git  

cd picoclaw  

  

# 2. First run — auto-generates docker/data/config.json then exits  

docker compose -f docker/docker-compose.yml --profile gateway up  

# The container prints "First-run setup complete." and stops.  

  

# 3. Set your API keys  

vim docker/data/config.json   # Set provider API keys, bot tokens, etc.  

  

# 4. Start  

docker compose -f docker/docker-compose.yml --profile gateway up -d  

```

--------------------------------

### Security Configuration Example (.security.yml)

Source: https://docs.picoclaw.io/docs/configuration/token_authentication

Example of how to configure security tokens in a .security.yml file for different channels.

```yaml
channels:
  pico:
    token: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  telegram:
    token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
  discord:
    token: "your-discord-bot-token"
```

--------------------------------

### Install PicoClaw using one-click script

Source: https://docs.picoclaw.io/docs/installation/licheervnano

Use this command to download and execute the installation script for PicoClaw. Ensure your host machine and LicheeRV Nano are on the same network.

```bash
curl -o install_picoclaw.py https://raw.githubusercontent.com/sipeed/picoclaw_docs/main/static/scripts/maixcam/install_picoclaw.py && python3 install_picoclaw.py  
```

--------------------------------

### Full config.json Example

Source: https://docs.picoclaw.io/docs/configuration/config-reference

This is a complete example of the `config.json` file, illustrating all available configuration options. Version 2 of the schema is indicated by `"version": 2`.

```json
{
  "version": 2,
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true,
      "model_name": "gpt-5.4",
      "max_tokens": 32768,
      "max_tool_iterations": 50
    }
  },
  "model_list": [
    {
      "model_name": "ark-code-latest",
      "model": "volcengine/ark-code-latest",
      "api_keys": ["sk-your-volcengine-key"]
    },
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_keys": ["sk-your-openai-key"],
      "api_base": "https://api.openai.com/v1"
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_keys": ["sk-ant-your-key"],
      "api_base": "https://api.anthropic.com/v1"
    },
    {
      "model_name": "gemini",
      "model": "antigravity/gemini-2.0-flash",
      "auth_method": "oauth"
    },
    {
      "model_name": "deepseek",
      "model": "deepseek/deepseek-chat",
      "api_keys": ["sk-your-deepseek-key"]
    },
    {
      "model_name": "loadbalanced-gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_keys": ["sk-key1"],
      "api_base": "https://api1.example.com/v1"
    },
    {
      "model_name": "loadbalanced-gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_keys": ["sk-key2"],
      "api_base": "https://api2.example.com/v1"
    }
  ],
  "channels": {
    "telegram": {
      "enabled": false,
      "token": "YOUR_TELEGRAM_BOT_TOKEN",
      "base_url": "",
      "proxy": "",
      "allow_from": ["YOUR_USER_ID"],
      "reasoning_channel_id": ""
    },
    "discord": {
      "enabled": false,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "proxy": "",
      "allow_from": [],
      "group_trigger": {
        "mention_only": false
      },
      "reasoning_channel_id": ""
    },
    "qq": {
      "enabled": false,
      "app_id": "YOUR_QQ_APP_ID",
      "app_secret": "YOUR_QQ_APP_SECRET",
      "allow_from": [],
      "reasoning_channel_id": ""
    },
    "maixcam": {
      "enabled": false,
      "host": "0.0.0.0",
      "port": 18790,
      "allow_from": [],
      "reasoning_channel_id": ""
    },
    "whatsapp": {
      "enabled": false,
      "bridge_url": "ws://localhost:3001",
      "use_native": false,
      "session_store_path": "",
      "allow_from": [],
      "reasoning_channel_id": ""
    },
    "feishu": {
      "enabled": false,
      "app_id": "",
      "app_secret": "",
      "encrypt_key": "",
      "verification_token": "",
      "allow_from": [],
      "reasoning_channel_id": ""
    },
    "dingtalk": {
      "enabled": false,
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "allow_from": [],
      "reasoning_channel_id": ""
    },
    "slack": {
      "enabled": false,
      "bot_token": "xoxb-YOUR-BOT-TOKEN",
      "app_token": "xapp-YOUR-APP-TOKEN",
      "allow_from": [],
      "reasoning_channel_id": ""
    },
    "line": {
      "enabled": false,
      "channel_secret": "YOUR_LINE_CHANNEL_SECRET",
      "channel_access_token": "YOUR_LINE_CHANNEL_ACCESS_TOKEN",
      "webhook_path": "/webhook/line",
      "allow_from": [],
      "reasoning_channel_id": ""
    },
    "onebot": {
      "enabled": false,
      "ws_url": "ws://127.0.0.1:3001",
      "access_token": "",
      "reconnect_interval": 5,
      "group_trigger_prefix": [],
      "allow_from": [],
      "reasoning_channel_id": ""
    },
    "wecom": {
      "enabled": false,
      "bot_id": "YOUR_BOT_ID",
      "secret": "YOUR_SECRET",
      "websocket_url": "wss://openws.work.weixin.qq.com",
      "send_thinking_message": true,
      "allow_from": [],
      "reasoning_channel_id": ""
    },
    "matrix": {
      "enabled": false,
      "homeserver": "https://matrix.org",
      "user_id": "@your-bot:matrix.org",
      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
      "device_id": "",
      "join_on_invite": true,
      "allow_from": [],
      "group_trigger": {
        "mention_only": true
      },
      "placeholder": {
        "enabled": true,
        "text": "Thinking..."
      },
      "reasoning_channel_id": ""
    }
  },
  "tools": {
    "web": {

```

--------------------------------

### Mixed MCP Setup with Per-Server Deferred Override

Source: https://docs.picoclaw.io/docs/configuration/tools

Configures MCP with global tool discovery enabled, but allows per-server overrides for deferred loading. This example pins 'filesystem' as always-visible and sets 'aws' to deferred mode.

```json
{
  "tools": {
    "mcp": {
      "enabled": true,
      "discovery": {
        "enabled": true,
        "ttl": 5,
        "max_search_results": 5,
        "use_bm25": true
      },
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
          "deferred": false
        },
        "context7": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@upstash/context7-mcp"]
        },
        "aws": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "aws-mcp-server"],
          "deferred": true
        }
      }
    }
  }
}
```

--------------------------------

### Test PicoClaw Installation

Source: https://docs.picoclaw.io/docs/hardware-compatibility

Run these commands on your target device to verify PicoClaw installation and basic functionality. If the binary starts and connects to an API, your hardware is supported.

```bash
./picoclaw onboard
```

```bash
./picoclaw agent -m "Hello, what device am I running on?"
```

--------------------------------

### Legacy `providers` Configuration Example

Source: https://docs.picoclaw.io/docs/migration/model-list-migration

This is an example of the older configuration format using the `providers` key to define API access for different services.

```json
{
  "providers": {
    "openai": {
      "api_key": "sk-your-openai-key",
      "api_base": "https://api.openai.com/v1"
    },
    "anthropic": {
      "api_key": "sk-ant-your-key"
    },
    "deepseek": {
      "api_key": "sk-your-deepseek-key"
    }
  },
  "agents": {
    "defaults": {
      "provider": "openai",
      "model": "gpt-5.4"
    }
  }
}
```

--------------------------------

### Agent Configuration Example

Source: https://docs.picoclaw.io/docs/design/provider-refactoring

Demonstrates the current agent configuration where both provider and model names are required.

```json
{
  
  "agents": {
  
    "defaults": {
  
      "provider": "deepseek",  // need to know provider name  

      "model": "deepseek-chat"
  
    }
  
  }

}

```

--------------------------------

### Example config.json Structure

Source: https://docs.picoclaw.io/docs/configuration/security-reference

This is an example of a config.json file that pairs with a .security.yml file for sensitive configurations.

```json
{
  "version": 2,
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4"
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4-6"
    }
  ],
  "channels": {
    "telegram": {
      "enabled": true
    },
    "wecom": {
      "enabled": true,
      "bot_id": "YOUR_BOT_ID"
    }
  },
  "tools": {
    "web": {
      "brave": {
        "enabled": true
      }
    },
    "skills": {
      "github": {}
    }
  }
}
```

--------------------------------

### Manually install PicoClaw

Source: https://docs.picoclaw.io/docs/installation/licheervnano

Follow these commands for a manual installation of PicoClaw. This involves downloading a tarball, extracting it, and copying binaries to the system path.

```bash
curl -L# -o picoclaw_Linux_riscv64.tar.gz \
https://picoclaw-downloads.tos-cn-beijing.volces.com/latest/picoclaw_Linux_riscv64.tar.gz  

mkdir -p /root/picoclaw  
gzip -dc picoclaw_Linux_riscv64.tar.gz | tar -xvf - -C /root/picoclaw  

cp /root/picoclaw/picoclaw* /usr/bin  

rm -rf /root/picoclaw /root/picoclaw_Linux_riscv64.tar.gz  
```

--------------------------------

### Example: Enable Isolation with Exposed Paths

Source: https://docs.picoclaw.io/docs/configuration/isolation

An example configuration enabling isolation and exposing multiple host paths with different access modes and target locations within the isolated environment.

```json
{
  "isolation": {
    "enabled": true,
    "expose_paths": [
      {
        "source": "/opt/toolchains/go",
        "target": "/opt/toolchains/go",
        "mode": "ro"
      },
      {
        "source": "/data/shared-assets",
        "target": "/opt/picoclaw-instance-a/workspace/assets",
        "mode": "rw"
      }
    ]
  }
}
```

--------------------------------

### Start PicoClaw TUI

Source: https://docs.picoclaw.io/docs/installation/licheervnano

Run this command after installation to launch the PicoClaw terminal user interface for configuration and management.

```bash
picoclaw-launcher-tui  
```

--------------------------------

### Exec Tool Configuration Example

Source: https://docs.picoclaw.io/docs/configuration/tools

Example configuration for the exec tool, including enabling deny patterns and defining custom deny and allow patterns for shell commands.

```json
{
  "tools": {
    "exec": {
      "enable_deny_patterns": true,
      "custom_deny_patterns": ["\\brm\\s+-r\\b", "\\bkillall\\s+python"],
      "custom_allow_patterns": []
    }
  }
}

```

--------------------------------

### Cron Job Configuration Example

Source: https://docs.picoclaw.io/docs/cron

Configure the cron and exec tools within the PicoClaw settings. This example enables both tools and sets a 5-minute timeout for command execution.

```json
{
  "tools": {
    "cron": {
      "enabled": true,
      "exec_timeout_minutes": 5,
      "allow_command": true
    },
    "exec": {
      "enabled": true
    }
  }
}
```

--------------------------------

### Install PicoClaw using MaixVision Python Script

Source: https://docs.picoclaw.io/docs/installation/maixcam

This Python script, when run within MaixVision, downloads and installs PicoClaw on the device and starts the Web UI. Access the Web UI via http://<device-ip>:18800.

```python
import os

# Download PicoClaw
url = "https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_aarch64.deb"
filename = "picoclaw_aarch64.deb"
os.system(f"curl -L# -o {filename} {url}")

# Install PicoClaw
os.system(f"dpkg -i {filename}")

# Remove downloaded file
os.system(f"rm -rf {filename}")

# Start PicoClaw launcher
os.system("picoclaw-launcher-tui")
```

--------------------------------

### Skills Configuration Example

Source: https://docs.picoclaw.io/docs/configuration/tools

Example JSON structure for configuring skills, including registries and GitHub integration. This configuration can be used in a config.json file.

```json
{
  "tools": {
    "skills": {
      "registries": {
        "clawhub": {
          "enabled": true,
          "base_url": "https://clawhub.ai",
          "auth_token": ""
        }
      },
      "github": {
        "proxy": "",
        "token": ""
      },
      "max_concurrent_searches": 2,
      "search_cache": {
        "max_size": 50,
        "ttl_seconds": 300
      }
    }
  }
}
```

--------------------------------

### Configure Stdio MCP Server

Source: https://docs.picoclaw.io/docs/configuration/tools

Example configuration for a local MCP server using stdio transport. This setup is useful for running tools directly on the local machine.

```json
{
  "tools": {
    "mcp": {
      "enabled": true,
      "servers": {
        "filesystem": {
          "enabled": true,
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-filesystem",
            "/tmp"
          ]
        }
      }
    }
  }
}
```

--------------------------------

### Start PicoClaw Gateway

Source: https://docs.picoclaw.io/docs/channels

Run this command to start the PicoClaw gateway, which handles all configured channels concurrently.

```bash
picoclaw gateway  

```

--------------------------------

### Start PicoClaw Web UI

Source: https://docs.picoclaw.io/docs/installation/licheervnano

Execute this command to start the PicoClaw web service. Access the graphical interface via a web browser on a device within the same local network.

```bash
picoclaw-launcher -no-browser -public  
```

--------------------------------

### Initialize and Start PicoClaw with Docker Compose

Source: https://docs.picoclaw.io/docs/installation

Clone the repository and use Docker Compose to set up and run the PicoClaw gateway. The first run automatically generates the configuration file.

```bash
# 1. Clone this repo
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw

# 2. First run — auto-generates docker/data/config.json then exits
docker compose -f docker/docker-compose.yml --profile gateway up
# The container prints "First-run setup complete." and stops.

# 3. Set your API keys
vim docker/data/config.json   # Set provider API keys, bot tokens, etc.

# 4. Start
docker compose -f docker/docker-compose.yml --profile gateway up -d
```

--------------------------------

### Start PicoClaw Launcher WebUI

Source: https://docs.picoclaw.io/docs/getting-started

Launch the WebUI for configuration. This is the recommended method for most users. Ensure you have the launcher executable available.

```bash
picoclaw-launcher
```

--------------------------------

### Build PicoClaw from Source

Source: https://docs.picoclaw.io/docs/installation

Steps to clone the repository, install dependencies, and build the PicoClaw binary for the current or all platforms. Requires Go 1.21+.

```bash
git clone https://github.com/sipeed/picoclaw.git

cd picoclaw

# Install dependencies
make deps

# Build for current platform
make build

# Build for all platforms
make build-all

# Build and install to PATH
make install
```

--------------------------------

### Agent Configuration Example

Source: https://docs.picoclaw.io/docs/design/provider-refactoring

Defines models and agents with their respective configurations, including default models and system prompts.

```json
{
  "model_list": [...],
  "agents": {
    "defaults": {
      "model": "deepseek-chat"
    },
    "coder": {
      "model": "gpt-5.4",
      "system_prompt": "You are a coding assistant..."
    },
    "translator": {
      "model": "claude-sonnet-4.6"
    }
  }
}
```

--------------------------------

### Start Weixin Gateway

Source: https://docs.picoclaw.io/docs/channels/weixin

After onboarding, start the gateway to enable message processing. This command initiates the connection and message handling for the Weixin channel.

```bash
picoclaw gateway  
```

--------------------------------

### Start Chatting with PicoClaw Agent

Source: https://docs.picoclaw.io/docs/docker

Initiates a chat session with the PicoClaw agent to ask a question, for example, summarizing release notes.

```bash
picoclaw agent -m "Summarize the latest Rust release notes"  

```

--------------------------------

### Run PicoClaw with Custom Configuration and Home Directories

Source: https://docs.picoclaw.io/docs/configuration

Provides examples of running the PicoClaw gateway or agent with specific configuration files and home directories using environment variables.

```bash
# Run picoclaw using a specific config file  

PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway  

  

# Run picoclaw with all its data stored in /opt/picoclaw  

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  

  

```

--------------------------------

### Configure Web Tools

Source: https://docs.picoclaw.io/docs/configuration/tools

Example configuration for enabling and setting parameters for various web search tools like Brave, DuckDuckGo, Baidu, and Perplexity. Includes proxy settings.

```json
{
  "tools": {
    "web": {
      "brave": {
        "enabled": true,
        "api_keys": ["YOUR_BRAVE_API_KEY"],
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "baidu_search": {
        "enabled": false,
        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY"
      },
      "perplexity": {
        "enabled": false,
        "api_keys": ["pplx-xxx"],
        "max_results": 5
      },
      "proxy": "socks5://127.0.0.1:1080"
    }
  }
}

```

--------------------------------

### Download and Install PicoClaw via SSH (MaixCam2)

Source: https://docs.picoclaw.io/docs/installation/maixcam

Use these commands to download the PicoClaw AArch64 Debian package, install it, remove the package file, and launch the TUI.

```bash
curl -L# -o picoclaw_aarch64.deb \
https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_aarch64.deb

dpkg -i picoclaw_aarch64.deb
rm -rf picoclaw_aarch64.deb

picoclaw-launcher-tui
```

--------------------------------

### Complete Security Configuration Example

Source: https://docs.picoclaw.io/docs/configuration/exec

A comprehensive security configuration including workspace restriction, dangerous command blocking, and custom allow/deny patterns.

```json
{
  "agents": {
    "defaults": {
      "restrict_to_workspace": true
    }
  },
  "tools": {
    "exec": {
      "enabled": true,
      "allow_remote": false,
      "enable_deny_patterns": true,
      "custom_deny_patterns": [
        "\\brm\\s+-rf\\b",
        "\\bsudo\\b"
      ],
      "custom_allow_patterns": [
        "\\$\\{[A-Za-z_][A-Za-z0-9_]*:-[^}]*\\}"
      ]
    }
  }
}
```

--------------------------------

### New Configuration with Model List

Source: https://docs.picoclaw.io/docs/design/provider-refactoring

Example of the new configuration format using `model_list` for specifying model details, including API base and key.

```json
{
  "model_list": [
    {
      "model_name": "deepseek-chat",
      "model": "openai/deepseek-chat",
      "api_base": "https://api.deepseek.com/v1",
      "api_key": "sk-xxx"
    }
  ],
  "agents": {
    "defaults": {
      "model": "deepseek-chat"
    }
  }
}
```

--------------------------------

### Old Configuration with Providers

Source: https://docs.picoclaw.io/docs/design/provider-refactoring

Example of an older configuration format using the `providers` field for API key and base URL.

```json
{
  "providers": {
    "deepseek": {
      "api_key": "sk-xxx",
      "api_base": "https://api.deepseek.com/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "deepseek",
      "model": "deepseek-chat"
    }
  }
}
```

--------------------------------

### Start PicoClaw Web UI

Source: https://docs.picoclaw.io/docs/installation/maixcam

Run this command to start the PicoClaw launcher without opening a browser and make it publicly accessible. Access the Web UI via http://<device-ip>:18800.

```bash
picoclaw-launcher -no-browser -public
```

--------------------------------

### Example .security.yml Configuration

Source: https://docs.picoclaw.io/docs/configuration/security-reference

This YAML file demonstrates how to structure sensitive credentials for various services like OpenAI, Anthropic, Telegram, and GitHub. Ensure this file is added to .gitignore and has restricted permissions.

```yaml
model_list:  
  gpt-5.4:0:  
    api_keys:  
      - "sk-openai-..."  
  claude-sonnet-4.6:0:  
    api_keys:  
      - "sk-ant-..."  
  
channels:  
  telegram:  
    token: "123456:telegram-token"  
  wecom:  
    secret: "wecom-secret"  
  
web:  
  brave:  
    api_keys:  
      - "BSA-..."  
  
skills:  
  github:  
    token: "ghp-..."  

```

--------------------------------

### Download and Install PicoClaw via SSH (MaixCam/MaixCam-Pro)

Source: https://docs.picoclaw.io/docs/installation/maixcam

Use these commands to download the PicoClaw Linux RISC-V 64-bit version, extract it, copy the executable, and clean up temporary files.

```bash
curl -L# -o picoclaw_Linux_riscv64.tar.gz \
https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_riscv64.tar.gz

mkdir -p /root/picoclaw
gzip -dc picoclaw_Linux_riscv64.tar.gz | tar -xvf - -C /root/picoclaw
cp /root/picoclaw/picoclaw* /usr/bin
rm -rf /root/picoclaw /root/picoclaw_Linux_riscv64.tar.gz

picoclaw-launcher-tui
```

--------------------------------

### Configure New Provider via config.json

Source: https://docs.picoclaw.io/docs/providers/antigravity

Example of how to configure a newly added provider in `config.json`, specifying the model name, its identifier, and API keys or base URL.

```json
{
  "model_list": [
    {
      "model_name": "your-model",
      "model": "your-provider/model-name",
      "api_keys": ["your-api-key"],
      "api_base": "https://api.your-provider.com/v1"
    }
  ]
}
```

--------------------------------

### Massive MCP Setup with Tool Discovery

Source: https://docs.picoclaw.io/docs/configuration/tools

Enables the Massive Context Protocol (MCP) with tool discovery. The LLM will dynamically search and unlock tools like Github or Postgres when requested by the user.

```json
{
  "tools": {
    "mcp": {
      "enabled": true,
      "discovery": {
        "enabled": true,
        "ttl": 5,
        "max_search_results": 5,
        "use_bm25": true,
        "use_regex": false
      },
      "servers": {
        "github": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": {
            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
          }
        },
        "postgres": {
          "enabled": true,
          "command": "npx",
          "args": [
            "-y",
            "@modelcontextprotocol/server-postgres",
            "postgresql://user:password@localhost/dbname"
          ]
        },
        "slack": {
          "enabled": true,
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-slack"],
          "env": {
            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Run PicoClaw Gateway

Source: https://docs.picoclaw.io/docs/channels/matrix

Execute this command to start the PicoClaw gateway. The bot will connect to the configured Matrix homeserver and begin processing messages.

```bash
picoclaw gateway

```

--------------------------------

### LiteLLM Model List Configuration

Source: https://docs.picoclaw.io/docs/design/provider-refactoring

Example of a model list configuration similar to LiteLLM, specifying model names and their parameters.

```yaml
model_list:
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-5.4
      api_key: xxx
  - model_name: my-custom
    litellm_params:
      model: openai/custom-model
      api_base: https://my-api.com/v1
```

--------------------------------

### PicoClaw CLI Commands for Providers

Source: https://docs.picoclaw.io/docs/providers/antigravity

Common command-line interface commands for managing and interacting with PicoClaw providers, including authentication, listing models, and starting the gateway.

```bash
# Authenticate with a provider
picoclaw auth login --provider your-provider

# List models (for Antigravity)
picoclaw auth models

# Start the gateway
picoclaw gateway
```

--------------------------------

### Core picoclaw CLI Commands

Source: https://docs.picoclaw.io/docs/configuration/cli-parameters

These are the fundamental commands for interacting with the picoclaw CLI. Use 'onboard' to initialize, 'agent' for chat, 'gateway' to start the server, 'status' to check the system, and 'cron' for managing scheduled jobs.

```bash
picoclaw onboard
```

```bash
picoclaw agent -m "hello"
```

```bash
picoclaw agent
```

```bash
picoclaw gateway
```

```bash
picoclaw status
```

```bash
picoclaw cron list
```

```bash
picoclaw cron add ...
```

--------------------------------

### config.json Model Configuration for Antigravity

Source: https://docs.picoclaw.io/docs/providers/antigravity

Example configuration for `config.json` to set up an Antigravity model entry, specifying the model name, its Antigravity identifier, and authentication method.

```json
{
  "model_list": [
    {
      "model_name": "gemini-flash",
      "model": "antigravity/gemini-3-flash",
      "auth_method": "oauth"
    }
  ],
  "agents": {
    "defaults": {
      "model_name": "gemini-flash"
    }
  }
}
```

--------------------------------

### Implement 'respond' Action in Go

Source: https://docs.picoclaw.io/docs/hooks

Example of using the 'respond' action in a Go in-process hook to provide a tool result directly, bypassing actual tool execution. This is useful for plugin tool injection or result caching.

```go
func (h *MyHook) BeforeTool(

    ctx context.Context,

    call *agent.ToolCallHookRequest,

) (*agent.ToolCallHookRequest, agent.HookDecision, error) {

    if call.Tool == "my_plugin_tool" {

        next := call.Clone()

        next.HookResult = &tools.ToolResult{

            ForLLM:  "Plugin tool executed successfully",

            Silent:  false,

            IsError: false,

        }

        return next, agent.HookDecision{Action: agent.HookActionRespond}, nil

    }

    return call, agent.HookDecision{Action: agent.HookActionContinue}, nil

}

```

--------------------------------

### Implement 'respond' Action in Python (JSON-RPC)

Source: https://docs.picoclaw.io/docs/hooks

Example of using the 'respond' action in a Python process-hook via JSON-RPC to provide a tool result directly. This demonstrates how to handle tool calls from an external process.

```python
def handle_before_tool(id, params):

    if params.get("name") == "my_plugin_tool":

        _respond(id, {

            "decision": {"action": "respond"},

            "hook_result": {

                "for_llm": "Plugin tool executed successfully",

                "is_error": False,

            },

        })

        return

    _respond(id, {"decision": {"action": "continue"}})



```

--------------------------------

### Initialize PicoClaw Onboarding

Source: https://docs.picoclaw.io/docs/docker

Initializes PicoClaw by running the onboard command.

```bash
picoclaw onboard  

```

--------------------------------

### Set up HTTPS Tunnel with ngrok

Source: https://docs.picoclaw.io/docs/channels/line

LINE requires HTTPS for webhooks. This example demonstrates using ngrok to expose your local PicoClaw gateway (running on port 18790) to the internet. You will need to set the ngrok-provided URL as your webhook URL in the LINE Developers Console.

```bash
# Example with ngrok
ngrok http 18790
```

--------------------------------

### Add Default Config for New Provider (Go)

Source: https://docs.picoclaw.io/docs/providers/antigravity

Shows how to add a default configuration entry for a new provider in `pkg/config/defaults.go` to make it available for use.

```go
{
    ModelName: "your-model",
    Model:     "your-provider/model-name",
    APIKey:    "",
}
```

--------------------------------

### Add Auth Support for New Provider (Go)

Source: https://docs.picoclaw.io/docs/providers/antigravity

Demonstrates adding a case to `cmd/picoclaw/cmd_auth.go` to support OAuth or special authentication methods for a new provider.

```go
case "your-provider":
    authLoginYourProvider()
```

--------------------------------

### Run PicoClaw on Android with Termux

Source: https://docs.picoclaw.io/docs/installation/android

Install and run PicoClaw within the Termux environment on your Android device. This involves downloading the binary, extracting it, installing proot, and then running the application.

```bash
wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
```

```bash
tar xzf picoclaw_Linux_arm64.tar.gz
```

```bash
pkg install proot
```

```bash
termux-chroot ./picoclaw onboard
```

--------------------------------

### Example Command Triggering Dangerous Pattern Blocking

Source: https://docs.picoclaw.io/docs/configuration/exec

This example command, using shell variable expansion with a default value, triggers PicoClaw's dangerous pattern blocking mechanism.

```bash
echo "HOST=${AIEXCEL_API_HOST:-未设置}"
```

--------------------------------

### Onboard Weixin Channel

Source: https://docs.picoclaw.io/docs/channels/weixin

Use this command for quick onboarding. It requests a QR code, waits for scanning, and saves the access token.

```bash
picoclaw auth weixin  
```

--------------------------------

### Start PicoClaw Launcher Mode with Docker Compose

Source: https://docs.picoclaw.io/docs/docker

Starts the PicoClaw launcher service in detached mode using Docker Compose. This mode provides a web console for managing models, channels, and the gateway process.

```bash
docker compose -f docker/docker-compose.yml --profile launcher up -d  

```

--------------------------------

### Tool Output Before Filtering

Source: https://docs.picoclaw.io/docs/sensitive-data-filtering

Example of raw tool output containing sensitive data.

```text
Connected to database with password super-secret-db-pass  
API response from sk-abc123xxxxxxxxxxxxxxxxxx: {"status": "ok"}
```

--------------------------------

### Run PicoClaw Gateway

Source: https://docs.picoclaw.io/docs/channels/onebot

This command starts the PicoClaw gateway, which will then connect to the configured OneBot client.

```bash
picoclaw gateway
```

--------------------------------

### Git Ignore Configuration

Source: https://docs.picoclaw.io/docs/configuration/token_authentication

Example of a .gitignore file to prevent committing sensitive security configuration files.

```gitignore
.picoclaw/.security.yml
```

--------------------------------

### Download and Run Precompiled Binary for Linux ARM64

Source: https://docs.picoclaw.io/docs/installation

Use this command to download the latest release for Linux ARM64, extract it, and run the onboard command.

```bash
wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz

tar -xzf picoclaw_Linux_arm64.tar.gz

./picoclaw onboard
```

--------------------------------

### New Provider Implementation (Go)

Source: https://docs.picoclaw.io/docs/providers/antigravity

Defines the basic structure for implementing a new provider in PicoClaw using Go, including the Provider interface, constructor, and a placeholder for the Chat method.

```go
package providers

type YourProvider struct {
    apiKey  string
    apiBase string
}

func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
    if apiBase == "" {
        apiBase = "https://api.your-provider.com/v1"
    }
    return &YourProvider{apiKey: apiKey, apiBase: apiBase}
}

func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
    // Implement chat completion with streaming
}
```

--------------------------------

### Tool Output After Filtering

Source: https://docs.picoclaw.io/docs/sensitive-data-filtering

Example of tool output after PicoClaw has filtered sensitive data. Matching values are replaced with '[FILTERED]'.

```text
Connected to database with password [FILTERED]  
API response from [FILTERED]: {"status": "ok"}
```

--------------------------------

### Access PicoClaw Web UI

Source: https://docs.picoclaw.io/docs/installation/macos

If the browser does not automatically open after starting PicoClaw, navigate to this address to access the Web UI.

```text
http://localhost:18800
```

--------------------------------

### Environment Variable Overrides

Source: https://docs.picoclaw.io/docs/configuration/tools

Examples of environment variables used to override tool configuration settings. Format is PICOCLAW_TOOLS_<SECTION>_<KEY>.

```bash
PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true
```

```bash
PICOCLAW_TOOLS_EXEC_ENABLED=false
```

```bash
PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false
```

```bash
PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10
```

```bash
PICOCLAW_TOOLS_MCP_ENABLED=true
```

--------------------------------

### Authenticate with Antigravity

Source: https://docs.picoclaw.io/docs/providers/antigravity-usage

Run this command to initiate the authentication process with the Antigravity provider. For headless environments, follow the manual authentication steps.

```bash
picoclaw auth login --provider antigravity
```

--------------------------------

### Configure Telegram Proxy

Source: https://docs.picoclaw.io/docs/channels/telegram

If Telegram is blocked in your region, configure a proxy server to enable the channel. This example uses a SOCKS5 proxy.

```json
{
  "channels": {
    "telegram": {
      "proxy": "socks5://127.0.0.1:1080"
    }
  }
}
```

--------------------------------

### PicoClaw Configuration: Web Tools

Source: https://docs.picoclaw.io/docs/docker

JSON configuration for enabling and setting up web search tools for the agent, including options for Brave, Tavily, DuckDuckGo, Perplexity, and SearXNG.

```json
{
  "tools": {
    "web": {
      "brave": {
        "enabled": true,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
      "tavily": {
        "enabled": false,
        "api_key": "YOUR_TAVILY_API_KEY",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": false,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "YOUR_PERPLEXITY_API_KEY"
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://localhost:8080"
      }
    }
  }
}

```

--------------------------------

### Example .security.yml Configuration

Source: https://docs.picoclaw.io/docs/sensitive-data-filtering

Define sensitive data patterns in the .security.yml file. All string values meeting the minimum length are collected for filtering.

```yaml
openai:
  api_key: "sk-abc123xxxxxxxxxxxxxxxxxx"
database:
  password: "super-secret-db-pass"
```

--------------------------------

### Register Provider in Factory (Go)

Source: https://docs.picoclaw.io/docs/providers/antigravity

Illustrates how to register a new provider within the PicoClaw factory pattern in Go, enabling the system to instantiate the custom provider.

```go
case "your-provider":
    return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
```

--------------------------------

### Run PicoClaw Agent in Interactive Mode

Source: https://docs.picoclaw.io/docs/docker

Starts the PicoClaw agent in interactive mode, allowing for a conversational session. The container is removed after execution.

```bash
# Interactive mode  

docker compose -f docker/docker-compose.yml run --rm picoclaw-agent  

```

--------------------------------

### Custom Port and Explicit Config File

Source: https://docs.picoclaw.io/docs/configuration/cli-parameters

Launch picoclaw-launcher with a specified custom port and an explicit configuration file path.

```bash
picoclaw-launcher -port 19999 ./config.json
```
Tokens:
Raw