Operations

📝 Logging

OrcBot uses Winston for structured logging:

# Log location
~/.orcbot/logs/orcbot.log
~/.orcbot/logs/error.log

# Log levels: error, warn, info, debug

Configure log level in config:

logLevel: debug  # More verbose output

🔍 Troubleshooting

WhatsApp Won't Connect

• Delete ~/.orcbot/whatsapp-auth and re-scan QR
• Ensure phone has internet connectivity
• Check if WhatsApp Web is logged in elsewhere

Telegram Bot Not Responding

• Verify TELEGRAM_BOT_TOKEN is set
• Check bot is not blocked/deactivated
• Ensure telegramAutoReply: true

LLM Errors

• Verify API keys in ~/.orcbot/.env
• Check rate limits and quotas
• Try switching models: model: gpt-4o-mini

Browser Automation Fails

• Ensure Playwright is installed: npx playwright install
• Or use Lightpanda: orcbot lightpanda install
• Check browserEngine config matches installed browser

🖥️ CLI Commands Reference

Command	Description
orcbot run	Start the agent heartbeat loop
orcbot ui	Interactive TUI menu
orcbot push "task"	Add task to queue
orcbot gateway	Start REST/WebSocket server
orcbot config get/set	View or modify config
orcbot reset	Reset agent state
orcbot builder <url>	Generate skill from webpage
orcbot lightpanda	Manage Lightpanda browser

🚀 Production Tips

Run as Background Service

# Using PM2
npm install -g pm2
pm2 start "orcbot run" --name orcbot

# Using systemd (Linux)
# Create /etc/systemd/system/orcbot.service

Resource Management

• Use browserEngine: lightpanda for 9x less RAM
• Set heartbeatInterval higher to reduce API calls
• Enable memory consolidation to keep context lean

Monitoring

• Use Gateway dashboard for real-time status
• Watch logs with: tail -f ~/.orcbot/logs/orcbot.log
• Set up alerts on error.log growth

📁 Data Locations

🔄 Backup & Restore

# Backup entire data directory
tar -czvf orcbot-backup.tar.gz ~/.orcbot

# Restore
tar -xzvf orcbot-backup.tar.gz -C ~/

# Reset to clean state
orcbot reset