Your application has crashed.
The terminal has responded with 47 lines of red text, three warnings you don’t understand, and one particularly helpful message:
Something went wrong.
You could paste the whole thing into five browser tabs.
Or you could send it to a Telegram bot that explains the error, suggests what to check next, and patiently waits for the command output.
In this tutorial, we’ll build exactly that.
Meet Debug Duck 🦆: a private AI assistant that lives in Telegram and helps you work through stack traces, logs, and mysterious server errors.
Unlike a regular rubber duck, this one answers back.
Occasionally, it may even be useful.
The setup is simple:
You
↓
Telegram
↓
OpenClaw running on a VPS
↓
Language model API
↓
A debugging answer in Telegram
You send the bot an error, log fragment, command output, or stack trace.
OpenClaw adds the system prompt and conversation history, sends the request to the selected language model, and returns the answer to Telegram.
By the end of the guide, your bot will be able to:
It will not automatically log in to your server and fix everything.
That feature is also known as “giving an AI agent root access and hoping for character development.”
Prepare the following:
OpenClaw itself is lightweight when it uses an external model API.
For a private bot, a small VPS with the following configuration is enough:
| Resource | Configuration |
|---|---|
| Operating system | Ubuntu 24.04 |
| CPU | 1 vCPU |
| RAM | 1 GB |
| Storage | 20 GB |
| Access | SSH key recommended |
This tutorial uses a Serverspace VPS, but the OpenClaw and Telegram steps are the same on any regular Ubuntu server.
Create an Ubuntu server and connect to it over SSH:
ssh root@YOUR_SERVER_IP
Replace YOUR_SERVER_IP
with the public IP address of your VPS.
Update the installed packages:
apt update && apt upgrade -y
The language model itself runs through an external API, so the VPS mainly handles:
Local inference with Ollama is a different story.
A server with 1 GB of RAM will look at a 7B model, sigh quietly, and refuse to participate.
Run the official installer:
curl -fsSL https://openclaw.ai/install.sh | bash
The installer detects the operating system, installs the required dependencies, and starts the onboarding process.
OpenClaw requires Node.js 22.14 or newer. Node.js 24 is recommended.
During onboarding:
After installation, check that the OpenClaw CLI is available:
openclaw --version
Run the built-in diagnostics:
openclaw doctor
Then check the gateway status:
openclaw gateway status
When openclaw doctor
reports no critical problems, the duck is alive.
It just doesn’t have a Telegram account yet.
Open Telegram and find the official ** @botfather** account.
Send the following command:
/newbot
BotFather will ask you for:
bot
.For example:
Display name: Debug Duck
Username: debug_duck_bot
Once the bot is created, BotFather will give you a token that looks like this:
123456789:AAExampleTokenThatShouldRemainSecret
Treat this token as a password.
Do not paste it into a public GitHub repository unless you enjoy emergency token rotation.
Open the OpenClaw configuration file:
nano ~/.openclaw/openclaw.json
Add the Telegram channel:
{
"channels": {
"telegram": {
"enabled": true,
"botToken": "YOUR_TELEGRAM_BOT_TOKEN",
"dmPolicy": "pairing",
"groups": {
"*": {
"requireMention": true
}
}
}
}
}
Replace YOUR_TELEGRAM_BOT_TOKEN
with the token received from BotFather.
Save the file and exit Nano:
Ctrl + O
Enter
Ctrl + X
The important option here is:
"dmPolicy": "pairing"
Pairing means that finding the bot’s username is not enough to start using it. A new user must be approved first.
This prevents a random stranger from discovering your bot and spending your API budget asking it to write a 12-volume fantasy series.
For a private bot, avoid an open direct-message policy with unrestricted access.
A generic AI assistant will answer almost anything.
That sounds useful until you send it a stack trace and receive a five-paragraph essay about the importance of software quality.
We need to give the assistant a much clearer job.
Add the following system prompt through the assistant or agent configuration created during OpenClaw onboarding:
You are Debug Duck, a patient debugging assistant for beginner developers.
When the user sends an error message, stack trace, log fragment, command output, or code:
1. Explain the problem in plain English.
2. Separate confirmed facts from likely causes.
3. Suggest no more than three diagnostic steps at a time.
4. Include exact commands when they are useful.
5. Explain briefly what each command checks.
6. Ask the user to send the result of the most important check.
7. Never recommend destructive commands without a clear warning.
8. Never present a likely cause as a confirmed fact.
9. Keep answers concise and easy to scan.
10. You may use one light joke, but never make fun of the user.
Do not rewrite the entire application unless the user explicitly asks.
Do not suggest deleting files, reinstalling the server, or disabling security controls as the first solution.
Avoid prompts like this:
You are a helpful assistant.
That gives the model roughly the same amount of direction as:
Just fix production.
The more specific the role, rules, and response format are, the more predictable the assistant becomes.
Start the OpenClaw gateway:
openclaw gateway
Now open your new bot in Telegram and send it a message:
Hello
Because we enabled pairing, the bot should not immediately accept the conversation.
Return to the server and list pending Telegram pairing requests:
openclaw pairing list telegram
Approve the displayed code:
openclaw pairing approve telegram YOUR_PAIRING_CODE
Replace YOUR_PAIRING_CODE
with the actual code shown by OpenClaw.
Pairing codes remain valid for one hour.
Now send another Telegram message:
Are you alive?
A good response would be:
Yes. Send me an error message, stack trace, or command output, and I’ll help you work through it.
A less useful response would be an existential discussion about whether software can truly be alive.
That may require another look at the system prompt.
Let’s test the bot with a few common errors.
Send the following error to the bot:
nginx: [emerg] bind() to 0.0.0.0:80 failed
(98: Address already in use)
Debug Duck should explain that another process is already listening on port 80 and suggest a diagnostic command such as:
sudo lsof -i :80
A good response might look like this:
Port 80 is already occupied. Nginx is trying to sit in a chair that someone else has taken.
Check which process is using the port:
sudo lsof -i :80
This command shows the process currently listening on port 80.
Likely causes:
1. Another Nginx instance is already running.
2. Apache is using the port.
3. A Docker container published port 80.
Send me the command output, and we’ll narrow it down.
The joke takes one sentence.
The diagnostic step remains the main point.
Send:
Error: Cannot find module 'express'
The assistant should explain that the dependency is missing from the current environment and suggest checking the project directory and installed packages:
pwd
npm list express
It should not immediately recommend:
node_modules
;Good debugging starts with checking what is actually happening.
Send:
No space left on device
The bot should begin with a safe diagnostic command:
df -h
It may then suggest checking which top-level directories consume the most disk space:
du -xhd1 / 2>/dev/null | sort -h
It should warn you before suggesting deletion.
“Disk full” is a diagnosis.
“Delete random things until the server boots” is a lifestyle choice.
The goal is not simply to make the bot respond.
A useful debugging assistant should:
For example, this is not a good answer:
Reinstall Nginx and restart the server.
The assistant has not checked:
A better answer starts with diagnosis.
Debug Duck should behave like a patient teammate, not like someone trying to close the ticket before lunch.
The bot has access to a paid language model API, so access control matters.
For a personal assistant, keep the pairing policy enabled.
Avoid this configuration:
{
"dmPolicy": "open",
"allowFrom": ["*"]
}
It allows anyone who discovers the username to use the bot.
You should also review logs and stack traces before sending them to an external language model.
They may contain:
Debug Duck is here to inspect errors, not quietly collect your entire infrastructure map.
Never store Telegram or model-provider tokens in a public repository.
At minimum:
.gitignore
.Restrict access to the OpenClaw configuration file:
chmod 600 ~/.openclaw/openclaw.json
If you accidentally push a token to GitHub, removing it from the latest commit is not enough.
The token may still exist in the repository history.
Revoke it and create a new one.
The internet has a remarkable ability to find leaked secrets approximately four seconds before you do.
OpenClaw can retain conversation context.
That allows the bot to follow a debugging session:
However, longer histories can increase API costs because previous messages may be included in later requests.
For a debugging assistant, keeping around 10–20 message exchanges is usually enough.
You rarely need the complete emotional history of your relationship with Nginx.
Set an appropriate history limit in the OpenClaw configuration supported by your version.
A debugging bot that disappears after every server restart creates a new debugging problem.
Install the OpenClaw gateway as a background service:
openclaw gateway install
You can also install it during onboarding:
openclaw onboard --install-daemon
On Linux, OpenClaw configures a systemd user service.
Check the gateway status:
openclaw gateway status
If the bot stops responding, start with:
openclaw doctor
openclaw gateway status
openclaw logs --follow
These commands can help determine whether the problem is:
Yes, eventually you may need to debug the debugging bot.
Every tool becomes infrastructure if you depend on it long enough.
Once the basic version works, adjust the system prompt for the technologies you use most often.
For example:
The user mainly works with:
- Ubuntu
- Nginx
- Docker Compose
- Node.js
- Express
- PostgreSQL
Prioritize diagnostic commands for this stack.
You can also require a fixed response format:
What the error means
What is confirmed
Most likely causes
Run this next
Send me this output
A predictable format makes answers easier to scan from a phone.
You can also create specialized versions of the bot.
Send it a description of your changes and receive something better than:
fix stuff final final
Send it chaotic notes from yesterday and get:
What I completed
What I’m working on
Current blockers
Send it a technical issue and receive two explanations:
Still, a read-only debugging assistant is a good first project.
Avoid giving the bot permission to execute arbitrary commands until you understand how the model behaves.
You now have a private Telegram bot that can:
It will not replace learning how your stack works.
It may still make mistakes, so review commands before running them.
But it can save you from opening twelve browser tabs just to discover that port 80 was occupied.
And unlike a real rubber duck, this one answers back.
Ready to build your own Debug Duck? 🦆
Deploy a small Ubuntu VPS on Serverspace and start with the first command.