Merge pull request #57 from techartdev/force_ipv4_oc_bump

chore: Add force_ipv4_dns option and update translations; bump OpenCl…

DOCS.md

@@ -203,6 +203,7 @@ All options are set via **Settings → Apps/Add-ons → OpenClaw Assistant → C
 | `gateway_public_url` | string | _(empty)_ | Public URL for the "Open Gateway Web UI" button. Example: `http://192.168.1.119:18789` |
 | `enable_openai_api` | bool | `false` | Enable the OpenAI-compatible `/v1/chat/completions` endpoint. Required for [Assist pipeline integration](#6c-assist-pipeline-integration-openai-api) |
 | `allow_insecure_auth` | bool | `false` | Allow HTTP (non-HTTPS) authentication on LAN. **Required** for browser access over plain HTTP |
+| `force_ipv4_dns` | bool | `false` | Force IPv4-first DNS ordering for Node network calls. Useful if IPv6 DNS resolves but IPv6 egress is broken (can affect Telegram API polling). |
 
 ### Terminal
 
@@ -592,6 +593,19 @@ Paste this token when the UI prompts for authentication, or append it to the URL
 2. Check logs for `Starting web terminal (ttyd)` — if missing, the terminal is disabled
 3. If you see a port conflict error, change `terminal_port` to a different value
 
+### Telegram network errors (`TypeError: fetch failed` / `getUpdates` fails)
+
+If Telegram is configured but polling fails with network fetch errors:
+
+1. In add-on terminal, test IPv4 vs IPv6 explicitly:
+   ```sh
+   curl -4 https://api.telegram.org/bot<token>/getMe
+   curl -6 https://api.telegram.org/bot<token>/getMe
+   ```
+2. If IPv4 works but default/IPv6 fails, set add-on option `force_ipv4_dns: true` and restart.
+3. Keep `channels.telegram.network.autoSelectFamily: false` (default on Node 22).
+4. If still failing, check host/VM IPv6 routing and DNS configuration.
+
 ### Skills disappearing after update
 
 Built-in skills are synced to persistent storage on each startup. If skills are missing:

openclaw_assistant/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to the OpenClaw Assistant Home Assistant Add-on will be documented in this file.
 
+## [0.5.46] - 2026-02-18
+
+### Added
+- New add-on option `force_ipv4_dns` to enable IPv4-first DNS ordering for Node network calls (`NODE_OPTIONS=--dns-result-order=ipv4first`), helping Telegram connectivity on IPv6-broken networks.
+
+### Changed
+- Added translations for `force_ipv4_dns` option.
+- Updated docs with `force_ipv4_dns` configuration and Telegram network troubleshooting note.
+- Bump OpenClaw to 2026.2.17
+
 ## [0.5.45] - 2026-02-16
 
 ### Changed

openclaw_assistant/Dockerfile

@@ -102,7 +102,7 @@ USER root
 
 # Install OpenClaw globally
 RUN npm config set fund false && npm config set audit false \
- && npm install -g openclaw@2026.2.15
+ && npm install -g openclaw@2026.2.17
 
 # Shell aliases and color options for interactive use
 RUN tee -a /etc/bash.bashrc <<'EOF'

openclaw_assistant/config.yaml

@@ -1,5 +1,5 @@
 name: OpenClaw Assistant
-version: "0.5.45"
+version: "0.5.46"
 slug: openclaw_assistant
 description: Run OpenClaw Assistant (OpenClaw-compatible) as a Home Assistant add-on.
 url: https://github.com/techartdev/OpenClawHomeAssistant
@@ -75,6 +75,11 @@ options:
   # Default is false for security.
   allow_insecure_auth: false
 
+  # Force IPv4-first DNS result ordering for Node fetch/network calls.
+  # Useful on networks where IPv6 resolution exists but IPv6 egress is broken
+  # (can affect Telegram API polling in some HAOS/VM setups).
+  force_ipv4_dns: false
+
 
 schema:
   timezone: str
@@ -94,4 +99,5 @@ schema:
   gateway_port: int(1,65535)?
   enable_openai_api: bool?
   allow_insecure_auth: bool?
+  force_ipv4_dns: bool?
 

openclaw_assistant/run.sh

@@ -50,12 +50,24 @@ GATEWAY_BIND_MODE=$(jq -r '.gateway_bind_mode // "loopback"' "$OPTIONS_FILE")
 GATEWAY_PORT=$(jq -r '.gateway_port // 18789' "$OPTIONS_FILE")
 ENABLE_OPENAI_API=$(jq -r '.enable_openai_api // false' "$OPTIONS_FILE")
 ALLOW_INSECURE_AUTH=$(jq -r '.allow_insecure_auth // false' "$OPTIONS_FILE")
+FORCE_IPV4_DNS=$(jq -r '.force_ipv4_dns // false' "$OPTIONS_FILE")
 
 export TZ="$TZNAME"
 
 # Reduce risk of secrets ending up in logs
 set +x
 
+# Optional network hardening/workaround: force IPv4-first DNS ordering for Node.js.
+# Helps in environments where IPv6 resolves but has no working egress.
+if [ "$FORCE_IPV4_DNS" = "true" ] || [ "$FORCE_IPV4_DNS" = "1" ]; then
+  if [ -n "${NODE_OPTIONS:-}" ]; then
+    export NODE_OPTIONS="${NODE_OPTIONS} --dns-result-order=ipv4first"
+  else
+    export NODE_OPTIONS="--dns-result-order=ipv4first"
+  fi
+  echo "INFO: Enabled IPv4-first DNS ordering (NODE_OPTIONS=--dns-result-order=ipv4first)"
+fi
+
 # HA add-ons mount persistent storage at /config (maps to /addon_configs/<slug> on the host).
 export HOME=/config
 
@@ -356,6 +368,21 @@ if [ -f "$TTYD_PID_FILE" ]; then
 fi
 
 if [ "$ENABLE_TERMINAL" = "true" ] || [ "$ENABLE_TERMINAL" = "1" ]; then
+  # Check if the terminal port is already in use before starting ttyd
+  if command -v ss >/dev/null 2>&1 && ss -tlnp 2>/dev/null | grep -q ":${TERMINAL_PORT} "; then
+    echo ""
+    echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+    echo "!!  WARNING: terminal_port ${TERMINAL_PORT} IS ALREADY IN USE  !!"
+    echo "!!                                                             !!"
+    echo "!!  The web terminal (ttyd) may FAIL to start because port     !!"
+    echo "!!  ${TERMINAL_PORT} appears to be in use by another process.  !!"
+    echo "!!                                                             !!"
+    echo "!!  ACTION REQUIRED: If the terminal does not work, go to      !!"
+    echo "!!  Add-on Configuration and change 'terminal_port' to a free  !!"
+    echo "!!  port, then restart the add-on.                             !!"
+    echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
+    echo ""
+  fi
   echo "Starting web terminal (ttyd) on 127.0.0.1:${TERMINAL_PORT} ..."
   ttyd -W -i 127.0.0.1 -p "${TERMINAL_PORT}" -b /terminal bash &
   TTYD_PID=$!

openclaw_assistant/translations/bg.yaml

@@ -58,3 +58,7 @@ configuration:
   allow_insecure_auth:
     name: Разрешаване на HTTP автентикация
     description: Разрешаване на HTTP автентикация за достъп до gateway в локалната мрежа. ВНИМАНИЕ - Активирайте само ако използвате HTTP (не HTTPS) за gateway_public_url. Необходимо за достъп от браузър през HTTP.
+
+  force_ipv4_dns:
+    name: Принудителен IPv4 DNS ред
+    description: Принудително задава IPv4-приоритет при DNS резолв за Node мрежови заявки. Полезно е, когато IPv6 DNS се резолвира, но IPv6 интернет маршрутизацията е неработеща (може да влияе на Telegram API polling).

openclaw_assistant/translations/de.yaml

@@ -58,3 +58,7 @@ configuration:
   allow_insecure_auth:
     name: Unsichere HTTP-Authentifizierung erlauben
     description: HTTP-Authentifizierung für Gateway-Zugriff im LAN erlauben. WARNUNG - Nur aktivieren, wenn HTTP (nicht HTTPS) für gateway_public_url verwendet wird. Erforderlich für Browser-Zugriff über HTTP.
+
+  force_ipv4_dns:
+    name: IPv4-DNS-Reihenfolge erzwingen
+    description: Erzwingt IPv4-vorrangige DNS-Auflösung für Node-Netzwerkaufrufe. Nützlich, wenn IPv6-DNS aufgelöst wird, aber IPv6-Internet-Routing nicht funktioniert (kann Telegram-API-Polling beeinträchtigen).

openclaw_assistant/translations/en.yaml

@@ -58,3 +58,7 @@ configuration:
   allow_insecure_auth:
     name: Allow Insecure HTTP Auth
     description: Allow HTTP authentication for gateway access on LAN. WARNING - Only enable if using HTTP (not HTTPS) for gateway_public_url. Required for browser access over HTTP.
+
+  force_ipv4_dns:
+    name: Force IPv4 DNS Order
+    description: Force IPv4-first DNS ordering for Node network calls. Useful when IPv6 DNS resolves but IPv6 internet routing is broken (can affect Telegram API polling).

openclaw_assistant/translations/es.yaml

@@ -58,3 +58,7 @@ configuration:
   allow_insecure_auth:
     name: Permitir autenticación HTTP insegura
     description: Permitir autenticación HTTP para acceso al gateway en LAN. ADVERTENCIA - Solo habilitar si usa HTTP (no HTTPS) para gateway_public_url. Requerido para acceso desde navegador por HTTP.
+
+  force_ipv4_dns:
+    name: Forzar orden DNS IPv4
+    description: Fuerza el orden de DNS con prioridad IPv4 para llamadas de red de Node. Útil cuando el DNS IPv6 resuelve, pero el enrutamiento IPv6 a Internet falla (puede afectar el polling de la API de Telegram).

openclaw_assistant/translations/pl.yaml

@@ -58,3 +58,7 @@ configuration:
   gateway_mode:
     name: Tryb Gateway
     description: Tryb działania gateway - local (uruchom gateway lokalnie, zalecane) lub remote (połącz się ze zdalnym gateway)
+
+  force_ipv4_dns:
+    name: Wymuś kolejność DNS IPv4
+    description: Wymusza preferowanie IPv4 przy rozwiązywaniu DNS dla wywołań sieciowych Node. Przydatne, gdy DNS IPv6 się rozwiązuje, ale routing IPv6 do Internetu nie działa (może wpływać na polling API Telegrama).

openclaw_assistant/translations/pt-BR.yaml

@@ -58,3 +58,7 @@ configuration:
   allow_insecure_auth:
     name: Permitir Autenticação HTTP Insegura
     description: Permitir autenticação HTTP para acesso ao gateway na LAN. AVISO - Habilite somente se estiver usando HTTP (não HTTPS) para gateway_public_url. Necessário para acesso pelo navegador via HTTP.
+
+  force_ipv4_dns:
+    name: Forçar ordem DNS IPv4
+    description: Força a ordem de DNS com prioridade para IPv4 nas chamadas de rede do Node. Útil quando o DNS IPv6 resolve, mas o roteamento IPv6 para a internet está quebrado (pode afetar o polling da API do Telegram).