Documentation Index
Fetch the complete documentation index at: https://mintlify.com/sipeed/picoclaw/llms.txt
Use this file to discover all available pages before exploring further.
Overview
All PicoClaw configuration options can be overridden using environment variables. This is useful for:
- Containerized deployments (Docker, Kubernetes)
- CI/CD pipelines
- Temporary overrides without editing config files
- Secret management (API keys, tokens)
Environment variables follow this pattern:
PICOCLAW_<SECTION>_<SUBSECTION>_<FIELD>
PICOCLAW_AGENTS_DEFAULTS_MODEL_NAMEPICOCLAW_TOOLS_WEB_BRAVE_API_KEYPICOCLAW_HEARTBEAT_ENABLED
Core Configuration
PICOCLAW_CONFIG
Purpose: Override config file location
PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
~/.picoclaw/config.json.
PICOCLAW_HOME
Purpose: Override root directory for PicoClaw data
PICOCLAW_HOME=/opt/picoclaw picoclaw agent
- Default workspace to
/opt/picoclaw/workspace
- Default config to
/opt/picoclaw/config.json (if not using PICOCLAW_CONFIG)
Agent Configuration
Workspace and Security
# Workspace location
PICOCLAW_AGENTS_DEFAULTS_WORKSPACE=/custom/workspace
# Workspace restrictions
PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=true
PICOCLAW_AGENTS_DEFAULTS_ALLOW_READ_OUTSIDE_WORKSPACE=false
Model Configuration
# Model selection
PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME=claude-sonnet-4.6
# Legacy provider (deprecated)
PICOCLAW_AGENTS_DEFAULTS_PROVIDER=anthropic
PICOCLAW_AGENTS_DEFAULTS_MODEL=claude-sonnet-4.6
# Image model
PICOCLAW_AGENTS_DEFAULTS_IMAGE_MODEL=gpt-5.2-vision
Agent Behavior
# Token limits
PICOCLAW_AGENTS_DEFAULTS_MAX_TOKENS=8192
# Temperature (0.0 - 2.0)
PICOCLAW_AGENTS_DEFAULTS_TEMPERATURE=0.7
# Tool iteration limit
PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS=20
# Media size limit (bytes)
PICOCLAW_AGENTS_DEFAULTS_MAX_MEDIA_SIZE=20971520
Provider Configuration (Legacy)
OpenAI
PICOCLAW_PROVIDERS_OPENAI_API_KEY=sk-proj-...
PICOCLAW_PROVIDERS_OPENAI_API_BASE=https://api.openai.com/v1
PICOCLAW_PROVIDERS_OPENAI_PROXY=http://proxy:8080
PICOCLAW_PROVIDERS_OPENAI_REQUEST_TIMEOUT=300
PICOCLAW_PROVIDERS_OPENAI_WEB_SEARCH=true
Anthropic
PICOCLAW_PROVIDERS_ANTHROPIC_API_KEY=sk-ant-...
PICOCLAW_PROVIDERS_ANTHROPIC_API_BASE=https://api.anthropic.com/v1
PICOCLAW_PROVIDERS_ANTHROPIC_REQUEST_TIMEOUT=300
Zhipu (智谱)
PICOCLAW_PROVIDERS_ZHIPU_API_KEY=your-key
PICOCLAW_PROVIDERS_ZHIPU_API_BASE=https://open.bigmodel.cn/api/paas/v4
OpenRouter
PICOCLAW_PROVIDERS_OPENROUTER_API_KEY=sk-or-v1-...
PICOCLAW_PROVIDERS_OPENROUTER_API_BASE=https://openrouter.ai/api/v1
Groq
PICOCLAW_PROVIDERS_GROQ_API_KEY=gsk_...
PICOCLAW_PROVIDERS_GROQ_API_BASE=https://api.groq.com/openai/v1
Gemini
PICOCLAW_PROVIDERS_GEMINI_API_KEY=AIza...
PICOCLAW_PROVIDERS_GEMINI_API_BASE=https://generativelanguage.googleapis.com/v1beta
Other Providers
# DeepSeek
PICOCLAW_PROVIDERS_DEEPSEEK_API_KEY=sk-...
PICOCLAW_PROVIDERS_DEEPSEEK_API_BASE=https://api.deepseek.com/v1
# Qwen
PICOCLAW_PROVIDERS_QWEN_API_KEY=sk-...
PICOCLAW_PROVIDERS_QWEN_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
# Moonshot
PICOCLAW_PROVIDERS_MOONSHOT_API_KEY=sk-...
PICOCLAW_PROVIDERS_MOONSHOT_API_BASE=https://api.moonshot.cn/v1
# Cerebras
PICOCLAW_PROVIDERS_CEREBRAS_API_KEY=...
PICOCLAW_PROVIDERS_CEREBRAS_API_BASE=https://api.cerebras.ai/v1
# Ollama (local)
PICOCLAW_PROVIDERS_OLLAMA_API_BASE=http://localhost:11434/v1
# vLLM (local)
PICOCLAW_PROVIDERS_VLLM_API_BASE=http://localhost:8000/v1
Web Search - Brave
PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true
PICOCLAW_TOOLS_WEB_BRAVE_API_KEY=BSA...
PICOCLAW_TOOLS_WEB_BRAVE_MAX_RESULTS=5
Web Search - Tavily
PICOCLAW_TOOLS_WEB_TAVILY_ENABLED=true
PICOCLAW_TOOLS_WEB_TAVILY_API_KEY=tvly-...
PICOCLAW_TOOLS_WEB_TAVILY_BASE_URL=https://api.tavily.com
PICOCLAW_TOOLS_WEB_TAVILY_MAX_RESULTS=5
Web Search - DuckDuckGo
PICOCLAW_TOOLS_WEB_DUCKDUCKGO_ENABLED=true
PICOCLAW_TOOLS_WEB_DUCKDUCKGO_MAX_RESULTS=5
# Proxy for all web tools
PICOCLAW_TOOLS_WEB_PROXY=http://proxy:8080
# Fetch size limit (bytes)
PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES=10485760
# Timeout for cron tasks (minutes)
PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=5
PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=true
MCP
PICOCLAW_TOOLS_MCP_ENABLED=true
Skills Registry
PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_ENABLED=true
PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_BASE_URL=https://clawhub.ai
PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_AUTH_TOKEN=...
PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_TIMEOUT=30
PICOCLAW_SKILLS_MAX_CONCURRENT_SEARCHES=2
PICOCLAW_SKILLS_SEARCH_CACHE_MAX_SIZE=50
PICOCLAW_SKILLS_SEARCH_CACHE_TTL_SECONDS=300
PICOCLAW_MEDIA_CLEANUP_ENABLED=true
PICOCLAW_MEDIA_CLEANUP_MAX_AGE=30
PICOCLAW_MEDIA_CLEANUP_INTERVAL=5
Gateway Configuration
PICOCLAW_GATEWAY_HOST=0.0.0.0
PICOCLAW_GATEWAY_PORT=18790
Heartbeat Configuration
PICOCLAW_HEARTBEAT_ENABLED=true
PICOCLAW_HEARTBEAT_INTERVAL=30 # minutes
Devices Configuration
PICOCLAW_DEVICES_ENABLED=false
PICOCLAW_DEVICES_MONITOR_USB=true
Channel Configuration
Telegram
PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
PICOCLAW_CHANNELS_TELEGRAM_TOKEN=123456:ABC-DEF...
PICOCLAW_CHANNELS_TELEGRAM_BASE_URL=https://api.telegram.org
PICOCLAW_CHANNELS_TELEGRAM_PROXY=socks5://proxy:1080
PICOCLAW_CHANNELS_TELEGRAM_REASONING_CHANNEL_ID=
Discord
PICOCLAW_CHANNELS_DISCORD_ENABLED=true
PICOCLAW_CHANNELS_DISCORD_TOKEN=your-bot-token
PICOCLAW_CHANNELS_DISCORD_PROXY=
PICOCLAW_CHANNELS_DISCORD_MENTION_ONLY=false
WhatsApp
PICOCLAW_CHANNELS_WHATSAPP_ENABLED=true
PICOCLAW_CHANNELS_WHATSAPP_BRIDGE_URL=ws://localhost:3001
PICOCLAW_CHANNELS_WHATSAPP_USE_NATIVE=true
PICOCLAW_CHANNELS_WHATSAPP_SESSION_STORE_PATH=
PICOCLAW_CHANNELS_QQ_ENABLED=true
PICOCLAW_CHANNELS_QQ_APP_ID=your-app-id
PICOCLAW_CHANNELS_QQ_APP_SECRET=your-secret
DingTalk
PICOCLAW_CHANNELS_DINGTALK_ENABLED=true
PICOCLAW_CHANNELS_DINGTALK_CLIENT_ID=your-client-id
PICOCLAW_CHANNELS_DINGTALK_CLIENT_SECRET=your-secret
LINE
PICOCLAW_CHANNELS_LINE_ENABLED=true
PICOCLAW_CHANNELS_LINE_CHANNEL_SECRET=your-secret
PICOCLAW_CHANNELS_LINE_CHANNEL_ACCESS_TOKEN=your-token
PICOCLAW_CHANNELS_LINE_WEBHOOK_HOST=0.0.0.0
PICOCLAW_CHANNELS_LINE_WEBHOOK_PORT=18791
PICOCLAW_CHANNELS_LINE_WEBHOOK_PATH=/webhook/line
WeCom
PICOCLAW_CHANNELS_WECOM_ENABLED=true
PICOCLAW_CHANNELS_WECOM_TOKEN=your-token
PICOCLAW_CHANNELS_WECOM_ENCODING_AES_KEY=your-key
PICOCLAW_CHANNELS_WECOM_WEBHOOK_URL=https://qyapi.weixin.qq.com/...
PICOCLAW_CHANNELS_WECOM_WEBHOOK_PATH=/webhook/wecom
Usage Examples
Docker Compose
version: '3'
services:
picoclaw:
image: picoclaw:latest
environment:
- PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME=claude-sonnet-4.6
- PICOCLAW_PROVIDERS_ANTHROPIC_API_KEY=sk-ant-...
- PICOCLAW_TOOLS_WEB_BRAVE_API_KEY=BSA...
- PICOCLAW_CHANNELS_TELEGRAM_TOKEN=123456:ABC...
- PICOCLAW_GATEWAY_HOST=0.0.0.0
Kubernetes Secret
apiVersion: v1
kind: Secret
metadata:
name: picoclaw-secrets
type: Opaque
stringData:
PICOCLAW_PROVIDERS_ANTHROPIC_API_KEY: sk-ant-...
PICOCLAW_TOOLS_WEB_BRAVE_API_KEY: BSA...
PICOCLAW_CHANNELS_TELEGRAM_TOKEN: 123456:ABC...
Shell Script
#!/bin/bash
export PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME=gpt-5.2
export PICOCLAW_PROVIDERS_OPENAI_API_KEY=sk-proj-...
export PICOCLAW_TOOLS_WEB_BRAVE_API_KEY=BSA...
picoclaw gateway
systemd Service
[Unit]
Description=PicoClaw Gateway
After=network.target
[Service]
Type=simple
User=picoclaw
Environment="PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME=claude-sonnet-4.6"
Environment="PICOCLAW_PROVIDERS_ANTHROPIC_API_KEY=sk-ant-..."
Environment="PICOCLAW_GATEWAY_HOST=0.0.0.0"
ExecStart=/usr/local/bin/picoclaw gateway
Restart=always
[Install]
WantedBy=multi-user.target
Best Practices
- Use secrets management for API keys in production
- Never commit
.env files with real credentials
- Use read-only environment variables in containers
- Override selectively - only set what you need to change
- Document environment variable usage in deployment docs
Precedence
Configuration resolution order:
- Environment Variables (highest priority)
- Config File (
~/.picoclaw/config.json)
- Default Values (lowest priority)
Example:
# config.json has model_name: "gpt-5.2"
# Environment variable overrides it
PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME=claude-sonnet-4.6 picoclaw agent
# Agent will use claude-sonnet-4.6
Next Steps