From d5fae52ad6bd8848e3c99ff9ef3d6cc1e3156bf2 Mon Sep 17 00:00:00 2001
From: techartdev <admin@techart.bg>
Date: Wed, 18 Feb 2026 15:38:06 +0200
Subject: [PATCH 1/5] chore: Add force_ipv4_dns option and update translations;
 bump OpenClaw to 2026.2.17

---
 openclaw_assistant/CHANGELOG.md            | 10 +++++++++
 openclaw_assistant/Dockerfile              |  2 +-
 openclaw_assistant/config.yaml             |  8 ++++++-
 openclaw_assistant/run.sh                  | 26 ++++++++++++++++++++++
 openclaw_assistant/translations/bg.yaml    |  4 ++++
 openclaw_assistant/translations/de.yaml    |  4 ++++
 openclaw_assistant/translations/en.yaml    |  4 ++++
 openclaw_assistant/translations/es.yaml    |  4 ++++
 openclaw_assistant/translations/pl.yaml    |  4 ++++
 openclaw_assistant/translations/pt-BR.yaml |  4 ++++
 10 files changed, 68 insertions(+), 2 deletions(-)

diff --git a/openclaw_assistant/CHANGELOG.md b/openclaw_assistant/CHANGELOG.md
index dbec6fb..8c4df31 100644
--- a/openclaw_assistant/CHANGELOG.md
+++ b/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
diff --git a/openclaw_assistant/Dockerfile b/openclaw_assistant/Dockerfile
index 583561c..56252fc 100644
--- a/openclaw_assistant/Dockerfile
+++ b/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'
diff --git a/openclaw_assistant/config.yaml b/openclaw_assistant/config.yaml
index 17b3dfc..9c609d1 100644
--- a/openclaw_assistant/config.yaml
+++ b/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?
 
diff --git a/openclaw_assistant/run.sh b/openclaw_assistant/run.sh
index 4dfe766..f49135b 100644
--- a/openclaw_assistant/run.sh
+++ b/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,20 @@ 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) could NOT be started because port  !!"
+    echo "!!  ${TERMINAL_PORT} is occupied by another process.           !!"
+    echo "!!                                                             !!"
+    echo "!!  ACTION REQUIRED: Go to Add-on Configuration and change     !!"
+    echo "!!  'terminal_port' to a free 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=$!
diff --git a/openclaw_assistant/translations/bg.yaml b/openclaw_assistant/translations/bg.yaml
index be72e85..03c33cf 100644
--- a/openclaw_assistant/translations/bg.yaml
+++ b/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).
diff --git a/openclaw_assistant/translations/de.yaml b/openclaw_assistant/translations/de.yaml
index 4478793..96cba4d 100644
--- a/openclaw_assistant/translations/de.yaml
+++ b/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).
diff --git a/openclaw_assistant/translations/en.yaml b/openclaw_assistant/translations/en.yaml
index d8c7bf1..c8268ad 100644
--- a/openclaw_assistant/translations/en.yaml
+++ b/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).
diff --git a/openclaw_assistant/translations/es.yaml b/openclaw_assistant/translations/es.yaml
index 62de2b8..7ad2e36 100644
--- a/openclaw_assistant/translations/es.yaml
+++ b/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).
diff --git a/openclaw_assistant/translations/pl.yaml b/openclaw_assistant/translations/pl.yaml
index ddcc614..6b23b18 100644
--- a/openclaw_assistant/translations/pl.yaml
+++ b/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).
diff --git a/openclaw_assistant/translations/pt-BR.yaml b/openclaw_assistant/translations/pt-BR.yaml
index c676e30..3f5c97a 100644
--- a/openclaw_assistant/translations/pt-BR.yaml
+++ b/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).

From 0c4187c119879bd28d3d619d227d1cad7420dc5a Mon Sep 17 00:00:00 2001
From: TechArtDev <rpgattack@gmail.com>
Date: Wed, 18 Feb 2026 18:06:00 +0200
Subject: [PATCH 2/5] Update openclaw_assistant/run.sh

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 openclaw_assistant/run.sh | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/openclaw_assistant/run.sh b/openclaw_assistant/run.sh
index f49135b..3f259a9 100644
--- a/openclaw_assistant/run.sh
+++ b/openclaw_assistant/run.sh
@@ -374,11 +374,12 @@ if [ "$ENABLE_TERMINAL" = "true" ] || [ "$ENABLE_TERMINAL" = "1" ]; then
     echo "!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"
     echo "!!  WARNING: terminal_port ${TERMINAL_PORT} IS ALREADY IN USE  !!"
     echo "!!                                                             !!"
-    echo "!!  The web terminal (ttyd) could NOT be started because port  !!"
-    echo "!!  ${TERMINAL_PORT} is occupied by another process.           !!"
+    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: Go to Add-on Configuration and change     !!"
-    echo "!!  'terminal_port' to a free port, then restart the add-on.  !!"
+    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

From ff4a5c62ebaf4958bf9e6d1d7bd940b01e7abd9d Mon Sep 17 00:00:00 2001
From: techartdev <admin@techart.bg>
Date: Wed, 18 Feb 2026 18:07:17 +0200
Subject: [PATCH 3/5] docs update

---
 DOCS.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/DOCS.md b/DOCS.md
index 46633f7..f7ff05d 100644
--- a/DOCS.md
+++ b/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:

From adbfcfee72575e806a850d2f4ca40270eac334c2 Mon Sep 17 00:00:00 2001
From: Nathan Guenther <nathang21@users.noreply.github.com>
Date: Fri, 20 Feb 2026 11:44:43 -0500
Subject: [PATCH 4/5] feat: add tailnet and auto bind mode support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OpenClaw natively supports 'tailnet' and 'auto' bind modes but the
addon rejected them in oc_config_helper.py validation and the config.yaml
schema didn't list them as valid options.

- oc_config_helper.py: expand bind_mode validation to accept 'tailnet'
  and 'auto' in addition to 'loopback' and 'lan'
- config.yaml: add 'tailnet' and 'auto' to schema and document them
  in the options comments

Users running Tailscale as a separate HA addon (non-userspace mode)
can now set gateway_bind_mode: tailnet to restrict gateway access
exclusively to their Tailscale network — no iptables rules needed.

Closes #59
---
 openclaw_assistant/config.yaml         | 6 ++++--
 openclaw_assistant/oc_config_helper.py | 8 ++++----
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/openclaw_assistant/config.yaml b/openclaw_assistant/config.yaml
index 9c609d1..eabd83c 100644
--- a/openclaw_assistant/config.yaml
+++ b/openclaw_assistant/config.yaml
@@ -57,8 +57,10 @@ options:
   gateway_mode: local
 
   # Gateway network bind mode:
-  # - loopback: bind to 127.0.0.1 only (local access only, more secure)
+  # - loopback: bind to 127.0.0.1 only (local access only, most secure)
   # - lan: bind to all interfaces (accessible from local network)
+  # - tailnet: bind to Tailscale IP only (accessible only via Tailscale — recommended for remote access)
+  # - auto: prefer loopback; use tailnet if Tailscale is available
   # Default is loopback for security.
   gateway_bind_mode: loopback
 
@@ -95,7 +97,7 @@ schema:
   clean_session_locks_on_start: bool?
   clean_session_locks_on_exit: bool?
   gateway_mode: list(local|remote)?
-  gateway_bind_mode: list(loopback|lan)?
+  gateway_bind_mode: list(loopback|lan|tailnet|auto)?
   gateway_port: int(1,65535)?
   enable_openai_api: bool?
   allow_insecure_auth: bool?
diff --git a/openclaw_assistant/oc_config_helper.py b/openclaw_assistant/oc_config_helper.py
index 1fec9d6..b40e77a 100644
--- a/openclaw_assistant/oc_config_helper.py
+++ b/openclaw_assistant/oc_config_helper.py
@@ -63,7 +63,7 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, enable_openai_a
     
     Args:
         mode: "local" or "remote"
-        bind_mode: "loopback" or "lan"
+        bind_mode: "loopback", "lan", "tailnet", or "auto"
         port: Port number to listen on (must be 1-65535)
         enable_openai_api: Enable OpenAI-compatible Chat Completions endpoint
         allow_insecure_auth: Allow insecure HTTP authentication
@@ -74,8 +74,8 @@ def apply_gateway_settings(mode: str, bind_mode: str, port: int, enable_openai_a
         return False
     
     # Validate bind mode
-    if bind_mode not in ["loopback", "lan"]:
-        print(f"ERROR: Invalid bind_mode '{bind_mode}'. Must be 'loopback' or 'lan'")
+    if bind_mode not in ["loopback", "lan", "tailnet", "auto"]:
+        print(f"ERROR: Invalid bind_mode '{bind_mode}'. Must be 'loopback', 'lan', 'tailnet', or 'auto'")
         return False
     
     # Validate port range
@@ -157,7 +157,7 @@ def main():
     
     if cmd == "apply-gateway-settings":
         if len(sys.argv) != 7:
-            print("Usage: oc_config_helper.py apply-gateway-settings <local|remote> <loopback|lan> <port> <enable_openai_api:true|false> <allow_insecure:true|false>")
+            print("Usage: oc_config_helper.py apply-gateway-settings <local|remote> <loopback|lan|tailnet|auto> <port> <enable_openai_api:true|false> <allow_insecure:true|false>")
             sys.exit(1)
         mode = sys.argv[2]
         bind_mode = sys.argv[3]

From 7625d370c4560de34dbf997ae120a1132b9ff795 Mon Sep 17 00:00:00 2001
From: TechArtDev <rpgattack@gmail.com>
Date: Sat, 21 Feb 2026 01:39:37 +0200
Subject: [PATCH 5/5] Update README with OpenClaw integration details

Added a note about OpenClaw Home Assistant integration.
---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index f3ce035..e7857c6 100644
--- a/README.md
+++ b/README.md
@@ -3,6 +3,8 @@
 ## [Join our Discord Server!](https://discord.gg/Nx4H3XmY)
 ![OpenClaw Assistant](https://github.com/techartdev/OpenClawHomeAssistant/blob/main/oca_addon.png?raw=true)
 
+### OpenClaw Home Assistant integration is available now!  https://github.com/techartdev/OpenClawHomeAssistantIntegration
+
 This repository contains a Home Assistant add-on that runs **OpenClaw** inside **Home Assistant OS (HAOS)**.
 
 > Upstream rename history (FYI): clawdbot → moltbot → **openclaw** (final).