←
🤖Agent ProtocolAgent Protocol
0%
The AI Agent Playbook
Your AI.
Your Telegram.
Always On.
From BotFather to autonomous agent. From prompt to production.
⚠️Educational Only • NFA • DYOR
10 levels. 2 tracks. 100% practical.
Choose Your Track
Complete levels 1-4 first, then your chosen track, then 8-10.
Before starting, you need a place to run commands. Good news: Track B works on your laptop!
Track A vs Track B Requirements
Critical💡 Why This Matters
Different tracks have different needs!
🟣 Track B: Claude Code (easiest to start)
Just your laptop! No server needed.
→ Mac, Windows, or Linux
→ Bot works while Claude Code is running
→ Jump to "Local Setup" below
🔵 Track A: OpenClaw
Needs a server (VPS) for 24/7 availability.
→ Your bot runs even when your laptop is off
→ See VPS options below
TL;DR:
• Learning/testing → Your laptop is fine (both tracks)
• 24/7 production → Need a VPS (Track A) or keep laptop on (Track B)
Local Setup (Mac/Windows/Linux)
💡 Why This Matters
Start here! Works for both tracks.
Mac:
• Open Terminal (Cmd+Space, type "Terminal")
• Install Node.js: https://nodejs.org
Windows:
• Open PowerShell (Win+X, select "PowerShell")
• Install Node.js: https://nodejs.org
Linux:
Verify installation:
✅ That's it for Track B! Continue to Level 1.
🔵 Track A users: also set up a VPS below for 24/7.
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejsnode --version
npm --versionVPS Options (Track A / 24/7 Production)
Only needed if:
• You want your bot online 24/7
• You chose Track A (OpenClaw)
Option 1: Managed VPS (easiest)
• Hostinger VPS - beginner-friendly panel
• No SSH knowledge needed
• https://hostinger.com?REFERRALCODE=NB4JULIENWW7
Option 2: Traditional VPS
• $5-20/month (DigitalOcean, Hetzner, OVH, Vultr)
• You connect via SSH
• More control, more learning curve
Option 3: Home Server
• Mac Mini, old laptop, Raspberry Pi
• One-time cost, runs at home
• Needs stable internet
VPS Quick Setup
1. Create a VPS
Sign up at DigitalOcean, Hetzner, or OVH
Choose: Ubuntu 22.04, 1GB RAM, $5/month
2. Connect via SSH
3. Install Node.js
4. Verify
Now you're ready for the next levels!
ssh root@your-server-ipcurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejsnode --version
npm --versionEasy Option: Hostinger VPS
💡 Why This Matters
Don't want to deal with SSH? Hostinger has a friendly panel.
Hostinger VPS - Perfect for beginners!
✅ Visual control panel (no terminal needed)
✅ One-click Node.js install
✅ 24/7 support
✅ Starting at ~$5/month
Get started:
https://hostinger.com?REFERRALCODE=NB4JULIENWW7
After signup:
1. Create a VPS with Ubuntu
2. Use the panel to install Node.js
3. Upload your files via the file manager
4. Start your agent from the panel
Every Telegram bot starts with @BotFather. It's the official bot that creates and manages all other bots. No coding required - just a Telegram conversation!
Create Your Bot
Critical💡 Why This Matters
Your bot token is the key to everything. Guard it like a password.
Step 1: Start BotFather
Open Telegram, search for @BotFather, and start a chat.
Step 2: Create New Bot
Send /newbot and follow the prompts:
• Choose a display name (anything)
• Choose a username (must end in 'bot')
Step 3: Get Your Token
BotFather gives you a token like:
123456789:ABCdefGHIjklMNOpqrsTUVwxyz
⚠️ NEVER share this token publicly!Configure Bot Settings
Use these BotFather commands to customize:
/setdescription - What users see before starting
/setabouttext - Bio shown in bot profile
/setuserpic - Bot avatar
/setcommands - Menu of available commands
Pro tip: Set commands even if your AI handles everything - it helps users discover features.
Privacy Mode
💡 Why This Matters
Privacy mode determines what messages your bot receives in groups.
/setprivacy controls group behavior:
Enabled (default): Bot only sees:
• Commands (/command)
• Replies to the bot
• @mentions
Disabled: Bot sees ALL messages in groups
For AI agents, you usually want privacy disabled so the agent can follow conversations.
A quick overview of how Telegram bots receive and send messages. Don't worry about the technical details - OpenClaw and Claude Code handle this for you!
The Simple Flow
How it works:
1️⃣ User sends message to your bot
2️⃣ Telegram delivers it to your agent
3️⃣ Your AI processes and responds
4️⃣ Response appears in Telegram
That's it! OpenClaw and Claude Code handle all the technical stuff (polling, webhooks, etc.) automatically.
What Your Bot Can Do
DMs (Private Chats)
• 1-on-1 conversations with users
• Full message history
• Personal assistant mode
Groups
• Multiple users in one chat
• Bot can be @mentioned
• Useful for team assistants
Channels
• Broadcast to many subscribers
• Bot can post updates
• One-way communication
Message Types
Your AI agent can receive and send:
• Text - Regular messages
• Photos - Images with captions
• Documents - Files of any type
• Voice - Audio messages
• Stickers - Fun images
• Buttons - Interactive choices
The AI can analyze images, process files, and respond with rich media.
Before connecting AI to Telegram, understand the core concepts that make agents work.
Large Language Models
What is an LLM?
A neural network trained on text that can:
• Understand natural language
• Generate human-like responses
• Follow instructions
• Use tools
Popular models:
• Claude (Anthropic) - reasoning, safety
• GPT-4 (OpenAI) - general purpose
• Gemini (Google) - multimodal
Agent Protocol focuses on Claude via OpenClaw and Claude Code.
System Prompts
Critical💡 Why This Matters
The system prompt defines who your agent IS.
System prompt = Agent personality + rules + capabilities
A good system prompt includes:
• Identity: Who is this agent?
• Tone: Formal? Casual? Playful?
• Boundaries: What it won't do
• Tools: What it can access
• Context: Relevant background
Example:
"You are Luna, a friendly assistant for crypto traders. You help with portfolio tracking and market analysis. Never give financial advice. Always cite sources."
Context Window
Context = Everything the model "remembers"
Each model has a limit:
• Claude 3.5/4: 200K tokens (~150K words)
• GPT-4: 128K tokens
What fills context:
• System prompt
• Conversation history
• Tool results
• Retrieved documents
Strategy: Summarize old messages, keep recent ones detailed.
Tool Use
💡 Why This Matters
Tools give your agent superpowers beyond conversation.
Tools = Functions the AI can call
Examples:
•
search_web(query) - Search the internet
• get_balance(wallet) - Check crypto balance
• send_message(to, text) - Message someone
• execute_trade(pair, amount) - Trading
Flow:
1. User asks something
2. AI decides to use a tool
3. Your code executes the tool
4. Result goes back to AI
5. AI responds to user
This is how agents ACT, not just talk.Two ways to connect Claude to Telegram. Choose based on your skills and needs.
Stack Comparison
| Feature | OpenClaw | Claude Code |
|---------|----------|-------------|
| Coding required | Minimal | Some |
| Setup time | 10 minutes | 15 minutes |
| Customization | Config-based | Unlimited |
| Multi-channel | Built-in | Plugin-based |
| Runs 24/7 | Yes (VPS) | When open |
| Best for | Quick deploy | Interactive dev |
Track A: OpenClaw
OpenClaw = Claude as a service
• Pre-built Telegram integration
• Config file, minimal code
• Skills system for extensibility
• Multi-channel (Telegram, WhatsApp, Signal...)
• Memory and context management
• Built-in security
Choose if:
✅ You want to deploy fast
✅ Config > code is your style
✅ You need multiple channels
✅ You want 24/7 always-on agent
Track B: Claude Code
Claude Code = AI coding assistant with channels
• Anthropic's official CLI tool
• Built-in Telegram plugin
• Interactive development
• Full Claude capabilities
• Your local machine
Choose if:
✅ You want Claude as a dev partner
✅ You prefer interactive workflows
✅ You're learning AI development
✅ You don't need 24/7 (yet)
Make Your Choice
Critical💡 Why This Matters
You can always switch later - the concepts transfer.
Quick decision tree:
Do you need 24/7 availability?
├── Yes → Track A: OpenClaw
└── No → Are you a developer?
├── No → Track A: OpenClaw (simpler)
└── Yes → Track B: Claude Code
Next levels split by track. Complete either A or B, then continue with Level 8.
Combine AI with Web3. Your agent can check balances, send transactions, and interact with DeFi.
TON for Agents
Why TON + Telegram?
• Native integration (TON Space)
• 950M Telegram users
• Instant, cheap transactions
• Mini Apps ecosystem
Agent capabilities:
• Check wallet balances
• Send TON/jettons
• Interact with DeFi
• Mint NFTs
• Execute swaps
TON in OpenClaw (Track A)
Install TON skill:
Available tools:
•
openclaw skills install ton-blockchainget_balance(address)
• get_transactions(address)
• send_ton(to, amount)
• swap_tokens(from, to, amount)
• get_token_price(symbol)
The skill handles wallet connection and transaction signing.TON in Claude Code (Track B)
Add TON MCP server:
Or build custom integration:
Expose this as an MCP tool for Claude to use!
/mcp add ton-blockchainimport { TonClient } from '@ton/ton';
const client = new TonClient({
endpoint: 'https://toncenter.com/api/v2/jsonRPC'
});
// Tool: check_balance
async function checkBalance(address) {
const balance = await client.getBalance(address);
return `Balance: ${balance / 1e9} TON`;
}Web3 Security
Critical💡 Why This Matters
Blockchain = irreversible. Be careful!
Best practices:
✅ Hot wallet limits
• Only keep what you need for daily ops
• Large amounts in cold storage
✅ Transaction confirmations
• Require human approval for big transfers
• Set spending limits per day
✅ Testnet first
• Always develop on testnet
• Test thoroughly before mainnet
✅ Key management
• Never expose private keys in prompts
• Use environment variables
• Consider hardware wallets
Before going live, secure your agent and prepare for scale.
API Key Security
Critical💡 Why This Matters
Leaked keys = stolen funds and runaway bills.
Never do:
❌ Commit keys to git
❌ Put keys in frontend code
❌ Share keys in screenshots
❌ Paste keys in chat
Always do:
✅ Use environment variables
✅ Use secrets manager (Vault, AWS SM)
✅ Rotate keys regularly
✅ Set spending limits
✅ Use .gitignore for .env files
Rate Limiting
Protect your agent:
• Limit messages per user per minute
• Set daily token budgets
• Implement cooldowns for expensive operations
• Monitor for abuse patterns
OpenClaw has built-in limits.
For Claude Code, implement manually:
const userCounts = new Map();
function checkLimit(userId) {
const count = userCounts.get(userId) || 0;
if (count > 10) throw new Error('Rate limit');
userCounts.set(userId, count + 1);
}Deployment Options
OpenClaw (Track A):
• VPS with
openclaw gateway start
• Docker + docker-compose
• PM2 for process management
Claude Code (Track B):
• Run in screen or tmux session
• Use a dedicated server
• Consider OpenClaw for true 24/7
Cloud options:
• Railway, Render, Fly.io
• AWS ECS / Google Cloud Run
• DigitalOcean App PlatformMonitoring
Track these metrics:
• Messages processed per hour
• API costs per day
• Error rates
• Response times
• User growth
Tools:
• Grafana + Prometheus
• Datadog
• Simple: Log to file + grep
Set up alerts for:
• Bot offline
• Error spike
• Cost threshold exceeded
Final project: Deploy your own AI agent that runs on Telegram.
Project: Personal Assistant
Build an agent that:
• Responds to your messages
• Remembers context
• Has at least 2 tools/skills
• Is properly secured
Example features:
• Weather checks
• TON balance monitoring
• Daily briefings
• Web search
• Calendar reminders
Choose OpenClaw for quick deploy, or Claude Code for interactive dev.
Launch Checklist
Critical💡 Why This Matters
Don't ship without checking these.
Before launch:
☐ Bot token secured (not in code)
☐ API keys in environment variables
☐ Rate limiting implemented
☐ Error handling complete
☐ Tested with edge cases
☐ Access restricted (pairing/allowlist)
☐ Backup plan for downtime
After launch:
☐ Monitor first 24 hours
☐ Check costs/usage
☐ Gather feedback
☐ Iterate and improve!
What's Next?
Congratulations! 🎉
You've built and deployed an AI agent on Telegram.
Level up:
• Add more tools/skills
• Build Mini Apps (TMAs)
• Create multi-agent systems
• Monetize your agent
• Contribute to the ecosystem
Resources:
• OpenClaw docs: docs.openclaw.ai
• Claude docs: docs.anthropic.com
• Telegram Bot API: core.telegram.org
• Skills: clawhub.com
Share your agent with us! 🦞
🔐 Agent Security Checklist
Complete before deploying any agent to production.
🚩 Common Agent Pitfalls
⚠️Committing API keys to public repos
⚠️No rate limiting = runaway API costs
⚠️Storing conversation history forever
⚠️Not handling Telegram API errors
⚠️Trusting user input without validation
⚠️Large hot wallet balances
📚 Sources & Resources
Official documentation — verify everything and DYOR!
🟣 Claude Code
🔵 OpenClaw
🛠️ Tools & Frameworks
⚠️ Always verify commands and instructions against official sources before running them.