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 \
|
||||
"${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
|
||||
env:
|
||||
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
|
||||
# GEMINI_API_KEY=xxx
|
||||
|
||||
# ── Chat Channel ─────────────────────────────────────
|
||||
# TELEGRAM_BOT_TOKEN=123456:ABC...
|
||||
# ── Telegram Bot ─────────────────────────────────────
|
||||
# Get token from @BotFather on Telegram
|
||||
PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
|
||||
PICOCLAW_CHANNELS_TELEGRAM_TOKEN=
|
||||
|
||||
# ── Other Chat Channels ──────────────────────────────
|
||||
# DISCORD_BOT_TOKEN=xxx
|
||||
|
||||
# ── Web Search (optional) ────────────────────────────
|
||||
|
|
@ -216,8 +220,9 @@ if [ ! -f "${PICOCLAW_HOME}/config/config.json" ]; then
|
|||
},
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": false,
|
||||
"enabled": true,
|
||||
"token": "",
|
||||
"proxy": "",
|
||||
"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