DEV Community: sir'Alexander

Why Your OpenClaw Telegram Bot Goes Silent

sir'Alexander — Tue, 12 May 2026 09:21:48 +0000

The silent failures, the two-switch approval trap, and the config gaps that kept adding sessions.

TL;DR: The OpenClaw Telegram integration guide gives you five steps. They work. What they skip: groupPolicy: "allowlist" is the right setting for group chat access, but it needs a companion — groupAllowFrom, the actual sender allowlist. groupAllowFrom takes your numeric Telegram user ID, which the app never shows you. If groupAllowFrom is absent, OpenClaw falls back to allowFrom. If that is also empty, nobody can invoke the agent in groups — silently, with no error. The exec approval system is the other trap: it has two independent layers. I disabled the first and was still getting prompts. The fix is two steps, not one. None of this is documented in the setup guide. Correct config is in the second section.

I followed the Telegram integration guide for OpenClaw and connected the bot. Five steps, they worked. What the guide did not prepare me for: config keys with undocumented dependencies, an approval system with two independent layers that need to be disabled separately, and a config file that gives you near-zero diagnostic output when it breaks.

Each one cost a session I had not planned for.

The Five Steps

The guide covers getting the bot connected. Here is the sequence.

BotFather on Telegram — send /newbot, give it a name and a username, and BotFather hands you a token. Add it to ~/.openclaw/openclaw.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing"
    }
  }
}

Pair your account: send /start to the bot in Telegram. Then approve the pairing from the CLI:

openclaw pairing list telegram
openclaw pairing approve telegram <CODE> --notify

Replace <CODE> with the code shown by pairing list. The --notify flag sends a confirmation back to you in Telegram. Once approved, messages you send to the bot route to your agent.

On the happy path — one user, direct messages, default config — this works. The gateway starts. The agent responds. The guide delivered.

What the guide did not give you:

groupPolicy: "allowlist" — the default setting, but requires groupAllowFrom (or allowFrom) to have your user ID before it does anything
groupAllowFrom — the sender allowlist; takes a numeric user ID the app never shows you; if absent, falls back to allowFrom; if both are empty, fails silently
execApprovals — two independent systems; disabling only the first leaves the second still prompting
Config file integrity — the gateway fails to start with near-zero diagnostic output if openclaw.json is structurally broken
Schema migration — openclaw doctor --fix is a migration tool you have to know to run

Each of those is a session I did not expect to spend.

The Correct Config — Before the Story

If you just need the answer, here it is.

In ~/.openclaw/openclaw.json:

"channels": {
  "telegram": {
    "botToken": "YOUR_BOT_TOKEN",
    "groupPolicy": "allowlist",
    "groupAllowFrom": ["YOUR_NUMERIC_TELEGRAM_USER_ID"],
    "execApprovals": {
      "enabled": false
    },
    "streaming": {
      "mode": "partial"
    }
  }
}

In ~/.openclaw/exec-approvals.json (separate file — System 2):

{
  "version": 1,
  "defaults": {
    "security": "full",
    "ask": "off",
    "askFallback": "full"
  }
}

One sentence per key:

botToken: your BotFather token — required, you have this already
groupPolicy: controls who can invoke the agent in group chats — "allowlist" is correct; requires groupAllowFrom or allowFrom to contain your numeric user ID
groupAllowFrom: the sender allowlist — your numeric Telegram user ID (not your @username); if absent, OpenClaw falls back to allowFrom
execApprovals.enabled: false: disables channel-level approval prompts — System 1 of two
defaults.security: "full" / ask: "off" / askFallback: "full" in exec-approvals.json: disables the host exec policy — System 2 of two
streaming.mode: "partial": object form; run openclaw doctor --fix if you have the older streaming: "partial" scalar

Here is what each of those actually means.

The Keys, and What Happens Without Them

None of these are in the setup guide, the README, or the standard integration walkthrough. A fresh install will not warn you they are missing. You find them when something stops working — or when something is not working and you cannot tell why.

groupPolicy and groupAllowFrom — the policy needs a list

groupPolicy: "allowlist" is correct. It is also the default. What the guide does not explain is that this key needs a populated allowlist to do anything. "allowlist" means: only users on the allowlist may invoke the agent in group chats. The allowlist is groupAllowFrom. If groupAllowFrom is absent, OpenClaw falls back to allowFrom for group sender authorization. If neither contains your numeric user ID, nobody can invoke the agent in groups — including you — with no error and no log entry.

The guide shows the lock. It does not mention the key.

groupAllowFrom takes an array of numeric Telegram user IDs. Not @usernames — numeric IDs. A long integer Telegram assigns internally to every account. It does not appear in the app's profile screen, settings, or any menu.

Two ways to get it:

Via gateway logs — send a message to your bot while running openclaw logs --follow. The log output includes from.id for each inbound message. That is your numeric ID. This works if your gateway is already running.
Via the Bot API — works from any state, as long as the bot has received at least one message:

   curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates"

The response includes message.from.id.

Once you have the number, put it in groupAllowFrom. A wrong value fails silently — the agent stops responding in group chats with no error and no log entry. If groupAllowFrom is absent, OpenClaw falls back to allowFrom; if that is also missing or wrong, same silent failure.

execApprovals — two switches, not one

This was the one I expected to solve in a single config change. It took two.

OpenClaw has two independent exec approval systems. Disabling only the first left the second still prompting.

System 1 — channels.telegram.execApprovals in openclaw.json

Controls channel-level approval prompts — the ones triggered when you send a message via Telegram or the web UI. Auto-enables when approvers are resolvable.

What that means in practice: the agent wants to open a browser — Approve? Navigate to a URL — Approve? Read the page — Approve? Run a command — Approve? Not once per task — once per step.

Ask the agent to summarize a webpage: approve the browser open, approve the navigation, approve the DOM read, potentially approve a redirect. Four approvals for thirty seconds of actual work.

Fix: set execApprovals.enabled: false in openclaw.json under channels.telegram.

System 2 — ~/.openclaw/exec-approvals.json

A separate file-based policy system. Its own file, its own config, completely independent of openclaw.json. When the file does not exist, the system defers to the tools.exec.* settings in openclaw.json. If those are also unset, the stricter of the two wins — which means you can still get prompted even after disabling System 1.

For a single-user personal setup, set it to allow everything and ask nothing:

{
  "version": 1,
  "defaults": {
    "security": "full",
    "ask": "off",
    "askFallback": "full"
  }
}

Note: security: "full" is counterintuitive — it means all commands are permitted and the allowlist is bypassed entirely. It is the permissive setting, not the restrictive one. askFallback: "full" covers the case where no UI is available; without it, the default is deny.

If the file does not exist, create it at ~/.openclaw/exec-approvals.json with that content. If it already exists, update the defaults block. Restart the gateway.

YOLO mode also requires the gateway-side policy to match. The cleanest way to set both layers at once:

openclaw exec-policy preset yolo

Or manually: openclaw config set tools.exec.security full and openclaw config set tools.exec.ask off.

After both layers are aligned: no approval prompts. If you ever open access to other users, re-enable both.

The Sessions I Didn't Plan For

Even with the config keys right, two incidents added sessions I hadn't budgeted for.

The AI wrote a config line outside the config file

Early in testing, the gateway entered a crash-loop that lasted three days. No response to messages. The logs offered almost nothing — the failure was happening before the gateway could initialise.

Opening ~/.openclaw/openclaw.json showed the problem. A groupAllowFrom value had been written as a bare property assignment after the closing } of the JSON5 file:

channels.telegram.groupAllowFrom = ["<user-id>"]

Invalid JSON5. The gateway cannot parse the file on startup, so it cannot start.

Fix: delete everything after the final }, re-add the value correctly inside the channels.telegram block. Before restarting, run the doctor to confirm the config is valid:

openclaw doctor

If it reports no errors, restart the gateway.

This is a different failure from the hallucinated config keys in my first post on this setup — there the AI added invented keys inside a structurally valid file; here it wrote a syntactically invalid line outside the file entirely. Same class of problem, different location. Lesson either way: after any AI-assisted config edit, run openclaw doctor before restarting.

The schema migration

A openclaw doctor run during a config hardening session flagged a format change:

Before: streaming: "partial"

After:

streaming: { mode: "partial" }

Fix: openclaw doctor --fix migrated it in-place. Restart.

openclaw doctor --fix is a migration tool, not just a health check. If your config has drifted across versions, it catches and repairs format changes in one command. Run it after upgrades.

What It Becomes

After the config keys. After the two-system approval fix. After the schema migration. Telegram works — fully works.

And then Whisper.

OpenClaw routes incoming Telegram voice messages through a local Whisper server and passes the transcription to the agent as text, as if you had typed it. Three things make this work once Telegram is stable:

faster-whisper-server running locally: CPU inference, base model, port 8765
Two env vars in the gateway's systemd environment: OPENAI_BASE_URL=http://127.0.0.1:8765/v1 and OPENAI_API_KEY=local
One non-obvious requirement: the openai-whisper-api skill defaults to response_format=text in its transcribe.sh. Local Whisper servers require response_format=json — the text format fails silently. The gateway drops the voice message with no error, no log entry, no indication anything arrived. If voice messages are sending but nothing is responding, that value is the first thing to check. Editing it in the skill file is reset on upgrade, which is why the full installation walkthrough is in a dedicated video and follow-up post in this series.

With that in place: you record a voice note on your phone. Send it. The local Whisper instance transcribes it on your server — no cloud service involved. The agent responds to what you said out loud.

You are not at a keyboard. You are walking, in another room, hands full. You ask a question and your agent answers it.

That is what changes when Telegram is fully and correctly configured. The interface disappears. The phone becomes a terminal that listens.

Everything in this post — the config keys, the two approval systems, the schema migration — is the cost of admission to that experience. It is worth paying.

What I'd Do Differently From the Start

If I were setting this up again today, here is what I would do in the first ten minutes instead of discovering it across multiple sessions:

Set groupAllowFrom (or allowFrom) alongside groupPolicy: "allowlist" — not the policy alone. Get your numeric Telegram user ID first via the gateway logs or the Bot API (both methods are in The Keys, and What Happens Without Them above), then put the number in groupAllowFrom. The policy without a populated allowlist — and with allowFrom also empty — silently locks everyone out of groups, including you.
Disable both exec approval systems, not just one. System 1: channels.telegram.execApprovals.enabled: false in openclaw.json. System 2: ~/.openclaw/exec-approvals.json with defaults.security: "full", ask: "off", and askFallback: "full" — plus the gateway-side policy (openclaw exec-policy preset yolo sets both at once). Disabling only the first leaves the second still prompting. The session that revealed this was not short.
Run openclaw doctor after every AI-assisted config edit. The AI will write outside the JSON5 structure at some point. openclaw doctor catches config problems before they become a gateway that refuses to start with no useful explanation.
Run openclaw doctor after every upgrade. It is a migration tool. If your config has drifted across versions, --fix catches and repairs it in one command.

One open item: live Telegram-path verification on the 2026.4.21 runtime is still pending. The integration was confirmed working on the version before that upgrade. I will update this post when that test is complete.

If groupAllowFrom was your silent failure — or if you hit the two-system exec approval problem and only found one of the fixes — drop a comment. I want to know what the guides are missing.

Tags: AI, Self-Hosting, DevOps, Telegram, Software Engineering

From Broken Docker Containers to a Working AI Agent: The Full OpenClaw Journey

sir'Alexander — Sun, 05 Apr 2026 15:53:27 +0000

Every blocker, every fix, and why bare metal is the sweet spot for a personal AI agent setup.

TL;DR: I spent several weeks self-hosting OpenClaw on a Hetzner VPS. The setup involved more blockers than I expected — a 3-day crash loop caused by a model hallucinating its own config, a Docker isolation wall that prevented the agent from using any tools I didn't bake into the image at build time, and a browser control problem I had completely misunderstood. I migrated to bare metal. Everything works now. Here's the full story with every exact fix.

What is OpenClaw and why did I want it?

OpenClaw is an open-source AI agent gateway. You connect it to Telegram (or a web chat), point it at a model, and you get a personal AI agent that can browse the web, read files, run code, and respond to messages. The selling point is control: you pick the model, you own the server, you pay for it if you want or run it for free with community models.

I wanted a personal AI agent that could take real actions — not just answer questions. One I could message from my phone and have it actually do things. A Hetzner 4GB VPS at around €5/month seemed like the right place to start.

Here is what actually happened.

Part 1: Getting Docker running (it took longer than it should have)

The official setup uses Docker. You clone the repo, configure a .env file, and run a setup script. Straightforward in theory.

Blocker 1: Cannot find package 'nostr-tools'

The first time I ran the gateway, it crashed immediately with this:

Error: Cannot find package 'nostr-tools'

After digging into the repo, the root cause was simple: the Docker image needs to be built with the nostr extension included, and if you don't pass it explicitly, the build skips it.

Fix: add this to docker-compose.yml under the build section:

build:
  args:
    OPENCLAW_EXTENSIONS: nostr

Then rebuild the image with docker compose build before running. That cleared it.

Blocker 2: The .env trap

The setup script uses an environment variable called OPENCLAW_IMAGE to know which Docker image to use. I had it set in my .env file. The script silently ignored it.

The fix is to export it in the shell before running the script:

export OPENCLAW_IMAGE=openclaw:local
./scripts/docker/setup.sh

Setting it in .env is not enough — the script doesn't source the file. This one cost me more time than it should have because there was no error, just the wrong image being used.

After both fixes: the gateway started, and /healthz returned {"ok":true}. First win.

Part 2: Browser control — I had the wrong mental model

I wanted the agent to be able to browse the web. OpenClaw supports browser control via Chrome DevTools Protocol. I installed Google Chrome on the VPS host, enabled browser control in the config, and expected it to work.

It didn't. The agent couldn't find the browser at all.

The problem was my mental model. The gateway runs inside a Docker container. The browser I installed is on the host. The container has no visibility into the host's binaries. The browser has to be inside the container.

The fix is to rebuild the image with Chromium and the required display server baked in:

export OPENCLAW_DOCKER_APT_PACKAGES="chromium xvfb xauth"
export OPENCLAW_IMAGE=openclaw:local
./scripts/docker/setup.sh

After the rebuild, openclaw browser open https://example.com worked. openclaw browser snapshot printed the page structure. Browser control was live.

Part 3: The 3-day crash loop (this one was subtle)

About three weeks in, the gateway started crash-looping. It would start, run for a few seconds, and crash. Every time.

I spent a while looking at the logs before I found the problem. Someone had appended a stray line after the closing } in openclaw.json, making the whole file invalid JSON5:

// end of the file, after the closing brace:
channels.telegram.groupAllowFrom = ["<your-telegram-id>"]

Stripping that line fixed the first crash. But the gateway crashed again.

This time, the config itself was valid JSON, but it contained these keys in the session block:

"session": {
  "dmScope": "per-channel-peer",
  "persistence": true,
  "autoSaveInterval": 300000
}

persistence and autoSaveInterval do not exist in the OpenClaw config schema. The gateway was rejecting them on startup.

I had not written those keys. The AI agent had. During a previous session, the agent had edited its own config file and invented plausible-sounding but completely invalid configuration.

Why this happened: the model quality problem

The default model in a fresh OpenClaw setup routes to openrouter/free. That endpoint cycles through whatever free models are available — often small ones with 4,000–8,000 token context windows. In a long enough session, the model loses context and starts guessing. It guessed config keys that sounded reasonable but didn't exist.

The fix was to upgrade the model before anything else.

I switched to Kimi K2.5 via Ollama's cloud model feature:

"agents": {
  "defaults": {
    "model": {
      "primary": "ollama/kimi-k2.5:cloud",
      "fallbacks": [
        "ollama/minimax-m2.5:cloud",
        "ollama/glm-5:cloud",
        "openrouter/free"
      ]
    }
  }
}

Kimi K2.5 is free, runs on Moonshot's infrastructure (no VPS RAM impact), and has a 131k token context window. The community consistently ranks it as the top free model for agentic tasks. The fabricated config problem disappeared.

The lesson here is uncomfortable: if your agent edits its own config and the model is bad enough, it will silently break itself. Model quality is not optional once you're running long agentic sessions.

Part 4: The moment Docker stopped being enough

After sorting the model, everything felt stable. Telegram was working. Browser control was working. Then I asked the agent to read a PDF.

pdftotext: command not found

I could install pdftotext on the host easily enough. But the agent can't see the host. It can't run apt-get install inside a running container. It can't reach the host filesystem outside the mounted volume.

This isn't a config problem. It's the design of Docker. Containers are isolated. That isolation is useful for security and repeatability, but it means the agent's tool access is fixed at image build time. Every new capability requires a full image rebuild.

For a personal AI agent — where the whole point is that it can do anything you'd do at a terminal — that's the wrong tradeoff.

Part 5: The bare metal migration

Once I understood the Docker wall as a structural constraint rather than a config problem, the migration decision was straightforward. OpenClaw supports npm install -g openclaw plus a systemd service on bare metal. The agent gets full host access.

Here's what the migration actually involved.

Step 1: Node.js 24

Ubuntu's default Node.js is outdated. Install via NodeSource:

curl -fsSL https://deb.nodesource.com/setup_24.x | bash -
apt-get install -y nodejs

Step 2: Google Chrome .deb — not the snap

The snap version of Chromium breaks under systemd. AppArmor blocks Chrome DevTools Protocol from binding. You need the .deb package from Google directly.

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
apt install ./google-chrome-stable_current_amd64.deb

Verify headless mode works:

google-chrome --headless --no-sandbox --dump-dom https://example.com

If that returns HTML, you're good.

Step 3: Install OpenClaw and update the config

npm install -g openclaw

Then update two values in openclaw.json:

// Change the Ollama URL from Docker bridge to localhost
"models": {
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434"
    }
  }
}

// Update workspace path from Docker container path to host path
"agents": {
  "defaults": {
    "workspace": "/home/<your-user>/.openclaw/workspace"
  }
}

Step 4: Stop Docker, start the systemd service

docker compose down
openclaw gateway install
openclaw gateway start

Check both health endpoints:

curl http://localhost:3000/healthz   # {"ok":true}
curl http://localhost:3000/readyz    # {"ready":true}

The Chrome lock file problem

First browser open attempt failed:

Failed to start Chrome CDP — profile appears to be in use by another process
(hostname: <docker-container-id>)

That hostname is the old Docker container. It had left lock files behind in the Chrome profile directory. Remove them:

rm ~/.openclaw/browser/openclaw/user-data/Singleton*

After that, openclaw browser open https://example.com succeeded. Browser control working on bare metal.

Step 5: Install the tools the agent actually needs

Now that the agent has host access, this is just a one-liner:

apt install poppler-utils  # pdftotext

No image rebuild. No container restart. The agent can now read PDFs.

Part 6: The verdict

After all of this, here's where I landed:

	Docker	Bare Metal
Agent tool access	Sealed — no installs at runtime	Full host access
Browser control	Chromium + Xvfb inside container	Headless Chrome `.deb` on host
Model quality	`openrouter/free` default — dangerous	Kimi K2.5 cloud — 131k context, free
RAM overhead	Higher	~1–1.5 GB idle
PDF / host tools	Blocked	Works natively
Update process	Rebuild image	`npm install -g openclaw`
Best for	Isolated multi-user setups	Single-user VPS — the sweet spot

Docker is not wrong. For multi-user setups or anything security-critical, the isolation it provides is valuable. But for a personal AI agent on a VPS you control, it's the wrong default. The agent's whole value is its ability to act. Sealing it in a container limits what it can act on.

Bare metal gives you a lighter setup, simpler operations, and a proper agent.

What I would do differently from the start

If I were starting over today, these are the things I'd do in the first ten minutes rather than discovering them the hard way:

Upgrade the model immediately. Before anything else. openrouter/free is dangerous for agents that modify their own state.
Use bare metal from day one if you're on a personal VPS and you're the only user. Docker adds overhead and constraints that don't pay off in this scenario.
Export environment variables in your shell, not just .env, when running setup scripts.
Use Google Chrome .deb, not the snap. AppArmor will kill you.
Keep the config minimal. If you're not sure a config key exists, don't add it. Let the agent work with valid defaults before customising.

Current state

The gateway has been running on bare metal for several weeks. Telegram is working. Browser control is working. The agent can read PDFs, run commands, and manage files. Kimi K2.5 hasn't hallucinated a single config key.

If you're running OpenClaw or thinking about it, drop a comment. I'm curious what setups others are running and whether the Docker-to-bare-metal migration pattern holds up across different VPS providers.

Tags: AI, Self-Hosting, DevOps, Docker, Software Engineering