Skip to main content

​
Web Search Issues

​
”API key configuration issue” Error

This is normal if you haven’t configured a search API key yet. PicoClaw will provide helpful links for manual searching.
Solution: Enable web search by configuring an API key:

​
Provider Issues

​
Content Filtering Errors

Some providers (like Zhipu) have content filtering that may block certain queries.
Solutions:
  1. Rephrase your query to avoid triggering filters
  2. Switch to a different model/provider
  3. Use OpenRouter to access multiple providers
Example config with fallback models: 
{
  "model_list": [
    {
      "model_name": "primary-model",
      "model": "zhipu/glm-4.7",
      "api_key": "your-key"
    },
    {
      "model_name": "fallback-model",
      "model": "openai/gpt-4",
      "api_key": "your-openai-key"
    }
  ]
}

​
Request Timeout Issues

Problem: Requests timing out with slow providers Solution: Increase the timeout in your model configuration: 
{
  "model_list": [
    {
      "model_name": "slow-model",
      "model": "provider/model-name",
      "api_key": "your-key",
      "request_timeout": 300
    }
  ]
}
request_timeout is in seconds. Default is 120s if omitted or set to <= 0.

​
Channel Issues

​
Telegram: “Conflict: terminated by other getUpdates”

This happens when another instance of the bot is running.
Solution:
  1. Stop all running picoclaw gateway instances: 
    pkill picoclaw
  2. Start only one instance: 
    picoclaw gateway

​
Discord: Bot Not Responding

Common Causes:
Solution: Go to Discord Developer Portal → Your App → Bot → Enable MESSAGE CONTENT INTENT
Solution:
  1. Enable Developer Mode in Discord (Settings → Advanced → Developer Mode)
  2. Right-click your avatar → Copy User ID
  3. Add to config:
{
  "channels": {
    "discord": {
      "allow_from": ["YOUR_USER_ID"]
    }
  }
}
Solution: When inviting the bot, ensure these permissions are selected:
  • Send Messages
  • Read Message History
  • View Channels

​
WhatsApp: QR Code Not Appearing

Prerequisites:
  • Must build with WhatsApp support: make build-whatsapp-native
  • Or use the WhatsApp-enabled binary
Debug Steps: 
# Check if native WhatsApp is enabled
picoclaw gateway
# Look for "Starting WhatsApp native channel" in logs
Config: 
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "use_native": true,
      "session_store_path": "",
      "allow_from": []
    }
  }
}

​
LINE/WeCom: Webhook Not Receiving Messages

All webhook-based channels use the shared Gateway HTTP server.
Default Gateway Settings:
  • Host: 127.0.0.1
  • Port: 18790
For Production Deployment:
  1. Use a reverse proxy (nginx, caddy) for HTTPS
  2. Or use a tunnel (ngrok, cloudflare tunnel):
# Example with ngrok
ngrok http 18790
  1. Configure webhook URL in LINE/WeCom console:
    • LINE: https://your-domain/webhook/line
    • WeCom: https://your-domain/webhook/wecom
    • WeCom App: https://your-domain/webhook/wecom-app
    • WeCom AI Bot: https://your-domain/webhook/wecom-aibot
For Docker users: Set PICOCLAW_GATEWAY_HOST=0.0.0.0 to allow external connections.

​
Installation Issues

​
Build Fails on Raspberry Pi Zero 2 W

Problem: Wrong architecture binary 
make build-linux-arm
# Binary: build/picoclaw-linux-arm

​
Android/Termux: “No such file or directory”

Solution: Use proot environment: 
pkg install proot
termux-chroot ./picoclaw-linux-arm64 onboard
For Termux persistent installation: 
# Move binary to Termux bin
mv picoclaw-linux-arm64 $PREFIX/bin/picoclaw
chmod +x $PREFIX/bin/picoclaw

# Run from anywhere
picoclaw gateway

​
Configuration Issues

​
Config File Not Found

Default location: ~/.picoclaw/config.json Solution: Initialize configuration: 
picoclaw onboard
Custom config location: 
export PICOCLAW_CONFIG=/path/to/config.json
picoclaw gateway

​
Workspace Path Issues

Option 1: Via config file
{
  "agents": {
    "defaults": {
      "workspace": "/custom/path/workspace"
    }
  }
}
Option 2: Via environment variable
export PICOCLAW_HOME=/custom/path
picoclaw gateway
# Workspace will be at /custom/path/workspace
Ensure the workspace directory has proper permissions:
mkdir -p ~/.picoclaw/workspace
chmod 755 ~/.picoclaw/workspace

​
Performance Issues

​
High Memory Usage

Recent versions (with many merged PRs) may use 10-20MB instead of the target <10MB. Memory optimization is prioritized in the roadmap.
Temporary Solutions:
  1. Disable unused channels in config
  2. Reduce max_tool_iterations in agent defaults
  3. Use smaller models (e.g., glm-4-flash instead of glm-4.7)

​
Slow Response Times

Common Causes:
1

Check Model Performance

Some models are slower than others. Try switching to a faster model:
  • Groq: Ultra-fast inference
  • Cerebras: Fast inference
  • Local Ollama: Fast but requires local resources
2

Check Network Latency

For cloud providers, network latency matters:
# Test API latency
curl -w "@curl-format.txt" -o /dev/null -s https://api.provider.com/v1/models
3

Reduce Tool Iterations

{
  "agents": {
    "defaults": {
      "max_tool_iterations": 10
    }
  }
}

​
Security Issues

​
Agent Accessing Files Outside Workspace

By default, restrict_to_workspace is set to true for security.
If you need broader access (use with caution): 
{
  "agents": {
    "defaults": {
      "restrict_to_workspace": false
    }
  }
}
Or via environment variable: 
export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
Even with restrictions disabled, dangerous commands (rm -rf, format, etc.) are still blocked.

​
Docker Issues

​
Container Exits Immediately

Cause: First run generates config then exits Solution: This is expected behavior 
# 1. First run - generates config
docker compose -f docker/docker-compose.yml --profile gateway up
# Container prints "First-run setup complete." and stops

# 2. Edit config
vim docker/data/config.json

# 3. Start normally
docker compose -f docker/docker-compose.yml --profile gateway up -d

​
Health Endpoints Not Accessible

Problem: Gateway listens on 127.0.0.1 by default Solution: Set host to 0.0.0.0: 
export PICOCLAW_GATEWAY_HOST=0.0.0.0
docker compose -f docker/docker-compose.yml --profile gateway up -d

​
Debug Tips

​
Enable Verbose Logging

# Set log level to debug
export PICOCLAW_LOG_LEVEL=debug
picoclaw gateway

​
Check Configuration

# Validate config syntax
cat ~/.picoclaw/config.json | jq .

# Check for common issues
picoclaw status

​
Test Provider Connection

# Quick test with agent mode
picoclaw agent -m "Hello, test message"

​
Monitor Resource Usage

# Linux
top -p $(pgrep picoclaw)

# macOS
top -pid $(pgrep picoclaw)

# Detailed memory analysis
ps aux | grep picoclaw

​
Getting Help

GitHub Issues

Report bugs or request features

GitHub Discussions

Ask questions and share ideas

Discord

Join the community chat

Documentation

Read the full documentation
Before opening an issue, search existing issues to see if your problem has already been reported or solved.

Build docs developers (and LLMs) love

Get started for freeTalk to us