feat(gateway): add IP:port configuration and helper script

- Bump version to 0.5.35
- Add gateway_bind_ip and gateway_port options
- Create oc_config_helper.py for safe config management
- Update DOCS.md with new LAN mode configuration options
- Support prepopulation from existing config

Author: root

DOCS.md

@@ -65,9 +65,22 @@ You have two common setups:
 If your Home Assistant is already exposed via HTTPS (Nabu Casa, reverse proxy, etc.), use that.
 This avoids browser security issues.
 
-#### Option 2: LAN access (http://192.168.x.x)
-If you want to open it directly on your LAN, you must ensure OpenClaw binds to LAN.
-In the terminal:
+#### Option 2: LAN access (http://192.168.x.x) — using add-on options (recommended)
+The easiest way to enable LAN access is via the add-on configuration:
+
+1. Go to Home Assistant → **Settings → Add-ons → OpenClaw Assistant → Configuration**
+2. Set the following options:
+   - `gateway_lan_mode`: **true** (enables LAN binding)
+   - `gateway_bind_ip`: **"0.0.0.0"** (binds to all interfaces) or a specific IP like **"192.168.1.10"**
+   - `gateway_port`: **18789** (or your preferred port)
+3. Restart the add-on
+
+The add-on will automatically update OpenClaw's configuration on startup.
+
+**Pre-population**: If you previously configured OpenClaw manually, the add-on will detect and respect those settings. You can still override them via the add-on options.
+
+#### Option 3: LAN access — manual configuration (advanced)
+If you prefer to configure manually via terminal:
 
 ```sh
 openclaw config set gateway.bind lan
@@ -132,10 +145,25 @@ This allows using the Control UI over LAN HTTP.
 
 ## 5) Add-on options (custom / HA-specific)
 
-This add-on intentionally keeps options minimal. See `openclaw_assistant_dev/config.yaml` (DEV repo).
+This add-on keeps options minimal but practical. See `openclaw_assistant_dev/config.yaml` for the full schema.
+
+### Gateway LAN Mode (NEW)
+Control how the OpenClaw gateway binds to the network:
+
+- **`gateway_lan_mode`** (bool, default **false**)
+  - **false**: Bind to loopback only (127.0.0.1) — secure, local access only
+  - **true**: Bind to LAN — accessible from your local network
+
+When `gateway_lan_mode` is **true**:
+- **`gateway_bind_ip`** (string, default **"0.0.0.0"**)
+  - IP address to bind to. Use `"0.0.0.0"` for all interfaces, or a specific IP like `"192.168.1.10"`
+- **`gateway_port`** (int, default **18789**)
+  - Port number for the gateway to listen on
+
+These settings are applied automatically on add-on startup. No need to run `openclaw config` commands.
 
 ### Terminal
-- `enable_terminal` (default **true**)
+- `enable_terminal` (bool, default **true**)
 
 Security note: the terminal gives shell access inside the add-on container.
 
@@ -155,6 +183,10 @@ How to provide the key:
 - Put the private key file under the add-on config directory so it appears in-container at `/data/keys/...`
 - Recommended permissions: `chmod 600`
 
+### Session cleanup
+- `clean_session_locks_on_start` (bool, default **true**) — Remove stale lock files on startup
+- `clean_session_locks_on_exit` (bool, default **true**) — Remove stale lock files on shutdown
+
 ---
 
 ## Troubleshooting

openclaw_assistant_dev/config.yaml

@@ -1,5 +1,5 @@
 name: OpenClaw Assistant (DEV)
-version: "0.5.34"
+version: "0.5.35"
 slug: openclaw_assistant_dev
 description: Run OpenClaw Assistant (OpenClaw-compatible) as a Home Assistant add-on.
 url: https://github.com/techartdev/OpenClawHomeAssistant
@@ -48,11 +48,17 @@ options:
   clean_session_locks_on_exit: true
 
   # Gateway network bind mode:
-  # - true: bind to LAN (accessible from local network, e.g., 0.0.0.0 or LAN IP)
+  # - true: bind to LAN (accessible from local network)
   # - false: bind to loopback only (127.0.0.1, local access only)
   # Default is false for security. Toggle this on if you need external access.
   gateway_lan_mode: false
 
+  # Gateway bind configuration (used when gateway_lan_mode is true)
+  # IP address to bind to. Use "0.0.0.0" for all interfaces, or specific IP like "192.168.1.10"
+  gateway_bind_ip: "0.0.0.0"
+  # Port to listen on
+  gateway_port: 18789
+
 
 schema:
   timezone: str
@@ -67,4 +73,6 @@ schema:
   clean_session_locks_on_start: bool?
   clean_session_locks_on_exit: bool?
   gateway_lan_mode: bool?
+  gateway_bind_ip: str?
+  gateway_port: int(1,65535)?
 

openclaw_assistant_dev/oc_config_helper.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+OpenClaw config helper for Home Assistant add-on.
+Safely reads/writes openclaw.json without corrupting it.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+CONFIG_PATH = Path(os.environ.get("OPENCLAW_CONFIG_PATH", "/config/.openclaw/openclaw.json"))
+
+
+def read_config():
+    """Read and parse openclaw.json."""
+    if not CONFIG_PATH.exists():
+        return None
+    try:
+        return json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, IOError) as e:
+        print(f"ERROR: Failed to read config: {e}", file=sys.stderr)
+        return None
+
+
+def write_config(cfg):
+    """Write config back to file with nice formatting."""
+    try:
+        CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        CONFIG_PATH.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
+        return True
+    except IOError as e:
+        print(f"ERROR: Failed to write config: {e}", file=sys.stderr)
+        return False
+
+
+def get_gateway_setting(key, default=None):
+    """Get a gateway setting from config."""
+    cfg = read_config()
+    if cfg is None:
+        return default
+    return cfg.get("gateway", {}).get(key, default)
+
+
+def set_gateway_setting(key, value):
+    """Set a gateway setting, preserving other config."""
+    cfg = read_config()
+    if cfg is None:
+        cfg = {}
+    
+    if "gateway" not in cfg:
+        cfg["gateway"] = {}
+    
+    cfg["gateway"][key] = value
+    return write_config(cfg)
+
+
+def apply_lan_mode_settings(lan_mode: bool, bind_ip: str, port: int):
+    """
+    Apply LAN mode settings to OpenClaw config.
+    
+    Args:
+        lan_mode: True for LAN access, False for loopback only
+        bind_ip: IP address to bind to (e.g., "0.0.0.0" or "192.168.1.10")
+        port: Port number to listen on
+    """
+    cfg = read_config()
+    if cfg is None:
+        cfg = {}
+    
+    if "gateway" not in cfg:
+        cfg["gateway"] = {}
+    
+    gateway = cfg["gateway"]
+    
+    # Determine bind value
+    if lan_mode:
+        desired_bind = bind_ip if bind_ip else "0.0.0.0"
+    else:
+        desired_bind = "loopback"
+    
+    current_bind = gateway.get("bind", "")
+    current_port = gateway.get("port", 18789)
+    
+    changes = []
+    
+    if current_bind != desired_bind:
+        gateway["bind"] = desired_bind
+        changes.append(f"bind: {current_bind} -> {desired_bind}")
+    
+    if current_port != port:
+        gateway["port"] = port
+        changes.append(f"port: {current_port} -> {port}")
+    
+    if changes:
+        if write_config(cfg):
+            print(f"INFO: Updated gateway settings: {', '.join(changes)}")
+            return True
+        else:
+            print("ERROR: Failed to write config")
+            return False
+    else:
+        print(f"INFO: Gateway settings already correct (bind={desired_bind}, port={port})")
+        return True
+
+
+def main():
+    """CLI entry point for use by run.sh"""
+    if len(sys.argv) < 2:
+        print("Usage: oc_config_helper.py <command> [args...]")
+        sys.exit(1)
+    
+    cmd = sys.argv[1]
+    
+    if cmd == "apply-lan-mode":
+        if len(sys.argv) != 5:
+            print("Usage: oc_config_helper.py apply-lan-mode <true|false> <bind_ip> <port>")
+            sys.exit(1)
+        lan_mode = sys.argv[2].lower() == "true"
+        bind_ip = sys.argv[3]
+        port = int(sys.argv[4])
+        success = apply_lan_mode_settings(lan_mode, bind_ip, port)
+        sys.exit(0 if success else 1)
+    
+    elif cmd == "get":
+        if len(sys.argv) != 3:
+            print("Usage: oc_config_helper.py get <key>")
+            sys.exit(1)
+        key = sys.argv[2]
+        value = get_gateway_setting(key)
+        if value is not None:
+            print(value)
+        sys.exit(0)
+    
+    elif cmd == "set":
+        if len(sys.argv) != 4:
+            print("Usage: oc_config_helper.py set <key> <value>")
+            sys.exit(1)
+        key = sys.argv[2]
+        value = sys.argv[3]
+        # Try to convert to int if it looks like a number
+        try:
+            value = int(value)
+        except ValueError:
+            pass
+        success = set_gateway_setting(key, value)
+        sys.exit(0 if success else 1)
+    
+    else:
+        print(f"Unknown command: {cmd}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

openclaw_assistant_dev/run.sh

@@ -29,6 +29,8 @@ CLEAN_LOCKS_ON_EXIT=$(jq -r '.clean_session_locks_on_exit // true' "$OPTIONS_FIL
 
 # Gateway LAN mode toggle (default false for security)
 GATEWAY_LAN_MODE=$(jq -r '.gateway_lan_mode // false' "$OPTIONS_FILE")
+GATEWAY_BIND_IP=$(jq -r '.gateway_bind_ip // "0.0.0.0"' "$OPTIONS_FILE")
+GATEWAY_PORT=$(jq -r '.gateway_port // 18789' "$OPTIONS_FILE")
 
 export TZ="$TZNAME"
 
@@ -186,42 +188,17 @@ PY
 fi
 
 # ------------------------------------------------------------------------------
-# Apply gateway LAN mode setting safely (non-destructive config patch)
-# This updates gateway.bind without touching other settings (auth token, etc.)
+# Apply gateway LAN mode settings safely using helper script
+# This updates gateway.bind and gateway.port without touching other settings
 # ------------------------------------------------------------------------------
-LAN_MODE="${GATEWAY_LAN_MODE}"
-if [ -f "$OPENCLAW_CONFIG_PATH" ]; then
-  python3 - <<PY
-import json
-from pathlib import Path
-import os
+ADDON_DIR="$(cd "$(dirname "$0")" && pwd)"
+export OPENCLAW_CONFIG_PATH="/config/.openclaw/openclaw.json"
 
-cfg_path = Path(os.environ['OPENCLAW_CONFIG_PATH'])
-lan_mode = os.environ.get('GATEWAY_LAN_MODE', 'false').lower() == 'true'
-
-# Read existing config (preserve formatting as much as possible)
-text = cfg_path.read_text(encoding='utf-8')
-cfg = json.loads(text)
-
-# Determine desired bind value
-desired_bind = "lan" if lan_mode else "loopback"
-
-current_bind = cfg.get("gateway", {}).get("bind", "")
-
-if current_bind != desired_bind:
-    # Ensure gateway section exists
-    if "gateway" not in cfg:
-        cfg["gateway"] = {}
-    cfg["gateway"]["bind"] = desired_bind
-    
-    # Write back with nice formatting
-    cfg_path.write_text(json.dumps(cfg, indent=2) + "\n", encoding='utf-8')
-    print(f"INFO: Updated gateway.bind to '{desired_bind}' (gateway_lan_mode={lan_mode})")
-else:
-    print(f"INFO: gateway.bind already '{desired_bind}', no change needed")
-PY
+if [ -f "$OPENCLAW_CONFIG_PATH" ]; then
+  python3 "${ADDON_DIR}/oc_config_helper.py" apply-lan-mode "$GATEWAY_LAN_MODE" "$GATEWAY_BIND_IP" "$GATEWAY_PORT"
 else
-  echo "WARN: OpenClaw config not found at $OPENCLAW_CONFIG_PATH, cannot apply gateway_lan_mode"
+  echo "WARN: OpenClaw config not found at $OPENCLAW_CONFIG_PATH, cannot apply gateway settings"
+  echo "INFO: Run 'openclaw onboard' first, then restart the add-on"
 fi
 
 echo "Starting OpenClaw Assistant gateway (openclaw)..."