feat: integrate telegram bot support
- Add comprehensive Telegram bot setup guide (docs/TELEGRAM_SETUP.md) - Create quick start guide for rapid Telegram integration (TELEGRAM_QUICKSTART.md) - Update config.json template to enable Telegram by default - Update .env template with Telegram bot token configuration - Add deploy workflow step to configure environment variables from GitHub secrets - Support PICOCLAW_TELEGRAM_BOT_TOKEN secret for automated deployments Features: - Text messages, voice notes (auto-transcribed), images, documents - Optional user whitelist via allow_from config - Proxy support for restricted regions - Commands: /start, /help, /show, /list Enables: 1. Users to create bot via @BotFather 2. Add PICOCLAW_TELEGRAM_BOT_TOKEN to GitHub Secrets 3. Automated deployment with secrets injection 4. Manual configuration via SSH for direct deployments https://claude.ai/code/session_019vXaqxGmkdCjM8m3jp6rYj
This commit is contained in:
Claude
parent
7520aff373
commit
54e66f9eb0
4 changed files with 340 additions and 3 deletions
34
.github/workflows/deploy-hostinger.yml
vendored
34
.github/workflows/deploy-hostinger.yml
vendored
|
|
@ -65,6 +65,40 @@ jobs:
|
||||||
deploy/hostinger/docker-compose.production.yml \
|
deploy/hostinger/docker-compose.production.yml \
|
||||||
"${SSH_USER}@${{ secrets.HOSTINGER_HOST }}:${REMOTE_DIR}/docker-compose.yml"
|
"${SSH_USER}@${{ secrets.HOSTINGER_HOST }}:${REMOTE_DIR}/docker-compose.yml"
|
||||||
|
|
||||||
|
- name: Configure environment variables
|
||||||
|
env:
|
||||||
|
SSHPASS: ${{ secrets.HOSTINGER_SSH_PASSWORD }}
|
||||||
|
run: |
|
||||||
|
SSH_PORT="${{ secrets.HOSTINGER_SSH_PORT }}"
|
||||||
|
SSH_PORT="${SSH_PORT:-22}"
|
||||||
|
SSH_USER="${{ secrets.HOSTINGER_SSH_USER }}"
|
||||||
|
SSH_USER="${SSH_USER:-root}"
|
||||||
|
|
||||||
|
sshpass -e ssh \
|
||||||
|
-o StrictHostKeyChecking=accept-new \
|
||||||
|
-o ConnectTimeout=15 \
|
||||||
|
-p "${SSH_PORT}" \
|
||||||
|
"${SSH_USER}@${{ secrets.HOSTINGER_HOST }}" <<'EOF'
|
||||||
|
# Update .env with secrets (keep existing values, only override if provided)
|
||||||
|
ENV_FILE="/opt/picoclaw/config/.env"
|
||||||
|
|
||||||
|
# Telegram Bot Token
|
||||||
|
if [ -n "${{ secrets.PICOCLAW_TELEGRAM_BOT_TOKEN }}" ]; then
|
||||||
|
grep -q "PICOCLAW_CHANNELS_TELEGRAM_TOKEN" "$ENV_FILE" && \
|
||||||
|
sed -i "s|^PICOCLAW_CHANNELS_TELEGRAM_TOKEN=.*|PICOCLAW_CHANNELS_TELEGRAM_TOKEN=${{ secrets.PICOCLAW_TELEGRAM_BOT_TOKEN }}|" "$ENV_FILE" || \
|
||||||
|
echo "PICOCLAW_CHANNELS_TELEGRAM_TOKEN=${{ secrets.PICOCLAW_TELEGRAM_BOT_TOKEN }}" >> "$ENV_FILE"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Anthropic API Key
|
||||||
|
if [ -n "${{ secrets.ANTHROPIC_API_KEY }}" ]; then
|
||||||
|
grep -q "ANTHROPIC_API_KEY" "$ENV_FILE" && \
|
||||||
|
sed -i "s|^ANTHROPIC_API_KEY=.*|ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}|" "$ENV_FILE" || \
|
||||||
|
echo "ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}" >> "$ENV_FILE"
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "Environment variables updated"
|
||||||
|
EOF
|
||||||
|
|
||||||
- name: Build and restart Docker container
|
- name: Build and restart Docker container
|
||||||
env:
|
env:
|
||||||
SSHPASS: ${{ secrets.HOSTINGER_SSH_PASSWORD }}
|
SSHPASS: ${{ secrets.HOSTINGER_SSH_PASSWORD }}
|
||||||
|
|
|
||||||
93
TELEGRAM_QUICKSTART.md
Normal file
93
TELEGRAM_QUICKSTART.md
Normal file
|
|
@ -0,0 +1,93 @@
|
||||||
|
# 🤖 PicoClaw Telegram Bot - Quick Start
|
||||||
|
|
||||||
|
**Get your PicoClaw AI assistant on Telegram in 3 minutes!**
|
||||||
|
|
||||||
|
## ⚡ Quick Setup
|
||||||
|
|
||||||
|
### 1️⃣ Get Your Bot Token
|
||||||
|
|
||||||
|
1. Open Telegram → Search `@BotFather`
|
||||||
|
2. Send `/newbot`
|
||||||
|
3. Follow prompts (name + username ending in `_bot`)
|
||||||
|
4. **Copy the token** 🔐
|
||||||
|
|
||||||
|
### 2️⃣ Add to GitHub Secrets
|
||||||
|
|
||||||
|
- Go to your repo: **Settings** → **Secrets and Variables** → **Actions**
|
||||||
|
- Click **New repository secret**
|
||||||
|
- Name: `PICOCLAW_TELEGRAM_BOT_TOKEN`
|
||||||
|
- Value: Your token from step 1
|
||||||
|
|
||||||
|
### 3️⃣ Deploy
|
||||||
|
|
||||||
|
Push to main branch or trigger workflow:
|
||||||
|
```bash
|
||||||
|
git push origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
The bot will be live in ~2 minutes ✨
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎯 Start Using
|
||||||
|
|
||||||
|
Find your bot on Telegram (search username) and send:
|
||||||
|
```
|
||||||
|
/start
|
||||||
|
Hello!
|
||||||
|
```
|
||||||
|
|
||||||
|
### Commands
|
||||||
|
- `/start` - Begin
|
||||||
|
- `/help` - Show help
|
||||||
|
- `/show` - Agent info
|
||||||
|
- `/list` - List agents
|
||||||
|
|
||||||
|
### Features
|
||||||
|
✨ Text messages
|
||||||
|
🎤 Voice notes (auto-transcribed)
|
||||||
|
📸 Images
|
||||||
|
📄 Documents
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 Manual Setup (Without GitHub Actions)
|
||||||
|
|
||||||
|
### SSH Setup
|
||||||
|
```bash
|
||||||
|
ssh root@YOUR_IP
|
||||||
|
nano /opt/picoclaw/config/.env
|
||||||
|
```
|
||||||
|
|
||||||
|
Add:
|
||||||
|
```
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_TOKEN=YOUR_TOKEN_HERE
|
||||||
|
```
|
||||||
|
|
||||||
|
Restart:
|
||||||
|
```bash
|
||||||
|
docker compose -f /opt/picoclaw/docker-compose.yml restart picoclaw
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛡️ Security
|
||||||
|
|
||||||
|
- ⚠️ Never commit tokens to git
|
||||||
|
- 🔐 Use GitHub Secrets
|
||||||
|
- 👥 Optional: Whitelist users in `allow_from` config
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📚 Full Guide
|
||||||
|
|
||||||
|
See [docs/TELEGRAM_SETUP.md](docs/TELEGRAM_SETUP.md) for advanced options.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Questions?** Check logs:
|
||||||
|
```bash
|
||||||
|
ssh root@YOUR_IP
|
||||||
|
tail -f /opt/picoclaw/logs/picoclaw.log | grep -i telegram
|
||||||
|
```
|
||||||
|
|
@ -185,8 +185,12 @@ if [ ! -f "${PICOCLAW_HOME}/config/.env" ]; then
|
||||||
# OPENROUTER_API_KEY=sk-or-v1-xxx
|
# OPENROUTER_API_KEY=sk-or-v1-xxx
|
||||||
# GEMINI_API_KEY=xxx
|
# GEMINI_API_KEY=xxx
|
||||||
|
|
||||||
# ── Chat Channel ─────────────────────────────────────
|
# ── Telegram Bot ─────────────────────────────────────
|
||||||
# TELEGRAM_BOT_TOKEN=123456:ABC...
|
# Get token from @BotFather on Telegram
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_TOKEN=
|
||||||
|
|
||||||
|
# ── Other Chat Channels ──────────────────────────────
|
||||||
# DISCORD_BOT_TOKEN=xxx
|
# DISCORD_BOT_TOKEN=xxx
|
||||||
|
|
||||||
# ── Web Search (optional) ────────────────────────────
|
# ── Web Search (optional) ────────────────────────────
|
||||||
|
|
@ -216,8 +220,9 @@ if [ ! -f "${PICOCLAW_HOME}/config/config.json" ]; then
|
||||||
},
|
},
|
||||||
"channels": {
|
"channels": {
|
||||||
"telegram": {
|
"telegram": {
|
||||||
"enabled": false,
|
"enabled": true,
|
||||||
"token": "",
|
"token": "",
|
||||||
|
"proxy": "",
|
||||||
"allow_from": []
|
"allow_from": []
|
||||||
}
|
}
|
||||||
},
|
},
|
||||||
|
|
|
||||||
205
docs/TELEGRAM_SETUP.md
Normal file
205
docs/TELEGRAM_SETUP.md
Normal file
|
|
@ -0,0 +1,205 @@
|
||||||
|
# PicoClaw Telegram Bot Setup Guide
|
||||||
|
|
||||||
|
Complete step-by-step guide to set up PicoClaw as a Telegram bot.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- Telegram account
|
||||||
|
- Running PicoClaw instance (deployed)
|
||||||
|
- GitHub secrets configured (for automated deployment)
|
||||||
|
|
||||||
|
## Step 1: Create a Telegram Bot with BotFather
|
||||||
|
|
||||||
|
1. Open Telegram and search for **@BotFather**
|
||||||
|
2. Start the chat and send `/start`
|
||||||
|
3. Send `/newbot` to create a new bot
|
||||||
|
4. Follow the prompts:
|
||||||
|
- **Name**: Give your bot a name (e.g., "PicoClaw AI")
|
||||||
|
- **Username**: Must be unique and end with `_bot` (e.g., `picoclaw_bot`)
|
||||||
|
5. **Copy the token** provided (looks like `123456789:ABCdefGHIjklMNOpqrSTUvwxYZ`)
|
||||||
|
- ⚠️ **Keep this token secret!** Anyone with this token can control your bot.
|
||||||
|
|
||||||
|
## Step 2: Configure PicoClaw
|
||||||
|
|
||||||
|
### Option A: Using Environment Variables (Production)
|
||||||
|
|
||||||
|
Add to your `.env` file or GitHub Secrets:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_TOKEN=YOUR_BOT_TOKEN_HERE
|
||||||
|
```
|
||||||
|
|
||||||
|
### Option B: Using config.json (Development)
|
||||||
|
|
||||||
|
Edit `config/config.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"telegram": {
|
||||||
|
"enabled": true,
|
||||||
|
"token": "YOUR_BOT_TOKEN_HERE",
|
||||||
|
"proxy": "",
|
||||||
|
"allow_from": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Optional: User Whitelist
|
||||||
|
|
||||||
|
To restrict access to specific users, add their Telegram user IDs:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"telegram": {
|
||||||
|
"enabled": true,
|
||||||
|
"token": "YOUR_BOT_TOKEN_HERE",
|
||||||
|
"allow_from": ["123456789", "987654321"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
To find your Telegram user ID:
|
||||||
|
1. Send any message to your bot
|
||||||
|
2. Check the logs: `cat /opt/picoclaw/logs/picoclaw.log | grep "user_id"`
|
||||||
|
3. Your user ID will be in the output
|
||||||
|
|
||||||
|
## Step 3: Deploy to Hostinger
|
||||||
|
|
||||||
|
### For GitHub Actions Deployment
|
||||||
|
|
||||||
|
1. Add the bot token to your GitHub repository secrets:
|
||||||
|
- Go to **Settings** → **Secrets and Variables** → **Actions**
|
||||||
|
- Click **New repository secret**
|
||||||
|
- **Name**: `PICOCLAW_TELEGRAM_BOT_TOKEN`
|
||||||
|
- **Value**: Your BotFather token
|
||||||
|
|
||||||
|
2. Update `.github/workflows/deploy-hostinger.yml` to use the secret:
|
||||||
|
```yaml
|
||||||
|
env:
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_ENABLED: "true"
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_TOKEN: ${{ secrets.PICOCLAW_TELEGRAM_BOT_TOKEN }}
|
||||||
|
```
|
||||||
|
|
||||||
|
### For Manual Deployment
|
||||||
|
|
||||||
|
SSH into your server:
|
||||||
|
```bash
|
||||||
|
ssh root@YOUR_HOSTINGER_IP
|
||||||
|
nano /opt/picoclaw/config/.env
|
||||||
|
```
|
||||||
|
|
||||||
|
Add:
|
||||||
|
```
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
|
||||||
|
PICOCLAW_CHANNELS_TELEGRAM_TOKEN=YOUR_BOT_TOKEN
|
||||||
|
```
|
||||||
|
|
||||||
|
Restart the container:
|
||||||
|
```bash
|
||||||
|
cd /opt/picoclaw && docker compose -f docker-compose.production.yml restart picoclaw
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 4: Start Using Your Bot
|
||||||
|
|
||||||
|
1. Find your bot on Telegram (search by username: @your_bot_username)
|
||||||
|
2. Send `/start` to initialize
|
||||||
|
3. Start chatting!
|
||||||
|
|
||||||
|
### Available Commands
|
||||||
|
|
||||||
|
- `/start` - Initialize the bot
|
||||||
|
- `/help` - Show available commands
|
||||||
|
- `/show` - Show current agent info
|
||||||
|
- `/list` - List available agents
|
||||||
|
|
||||||
|
### Features
|
||||||
|
|
||||||
|
✅ **Text Messages** - Ask questions, get AI responses
|
||||||
|
✅ **Voice Messages** - Send voice notes (auto-transcribed)
|
||||||
|
✅ **Images** - Send photos for analysis
|
||||||
|
✅ **Documents** - Share files for processing
|
||||||
|
✅ **Multi-agent** - Switch between different AI agents
|
||||||
|
✅ **Thinking Indicator** - See when the AI is processing
|
||||||
|
|
||||||
|
## Step 5: Verify It's Working
|
||||||
|
|
||||||
|
Check the logs to confirm the bot is running:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
ssh root@YOUR_HOSTINGER_IP
|
||||||
|
tail -f /opt/picoclaw/logs/picoclaw.log | grep -i telegram
|
||||||
|
```
|
||||||
|
|
||||||
|
You should see:
|
||||||
|
```
|
||||||
|
[INFO] [telegram] Starting Telegram bot (polling mode)...
|
||||||
|
[INFO] [telegram] Telegram bot connected
|
||||||
|
```
|
||||||
|
|
||||||
|
Send a test message to your bot and check:
|
||||||
|
```bash
|
||||||
|
tail -f /opt/picoclaw/logs/picoclaw.log | grep -i "Received message"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Bot doesn't respond
|
||||||
|
|
||||||
|
1. Check if Telegram is enabled:
|
||||||
|
```bash
|
||||||
|
docker exec picoclaw cat /opt/picoclaw/config/.env | grep TELEGRAM
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Verify the token is correct (no spaces, exact copy from BotFather)
|
||||||
|
|
||||||
|
3. Check logs for errors:
|
||||||
|
```bash
|
||||||
|
docker exec picoclaw tail -100 /opt/picoclaw/logs/picoclaw.log | grep -i telegram
|
||||||
|
```
|
||||||
|
|
||||||
|
### "Failed to create telegram bot"
|
||||||
|
|
||||||
|
- Token is invalid or expired
|
||||||
|
- Token is incomplete (missing characters)
|
||||||
|
- Try creating a new bot with BotFather
|
||||||
|
|
||||||
|
### "Message rejected by allowlist"
|
||||||
|
|
||||||
|
- Your Telegram user ID is not in the whitelist
|
||||||
|
- Check your actual ID by removing `allow_from` temporarily
|
||||||
|
- Add your ID to the whitelist
|
||||||
|
|
||||||
|
## Advanced: Using Proxy
|
||||||
|
|
||||||
|
If you're in a region with restricted access to Telegram, configure a proxy:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"channels": {
|
||||||
|
"telegram": {
|
||||||
|
"enabled": true,
|
||||||
|
"token": "YOUR_BOT_TOKEN_HERE",
|
||||||
|
"proxy": "socks5://user:pass@proxy-host:1080",
|
||||||
|
"allow_from": []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Security Notes
|
||||||
|
|
||||||
|
⚠️ **Never commit your bot token to version control**
|
||||||
|
⚠️ **Use GitHub Secrets for CI/CD deployments**
|
||||||
|
⚠️ **Consider using user whitelists for sensitive deployments**
|
||||||
|
⚠️ **Regularly rotate tokens if compromised**
|
||||||
|
|
||||||
|
## Getting Help
|
||||||
|
|
||||||
|
- Telegram Bot API Docs: https://core.telegram.org/bots
|
||||||
|
- BotFather Commands: https://core.telegram.org/bots#botfather
|
||||||
|
- PicoClaw Issues: https://github.com/sipeed/picoclaw/issues
|
||||||
Loading…
Add table
Reference in a new issue