How to Run PicoClaw as a Telegram Bot on Opalstack with Podman

PicoClaw is a lightweight, open-source AI agent framework that can run as a persistent Telegram bot. Opalstack provides AlmaLinux 9 servers with native Podman support, making it a suitable hosting environment.

This tutorial assumes you already have:

• An Opalstack account
• An AlmaLinux 9 shell user (Podman is only available on AlmaLinux 9; contact support to migrate if needed)
• A Proxy Port app named “picoclaw” (you only need the assigned internal port if you later use webhooks)
• A domain (optional for polling mode)

# Step 1 – Prepare the directory and clone PicoClaw

1. SSH into your Opalstack server:

   ssh yourshelluser@yourserver.opalstack.com
   

2. Enter the application directory (Opalstack convention):

   cd ~/apps/picoclaw
   

3. Clone the repository into the current directory:

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

# Step 2 – Configure PicoClaw

1. Copy the example configuration:

   cp config/config.example.json config/config.json
   

2. Get OpenRouter key

• Sign up at https://openrouter.ai → add at least $10 credit (free models are heavily rate-limited and unreliable for production use).
• Generate an API key and paste it.

3. Get Telegram bot token & user ID

• Message @BotFather → /newbot → follow prompts → copy the token
• Message @userinfobot → get your numeric Telegram ID (e.g. 123456789)

4. Edit config/config.json (use nano config/config.json or vim).

   I used openrouter + minimax. You can choose other providers & model.

   "providers": {
     "openrouter": {
       "api_key": "sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
       "api_base": "https://openrouter.ai/api/v1"
     }
   },
   
   "agents": {
     "defaults": {
       "model": "minimax/minimax-m2.5"
     }
   },
   
   "channels": {
     "telegram": {
       "enabled": true,
       "token": "YOUR_BOT_TOKEN_HERE",
       "allow_from": ["YOUR_NUMERIC_TELEGRAM_ID"]
     }
   }
   

5. (Optional but recommended) Reduce heartbeat cost
   Heartbeat runs every 30 minutes by default and consumes tokens even when idle.

   "heartbeat": {
     "enabled": true,
     "interval": 120          // 120 minutes = 2 hours
   }
   

   You can set it to 1440 (24 hours), 2880 (2 days), or disable it completely ("enabled": false).

# Step 4 – Build and start the container

podman-compose --profile gateway build
podman-compose --profile gateway up -d

Check that the container is running:

podman ps

You should see a container named picoclaw-gateway (or similar) in Up status.

# Step 5 – Quick functional test

Run a one-shot agent query inside the container:

podman exec -it picoclaw-gateway picoclaw agent -m "Tell me a joke"

If you see a joke reply → the LLM connection works.

# Step 6 – Verify Telegram integration

1. Open Telegram

2. Search for your bot username (the one you created with BotFather)

3. Send any message, e.g.:

   what can you do for me
   

You should receive the capabilities list reply within a few seconds.

# Step 7 – Monitoring & Troubleshooting

• Real-time logs:

  podman logs -f picoclaw-gateway
  

• List all containers (including stopped ones):

  podman ps -a
  

• Restart after config changes:

  podman-compose --profile gateway down && podman-compose --profile gateway up -d
  

• Check OpenRouter dashboard (https://openrouter.ai/activity)
  You should see activity only when you message the bot or when heartbeat runs.

# Optional – Updating PicoClaw later

Keep the git repository so you can update easily:

cd ~/apps/picoclaw
git pull
podman-compose --profile gateway build --no-cache
podman-compose --profile gateway up -d

# Summary

You now have a private, persistent AI agent running as a Telegram bot on Opalstack using Podman.
All configuration lives in ~/apps/picoclaw/config/config.json.
Background costs are controlled mainly by the heartbeat interval and model choice.

You can now extend the bot by:

• enabling more tools in config.json
• adding cron jobs (picoclaw cron add ...)
• connecting additional channels (Discord, LINE, etc.)
• writing custom skills in the workspace folder

Enjoy your personal AI assistant.