Build a Telegram AI Bot with OpenClaw
Install OpenClaw, connect it to Telegram, and run your own 24/7 AI assistant.
Introduction
⚡️ 30 Second Summary
Set up an AI assistant that's always on, message it from your phone, and watch it actually get things done for you.
In this project, you will set up OpenClaw, a free, open-source AI agent, as your personal assistant. You'll connect it to Telegram for mobile access, lock it down so only you can use it, and keep the OpenClaw Gateway running in the background.
What You'll Build
You'll install and run OpenClaw on your machine, connect it to the Anthropic API, link a Telegram bot, and lock it down so only you can use it.
The Gateway is the hub: you send messages from Telegram or your browser, the Gateway forwards them to Claude, and routes the response back to you.
By the end of this project, you'll have:
- 🛠️ A locally-running OpenClaw assistant that's always on.
- 💬 A Telegram bot connected to your assistant for chatting from any device.
- 🔒 Allowlist security so only you can talk to your assistant.
- 💎 Secret Mission: Set up an automated check that runs every 10 minutes for proactive automation.
Want a complete demo of how to do this project, from start to finish? Check out our 🎬 walkthrough with Jon.
Do I need to pay to do this project?
OpenClaw is completely free and open source. This project uses Claude via the Anthropic API, which is pay-as-you-go (new accounts get $5 in free credits). Feel free to use whatever AI provider you have on hand.
Not sure if this project is right for you? Check if it matches your goals
If you're up for a bit of a challenge, quiz yourself on the key concepts up ahead in this project.
Set Up Your Environment
To build a personal assistant, the first thing is to install OpenClaw and get the OpenClaw Gateway running locally. The Gateway is what keeps your assistant alive in the background, ready to respond whenever you message it.
In this step, get ready to:
- Install or verify Node.js v22+.
- Install OpenClaw on your machine.
- Answer the installer prompt and verify the Gateway is running.
What is OpenClaw?
OpenClaw is an open-source AI assistant platform and one of the hottest repos on GitHub, with thousands of contributors making it more secure every day.
💡 Is it safe to run on my computer?
Yes! OpenClaw runs entirely on your local machine, so your conversations and data never leave your computer unless you choose to connect an external AI provider. The open-source community actively audits the codebase, and you can inspect every line yourself.
Install or Verify Node.js
OpenClaw requires Node.js version 22 or higher. Let's check if you already have it.
🍎 macOS
- Press ⌘ + Space to open Spotlight Search.
- Type Terminal and press Enter to open the Terminal app.
- Run the following command:
node --version
🖼️ Windows
- Press the Win key and type PowerShell.
- Run the following command:
node --version
Linux
- Open your terminal app.
- Run the following command:
node --version
- What do you see?
✔️ v22 or higher
You're all set. Continue to the next substep.
ⓧ Lower than v22 or not installed
You'll need to install or update Node.js.
- Go to nodejs.org.
- Download the LTS version (v22+).
- Run the installer and follow the prompts.
- Close and reopen your terminal.
- Verify with node --version.
Still stuck?
Get help with your error or share your error with the NextWork community!
Install OpenClaw
Now let's install OpenClaw itself. Time to get those claws. 🦞
🍎 macOS / Linux
- Run the following command in your terminal:
curl -fsSL https://openclaw.ai/install.sh | bash
What does curl ... | bash do?
This command downloads and runs a script in one step. Here's what each part does:
- curl downloads the install script from openclaw.ai.
- -fsSL tells curl to fail silently on errors, follow redirects, and show no progress bar.
- | bash pipes the downloaded script directly into your shell to execute it.
🖼️ Windows (WSL2)
OpenClaw requires WSL2 (Windows Subsystem for Linux) on Windows. Native Windows is not supported.
- Open PowerShell as administrator.
- Run the following command:
iwr -useb https://openclaw.ai/install.ps1 | iex
Don't have WSL2?
Install it first by running wsl --install in PowerShell as administrator, then restart your computer. After that, open your WSL2 terminal and use the macOS/Linux install command instead.
📣 Enable systemd in WSL2 (required)
OpenClaw's Gateway needs systemd to run as a background service. WSL2 doesn't enable it by default. In your WSL2 terminal, run:
sudo sh -c 'echo -e "[boot]\nsystemd=true" >> /etc/wsl.conf'
Then from PowerShell: wsl --shutdown. Reopen your WSL2 terminal before continuing.
- What do you see after the install finishes?
I see the Onboarding Wizard
Epic! Welcome to the OpenClaw Onboarding Wizard.
I see a big security message!
This is normal - OpenClaw shows this to every new user. It's reminding you that OpenClaw is a personal agent (designed for one trusted user, you!), and that if you ever enable tools or share it with others, you'd want to think carefully about access control. For now, you're just setting it up for yourself, so you're in good shape.
The Onboarding Wizard will ask you to make several choices. Here's what to select:
- When asked "I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?", use your arrow keys to select Yes.
What does this confirmation mean?
OpenClaw runs in personal-by-default mode unless you explicitly enable lockdown. Personal-by-default means OpenClaw's server is open to whoever can reach it, which is fine for a local machine where only you have access.
Shared/multi-user environments (like a team server) require lockdown to restrict who can connect. Confirming here just means you understand the distinction - you're not enabling anything risky, just acknowledging that you're running this locally for yourself and don't need lockdown.
- When asked "Select an onboarding mode", select QuickStart.
- When asked "Select your AI provider", select Anthropic.
- When asked "Select your Anthropic auth method", select Anthropic API key.
You'll need an Anthropic API key to continue. Let's get one now.
Get your Anthropic API key
- Go to console.anthropic.com in your browser.
- Create an account if you don't have one, or log in.
- Add a payment method under Billing (new accounts get $5 in free credits).
- From the Dashboard, click Get API Key.
- Click + Create key.
- Name your key something like nextwork-openclaw and click Add.
- Click Copy key to copy it to your clipboard. It starts with sk-ant- and you won't be able to see it again.
Set a monthly spending limit!
While you're in the Console, go to Settings > Billing > Usage limits and set a monthly cap. This protects you from unexpected charges if your assistant runs more than expected. A $10-20 limit is a good starting point for this project.
- Go back to the onboarding wizard terminal.
- Paste in your API key when prompted.
How much does this cost?
Anthropic charges per token (the units AI models use to process text). For this project, expect to spend a few dollars at most. The spending limit you just set ensures you'll never be surprised.
📣 Keep your API key secure!
Your key is stored locally in ~/.openclaw/credentials/. Never commit this directory to version control or share its contents publicly.
- When asked "Select your default AI model", select Claude Sonnet 4.5.
- Use your keyboard arrows to select, then Enter.
Why Sonnet?
Sonnet is faster and cheaper than Opus while still very capable. It's the best default for a personal assistant.
- When asked "Select channel", select Skip for now. Use the arrow keys to scroll down to find it.
- When asked "Select provider", select Skip for now. Use the arrow keys to scroll down to find it.
- When asked "Configure skills?", select No.
- When asked "Enable hooks?", select Skip for now.
- Use spacebar to select, then Enter.
Nothing happening when you press Enter?
Use spacebar to select or deselect an option, then press Enter to move to the next screen. If nothing happens when you press Enter, try spacebar first.
- When asked "How would you like to hatch your bot?", select Do this later.
The wizard may show additional prompts
If you see screens not listed above (API keys, additional channels, etc.), skip them. The wizard varies between OpenClaw versions.
💡 What's the Gateway install doing?
After the wizard screens, OpenClaw will install the Gateway as a background service on your machine. This is what keeps your assistant running 24/7. It may take 1-2 minutes to complete.
- If you see a security or network access prompt, select Allow. The Gateway needs permissions to run and communicate with the Anthropic API.
✔️ Onboarding complete
Wooho! Let's verify everything works.
ⓧ I exited or it crashed mid-way
If the wizard was interrupted (Ctrl+C, terminal closed, or a crash), don't worry. Re-running openclaw onboard is safe. It picks up where you left off and won't duplicate any configuration.
- Re-run the onboarding wizard:
openclaw onboard --install-daemon
The wizard detects existing settings and skips completed steps. You won't need to re-enter your API key unless the interruption happened before the authentication step completed.
What if I want a completely fresh start?
If something feels broken and you want to start over, remove the config and re-run the wizard:
rm -rf ~/.openclaw
openclaw onboard --install-daemon
This clears all settings, credentials, and channel configs. You'll need to re-authenticate and reconfigure Telegram.
🙋♀️ Still stuck?
Get help with your error or share your error with the NextWork community!
The Gateway opened in my browser
Some versions of OpenClaw skip the Onboarding Wizard and launch the Gateway directly in your browser. This means the installer auto-configured everything for you.
Why did it skip the wizard?
If OpenClaw detects existing credentials or a previous installation, it may skip the interactive onboarding and go straight to launching the Gateway. This is normal and means your setup is already complete.
You'll still need to configure your AI provider. Run the onboarding wizard manually to set up authentication:
openclaw onboard
- When asked "Select your AI provider", select Anthropic.
- When asked "Select your Anthropic auth method", select API key.
- You'll need an Anthropic API key. If you don't have one yet, go to console.anthropic.com, create an account, add a payment method, and create a key under Settings > API Keys.
- Paste your API key (starts with sk-ant-) when prompted.
Keep your API key secure!
Your key is stored locally in ~/.openclaw/credentials/. Never commit this directory to version control or share its contents publicly.
- For any remaining prompts (model, channel, provider, skills, hooks, hatch), select the defaults or Skip for now.
- Run the following command:
openclaw gateway status
- Do you see a status showing the Gateway is active and healthy?
✔️ Gateway is active
Your Gateway is running and ready to go. 🦞
What is the OpenClaw Gateway?
The Gateway is a background service that runs locally on your machine - it's what just installed during the wizard. It acts as the always-on engine for your assistant: it listens for incoming messages (from your browser or Telegram), forwards them to the Anthropic API, and returns Claude's responses back to you.
Unlike a chatbot you open in a browser tab, the Gateway keeps running in the background even when you close your terminal. That's what makes your assistant feel "always on." Every conversation you have passes through it.
ⓧ Gateway not running
If the Gateway isn't running, try these steps in order:
- Install the Gateway service:
openclaw gateway install
- Start the Gateway:
openclaw gateway start
No browser window?
This command starts the Gateway service in the background. It won't open a browser window. You'll see a confirmation message in the terminal. Use openclaw gateway status to verify it's running.
Port 18789 already in use?
If the Gateway fails to start because the port is busy, another process is using it. Find out what's running on that port:
🍎 macOS / Linux
lsof -i :18789
This shows the process using port 18789. Note the PID (process ID) and kill it:
kill <PID>
Then try starting the Gateway again: openclaw gateway start.
🖼️ Windows
netstat -ano | findstr :18789
Note the PID in the last column, then stop the process:
taskkill /PID <PID> /F
Then try starting the Gateway again: openclaw gateway start.
- If issues persist, run the diagnostic tool:
openclaw doctor
- If the diagnostic tool finds issues, run it with the --fix flag to automatically apply fixes:
openclaw doctor --fix
Still stuck?
Get help with your error or share your error with the NextWork community!
With the Gateway running, your AI assistant is alive and waiting. Next up, you'll have your first conversation with it.
Meet Your AI Assistant
You've installed OpenClaw and the Gateway is running in the background. The next thing we need to do is actually talk to your assistant and see what it can do. OpenClaw comes with a built-in Control UI that you can open right in your browser.
But how do you actually send it a message? And what happens behind the scenes when you do?
In this step, get ready to:
- Open the Control UI in your browser.
- Have your first conversation with your assistant.
- Check your usage and costs with /status.
Open the Control UI
The Control UI is a web-based chat interface that connects directly to your local Gateway. Think of it as a private ChatGPT that runs entirely on your machine.
- Run the following command:
openclaw dashboard
- Did the Control UI open in your browser?
✔️ Control UI loaded
Great! You can see the OpenClaw dashboard with a chat interface. Continue below.
ⓧ Page won't load or shows error
If the Control UI shows a blank page, a "disconnected" error, or won't load at all:
"disconnected (1008): pairing required"
This is the most common Control UI error. The Gateway needs to approve your browser as a trusted device.
- Check for pending device pairings and approve them:
openclaw devices list
openclaw devices approve <requestId>
- Refresh the Control UI page after approving.
Blank page or "disconnected (1008)" (other causes)
If the pairing is already approved but you still see a disconnect:
- Check the Gateway status:
openclaw gateway status
- If it shows authentication issues, re-authenticate:
openclaw onboard
- Restart the Gateway after re-authenticating:
openclaw gateway restart
"Connection refused" or page doesn't load
The Gateway may not be running, or another service is using port 18789.
- Start the Gateway: openclaw gateway start.
- If that fails, check if another process is using the port:
lsof -i :18789
- Kill the conflicting process, or check the port conflict troubleshooting section above.
Run diagnostics
openclaw doctor
If issues are found, apply automatic fixes:
openclaw doctor --fix
Still stuck?
Get help with your error or share your error with the NextWork community!
Have Your First Conversation
- Type a message in the chat box. Try something like:
Hello! Can you introduce yourself and tell me what you can do?
Your assistant will respond with information about itself and its available tools.
What's happening behind the scenes?
When you type a message in the Control UI, it goes to your local Gateway (running on port 18789). The Gateway then sends your message to the Anthropic API, receives the response, and displays it back to you. Your messages pass through your own machine first, giving you control over what gets sent.
✔️ Assistant responded
Great, your assistant is working. Continue below.
ⓧ I see an error
If you see an error or the assistant doesn't respond, check for these common issues:
Authentication error (most common)
If you see a message containing authentication_error or invalid bearer token:
- Re-run the onboarding wizard to re-authenticate with your Claude account:
openclaw onboard
- Select Anthropic as your provider and sign in again through the browser.
- Restart the Gateway (this also clears any cooldown state from previous auth failures):
openclaw gateway restart
Double-check your API key
Make sure your key starts with sk-ant- and that you've added a payment method in console.anthropic.com. If you just created your account, billing must be active before API requests will work.
No response at all
If the chat just hangs with no reply and no error message:
- Check the Gateway is running: openclaw gateway status
- If it's not running, start it: openclaw gateway start
- Start a new session in the Control UI and try again.
Something else?
- Run the diagnostic tool to check your setup:
openclaw doctor
- If issues are found, run openclaw doctor --fix to automatically apply fixes.
- Follow any remaining suggestions in the output.
Still stuck?
Get help with your error or share your error with the NextWork community!
- Ask your assistant to list its available tools:
What tools do you have available right now?
This shows you the AgentSkills your assistant has access to. These are the actions it can perform on your behalf.
Check Your Usage
Every message you send uses tokens from your Anthropic API credits. Let's check your current usage.
- Type the following command in the chat:
/status
This shows your current session info, including the model being used and token usage. Not sure what the other status fields show?
What are tokens?
Tokens are the units that AI models use to measure text. Roughly, 1 token equals about 4 characters or 0.75 words. The more you chat, the more tokens you use from your API credits. The /status command helps you keep track of your usage.
Your assistant is working. The claw is alive! 🦞 But right now you can only talk to it from this browser window. Next, let's connect it to Telegram so you can message it from your phone.
Connect Telegram
You've chatted with your assistant through the browser, which is great for testing. But the real power of OpenClaw is being able to message your assistant from anywhere, at any time. To do that, we're going to connect it to Telegram.
But wait. How does a messaging app even connect to software running on your machine?
In this step, get ready to:
- Create a Telegram bot using @BotFather.
- Add the bot token to your OpenClaw configuration.
- Test your assistant responds through Telegram.
You'll need a Telegram account
If you don't have Telegram yet, download it from telegram.org or your device's app store. Open the app, verify your phone number, and you're ready to go. Once you're logged in, continue with the steps below.
Create a Telegram Bot
Telegram bots are special accounts that are controlled by software rather than a person. You'll create one using Telegram's built-in bot creation tool called @BotFather.
- Open Telegram on your phone or desktop.
- Search for @BotFather and open a chat with it.
- Send the following message:
/newbot
- @BotFather will ask you for a name for your bot.
- Enter a display name like MyNextWorkClaw.
- Next, it will ask for a username. This must end in bot!
- Enter your chosen username: myassistantbot.
- @BotFather will respond with your bot token. It looks something like this:
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
- Copy your own token (not the one above!). You'll need it in the next substep.
Keep your bot token secret
Your bot token is like a password. Anyone who has it can control your bot. Never share it publicly or commit it to a git repository.
Configure OpenClaw for Telegram
Now you need to tell OpenClaw about your Telegram bot. Instead of manually editing config files, let's use your assistant to do it.
- In the Control UI, send the following message to your assistant. Replace YOUR_BOT_TOKEN with your actual bot token from @BotFather:
Here is my Telegram bot token: YOUR_BOT_TOKEN. Please add it to my OpenClaw configuration as a Telegram channel.
Want to verify the config?
You can ask your assistant: "Open my OpenClaw config file so I can see the Telegram settings."
- Restart the Gateway to pick up the new configuration:
openclaw gateway restart
Why is a restart required?
Whenever you make changes to your OpenClaw configuration, you'll need to restart the Gateway with openclaw gateway restart for the changes to take effect.
Test Your Telegram Bot
- Open Telegram on your phone.
- Search for your bot by the username you chose: myassistantbot.
- Send the following command:
/start
Your bot will respond with a pairing code and your Telegram user ID. This is the bot's way of verifying who you are before letting you chat.
- Enter your pairing code from Telegram: your pairing code from Telegram.
Save your Telegram user ID
The bot's response includes your numeric Telegram user ID (e.g., 1583504444). Copy it somewhere safe. You'll need it in Step 4 to lock down your bot.
- Go back to the Control UI in your browser.
- Tell your assistant to approve the pairing:
Approve the Telegram pairing. The pairing code is [[PAIRING_CODE="your pairing code from Telegram"]].
- Go back to Telegram and send a test message:
Hello! Are you working?
Your assistant should respond through Telegram. You're now chatting with your AI assistant from your phone. The claw reaches everywhere. 🦞
✔️ Bot responded
You're connected. Your assistant is now accessible from Telegram.
ⓧ No response
If your bot isn't responding, work through these common causes:
"access not configured" with a pairing code
You need to approve the pairing first. Go back to the Control UI and tell your assistant: "Approve the Telegram pairing. The code is [CODE]."
Pairing code expired
Pairing codes expire after a few minutes. If too much time has passed, send /start to your bot again to get a fresh pairing code, then approve the new code in the Control UI.
Gateway not running
- Check status: openclaw gateway status.
- If not running, start it: openclaw gateway start.
- Make sure you restarted after config changes: openclaw gateway restart.
Bot token is wrong
Verify the token in ~/.openclaw/openclaw.json matches the token @BotFather gave you exactly. A single missing character will cause silent failure.
"Network request failed" errors (IPv6 issue)
If you see errors like Network request failed (especially for deleteMyCommands or setMyCommands), this is a known Node.js 22 IPv6 compatibility issue. Fix it by adding a network setting to your Telegram channel config:
- Open ~/.openclaw/openclaw.json in your editor.
- Add "network": { "autoSelectFamily": false } inside your Telegram channel block:
{
"channels": {
"telegram": {
"botToken": "your-token",
"network": { "autoSelectFamily": false }
}
}
}
- Restart the Gateway: openclaw gateway restart.
Still stuck?
Get help with your error or share your error with the NextWork community!
Now you've got a remote control to your assistant, straight from your phone. But there's a problem. Right now, anyone who finds your bot username could start chatting with it and using your API credits. Let's fix that.
Lock Down Your Assistant
Your OpenClaw assistant is live on Telegram, which is amazing. But here's the issue: right now, any Telegram user who discovers your bot can send it messages and use your Anthropic API credits. We need to lock it down so only you can use it.
This step is about understanding the security model and making sure your assistant is safe to leave running 24/7.
In this step, get ready to:
- Find your Telegram user ID.
- Configure an allowlist so only you can use the bot.
- Verify your configuration is correct.
Find Your Telegram User ID
To restrict who can talk to your bot, you need your Telegram user ID.
Remember the Telegram user ID from the pairing response in Step 3? You'll use that now. If you didn't save it, ask your bot:
What is my Telegram user ID?
Your assistant will respond with your numeric user ID (e.g., 123456789).
- Copy this number. You'll need it next.
What's a Telegram user ID?
Every Telegram account has a unique numeric ID. Unlike your username (which you can change), your user ID is permanent. OpenClaw uses this ID to verify exactly who is sending messages to your bot.
Configure the Allowlist
Now let's update your OpenClaw configuration to only accept messages from your Telegram account. Once again, let your assistant handle the config change.
- Send your bot the following message in Telegram (replacing the placeholder with your actual user ID):
Add my Telegram user ID to the allowlist in my OpenClaw configuration so only I can message you.
- Restart the Gateway:
openclaw gateway restart
Now only messages from your Telegram account will be processed. Messages from anyone else will be shell-tered from your assistant. 🦞
What about your credentials?
Your API key is stored locally in ~/.openclaw/credentials/. Never commit this directory to a git repository or share its contents publicly. Anyone with your key could use your Anthropic API credits.
Verify Your Configuration
Let's confirm your security settings are in place by viewing the configuration file.
- Ask your assistant:
Open my OpenClaw configuration file so I can see my settings.
Your config file should show your Telegram bot token and your user ID in the allowFrom list. This confirms that only messages from your Telegram account will be processed.
- Run the diagnostic tool to verify everything is healthy:
openclaw doctor
Locked down. You have a fully configured, secure, 24/7 AI assistant running on your machine. Ready for the Secret Mission?
Secret mission
Your OpenClaw assistant is set up, secured, and accessible from Telegram. But right now it only responds when you message it. What if it could reach out to you?
In this secret mission, you'll configure a cron job that runs every 10 minutes, turning your assistant from a reactive chatbot into a proactive automation agent. This is the difference between a chatbot and an autonomous agent.
In this secret mission, get ready to:
- Ask your assistant to create an automated check that runs every 10 minutes.
- Verify the cron job with openclaw cron list.
- Customize the check and test it.
Set Up Automated Checks
Clean Up Your Resources
Clean Up Your Resources
Decide whether to keep your resources running, pause them to come back later, or delete them entirely.
Cost warning
Your OpenClaw Gateway uses Anthropic API credits each time you (or your cron jobs) send messages. Even if you don't finish the project today, come back to this section and review your options to avoid unexpected charges.
Resources you used:
- OpenClaw installation and Gateway
- Anthropic API key (in ~/.openclaw/credentials/)
- Telegram bot
- Cron jobs (if you completed the Secret Mission)
✔️ Keep everything running
No action needed. Let the claw roam free. 🦞 Choose this if you're still actively building or want to keep testing right away.
Your OpenClaw Gateway runs locally as a background service. The only ongoing cost is Anthropic API usage when you (or your cron jobs) send messages. There are no hosting fees.
✋ Pause - I'll come back to this later
Shut down running processes to free up memory, but keep all your files and data so you can pick up where you left off.
- Stop the Gateway:
openclaw gateway stop
- Your configuration and Telegram bot setup remain intact. Restart anytime with openclaw gateway start.
ⓧ Delete - I don't want to use this again
Remove all project resources and start fresh if you ever want to rebuild.
- Stop the Gateway:
openclaw gateway stop
- Remove OpenClaw:
npm uninstall -g openclaw
- Delete the configuration directory:
rm -rf ~/.openclaw
- Delete your Telegram bot via @BotFather: send /deletebot and select your bot.
Continuing with OpenClaw?
Keep OpenClaw installed for future projects.
That's a Wrap
That's a Wrap
Nice work! 🚀 You've just set up your own personal AI assistant with OpenClaw, connected it to Telegram, and secured it so only you can use it.
You've learned how to:
- 🛠️ Install OpenClaw and run the OpenClaw Gateway as a background service.
- 💬 Have conversations with your assistant through the Control UI.
- 📱 Connect a Telegram bot for mobile access from any device.
- 🔒 Secure your assistant with allowlists and verify your configuration.
- 💎 Set up cron jobs for proactive automation.
Congratulations!
You now have a 24/7 AI assistant running locally on your machine, accessible from your phone, and secured so only you can use it. Your assistant never sleeps.
Ready to quiz yourself? 💪
p.s. Does it say "Still tasks to complete!" at the bottom of the screen?
This means you still have screenshots left to upload, or questions left to answer!
- Press Ctrl+F (Windows) or Command+F (Mac) on your keyboard.
- Search for the text Return to later.
- Jump straight to your incomplete tasks!
- 🙋♀️ Still stuck? Ask the community!