Pico Claw Configuration Guide: Complete Reference

Pico Claw Configuration Overview

Pico Claw uses a simple YAML configuration file to control all aspects of the AI assistant. This guide covers everything from basic setup to advanced tuning.

Config File Structure

Location: ~/.picoclaw/config.yaml
Format: YAML (human-readable)
Validation: Built-in config checker
Reload: Hot reload without restart

Configuration Categories

API and authentication settings
Platform integrations (Telegram, Discord, QQ)
Memory and persistence
Skills and extensions
Security and privacy controls

Best Practices

Keep API keys in environment variables
Version control config (exclude secrets)
Test changes with picoclaw config validate
Backup before major changes

Default Config Structure

# config.yaml - Pico Claw Configuration
api:
  provider: anthropic
  key: ${ANTHROPIC_API_KEY}
  model: claude-3-5-sonnet-20241022

platforms:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}

memory:
  persistent: true
  max_size: 2MB

skills:
  enabled: true
  auto_install: false

logging:
  level: info
  file: /var/log/picoclaw.log

Basic Pico Claw Configuration

Essential configuration settings to get picoclaw up and running. API key setup is required before first use.

API Key Setup (Required)

# config.yaml - API Configuration
api:
  provider: anthropic        # Anthropic Claude
  key: ${ANTHROPIC_API_KEY}  # Use environment variable
  model: claude-3-5-sonnet-20241022
  max_tokens: 4096
  temperature: 1.0

# Set API key via environment
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Or in config.yaml (not recommended)
api:
  key: "sk-ant-api03-your-actual-key"

Security: Always use environment variables for API keys, never commit keys to version control

Model Selection

# Recommended models for Pico Claw
api:
  # High performance (default)
  model: claude-3-5-sonnet-20241022

  # Cost-effective option
  # model: claude-3-haiku-20240307

  # Maximum capability
  # model: claude-3-opus-20240229

Sonnet: Best balance of performance and cost (recommended)
Haiku: Fastest, lowest cost, good for simple tasks
Opus: Highest capability, premium pricing

Basic Settings

# General Pico Claw settings
general:
  name: "Pico Claw"
  language: en
  timezone: UTC

# Response behavior
response:
  max_length: 2000      # Character limit
  typing_indicator: true
  retry_on_error: 3

# System behavior
system:
  auto_update: false
  telemetry: false      # Respect privacy
  debug_mode: false

Configure Platforms for Pico Claw

Pico Claw supports multiple messaging platforms simultaneously. Configure Telegram, Discord, QQ, DingTalk, Feishu, and WhatsApp integrations.

Telegram Configuration

Full Support

# config.yaml - Telegram Setup
platforms:
  telegram:
    enabled: true
    token: ${TELEGRAM_BOT_TOKEN}

    # Optional: Advanced settings
    allowed_users: []       # Empty = all users
    admin_users: [123456]   # User IDs with admin access
    max_message_length: 4096

    # Commands
    commands:
      start: "Hello! I'm Pico Claw AI assistant."
      help: "Available commands: /start, /help, /status"

    # Features
    features:
      inline_mode: true
      group_chat: true
      file_upload: true

Get token from @BotFather on Telegram

Discord Configuration

Full Support

# config.yaml - Discord Setup
platforms:
  discord:
    enabled: true
    token: ${DISCORD_BOT_TOKEN}

    # Bot settings
    prefix: "!"             # Command prefix
    status: "online"
    activity: "Helping users"

    # Permissions
    allowed_guilds: []      # Empty = all servers
    allowed_channels: []    # Empty = all channels

    # Features
    features:
      slash_commands: true
      message_commands: true
      mentions: true
      dm_support: true

Create bot at Discord Developer Portal

QQ Configuration

Supported

# config.yaml - QQ Setup
platforms:
  qq:
    enabled: true
    protocol: "shamrock"    # or "go-cqhttp"

    # Connection
    host: "127.0.0.1"
    port: 8080
    access_token: ${QQ_ACCESS_TOKEN}

    # Bot account
    qq_number: 123456789

    # Features
    features:
      group_chat: true
      private_chat: true
      admin_mode: false

Requires QQ bot framework (Shamrock or go-cqhttp)

DingTalk & Feishu

Supported

# config.yaml - Enterprise Platforms
platforms:
  dingtalk:
    enabled: true
    app_key: ${DINGTALK_APP_KEY}
    app_secret: ${DINGTALK_APP_SECRET}

  feishu:
    enabled: true
    app_id: ${FEISHU_APP_ID}
    app_secret: ${FEISHU_APP_SECRET}

  whatsapp:
    enabled: false          # Configuration only
    # WhatsApp setup requires additional infrastructure

Enterprise platforms require app registration

Multi-Platform Support

Run Pico Claw on multiple platforms simultaneously - the same instance can serve Telegram, Discord, and QQ users concurrently.

Minimal Overhead

Each platform adds <2MB RAM - picoclaw can run 3+ platforms on devices with 64MB total memory.

Unified Configuration

Single config.yaml controls all platforms - change settings once, apply everywhere.

Advanced Pico Claw Configuration

Fine-tune picoclaw performance with memory management, persistent storage, custom prompts, and logging controls.

Memory Management

# Memory optimization for Pico Claw
memory:
  # Persistent memory
  persistent: true
  storage_path: ~/.picoclaw/memory
  max_size: 2MB

  # Runtime memory
  max_conversations: 10
  max_messages_per_conversation: 100

  # Cleanup
  auto_cleanup: true
  cleanup_interval: 24h
  retention_days: 7

Custom Prompts

# Customize Pico Claw behavior
prompts:
  system: |
    You are Pico Claw, a helpful AI assistant
    running on a RISC-V device with limited resources.
    Be concise and efficient.

  personality: friendly

  response_template: |
    {{ content }}

    ---
    Powered by Pico Claw

Logging Configuration

# Pico Claw logging settings
logging:
  level: info           # debug, info, warn, error

  # File logging
  file:
    enabled: true
    path: /var/log/picoclaw.log
    max_size: 10MB
    max_backups: 3
    compress: true

  # Console logging
  console:
    enabled: true
    format: json        # json or text

Performance Tuning

# Optimize Pico Claw performance
performance:
  # Concurrency
  max_concurrent_requests: 5
  request_timeout: 30s

  # Caching
  cache:
    enabled: true
    ttl: 5m
    max_entries: 100

  # Rate limiting
  rate_limit:
    requests_per_minute: 20
    burst: 5

Configure Skills for Pico Claw

Extend picoclaw functionality with skills installed from GitHub repositories. Manage skill permissions and create custom skills.

Install Skills from GitHub

# config.yaml - Skills Configuration
skills:
  enabled: true
  auto_install: false
  skills_directory: ~/.picoclaw/skills

  # Installed skills
  installed:
    - name: weather
      repo: github.com/picoclaw/skill-weather
      version: v1.0.0
      enabled: true

    - name: calculator
      repo: github.com/picoclaw/skill-calculator
      version: v1.2.0
      enabled: true

    - name: image-gen
      repo: github.com/picoclaw/skill-image
      version: v0.5.0
      enabled: false  # Disabled but installed

Install skills with: picoclaw skill install github.com/picoclaw/skill-name

Enable/Disable Skills

# Manage Pico Claw skills
# Enable skill
picoclaw skill enable weather

# Disable skill
picoclaw skill disable image-gen

# List all skills
picoclaw skill list

# Update skill
picoclaw skill update weather

# Remove skill
picoclaw skill remove calculator

Skill Permissions

# Per-skill permissions in config.yaml
skills:
  permissions:
    weather:
      network: true       # Allow internet access
      files: false        # No file system access
      users: []           # All users (empty = all)

    calculator:
      network: false
      files: false
      users: []

    admin-tools:
      network: true
      files: true
      users: [123456]     # Admin users only

Custom Skills

Create custom skills for Pico Claw:

Language: Any language (Python, JavaScript, Go, Bash)
Interface: JSON-RPC or command-line
Installation: Place in ~/.picoclaw/skills/custom/
Configuration: Each skill has own config file
Documentation: See skills development guide

Pico Claw Security Configuration

Protect your picoclaw deployment with API key security, user permissions, data privacy settings, and network controls.

API Key Security

# Secure API key management
# Use environment variables
export ANTHROPIC_API_KEY="sk-ant-..."
export TELEGRAM_BOT_TOKEN="123456:ABC-..."

# In config.yaml
api:
  key: ${ANTHROPIC_API_KEY}

# File permissions
chmod 600 ~/.picoclaw/config.yaml

# Key rotation
picoclaw config update-key --api

Never commit API keys to version control

User Permissions

# Access control for Pico Claw
security:
  # User authentication
  require_auth: true

  # Whitelist
  allowed_users:
    - 123456789  # Telegram user ID
    - 987654321

  # Admin users
  admin_users:
    - 123456789

  # Blacklist
  blocked_users:
    - 111111111

User IDs are platform-specific

Data Privacy Settings

# Privacy controls for Pico Claw
privacy:
  # Data collection
  store_messages: false
  store_user_data: false

  # Telemetry
  telemetry_enabled: false
  error_reporting: false

  # Encryption
  encrypt_memory: true
  encryption_key: ${ENCRYPTION_KEY}

Pico Claw respects user privacy by default

Network Security

# Network security for Pico Claw
security:
  # HTTPS enforcement
  require_https: true

  # Webhook validation
  validate_webhooks: true
  webhook_secret: ${WEBHOOK_SECRET}

  # IP filtering
  allowed_ips: []        # Empty = all IPs

  # Firewall integration
  firewall:
    enabled: true
    deny_by_default: false

Configure firewall rules on your system

Optimize Pico Claw Performance

Maximize picoclaw efficiency with memory optimization, response time tuning, resource limits, and monitoring.

Memory Optimization

Minimize Pico Claw memory footprint for ultra-low-resource devices:

# Optimize for minimal memory
memory:
  persistent: false       # Disable persistent memory
  max_size: 1MB          # Reduce max memory

  # Limit conversations
  max_conversations: 5
  max_messages_per_conversation: 50

  # Aggressive cleanup
  auto_cleanup: true
  cleanup_interval: 1h

Achieves <8MB RAM usage on minimal config

Response Time Tuning

Configure Pico Claw for optimal response speed:

# Optimize response time
performance:
  # Reduce timeout
  request_timeout: 15s

  # Increase concurrency
  max_concurrent_requests: 10

  # Enable caching
  cache:
    enabled: true
    ttl: 10m
    preload_common: true

Balance speed with API costs and rate limits

Resource Limits

Prevent Pico Claw from exceeding system resources:

# Resource constraints
limits:
  # Memory limits
  max_memory: 20MB       # Hard limit
  memory_warning: 15MB   # Warning threshold

  # CPU limits
  max_cpu_percent: 50

  # Disk limits
  max_disk_usage: 100MB

  # Connection limits
  max_connections: 100

Picoclaw respects system resource limits

Monitoring Configuration

Track Pico Claw performance metrics:

# Performance monitoring
monitoring:
  enabled: true

  # Metrics collection
  metrics:
    memory_usage: true
    response_time: true
    api_calls: true
    error_rate: true

  # Export format
  export:
    prometheus: true
    json: true

  # Alerts
  alerts:
    memory_threshold: 18MB
    error_rate_threshold: 5%

Integrate with monitoring tools like Prometheus

<10MB

Default RAM Usage

Idle Pico Claw instance

<1s

Boot Time

600MHz RISC-V core

8MB

Binary Size

Single Go binary

Configuration Examples

Explore complete configuration examples for different use cases: minimal devices, multi-platform deployments, and enterprise setups.

View on GitHub Official Documentation