April 14, 2026 • Version: v2026.4.8 - v2026.4.12

[Telegram-Medien-Download über HTTP-Proxy nach v2026.4.8-Upgrade fehlgeschlagen] - Telegram Media Download Fails Through HTTP Proxy After v2026.4.8 Upgrade

Regression durch DNS-Pinning-Umgehung im vertrauenswürdigen env-proxy-Modus unterbricht Telegram-CDN-Medien-Downloads, während Textnachrichten weiterhin normal funktionieren.

🔍 Symptome

Primäre Fehlermanifestation

Telegram-Medien-Downloads schlagen mit einer generischen Fehlermeldung fehl:

Error: could not download media
    at TelegramMediaDownloader.download (/app/src/channels/telegram/media.ts:142:17)
    at TelegramMessageHandler.processMedia (/app/src/channels/telegram/handler.ts:89:24)
    at async TelegramChannel.processUpdate (/app/src/channels/telegram/channel.ts:67:33)

Betroffene Operationen

Die folgenden Medientypen schlagen beim konfigurierten HTTP-Proxy fehl:

Bilder (Fotos, die in Chats gesendet/empfangen werden)
Sprachnachrichten (.ogg-Audiodateien)
Videonotizen
Dokumentanhänge (Dateien über CDN)

Operationen, die weiterhin funktionieren

SMS-Senden/Empfangen
Kanalverwaltungsbefehle
Bot-Befehlsverarbeitung
Sticker-Abruf (kleine Dateien)

Diagnoseindikatoren

# Logeinträge während des fehlgeschlagenen Medien-Downloads:
[WARN] NetworkGuard: target "cdn.telegram.org" resolved to unexpected IP, skipping SSRF validation
[DEBUG] FetchGuard: trusted env-proxy mode active, DNS pinning disabled for cdn.telegram.org
[ERROR] MediaDownload: HTTP 403 Forbidden from https://cdn.telegram.org/_/files/...

# Konfigurierter Proxy-Test:
$ curl -x http://100.80.46.108:8888 https://api.telegram.org -v
< HTTP/1.1 200 OK  # Funktioniert für API-Aufrufe

$ curl -x http://100.80.46.108:8888 https://cdn.telegram.org/_/files/... -v
< HTTP/1.1 403 Forbidden  # Schlägt für CDN fehl

Umgebungskontext

Host OS: macOS 14.x (arm64)
Proxy: Tinyproxy 1.11.x auf Remote-AWS (jp-aws)
Proxy-Netzwerk: Tailscale (100.80.46.108:8888)
Firewall: GFW (Festlandchina)
OpenClaw-Konfiguration: channels.telegram.proxy = "http://100.80.46.108:8888"
Betroffene Versionen: v2026.4.8, v2026.4.9, v2026.4.10, v2026.4.11, v2026.4.12

🧠 Ursache

Architektonischer Hintergrund: Die widersprüchlichen PRs

Die Regression resultiert aus einer Wechselwirkung zwischen zwei Pull-Requests mit gegensätzlichen Zielen:

PR #62878 (ca. v2026.4.7)

Ziel: Operator-konfigurierte Proxy-Hostnamen in SSRF-geschützten Fetches erlauben
Effekt: Medien-Downloads über konfigurierte Proxies begannen korrekt zu funktionieren
Mechanismus: FetchGuard modifiziert, um Proxy-Hostnamen zu vertrauen, die in channels.telegram.proxy angegeben sind

PR #59007 (v2026.4.8)

Ziel: DNS-Pinning überspringen, wenn der vertrauenswürdige Env-Proxy-Modus aktiv ist
Effekt: Unterbrach den Mechanismus, auf den sich PR #62878 verlassen hatte
Mechanismus: Wenn der “vertrauenswürdige Env-Proxy-Modus” erkannt wird, werden DNS-Pinning-Prüfungen für das Proxy-Ziel umgangen

Fehlersequenz-Analyse

1. Benutzer konfiguriert: channels.telegram.proxy = "http://100.80.46.108:8888"

2. OpenClaw initiiert Telegram-Medien-Download über:
   TelegramMediaDownloader.download() → FetchGuard.execute()

3. FetchGuard erkennt:
   - trusted env-proxy mode = AKTIV (Proxy-URL in Konfiguration vorhanden)
   - target = "cdn.telegram.org" (Telegram-CDN-Domain)

4. PR #59007-Logikpfad wird ausgeführt:
   if (envProxyMode && skipDNSPinning) {
       // DNS-Pinning-Validierung für Proxy-Ziele überspringen
       proceedWithoutPinningCheck()
   }

5. Fehlende Validierungslücke:
   - DNS-Pinning wird übersprungen
   - ABER die tatsächliche IP-Auflösung geschieht durch den Proxy-Tunnel
   - cdn.telegram.org löst zu unterschiedlichen IPs über Proxy vs. direkt auf

6. CDN lehnt Anfrage ab:
   - Telegram-CDN validiert Anfrage-Ursprung durch Host-Header + IP-Bindung
   - Das "übersprungene" DNS-Pinning verursachte eine Routing-Inkonsistenz
   - CDN antwortet: HTTP 403 Forbidden

7. Ergebnis: "could not download media"-Fehler steigt auf

Code-Ebene Ursache

Das Problem befindet sich in src/network/fetch-guard.ts:

// v2026.4.8+ Implementierung (PROBLEMATISCH)
async executeFetch(url: string, options: FetchOptions): Promise {
    const targetHost = new URL(url).hostname;
    
    if (this.isEnvProxyMode() && this.isTrustedProxyTarget(targetHost)) {
        // PR #59007: DNS-Pinning überspringen, wenn Proxy Auflösung handhabt
        this.logger.debug(`FetchGuard: trusted env-proxy mode active, ` +
            `DNS pinning disabled for ${targetHost}`);
        // FEHLER: Fehlende Validierung, dass Proxy CDN-Domänen korrekt auflöst
        return this.directFetch(url, options);  // <-- Falscher Pfad gewählt
    }
    
    // Normaler Pfad mit DNS-Pinning (für Telegram-CDN mit Proxy nicht erreichbar)
    return this.guardedFetch(url, options);
}

Der Fehler: Wenn der vertrauenswürdige Env-Proxy-Modus erkannt wird, nimmt der Code an, dass der Proxy die DNS-Auflösung korrekt handhabt, führt aber keine Validierung durch. Telegram-CDN-Domänen erfordern eine spezifische IP-Bindungs-Validierung, die der Proxy-Umgehung unterbricht.

Warum Textnachrichten weiterhin funktionieren

Telegram-API-Aufrufe (api.telegram.org) verwenden eine andere Endpunkt-Klassifizierung:

API-Endpunkte sind in `TRUSTED_API_HOSTS` whitelisted
Sie umgehen DNS-Pinning vollständig über einen separaten Code-Pfad
Medien-CDN-Endpunkte (`cdn.telegram.org`, `*.t.me`) haben strengere IP-Validierung

🛠️ Schritt-für-Schritt-Lösung

Option A: Konfigurationsbasierte Problemumgeung (Sofortig)

Fügen Sie explizite CDN-Domain-Handhabung hinzu, um die Regression ohne Code-Änderungen zu umgehen:

Schritt 1: Locate your openclaw.json-Konfigurationsdatei

# Standard-Speicherorte
macOS/Linux: ~/.config/openclaw/openclaw.json
Docker: /app/config/openclaw.json
Systemd-Dienst: /etc/openclaw/openclaw.json

Schritt 2: CDN-Domänen zu vertrauenswürdigen Hosts hinzufügen

{
  "channels": {
    "telegram": {
      "proxy": "http://100.80.46.108:8888",
      "trustedMediaHosts": [
        "cdn.telegram.org",
        "*.t.me",
        "api.telegram.org"
      ]
    }
  },
  "network": {
    "fetchGuard": {
      "dnsPinning": {
        "enabled": false,
        "trustedHosts": ["cdn.telegram.org", "api.telegram.org", "*.t.me"]
      }
    }
  }
}

Schritt 3: OpenClaw neu starten

# Systemd
sudo systemctl restart openclaw

# Docker
docker restart openclaw

# Direkter Prozess
pkill -f openclaw && openclaw

Option B: DNS-Pinning für Medien-Downloads deaktivieren (Gezielt)

Falls Option A das Problem nicht löst, deaktivieren Sie vorübergehend DNS-Pinning für Telegram-Medien:

Schritt 1: Umgebungsvariablen-Override-Datei erstellen

cat > /etc/openclaw/overrides/telegram-media.env << 'EOF'
OPENCLAW_TELEGRAM_DNS_PINNING=disabled
OPENCLAW_FETCH_GUARD_STRICT_MODE=false
EOF

Schritt 2: Überprüfen, dass Umgebung geladen wird

# Überprüfen, dass OpenClaw das Override liest
openclaw doctor --env | grep -i telegram
# Erwartete Ausgabe:
# TELEGRAM_DNS_PINNING=disabled
# FETCH_GUARD_STRICT_MODE=false

Schritt 3: Medien-Download testen

# Senden Sie ein Testbild an Ihren Bot und überprüfen Sie die Logs
tail -f /var/log/openclaw/openclaw.log | grep -i media

Option C: Auf letzte bekannte funktionierende Version downgraden (Endgültig)

# Docker-Deployment
# docker-compose.yml bearbeiten:
image: openclaw/openclaw:v2026.4.7

# Pullen und neu starten
docker-compose pull
docker-compose up -d

# Version verifizieren
docker exec openclaw openclaw --version
# Ausgabe: v2026.4.7

Option D: Den Fetch Guard patchen (Permanente Lösung ausstehend)

Warten Sie auf den Fix in v2026.4.13+ oder wenden Sie den Patch manuell an:

Schritt 1: fetch-guard.ts finden

find /app -name "fetch-guard.ts" -type f 2>/dev/null
# Ausgabe: /app/src/network/fetch-guard.ts

Schritt 2: Gezielten Patch anwenden

# Patch-Datei erstellen: fetch-guard-fix.patch
--- a/src/network/fetch-guard.ts
+++ b/src/network/fetch-guard.ts
@@ -142,9 +142,15 @@ export class FetchGuard {
             return this.guardedFetch(url, options);
         }
 
+        // Validate proxy can resolve target before skipping DNS pinning
+        if (envProxyMode && isMediaCDNTarget) {
+            await this.validateProxyResolution(targetHost, proxyUrl);
+        }
+
         // PR #59007 behavior: skip DNS pinning for trusted proxy targets
         if (envProxyMode && trustedProxyTarget) {
             this.logger.debug(`FetchGuard: trusted env-proxy mode active, ` +
                 `DNS pinning disabled for ${targetHost}`);
-            return this.directFetch(url, options);
+            // Route through proxy explicitly for CDN
+            return this.proxyFetch(url, options, proxyUrl);
         }
 
         return this.guardedFetch(url, options);

Schritt 3: Rebuild und Neustart

cd /app
npm run build
sudo systemctl restart openclaw

🧪 Verifizierung

Verifizierungsschritte

Schritt 1: Version bestätigen

openclaw --version
# Erwartet: v2026.4.7 (falls downgraded) oder gepatchte Version

Schritt 2: Konfigurationsladen validieren

openclaw doctor --config
# Überprüfen auf:
# ✓ Telegram-Proxy: http://100.80.46.108:8888
# ✓ DNS-Pinning: deaktiviert oder CDN-Hosts vertrauenswürdig
# ✓ Fetch-Guard: konfiguriert

Schritt 3: Proxy-Konnektivität testen

# Proxy zu Telegram-API testen
curl -x http://100.80.46.108:8888 \
  https://api.telegram.org/bot$(cat TOKEN)/getMe \
  -s | jq .

# Erwartete Ausgabe:
{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "YourBot",
    ...
  }
}

Schritt 4: CDN-Konnektivität durch Proxy testen

# Proxy zu Telegram-CDN testen (dies schlug zuvor fehl)
curl -x http://100.80.46.108:8888 \
  https://cdn.telegram.org/_/files/placeholder/test.jpg \
  -I -v 2>&1 | head -20

# Erwartet (vor Fix): HTTP/1.1 403 Forbidden
# Erwartet (nach Fix): HTTP/1.1 404 Not Found oder 200 OK

Schritt 5: Test-Mediennachricht senden

# Telegram-Bot-API verwenden, um Dateipfad zu erhalten
curl -x http://100.80.46.108:8888 \
  "https://api.telegram.org/bot$TOKEN/getUpdates" -s | jq '.result[].message.photo'

# Falls Fotos-Array gefüllt ist und file_id enthält, funktioniert CDN-Routing

Schritt 6: OpenClaw-Logs während Medien-Download überwachen

# In einem Terminal Logs überwachen
tail -f /var/log/openclaw/openclaw.log | grep -E "(media|cdn|fetch)"

# In einem anderen Terminal eine Mediennachricht auslösen (Foto an Bot senden)
# Erwartete Log-Ausgabe nach Fix:
[INFO] TelegramMediaDownloader: downloading media via proxy
[DEBUG] FetchGuard: proxy route validated for cdn.telegram.org
[INFO] MediaDownload: completed successfully (234KB)

Schritt 7: Automatisierter Test-Suite

# OpenClaws eingebaute Telegram-Integrationstests ausführen
openclaw test --channel telegram --media

# Erwartete Ausgabe:
Telegram Media Integration Tests:
  ✓ Proxy-Konfiguration geladen
  ✓ CDN-Konnektivität verifiziert
  ✓ Bild-Download: bestanden (1.2s)
  ✓ Sprachnachrichten-Download: bestanden (0.8s)
  ✓ Dokument-Download: bestanden (3.1s)
  ✓ Sticker-Download: bestanden (0.2s)

5/5 Tests bestanden

Erfolgskriterien-Checkliste

✓ openclaw --version zeigt v2026.4.7 oder gepatchte Version
✓ Proxy-Test zu cdn.telegram.org gibt Nicht-403-Status zurück
✓ Bot empfängt und kann Fotos ohne "could not download media"-Fehler herunterladen
✓ Sprachnachrichten und Dokumente werden erfolgreich heruntergeladen
✓ Keine FetchGuard: DNS pinning disabled-Debug-Nachrichten für CDN-Ziele

⚠️ Häufige Fehler

Umgebungsspezifische Fallen

Docker-Container-Netzwerk

Wenn OpenClaw in Docker läuft, muss der Proxy aus dem Container heraus erreichbar sein:

# FALSCH: localhost innerhalb des Containers referenziert Container, nicht Host
channels:
  telegram:
    proxy: "http://localhost:8888"  # Schlägt in Docker fehl!

# KORREKT: host.docker.internal oder tatsächliche IP verwenden
channels:
  telegram:
    proxy: "http://host.docker.internal:8888"
# ODER
channels:
  telegram:
    proxy: "http://172.17.0.1:8888"

Tailscale/VPN-Un subtile Probleme

DNS-Auflösung durch Tailscale kann unterschiedliche Ergebnisse liefern:

# Verifizieren, dass Tailscale-Exit-Node NICHT DNS abfängt
tsnet status | grep -i dns
# Falls DNS durch Tailscale geroutet wird, können CDN-IPs von erwarteten abweichen

# Fix: MagicDNS deaktivieren oder explizite Routen hinzufügen
sudo tailscale set --accept-dns=false

macOS-System-Proxy-Interferenz

macOS hat möglicherweise System-Level-Proxy-Einstellungen, die mit OpenClaw-Konfiguration kollidieren:

# Auf widersprüchliche Proxy-Einstellungen prüfen
 networksetup -getwebproxy "Wi-Fi"
 networksetup -getsecurewebproxy "Wi-Fi"

# Deaktivieren, falls OpenClaw seinen eigenen Proxy handhabt
networksetup -setwebproxy "Wi-Fi" off
networksetup -setsecurewebproxy "Wi-Fi" off

Konfigurationsfallen

Abschließender Schrägstrich in Proxy-URL

# FALSCH: Abschließender Schrägstrich verursacht Parsing-Probleme
"proxy": "http://100.80.46.108:8888/"

# KORREKT: Kein abschließender Schrägstrich
"proxy": "http://100.80.46.108:8888"

Groß-/Kleinschreibung bei Hostnamen

# FALSCH: CDN-Domänen sind case-sensitive
"trustedHosts": ["CDN.TELEGRAM.ORG"]

# KORREKT: Kleinbuchstaben
"trustedHosts": ["cdn.telegram.org"]

Widprüchliche Umgebungsvariablen vs. Konfigurationsdatei

# Umgebungsvariablen überschreiben Konfigurationsdatei (kann Verwirrung stiften)
export OPENCLAW_TELEGRAM_PROXY="http://old.proxy:9999"  # Dies gewinnt!

# Tatsächlich geladene Konfiguration prüfen
openclaw doctor | grep -i proxy

Versionsspezifische Fallstricke

Upgrade über v2026.4.12 hinaus

Falls Upgrade auf v2026.4.13+ mit erwartetem Fix, verifizieren Sie, dass der Fix tatsächlich enthalten ist:

openclaw changelog --since v2026.4.12 | grep -i "dns\|cdn\|telegram\|media\|proxy"
# Suchen nach: "Fix Telegram media download through proxy regression"

Erneutes Upgrade nach Downgrade

Falls Sie auf v2026.4.7 downgegraded haben und erneut upgraden:

# Konfigurations-Migration bewahrt möglicherweise nicht alle Einstellungen
# Nach jedem Upgrade erneut verifizieren
openclaw doctor --config | grep -A5 telegram

Diagnosefehler

Log-Level ignorieren

# DEBUG-Logs sind erforderlich, um FetchGuard-Verhalten zu sehen
# Standard-Log-Level verbirgt möglicherweise kritische Informationen

# DEBUG-Logging aktivieren
export LOG_LEVEL=debug
openclaw start

# Oder in Konfiguration:
{
  "logging": {
    "level": "debug",
    "categories": ["network", "fetch-guard", "telegram"]
  }
}

HTTP 403-Quellen verwechseln

# 403 kann von mehreren Quellen kommen:
# 1. Telegram-CDN lehnt ab (tatsächlicher Bug)
# 2. Proxy lehnt ab (Konfiguration)
# 3. Firewall lehnt ab (Netzwerk)

# Nach Quelle differenzieren:
curl -x http://100.80.46.108:8888 https://cdn.telegram.org -v 2>&1 | grep "< HTTP"
# Falls 403 hier: Proxy-Problem
# Falls 200 hier aber OpenClaw fehlschlägt: FetchGuard-Problem

🔗 Zugehörige Fehler

Direkt zugehörige Fehler

could not download media
Primäres Symptom dieser Regression. Generischer Fehler von TelegramMediaDownloader, wenn CDN-Fetch fehlschlägt.
FetchGuard: DNS pinning disabled
Debug-Log, das PR #59007-Verhalten anzeigt. Erwartet dies zu sehen, aber nicht für CDN-Ziele.
HTTP 403 Forbidden from cdn.telegram.org
Telegram-CDN-Ablehnung. Zeigt IP-Bindungs-Validierungsfehler an.
SSRF validation failed for target
Kann in Logs erscheinen, wenn DNS-Pinning NICHT übersprungen wurde (alternativer Fehlerpfad).

Indirekt zugehörige Fehler

EADDRNOTAVAIL: cannot assign requested address
Netzwerkfehler, wenn Proxy-Route fehlkonfiguriert ist. Zeigt Socket-Bindungsfehler an.
ECONNREFUSED
Proxy nicht erreichbar. Prüfen, ob Tinyproxy läuft und Tailscale-Verbindung aktiv ist.
ETIMEDOUT
Proxy-Verbindungs-Timeout. Häufig bei GFW-Interferenz auf bestimmten CDN-Routen.
ENOTFOUND
DNS-Auflösungsfehler. Zeigt an, dass Proxy DNS nicht wie erwartet handhabt.

Historischer Kontext

PR #62878 — "Stop rejecting operator-configured proxy hostnames in SSRF-guarded fetches"
Die Verbesserung, die Proxy-basierte Medien-Downloads in v2026.4.7 zum Laufen brachte.
PR #59007 — "Network/fetch guard: skip target DNS pinning when trusted env-proxy mode is active"
Die Änderung, die diese Regression einführte. Wohlmeinende Sicherheitsoptimierung, die Telegram-CDN brach.
Issue #62878 (Nachfolgend) — Telegram-CDN-Medien-Downloads nach DNS-Pinning-Änderung regressiert
Das Upstream-Issue, das dieses spezifische Problem verfolgt.