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:

1. groupPolicy: "allowlist" — the default setting, but requires groupAllowFrom (or allowFrom) to have your user ID before it does anything
2. 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
3. execApprovals — two independent systems; disabling only the first leaves the second still prompting
4. Config file integrity — the gateway fails to start with near-zero diagnostic output if openclaw.json is structurally broken
5. 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:

1. 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.
2. 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:

1. 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.

2. 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.

3. 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.

4. 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