@agenthippo-ai/agenthippo 0.1.0

package/out/scripts/gateway/setup-gateway-server.sh

@@ -0,0 +1,935 @@
+#!/usr/bin/env bash
+#
+# Copyright (c) AgentHippo.ai. All rights reserved.
+#
+# AgentHippo — Server Gateway Setup
+#
+# Installs OpenClaw Gateway on a server (headless or desktop) so agents
+# can connect from the CLI or IDE and be reached on messaging channels.
+#
+# This script mirrors setup-gateway.sh (IDE-triggered) but adds:
+#   - Background start (nohup) or systemd service
+#   - Auth token configuration
+#   - Remote bind address (0.0.0.0)
+#   - Connection info printout
+#
+# Usage:
+#   ./setup-gateway-server.sh --source /path/to/openclaw            # Local source
+#   ./setup-gateway-server.sh --source openclaw/openclaw#branch     # Git source
+#   ./setup-gateway-server.sh --source openclaw@latest              # npm source
+#   ./setup-gateway-server.sh --bind 0.0.0.0 --token mysecret      # Remote access
+#   ./setup-gateway-server.sh --systemd                             # systemd service
+#   ./setup-gateway-server.sh --check                               # Check status only
+#   ./setup-gateway-server.sh --uninstall                           # stop gateway + remove global openclaw (config kept)
+#   ./setup-gateway-server.sh --reinstall --source <src>            # uninstall, verify, install (+ start)
+#
+
+set -euo pipefail
+
+# npm/@npmcli: lifecycle hooks spawn bare `sh`; setPATH can omit /bin if parent PATH is empty.
+export PATH="/usr/bin:/bin:/usr/sbin:/sbin${PATH:+:$PATH}"
+export npm_config_script_shell=/bin/sh
+# Corepack should never block Agent Anywhere setup waiting for interactive approval.
+export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m'
+
+# Defaults
+INSTALL_SOURCE="${INSTALL_SOURCE:-}"
+CHECK_ONLY=false
+UNINSTALL=false
+REINSTALL=false
+GATEWAY_PORT="${GATEWAY_PORT:-18789}"
+GATEWAY_BIND="${GATEWAY_BIND:-127.0.0.1}"
+GATEWAY_TOKEN="${GATEWAY_TOKEN:-}"
+INSTALL_SYSTEMD=false
+CONFIG_TEMPLATE="${CONFIG_TEMPLATE:-}"
+START_GATEWAY=true
+PORT_FROM_CLI=false
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --source|-s)
+            INSTALL_SOURCE="$2"
+            shift 2
+            ;;
+        --check|-c)
+            CHECK_ONLY=true
+            shift
+            ;;
+        --uninstall)
+            UNINSTALL=true
+            shift
+            ;;
+        --reinstall)
+            REINSTALL=true
+            shift
+            ;;
+        --port|-p)
+            GATEWAY_PORT="$2"
+            PORT_FROM_CLI=true
+            shift 2
+            ;;
+        --bind|-b)
+            GATEWAY_BIND="$2"
+            shift 2
+            ;;
+        --token|-t)
+            GATEWAY_TOKEN="$2"
+            shift 2
+            ;;
+        --systemd)
+            INSTALL_SYSTEMD=true
+            shift
+            ;;
+        --no-start)
+            START_GATEWAY=false
+            shift
+            ;;
+        --config-template)
+            CONFIG_TEMPLATE="$2"
+            shift 2
+            ;;
+        --help|-h)
+            echo "Usage: $0 [options]"
+            echo ""
+            echo "Options:"
+            echo "  --source, -s <src>     npm install source (git repo, local path, or npm package)"
+            echo "  --check, -c            Check installation status only"
+            echo "  --uninstall            Stop gateway, remove global openclaw (~/.openclaw unchanged)"
+            echo "  --reinstall            With --source: uninstall, check, then full install"
+            echo "  --port, -p <port>      Gateway port (default: gateway.port in ~/.openclaw/openclaw.json, else 18789)"
+            echo "  --bind, -b <addr>      Bind address (default: 127.0.0.1, use 0.0.0.0 for remote)"
+            echo "  --token, -t <token>    Auth token for gateway connections"
+            echo "  --systemd              Install and enable systemd user service"
+            echo "  --no-start             Install and configure only, don't start the gateway"
+            echo "  --config-template <f>  Path to starter config template"
+            echo "  --help, -h             Show this help"
+            exit 0
+            ;;
+        *)
+            echo "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+read_openclaw_config_gateway_port() {
+    local f="$HOME/.openclaw/openclaw.json"
+    [[ -f "$f" ]] || return 1
+    command -v node &>/dev/null || return 1
+    node -e '
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const fp = path.join(os.homedir(), ".openclaw", "openclaw.json");
+if (!fs.existsSync(fp)) process.exit(1);
+let t = fs.readFileSync(fp, "utf8");
+t = t.replace(/^\s*\/\/.*$/gm, "").replace(/,\s*([\]}])/g, "$1");
+try {
+  const j = JSON.parse(t);
+  const p = j && j.gateway && j.gateway.port;
+  if (typeof p === "number" && p >= 1 && p <= 65535) { process.stdout.write(String(p)); process.exit(0); }
+  if (typeof p === "string" && /^[0-9]+$/.test(p)) { process.stdout.write(p); process.exit(0); }
+} catch (e) {}
+process.exit(1);
+' 2>/dev/null
+}
+
+if ! $PORT_FROM_CLI; then
+    _cfg_port=""
+    _cfg_port=$(read_openclaw_config_gateway_port) || true
+    if [[ -n "$_cfg_port" ]]; then
+        GATEWAY_PORT="$_cfg_port"
+    fi
+fi
+
+# Logging
+log_info()    { echo -e "${BLUE}[INFO]${NC} $1"; }
+log_success() { echo -e "${GREEN}  ✓${NC} $1"; }
+log_warn()    { echo -e "${YELLOW}  ✗${NC} $1"; }
+log_error()   { echo -e "${RED}[ERROR]${NC} $1"; }
+log_step()    { echo -e "\n${BOLD}${CYAN}$1${NC}"; }
+
+# Git / GitHub-style sources need a local UI build (published tarballs ship dist/).
+needs_source_build() {
+    if [[ -z "$INSTALL_SOURCE" ]]; then
+        return 1
+    fi
+    local s="$INSTALL_SOURCE"
+    if [[ "$s" == /* || "$s" == ./* ]]; then
+        return 0
+    fi
+    if [[ "$s" == github:* || "$s" == git+http:* || "$s" == git+https:* ]]; then
+        return 0
+    fi
+    if [[ "$s" == *"#"* ]]; then
+        return 0
+    fi
+    if [[ "$s" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
+        return 0
+    fi
+    return 1
+}
+
+needs_pnpm() {
+    needs_source_build
+}
+
+# Git checkouts omit compiled dist/; build in clone before npm pack so dist/entry.(m)js and control-ui exist.
+install_openclaw_from_remote_git_spec() {
+    local spec="$1"
+    local s="$spec" ref=""
+    if [[ "$s" == *"#"* ]]; then
+        ref="${s##*#}"
+        s="${s%#*}"
+    fi
+
+    local clone_url=""
+    if [[ "$s" == git+https:* || "$s" == git+http:* ]]; then
+        clone_url="${s#git+}"
+    elif [[ "$s" == github:* ]]; then
+        clone_url="https://github.com/${s#github:}.git"
+    elif [[ "$s" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
+        clone_url="https://github.com/${s}.git"
+    else
+        log_error "Unsupported git install source: $spec"
+        exit 1
+    fi
+
+    local work
+    work="$(mktemp -d "${TMPDIR:-/tmp}/openclaw-gateway-src.XXXXXX")"
+
+    log_info "Cloning $(basename "$clone_url" .git) (shallow) for npm pack install..."
+    if [[ -n "$ref" ]]; then
+        git clone --depth 1 -b "$ref" "$clone_url" "$work/src" || {
+            log_error "git clone failed (check ref and network)"
+            rm -rf "$work"
+            exit 1
+        }
+    else
+        git clone --depth 1 "$clone_url" "$work/src" || {
+            log_error "git clone failed"
+            rm -rf "$work"
+            exit 1
+        }
+    fi
+
+    build_openclaw_in_dir "$work/src" || {
+        log_error "OpenClaw build failed in clone (need pnpm, Node 22.12+, network for deps)"
+        rm -rf "$work"
+        exit 1
+    }
+
+    log_info "npm pack --ignore-scripts ..."
+    (cd "$work/src" && npm pack --ignore-scripts) || {
+        log_error "npm pack failed"
+        rm -rf "$work"
+        exit 1
+    }
+
+    local tgz
+    tgz="$(ls -t "$work/src"/openclaw-*.tgz 2>/dev/null | head -1)"
+    if [[ -z "$tgz" || ! -f "$tgz" ]]; then
+        log_error "npm pack did not produce openclaw-*.tgz under clone"
+        rm -rf "$work"
+        exit 1
+    fi
+
+    log_info "npm install -g $(basename "$tgz") ..."
+    npm install -g "$tgz" || {
+        log_error "npm install -g tarball failed"
+        rm -rf "$work"
+        exit 1
+    }
+
+    REMOTE_GATEWAY_CLONE_SRC="$work/src"
+    REMOTE_GATEWAY_WORK_DIR="$work"
+}
+
+# ============================================================================
+# Check prerequisites (same as setup-gateway.sh)
+# ============================================================================
+check_prerequisites() {
+    log_step "Checking prerequisites..."
+
+    local all_good=true
+
+    # Node.js >= 22
+    if command -v node &>/dev/null; then
+        local node_version
+        node_version=$(node -v | sed 's/v//' | cut -d. -f1)
+        if [[ "$node_version" -ge 22 ]]; then
+            log_success "Node.js $(node -v)"
+        else
+            log_warn "Node.js $(node -v) — version 22+ required"
+            all_good=false
+        fi
+    else
+        log_warn "Node.js not found (version 22+ required)"
+        echo "       Install: https://nodejs.org/ or: curl -fsSL https://fnm.vercel.app/install | bash && fnm install 22"
+        all_good=false
+    fi
+
+    # npm
+    if command -v npm &>/dev/null; then
+        log_success "npm $(npm -v)"
+    else
+        log_warn "npm not found"
+        all_good=false
+    fi
+
+    if needs_pnpm; then
+        local src="$INSTALL_SOURCE"
+        if [[ "$src" != /* && "$src" != ./* ]]; then
+            if command -v git &>/dev/null; then
+                log_success "git $(git --version | head -1)"
+            else
+                log_warn "git not found (required for GitHub / git URL gateway install sources)"
+                all_good=false
+            fi
+        fi
+    fi
+
+    # pnpm (needed for pnpm build + ui:build when installing from git/local source)
+    if needs_pnpm; then
+        if command -v pnpm &>/dev/null; then
+            log_success "pnpm $(pnpm -v)"
+        else
+            log_warn "pnpm not found (needed to build OpenClaw from source)"
+            echo "       Install: npm install -g pnpm"
+        fi
+    else
+        log_info "pnpm not required for published package install"
+    fi
+
+    $all_good
+}
+
+# ============================================================================
+# Ensure pnpm is available when we need to build the UI
+# ============================================================================
+ensure_pnpm() {
+    if command -v pnpm &>/dev/null; then
+        log_success "pnpm $(pnpm -v)"
+        return 0
+    fi
+
+    log_warn "pnpm not found — attempting to install"
+
+    if command -v corepack &>/dev/null; then
+        log_info "Installing pnpm via corepack..."
+        export COREPACK_ENABLE_DOWNLOAD_PROMPT=0
+        if corepack prepare pnpm@latest --activate &>/dev/null; then
+            if command -v pnpm &>/dev/null; then
+                log_success "pnpm $(pnpm -v)"
+                return 0
+            fi
+        fi
+    fi
+
+    if command -v npm &>/dev/null; then
+        log_info "Installing pnpm via npm..."
+        if npm install -g pnpm; then
+            log_success "pnpm $(pnpm -v)"
+            return 0
+        fi
+    fi
+
+    log_warn "pnpm install failed — skipping web UI build"
+    return 1
+}
+
+build_openclaw_in_dir() {
+    local dir="$1"
+    if [[ ! -d "$dir" ]]; then
+        log_error "build_openclaw_in_dir: not a directory: $dir"
+        return 1
+    fi
+    ensure_pnpm || {
+        log_error "pnpm is required to build OpenClaw from a git checkout"
+        return 1
+    }
+    log_info "pnpm install && pnpm build && pnpm ui:build in $(basename "$dir") (may take several minutes)..."
+    (
+        cd "$dir" || exit 1
+        if [[ ! -f pnpm-lock.yaml ]]; then
+            log_error "pnpm-lock.yaml missing — expected an OpenClaw repo checkout"
+            exit 1
+        fi
+        pnpm install || {
+            log_error "pnpm install failed"
+            exit 1
+        }
+        pnpm build || {
+            log_error "pnpm build failed"
+            exit 1
+        }
+        pnpm ui:build || {
+            log_error "pnpm ui:build failed"
+            exit 1
+        }
+    )
+}
+
+# ============================================================================
+# Check installed components (extended for server: systemd, bind, token)
+# ============================================================================
+check_installed() {
+    log_step "Checking installed components..."
+
+    local all_ok=true
+
+    # openclaw binary
+    if command -v openclaw &>/dev/null; then
+        local oc_version
+        oc_version=$(openclaw --version 2>/dev/null | head -1 || echo "unknown")
+        log_success "openclaw installed: $oc_version"
+    else
+        # Check common install locations
+        local found=false
+        for candidate in \
+            "$HOME/Library/pnpm/openclaw" \
+            "$HOME/.local/share/pnpm/openclaw" \
+            "$HOME/.npm-global/bin/openclaw" \
+            "/usr/local/bin/openclaw" \
+            "/usr/bin/openclaw"; do
+            if [[ -x "$candidate" ]]; then
+                local oc_version
+                oc_version=$("$candidate" --version 2>/dev/null | head -1 || echo "unknown")
+                log_success "openclaw installed at $candidate: $oc_version"
+                found=true
+                break
+            fi
+        done
+        if ! $found; then
+            log_warn "openclaw not installed"
+            all_ok=false
+        fi
+    fi
+
+    local groot
+    groot="$(npm root -g 2>/dev/null)/openclaw"
+    if [[ -f "$groot/dist/entry.mjs" || -f "$groot/dist/entry.js" ]]; then
+        log_success "CLI dist present ($groot/dist/entry.*)"
+    else
+        log_warn "CLI dist missing (run setup with source build or reinstall from npm)"
+        all_ok=false
+    fi
+
+    # Web UI assets
+    local ui_dir
+    ui_dir="$groot/dist/control-ui"
+    if [[ -f "$ui_dir/index.html" ]]; then
+        log_success "Web UI built ($ui_dir)"
+    else
+        log_warn "Web UI not built"
+        all_ok=false
+    fi
+
+    # Gateway running?
+    if nc -z 127.0.0.1 "$GATEWAY_PORT" 2>/dev/null; then
+        log_success "Gateway running on port $GATEWAY_PORT"
+    else
+        log_warn "Gateway not running on port $GATEWAY_PORT"
+    fi
+
+    # Config file
+    local config_path="$HOME/.openclaw/openclaw.json"
+    if [[ -f "$config_path" ]]; then
+        log_success "Config file present ($config_path)"
+    else
+        log_warn "Config file not found ($config_path)"
+    fi
+
+    # systemd service (Linux only)
+    if [[ "$(uname)" == "Linux" ]] && command -v systemctl &>/dev/null; then
+        if systemctl --user is-enabled openclaw-gateway &>/dev/null 2>&1; then
+            local svc_status
+            svc_status=$(systemctl --user is-active openclaw-gateway 2>/dev/null || echo "inactive")
+            log_success "systemd service: $svc_status"
+        elif [[ -f "$HOME/.config/systemd/user/openclaw-gateway.service" ]]; then
+            log_warn "systemd service installed but not enabled"
+        fi
+    fi
+
+    echo ""
+    if $all_ok; then
+        echo -e "${GREEN}${BOLD}Gateway is fully installed!${NC}"
+        return 0
+    else
+        echo -e "${YELLOW}${BOLD}Gateway setup is incomplete.${NC}"
+        return 1
+    fi
+}
+
+# ============================================================================
+# Install gateway (same as setup-gateway.sh)
+# ============================================================================
+install_gateway() {
+    if [[ -z "$INSTALL_SOURCE" ]]; then
+        log_error "No install source specified. Use --source <source>"
+        exit 1
+    fi
+
+    REMOTE_GATEWAY_CLONE_SRC=""
+    REMOTE_GATEWAY_WORK_DIR=""
+
+    log_step "Installing OpenClaw Gateway..."
+    log_info "Source: $INSTALL_SOURCE"
+
+    local _npm_root
+    _npm_root="$(npm root -g 2>/dev/null || true)"
+    if [[ -n "$_npm_root" && -e "$_npm_root/openclaw" ]]; then
+        log_info "Removing existing global openclaw tree (avoids partial install / tar errors)..."
+        rm -rf "$_npm_root/openclaw"
+    fi
+
+    if needs_source_build; then
+        if [[ "$INSTALL_SOURCE" == /* || "$INSTALL_SOURCE" == ./* ]]; then
+            local abs_src
+            abs_src="$(cd "$INSTALL_SOURCE" && pwd)"
+            build_openclaw_in_dir "$abs_src" || exit 1
+            npm install -g "$abs_src"
+        else
+            install_openclaw_from_remote_git_spec "$INSTALL_SOURCE"
+        fi
+    else
+        npm install -g "$INSTALL_SOURCE"
+    fi
+    log_success "npm install complete"
+
+    if needs_source_build; then
+        if [[ -n "${REMOTE_GATEWAY_WORK_DIR:-}" ]]; then
+            log_info "Removing temporary clone directory..."
+            rm -rf "$REMOTE_GATEWAY_WORK_DIR"
+            REMOTE_GATEWAY_WORK_DIR=""
+            REMOTE_GATEWAY_CLONE_SRC=""
+        fi
+    else
+        log_info "Published package — web UI should be pre-built"
+    fi
+}
+
+# ============================================================================
+# Stop gateway listeners (graceful CLI stop, then best-effort process/port cleanup)
+# ============================================================================
+resolve_openclaw_bin() {
+    if command -v openclaw &>/dev/null; then
+        command -v openclaw
+        return 0
+    fi
+    local candidate
+    for candidate in \
+        "$HOME/Library/pnpm/openclaw" \
+        "$HOME/.local/share/pnpm/openclaw" \
+        "$HOME/.npm-global/bin/openclaw" \
+        "/usr/local/bin/openclaw" \
+        "/usr/bin/openclaw"; do
+        if [[ -x "$candidate" ]]; then
+            printf '%s\n' "$candidate"
+            return 0
+        fi
+    done
+    return 1
+}
+
+free_local_gateway_ports_if_busy() {
+    log_step "Clearing local gateway listener(s) if still bound..."
+    rm -f "$HOME/.openclaw/gateway.pid" 2>/dev/null || true
+    local sweep_ports=("$GATEWAY_PORT")
+    [[ "$GATEWAY_PORT" != "18789" ]] && sweep_ports+=(18789)
+    local sp pids
+    for sp in "${sweep_ports[@]}"; do
+        nc -z 127.0.0.1 "$sp" 2>/dev/null || continue
+        command -v lsof &>/dev/null || {
+            log_warn "Port $sp in use but lsof not available — stop the process manually"
+            continue
+        }
+        log_info "Port $sp in use — stopping listener PID(s)..."
+        pids=$(lsof -nP -iTCP:"$sp" -sTCP:LISTEN -t 2>/dev/null | tr '\n' ' ' || true)
+        if [[ -n "${pids// }" ]]; then
+            # shellcheck disable=SC2086
+            kill $pids 2>/dev/null || true
+            sleep 1
+            pids=$(lsof -nP -iTCP:"$sp" -sTCP:LISTEN -t 2>/dev/null | tr '\n' ' ' || true)
+            if [[ -n "${pids// }" ]]; then
+                # shellcheck disable=SC2086
+                kill -9 $pids 2>/dev/null || true
+            fi
+        fi
+    done
+    local any_up=false
+    for sp in "${sweep_ports[@]}"; do
+        if nc -z 127.0.0.1 "$sp" 2>/dev/null; then
+            any_up=true
+            break
+        fi
+    done
+    if $any_up; then
+        log_warn "A process may still be listening on 127.0.0.1 (${sweep_ports[*]})"
+    else
+        log_success "Gateway port(s) free on 127.0.0.1 (${sweep_ports[*]})"
+    fi
+}
+
+# Official teardown: openclaw uninstall --service before npm remove (see docs.openclaw.ai/cli/uninstall).
+openclaw_cli_uninstall_service() {
+    local oc_bin=""
+    oc_bin=$(resolve_openclaw_bin) || true
+    if [[ -z "$oc_bin" ]]; then
+        return 0
+    fi
+    log_step "OpenClaw CLI: uninstall gateway service..."
+    log_info "Running: $oc_bin uninstall --service --yes --non-interactive"
+    if "$oc_bin" uninstall --service --yes --non-interactive; then
+        log_success "openclaw uninstall --service completed"
+    else
+        log_info "openclaw uninstall --service failed or skipped (continuing)"
+    fi
+}
+
+# ============================================================================
+# Uninstall gateway (OpenClaw service uninstall + npm global remove + port cleanup)
+# ============================================================================
+uninstall_gateway() {
+    openclaw_cli_uninstall_service
+    echo ""
+    log_step "Uninstalling OpenClaw (global npm package)..."
+    if ! command -v npm &>/dev/null; then
+        log_error "npm not found"
+        exit 1
+    fi
+    npm uninstall -g openclaw 2>/dev/null || true
+    log_success "Ran: npm uninstall -g openclaw (global tree removed if present)"
+    log_info "~/.openclaw was not removed (config, sessions, and credentials stay on disk)."
+    echo ""
+    free_local_gateway_ports_if_busy
+}
+
+# ============================================================================
+# Write starter config (extended for server: bind, token, port)
+# ============================================================================
+write_config() {
+    local config_path="$HOME/.openclaw/openclaw.json"
+
+    if [[ -f "$config_path" ]]; then
+        log_info "Config already exists at $config_path — skipping"
+        return
+    fi
+
+    log_step "Writing starter config..."
+    mkdir -p "$HOME/.openclaw"
+
+    if [[ -n "$CONFIG_TEMPLATE" && -f "$CONFIG_TEMPLATE" ]]; then
+        cp "$CONFIG_TEMPLATE" "$config_path"
+        log_success "Config written from template: $config_path"
+        return
+    fi
+
+    # Build bind mode
+    local bind_mode="loopback"
+    if [[ "$GATEWAY_BIND" == "0.0.0.0" || "$GATEWAY_BIND" == "::" ]]; then
+        bind_mode="any"
+    fi
+
+    # Build auth line
+    local auth_line=""
+    if [[ -n "$GATEWAY_TOKEN" ]]; then
+        auth_line="\"auth\": { \"token\": \"$GATEWAY_TOKEN\" },"
+    fi
+
+    cat > "$config_path" <<CONF
+// OpenClaw Gateway Configuration (JSON5)
+// Docs: https://docs.openclaw.ai/configuration
+// Created by: setup-gateway-server.sh
+{
+  "gateway": {
+    "mode": "local",
+    "port": $GATEWAY_PORT,
+    "bind": "$bind_mode",
+    ${auth_line}
+    "controlUi": { "enabled": true }
+  },
+  "bindings": [],
+  "channels": {},
+  "plugins": { "entries": {} },
+  "commands": { "nativeSkills": false },
+  "session": { "dmScope": "per-peer" },
+  "agents": { "defaults": { "maxConcurrent": 4 } }
+}
+CONF
+
+    chmod 600 "$config_path"
+    log_success "Config written: $config_path"
+}
+
+# ============================================================================
+# Start gateway (nohup background)
+# ============================================================================
+start_gateway() {
+    # Check if already running
+    if nc -z 127.0.0.1 "$GATEWAY_PORT" 2>/dev/null; then
+        log_info "Gateway already running on port $GATEWAY_PORT"
+        return
+    fi
+
+    log_step "Starting gateway..."
+
+    local openclaw_bin
+    openclaw_bin=$(command -v openclaw 2>/dev/null || echo "")
+    if [[ -z "$openclaw_bin" ]]; then
+        # Check common install locations
+        for candidate in \
+            "$HOME/Library/pnpm/openclaw" \
+            "$HOME/.local/share/pnpm/openclaw" \
+            "$HOME/.npm-global/bin/openclaw" \
+            "/usr/local/bin/openclaw"; do
+            if [[ -x "$candidate" ]]; then
+                openclaw_bin="$candidate"
+                break
+            fi
+        done
+    fi
+
+    if [[ -z "$openclaw_bin" ]]; then
+        log_error "openclaw binary not found in PATH or common locations"
+        return 1
+    fi
+
+    local log_file="$HOME/.openclaw/gateway.log"
+    nohup "$openclaw_bin" gateway run \
+        --bind "$GATEWAY_BIND" \
+        --port "$GATEWAY_PORT" \
+        --force \
+        > "$log_file" 2>&1 &
+
+    local pid=$!
+    echo "$pid" > "$HOME/.openclaw/gateway.pid"
+
+    # Wait for it to come up
+    local retries=10
+    while [[ $retries -gt 0 ]]; do
+        if nc -z 127.0.0.1 "$GATEWAY_PORT" 2>/dev/null; then
+            log_success "Gateway started (pid=$pid, port=$GATEWAY_PORT)"
+            return
+        fi
+        sleep 1
+        retries=$((retries - 1))
+    done
+
+    log_warn "Gateway may not have started. Check: tail -f $log_file"
+}
+
+# ============================================================================
+# systemd service (Linux only)
+# ============================================================================
+install_systemd_service() {
+    if [[ "$(uname)" != "Linux" ]]; then
+        log_warn "systemd is only available on Linux. Use nohup or launchd on macOS."
+        return 1
+    fi
+
+    log_step "Installing systemd user service..."
+
+    local openclaw_bin
+    openclaw_bin=$(command -v openclaw 2>/dev/null || echo "")
+    if [[ -z "$openclaw_bin" ]]; then
+        log_error "openclaw binary not found in PATH"
+        return 1
+    fi
+
+    local service_dir="$HOME/.config/systemd/user"
+    mkdir -p "$service_dir"
+
+    local node_bin
+    node_bin=$(command -v node 2>/dev/null || echo "/usr/bin/node")
+    local node_dir
+    node_dir=$(dirname "$node_bin")
+
+    # Include npm/pnpm bin dirs in PATH so openclaw resolves
+    local extra_paths=""
+    for dir in \
+        "$HOME/Library/pnpm" \
+        "$HOME/.local/share/pnpm" \
+        "$HOME/.npm-global/bin" \
+        "/usr/local/bin"; do
+        if [[ -d "$dir" ]]; then
+            extra_paths="${extra_paths:+$extra_paths:}$dir"
+        fi
+    done
+
+    cat > "$service_dir/openclaw-gateway.service" <<SERVICE
+[Unit]
+Description=OpenClaw Gateway (AgentHippo)
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=$openclaw_bin gateway run --bind $GATEWAY_BIND --port $GATEWAY_PORT --force
+Restart=on-failure
+RestartSec=5
+Environment=PATH=$node_dir:${extra_paths:+$extra_paths:}/usr/local/bin:/usr/bin:/bin
+Environment=HOME=$HOME
+WorkingDirectory=$HOME
+
+[Install]
+WantedBy=default.target
+SERVICE
+
+    systemctl --user daemon-reload
+    systemctl --user enable openclaw-gateway
+    systemctl --user start openclaw-gateway
+
+    log_success "systemd service installed and started"
+    echo ""
+    echo -e "  ${CYAN}Status:${NC}  systemctl --user status openclaw-gateway"
+    echo -e "  ${CYAN}Logs:${NC}    journalctl --user -u openclaw-gateway -f"
+    echo -e "  ${CYAN}Stop:${NC}    systemctl --user stop openclaw-gateway"
+    echo -e "  ${CYAN}Restart:${NC} systemctl --user restart openclaw-gateway"
+
+    # Enable lingering so service runs after SSH logout
+    if command -v loginctl &>/dev/null; then
+        loginctl enable-linger "$(whoami)" 2>/dev/null || true
+        log_success "Lingering enabled (service persists after SSH logout)"
+    fi
+}
+
+# ============================================================================
+# Print connection info
+# ============================================================================
+print_connection_info() {
+    log_step "Connection info"
+
+    local host
+    if [[ "$GATEWAY_BIND" == "0.0.0.0" || "$GATEWAY_BIND" == "::" ]]; then
+        host=$(hostname -f 2>/dev/null || hostname 2>/dev/null || echo "your-server")
+    else
+        host="127.0.0.1"
+    fi
+
+    echo ""
+    echo -e "  ${BOLD}Gateway URL:${NC}  ws://$host:$GATEWAY_PORT"
+    if [[ -n "$GATEWAY_TOKEN" ]]; then
+        echo -e "  ${BOLD}Auth token:${NC}   $GATEWAY_TOKEN"
+    fi
+    echo -e "  ${BOLD}Web UI:${NC}       http://$host:$GATEWAY_PORT"
+    echo ""
+    echo -e "  ${CYAN}Connect from AgentHippo CLI:${NC}"
+    echo -e "    export OPENCLAW_GATEWAY_URL=ws://$host:$GATEWAY_PORT"
+    if [[ -n "$GATEWAY_TOKEN" ]]; then
+        echo -e "    export OPENCLAW_GATEWAY_TOKEN=$GATEWAY_TOKEN"
+    fi
+    echo -e "    agenthippo serve -a myagent --bind telegram,whatsapp"
+    echo ""
+    echo -e "  ${CYAN}Connect from VS Code (AgentHippo IDE):${NC}"
+    echo -e "    Set agentide.gateway.url = ws://$host:$GATEWAY_PORT"
+    if [[ -n "$GATEWAY_TOKEN" ]]; then
+        echo -e "    Set agentide.gateway.token = $GATEWAY_TOKEN"
+    fi
+    echo ""
+}
+
+# ============================================================================
+# Main
+# ============================================================================
+
+echo -e "${BOLD}${CYAN}"
+echo "  ╔═══════════════════════════════════════╗"
+echo "  ║     AgentHippo Gateway (Server)       ║"
+echo "  ║   Reach your agents from anywhere     ║"
+echo "  ╚═══════════════════════════════════════╝"
+echo -e "${NC}"
+
+if $CHECK_ONLY; then
+    check_installed
+    exit $?
+fi
+
+if $REINSTALL; then
+    if [[ -z "$INSTALL_SOURCE" ]]; then
+        log_error "--reinstall requires --source <src> (or set INSTALL_SOURCE)"
+        exit 1
+    fi
+    log_step "Reinstall: uninstall → verify → install"
+    uninstall_gateway
+    echo ""
+    log_step "Post-uninstall verification (--check)..."
+    check_installed || true
+    echo ""
+    if ! check_prerequisites; then
+        echo ""
+        log_error "Prerequisites not met. Install the missing tools and try again."
+        exit 1
+    fi
+    echo ""
+    install_gateway
+    write_config
+    if $START_GATEWAY; then
+        if $INSTALL_SYSTEMD; then
+            install_systemd_service
+        else
+            start_gateway
+        fi
+    fi
+    echo ""
+    check_installed || true
+    print_connection_info
+    echo -e "${BOLD}Reinstall complete.${NC}"
+    echo ""
+    exit 0
+fi
+
+if $UNINSTALL; then
+    uninstall_gateway
+    echo ""
+    check_installed || true
+    exit 0
+fi
+
+# Prerequisites
+if ! check_prerequisites; then
+    echo ""
+    log_error "Prerequisites not met. Install the missing tools and try again."
+    exit 1
+fi
+
+# Install if not present
+if ! command -v openclaw &>/dev/null; then
+    echo ""
+    install_gateway
+fi
+
+# Write config if missing
+write_config
+
+# Start the gateway
+if $START_GATEWAY; then
+    if $INSTALL_SYSTEMD; then
+        install_systemd_service
+    else
+        start_gateway
+    fi
+fi
+
+# Final status
+echo ""
+check_installed || true
+
+# Print connection info
+print_connection_info
+
+echo -e "${BOLD}Done!${NC} Next steps:"
+echo -e "  1. Set up channels: open ${CYAN}http://${GATEWAY_BIND}:${GATEWAY_PORT}${NC} or edit ${CYAN}~/.openclaw/openclaw.json${NC}"
+echo -e "  2. Connect your agent: ${CYAN}agenthippo serve -a myagent --bind telegram${NC}"
+echo ""