Why Your OpenClaw Telegram Bot Goes Silent

OpenClaw Telegram Integration: Advanced Configuration and Silent Failure Resolution

Current Situation Analysis

The standard OpenClaw Telegram integration documentation provides a functional path for direct message interactions but omits critical configuration dependencies required for group chat access and production-grade stability. Developers frequently encounter silent failures where the gateway appears operational but rejects group invocations without logging errors, or experiences excessive approval friction that halts automated workflows.

The core issue stems from three undocumented behaviors in the configuration layer:

Implicit Allowlist Dependencies: The default groupPolicy: "allowlist" setting requires a populated sender list. Without explicit numeric user IDs, the gateway silently drops group messages.
Dual-Layer Approval Architecture: Execution approvals are governed by two independent configuration systems. Disabling one layer leaves the second active, resulting in unexpected prompts during agent operations.
Schema Drift and Integrity Risks: Configuration files are susceptible to structural corruption, particularly when modified by AI-assisted tools. Invalid JSON5 syntax causes immediate gateway startup failures with minimal diagnostic output.

These gaps force developers to spend unallocated debugging sessions resolving configuration state issues rather than focusing on agent logic. The problem is exacerbated by the lack of validation feedback; the system fails silently rather than reporting misconfiguration, making root cause analysis non-trivial.

WOW Moment: Key Findings

The following comparison illustrates the operational difference between a baseline configuration derived from standard setup guides and a production-hardened configuration that addresses silent failures and approval friction.

Configuration State	Group Chat Availability	Approval Friction	Startup Reliability
Baseline Guide Config	Blocked (Silent Drop)	High (4+ prompts per task)	Fragile (Crash on invalid JSON5)
Hardened Production Config	Authorized (Numeric ID)	Zero (Dual-layer disabled)	Robust (Doctor-validated schema)

Why this matters: The baseline configuration creates a false sense of functionality. Direct messages work, leading developers to assume the integration is complete. However, group chat access—a primary use case for collaborative agents—remains inaccessible due to the missing groupAllowFrom payload. Additionally, the dual-layer approval system introduces significant latency in automated workflows. Resolving these issues requires explicit configuration of numeric identifiers and synchronization of both approval subsystems, reducing operational friction and restoring expected group chat behavior.

Core Solution

This section outlines the technical implementation for a robust OpenClaw Telegram integration. The approach prioritizes explicit configuration, schema validation, and approval system alignment.

Step 1: Bot Provisioning and Token Retrieval

Initialize the Telegram bot via BotFather. Obtain the authentication token and store it securely. This token serves as the credential for the OpenClaw gateway to authenticate with the Telegram Bot API.

// Environment configuration for bot credentials
interface BotCredentials {
  tgApiToken: string;
  botUsername: string;
}

const credentials: BotCredentials = {
  tgApiToken: process.env.TG_BOT_AUTH_TOKEN || '',
  botUsername: 'your_agent_bot_username'
};

Step 2: Account Pairing Workflow

Establish the pairing between the Telegram user and the OpenClaw agent. This requires a two-step verification process involving the Telegram client and the CLI.

Initiate pairing by sending /start to the bot in Telegram.
Retrieve the pairing code via the CLI:
```
openclaw pairing list telegram
```

Approve the pairing and notify the user:

openclaw pairing approve telegram <AUTH_CODE> --notify

Replace <AUTH_CODE> with the identifier returned by the list command. The --notify flag ensures the Telegram client receives confirmation of successful pairing.

Step 3: Resolving Group Access via Numeric Identifiers

Group chat authorization relies on numeric Telegram User IDs, not usernames. The groupAllowFrom array must contain these identifiers to permit group invocations.

Retrieving the Numeric ID: Two methods are available for obtaining the numeric ID:

Method A: Bot API Query Query the Telegram Bot API for recent updates. The response includes the from.id field for inbound messages.

curl -s "https://api.telegram.org/bot${TG_BOT_AUTH_TOKEN}/getUpdates" | jq '.result[-1].message.from.id'

Method B: Gateway Log Inspection If the gateway is running, monitor logs while sending a test message. The output includes the sender ID.

openclaw logs --follow | grep "from.id"

Configuration Update: Populate the groupAllowFrom array with the retrieved numeric ID.

// Configuration builder for OpenClaw channels
class OpenClawConfigBuilder {
  private config: Record<string, any> = {
    channels: {
      telegram: {
        enabled: true,
        botToken: '',
        groupPolicy: 'allowlist',
        groupAllowFrom: [],
        execApprovals: { enabled: false },
        streaming: { mode: 'partial' }
      }
    }
  };

  setBotToken(token: string): this {
    this.config.channels.telegram.botToken = token;
    return this;
  }

  addAllowedGroupSender(numericId: string): this {
    this.config.channels.telegram.groupAllowFrom.push(numericId);
    return this;
  }

  build(): Record<string, any> {
    return this.config;
  }
}

// Usage example
const configBuilder = new OpenClawConfigBuilder()
  .setBotToken(credentials.tgApiToken)
  .addAllowedGroupSender('123456789012345'); // Numeric ID

const finalConfig = configBuilder.build();

Step 4: Neutralizing Dual-Layer Approval Friction

OpenClaw enforces execution approvals through two independent systems. Both must be configured to prevent workflow interruptions.

System 1: Channel-Level Configuration Located in ~/.openclaw/openclaw.json. This controls prompts triggered via Telegram or web UI channels.

{
  "channels": {
    "telegram": {
      "execApprovals": {
        "enabled": false
      }
    }
  }
}

System 2: Host-Level Policy File Located in ~/.openclaw/exec-approvals.json. This file-based policy operates independently of the channel configuration. If this file is absent or misconfigured, the system may default to restrictive behavior.

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

Critical Configuration Notes:

security: "full": Counterintuitively, this value permits all commands and bypasses allowlists. It is the permissive setting.
askFallback: "full": Ensures that in headless environments where no UI is available, commands are allowed rather than denied. The default fallback is deny, which can block operations in server contexts.

Automated Alignment: Use the CLI preset command to synchronize both layers simultaneously.

openclaw exec-policy preset yolo

This command updates both openclaw.json and exec-approvals.json to disable approval prompts, ensuring consistent behavior across all execution contexts.

Step 5: Schema Validation and Migration

Configuration files must adhere to the current schema version. Structural drift can cause gateway startup failures.

Validation: Run the diagnostic tool to check for syntax errors and schema compliance.

openclaw doctor

Migration: If the configuration uses deprecated formats, apply automatic migration.

openclaw doctor --fix

This command resolves schema changes, such as the migration of the streaming configuration from a scalar value to an object structure:

Deprecated: streaming: "partial" Current: streaming: { mode: "partial" }

Always run openclaw doctor --fix after upgrading OpenClaw versions to ensure configuration compatibility.

Pitfall Guide

Developers frequently encounter the following configuration errors. Each pitfall includes a detailed explanation and resolution strategy.

Pitfall Name	Explanation	Resolution
Username Trap	Using `@username` in `groupAllowFrom`. Telegram usernames are not valid for authorization; the system requires numeric IDs.	Retrieve the numeric ID via Bot API or logs and update `groupAllowFrom` with the integer value.
Approval Mirage	Disabling `execApprovals.enabled` in `openclaw.json` but neglecting `exec-approvals.json`. System 2 remains active, causing prompts.	Run `openclaw exec-policy preset yolo` or manually configure both files to disable approvals.
JSON5 Breach	AI tools writing configuration lines outside the JSON structure (e.g., `key = value` after closing brace). Gateway fails to parse and crashes.	Remove invalid lines outside the JSON object. Run `openclaw doctor` to validate syntax before restarting.
Security Semantics Error	Misinterpreting `security: "full"` as restrictive. This value actually enables permissive mode, allowing all commands.	Use `security: "full"` for unrestricted access. For restrictive policies, use `security: "strict"` with explicit allowlists.
Schema Drift	Using deprecated configuration formats (e.g., scalar `streaming`). Gateway may ignore settings or fail to start.	Run `openclaw doctor --fix` to migrate configuration to the current schema version.
Silent Group Lockout	Assuming the bot is offline when group messages fail. The issue is often an empty or incorrect `groupAllowFrom` array.	Verify `groupAllowFrom` contains the correct numeric ID. Check gateway logs for `from.id` mismatches.
Fallback Denial	Omitting `askFallback` in `exec-approvals.json`. In headless mode, missing UI causes commands to be denied by default.	Set `askFallback: "full"` in `exec-approvals.json` to allow commands when no UI is present.

Production Bundle

Action Checklist

Retrieve numeric Telegram User ID via Bot API or gateway logs.
Populate groupAllowFrom array with the numeric ID in openclaw.json.
Execute openclaw exec-policy preset yolo to disable dual-layer approvals.
Validate configuration syntax using openclaw doctor.
Apply schema migrations with openclaw doctor --fix.
Restart the OpenClaw gateway to apply changes.
Test group chat invocation to confirm access.
Verify approval prompts are disabled during agent operations.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Solo Development	YOLO preset + Numeric ID allowlist	Minimizes friction for personal workflows; enables rapid iteration.	Low (Reduced debugging time)
Team Collaboration	Allowlist policy + Approval enabled	Ensures security and accountability for shared agent access.	Medium (Increased operational overhead)
CI/CD Automation	Headless config + `askFallback: "full"`	Prevents blocking in automated pipelines where no UI is available.	Low (Enables automation reliability)
High-Security Env	Strict security + Explicit allowlists	Restricts command execution to approved operations only.	High (Requires careful policy management)

Configuration Template

Copy this template for a production-ready OpenClaw Telegram configuration. Replace placeholder values with your specific identifiers.

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

Host-Level Policy (~/.openclaw/exec-approvals.json):

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

Quick Start Guide

Provision Bot: Create a bot via BotFather and obtain the API token.
Get Numeric ID: Run curl "https://api.telegram.org/bot<TOKEN>/getUpdates" and extract from.id.
Apply Config: Update openclaw.json with the token and numeric ID. Run openclaw exec-policy preset yolo.
Validate: Execute openclaw doctor --fix to ensure schema compliance.
Launch: Restart the gateway and test group chat access.