Core Failure Manifestations

On Windows 10 with OpenClaw v2026.3.13, the Telegram channel exhibits three distinct failure modes:

1. Message Routing Failure

Messages fail to traverse between webchat and Telegram with zero context sharing:

[USER via webchat]
> hello test

[GATEWAY LOG - No Telegram dispatch]
[GATEWAY LOG - No Telegram dispatch]
[Telegram Bot - No incoming message]

Expected output should show Telegram provider invocation:

[2026-03-15T10:23:41.123] [INFO] channels.telegram: Dispatching message to provider
[2026-03-15T10:23:41.125] [INFO] channels.telegram: Outgoing payload sent to api.telegram.org
[2026-03-15T10:23:42.456] [DEBUG] channels.telegram: Message delivered, chat_id=123456789

2. 401 Unauthorized Despite Valid Token

The Telegram provider returns authentication failures even when the bot token is confirmed valid via direct API calls:

[2026-03-15T10:24:11.789] [ERROR] channels.telegram: Provider request failed
[2026-03-15T10:24:11.791] [ERROR] channels.telegram: HTTP 401 Unauthorized
[2026-03-15T10:24:11.793] [ERROR] channels.telegram: Response body: {"ok":false,"error_code":401,"description":"Unauthorized"}

Direct curl verification confirms token validity:

C:\> curl -s "https://api.telegram.org/bot<TOKEN>/getMe"
{"ok":true,"result":{"id":1234567890,"is_bot":true,"first_name":"TestBot","username":"TestBotDev"}}

3. Persistent Sub-Agent Loops

Spawned persistent sessions enter infinite response loops, ignoring subagents kill commands:

[SESSION LOG - Loop detected]
[10:25:01] Agent: Persistent session test
[10:25:03] Agent: Persistent session test
[10:25:05] Agent: Persistent session test
[10:25:07] Agent: Persistent session test
...
[INFINITE LOOP - Kill commands ignored]

CLI attempts to terminate fail:

gateway> sessions_send target=persistent-telegram-session msg="KILL"
[10:25:30] [WARN] channels.telegram: Message queued, session busy
gateway> subagents kill telegram-0
[10:25:31] [ERROR] subagents.kill: Target not found or already terminated
[10:25:32] [INFO] channels.telegram: Agent: Persistent session test

4. Config Changes Not Persisting

Edits to config.yaml are ignored after gateway restart:

# config.yaml - Line removed:
# channels:
#   telegram:
#     enabled: true

[GATEWAY RESTART]

gateway> status
channels:
  telegram:
    enabled: true      # <-- STILL PRESENT DESPITE REMOVAL
    botToken: "****"
    mode: "session"

Architectural Analysis

The reported issues stem from three distinct but interconnected root causes:

1. Windows Path Resolution and Session File Locking

OpenClaw’s session persistence mechanism writes to %APPDATA%\openclaw\sessions</code> on Windows. The Telegram channel’s session mode relies on file-based state management that encounters race conditions during concurrent access:

C:\Users\<username>\AppData\Roaming\openclaw\sessions\
├── telegram-0.lock    # File lock prevents clean termination
├── telegram-0.state    # Corrupted state triggers loop
└── persistent-queue.db # SQLite WAL mode conflicts

The Windows filesystem denies delete operations on locked files, causing:

• Session state to persist across “kills”
• Config reload to read stale session metadata
• Loop-inducing state to accumulate

2. Token Validation Cache Mismatch

The Telegram provider implements a token validation cache at startup that stores the bot token hash. On Windows, this cache persists in memory across config reloads due to how the gateway handles hot-reload:

// Internal flow (simplified)
1. Gateway.start() reads config.yaml
2. TelegramProvider.init(token) caches token hash
3. User edits config.yaml (new token)
4. Gateway.reload() triggers partial config update
5. TelegramProvider still holds OLD token hash
6. Requests fail with 401 because cached hash != actual token

The 401 Unauthorized occurs because:

• The API endpoint requires exact token match
• Cached validation considers token “valid” for getMe
• Actual message dispatch uses stale token reference

3. Session Registry Desynchronization

The subagents subsystem maintains a separate registry from the main session manager. On Windows, this registry persists in %LOCALAPPDATA%\openclaw\subagents</code> and becomes desynchronized:

# subagents registry (stale entry)
{
  "id": "telegram-0",
  "status": "running",
  "pid": 12345,
  "lastHeartbeat": "2026-03-15T10:20:00Z"
}

# Actual process state (terminated at 10:23)
{
  "pid": null,
  "status": "dead"
}

This desynchronization causes:

• Kill commands to target non-existent entries
• New sessions to reuse stale identifiers
• Loop agents to spawn with corrupted parent references

4. Config Hot-Reload Partial Failure

The gateway’s configuration merge strategy on Windows fails to properly handle removed sections:

// Config merge algorithm (buggy behavior)
function mergeConfig(base, overlay):
  if overlay[key] is null or undefined:
    base[key] = overlay[key]  // Correct: removes key
  else if isObject(overlay[key]):
    mergeConfig(base[key], overlay[key])  // Correct: recurses
  else:
    base[key] = overlay[key]  // Correct: updates value

// Windows-specific issue: Overlay not properly nulled
// Result: channels.telegram remains in effective config

The YAML parser on Windows with certain Node.js versions fails to distinguish between:

• Key explicitly set to null
• Key omitted entirely
• Key with ~ YAML null marker

Phase 1: Clean Session State

Terminate all running processes and clear corrupted session files:

# Step 1.1: Stop the gateway gracefully
gateway> shutdown
[2026-03-15T10:30:00] [INFO] Gateway shutdown initiated
[2026-03-15T10:30:01] [INFO] All channels disconnected
[2026-03-15T10:30:02] [INFO] Gateway stopped

# Step 1.2: Kill any orphaned sub-agents via Task Manager or CLI
gateway> subagents kill --all
[2026-03-15T10:30:05] [INFO] Killed 3 sub-agent processes

# Step 1.3: Delete session files (requires admin if locked)
C:\> rmdir /s /q "%APPDATA%\openclaw\sessions"
C:\> rmdir /s /q "%LOCALAPPDATA%\openclaw\subagents"

# Step 1.4: Verify deletion
C:\> dir "%APPDATA%\openclaw\sessions"
File Not Found

# Step 1.5: Restart gateway with fresh state
C:\> openclaw gateway start --clean

Phase 2: Validate Telegram Token Configuration

# Step 2.1: Create clean config section (config.yaml)
# BEFORE (problematic):
channels:
  telegram:
    enabled: true
    botToken: "old-token-123"
    mode: "webhook"
    dmPolicy: "closed"

# AFTER (corrected):
channels:
  telegram:
    enabled: true
    botToken: "valid-bot-token-from-botfather"
    mode: "polling"      # Use polling on Windows to avoid webhook SSL issues
    dmPolicy: "open"
    thread: false        # Disable threading on first run
    sessionDir: "C:/Users//AppData/Roaming/openclaw/sessions-telegram"

Phase 3: Full Gateway Restart (Not Hot-Reload)

# Step 3.1: Complete process termination
# Open Task Manager, end all openclaw.exe processes

# Step 3.2: Clear Windows-specific temp state
C:\> del /q "%TEMP%\openclaw-*"

# Step 3.3: Start fresh gateway instance
C:\> openclaw gateway start --config="C:\path\to\config.yaml"

# Step 3.4: Verify clean initialization
gateway> status
[2026-03-15T10:35:00] [INFO] Gateway v2026.3.13 initialized
[2026-03-15T10:35:01] [INFO] channels.telegram: Connecting via polling...
[2026-03-15T10:35:02] [INFO] channels.telegram: Bot @YourBotDev verified
[2026-03-15T10:35:03] [INFO] channels.telegram: Waiting for messages...

Phase 4: Test Message Routing

# Step 4.1: Send test from Telegram (direct bot interaction)
# Send /start to your bot from Telegram app

# Step 4.2: Verify in gateway logs
[2026-03-15T10:36:01] [INFO] channels.telegram: Incoming message from chat_id=123456789
[2026-03-15T10:36:01] [DEBUG] channels.telegram: Creating session for chat_id=123456789

# Step 4.3: Reply test
gateway> sessions_send target=chat:123456789 msg="test reply"
[2026-03-15T10:36:05] [INFO] channels.telegram: Outgoing message sent
[2026-03-15T10:36:05] [DEBUG] channels.telegram: Delivered to chat_id=123456789

Test Suite for Telegram Channel Health

Execute these verification steps in sequence:

Test 1: Bot Authentication

gateway> channels telegram verify
[2026-03-15T10:40:00] [INFO] channels.telegram: Verifying bot credentials...
[2026-03-15T10:40:01] [INFO] channels.telegram: Bot verified: @YourBotDev
[2026-03-15T10:40:01] [INFO] channels.telegram: API access: OK
[SUCCESS] Exit code: 0

Test 2: Inbound Message Reception

# From Telegram app, send: "verify inbound"
gateway> logs --follow --filter=telegram

# Expected output:
[2026-03-15T10:41:05] [INFO] channels.telegram: Message received
[2026-03-15T10:41:05] [DEBUG] channels.telegram: update_id=123456789, text="verify inbound"
[2026-03-15T10:41:05] [INFO] channels.telegram: Session matched: chat_id=123456789
[SUCCESS] Message logged within 5 seconds

Test 3: Outbound Message Dispatch

gateway> channels telegram send --chat-id=123456789 --text="outbound verification"
[2026-03-15T10:42:00] [INFO] channels.telegram: Sending message...
[2026-03-15T10:42:01] [INFO] channels.telegram: Message sent, message_id=999
[2026-03-15T10:42:01] [SUCCESS] Exit code: 0

# Verify message appears in Telegram within 10 seconds

Test 4: Config Change Persistence

# Step 4.1: Modify dmPolicy
gateway> config set channels.telegram.dmPolicy=closed
[2026-03-15T10:43:00] [INFO] Config updated in memory

# Step 4.2: Restart gateway (NOT hot-reload)
gateway> shutdown
# [Restart gateway]

gateway> config get channels.telegram.dmPolicy
closed
[SUCCESS] Config persisted correctly

Test 5: Session Loop Prevention

# Step 5.1: Create a persistent session with strict limits
gateway> sessions_create --channel=telegram --mode=persistent --max-turns=5

# Step 5.2: Send messages
gateway> sessions_send target=telegram-persistent-0 msg="hello"
[2026-03-15T10:44:01] [INFO] Agent response: Hello!
[2026-03-15T10:44:02] [INFO] Turn 1/5

# Step 5.3: Send 4 more messages
gateway> sessions_send target=telegram-persistent-0 msg="continue"
# [3 more successful turns]

# Step 5.4: Verify auto-termination
gateway> sessions_send target=telegram-persistent-0 msg="one more"
[2026-03-15T10:44:10] [WARN] channels.telegram: Session terminated, max turns reached
[SUCCESS] Loop prevented, session auto-terminated

Environment-Specific Traps

Windows-Specific Issues

• Path Separators: Always use forward slashes (/) in config paths on Windows. Backslashes in YAML are interpreted as escape sequences:

  # WRONG
  sessionDir: "C:\Users\...\sessions"
  CORRECT
  sessionDir: “C:/Users/…/sessions”
  

• AntiVirus Interference: Windows Defender or third-party AV may quarantine session files, causing corruption:

  # Add exclusion
  Windows Security > Virus & threat protection > Manage settings >
  Exclusions > Add exclusion > Folder > C:\Users\\AppData\Roaming\openclaw
  

• PowerShell Execution Policy: Scripts may fail silently:

  C:\> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  

Docker/WSL2 on Windows

• Path Mismatches: Config paths inside Docker containers differ from Windows paths:

  # In docker-compose.yml, mount correctly
  volumes:
    - ./config.yaml:/app/config.yaml
    - C:/Users/username/AppData/Roaming/openclaw:/root/.openclaw
  Environment variables inside container
  OPENCLAW_HOME: “/root/.openclaw”
  

• Network Mode: Telegram API requires network: host or proper port forwarding:

  # docker-compose.yml
  services:
    gateway:
      network_mode: host
      # OR
      ports:
        - "3000:3000"
  

Session Management Pitfalls

• Stale Lock Files: Never delete .lock files manually during operation:

  # CORRECT shutdown sequence
  gateway> subagents kill --all
  gateway> shutdown
  NOW safe to delete files
  

• Multiple Gateway Instances: Only one instance should access session files:

  # Check for running instances
  C:\> tasklist | findstr openclaw
  openclaw.exe              1234 Console                    1     45,120 K
  # Should show exactly ONE entry
  

Configuration Anti-Patterns

• Hot-Reload Assumption: Not all config changes support hot-reload. Always restart for:

  - botToken changes
  - mode changes (webhook/polling)
  - channel enable/disable
  - session directory changes
  

• YAML Null Syntax: Use explicit null, not empty string or tilde:

  # WRONG (may persist)
  channels:
    telegram: ~
  CORRECT
  channels:
  telegram:
  $undefined$
  Or remove the section entirely
  

Contextually Connected Issues

• ECONNREFUSED on Telegram API — Firewall blocking outbound HTTPS (port 443) to api.telegram.org. Verify with: Test-NetConnection api.telegram.org -Port 443
• ETIMEDOUT during polling — Network latency exceeds timeout threshold. Increase timeout in config or switch to webhook mode.
• Webhook SSL Certificate Errors — Self-signed certificates not supported. Use valid SSL or disable verification (dev only): sslVerify: false
• Session Not Found (404) — Session expired or deleted. Telegram sessions expire after 24h inactivity by default.
• Rate Limit Exceeded (429) — Exceeded 30 msg/sec to same chat. Implement message queue with backoff.
• Chat Not Found — User never started bot conversation. Bot cannot message users who haven't sent /start.
• Config Merge Conflict — Multiple config files merged in wrong order. Check OPENCLAW_CONFIG_PATHS environment variable.
• SQLite Lock Error — Concurrent write to persistent-queue.db. Ensure thread: false for Windows compatibility.

Historical Reference

These issues were reported across multiple Windows versions and configurations:

• Issue #892: Telegram polling stalls on Windows Server 2019
• Issue #1104: Session files not cleaned on abnormal shutdown
• Issue #1156: Config hot-reload skips channel sections
• Issue #1233: 401 errors persist after token rotation