@agenthippo-ai/agenthippo 0.2.3-dataplane → 1.110.11

package/out/scripts/analytics/setup-analytics.ps1

@@ -282,6 +282,37 @@ function Resolve-LiteLLMHooks {
     return $null
 }
 
+# Ensure the proxy has an auth key without ever asking the user for one.
+# Mirrors ensure_litellm_master_key in setup-analytics.sh — the launcher refuses to start
+# unauthenticated, so a first run with no key would leave LiteLLM dead with the error in a log.
+function Ensure-LiteLLMMasterKey {
+    $envFile = Join-Path $AgentHomeDir ".env"
+
+    if ((Test-Path $envFile) -and (Select-String -Path $envFile -Pattern '^\s*LITELLM_MASTER_KEY=' -Quiet)) {
+        Log-Success "LiteLLM master key already configured"
+        return
+    }
+    if ($env:LITELLM_MASTER_KEY) {
+        Log-Success "Using LITELLM_MASTER_KEY from the environment"
+        return
+    }
+
+    $bytes = New-Object byte[] 24
+    [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
+    $key = "sk-" + (($bytes | ForEach-Object { $_.ToString("x2") }) -join "")
+
+    New-Item -ItemType Directory -Path $AgentHomeDir -Force | Out-Null
+    $lines = @(
+        "# Generated by setup-analytics - authenticates the local LiteLLM proxy.",
+        "# Clients read the same value as AGENTHIPPO_LITELLM_API_KEY.",
+        "LITELLM_MASTER_KEY=$key",
+        "AGENTHIPPO_LITELLM_API_KEY=$key"
+    )
+    Add-Content -Path $envFile -Value $lines
+    $env:LITELLM_MASTER_KEY = $key
+    Log-Success "Generated a LiteLLM master key (stored in $envFile)"
+}
+
 function Setup-Config {
     Log-Step "Setting up configuration..."
 
@@ -289,6 +320,9 @@ function Setup-Config {
     New-Item -ItemType Directory -Path (Join-Path $AnalyticsDir "config") -Force | Out-Null
     New-Item -ItemType Directory -Path (Join-Path $AnalyticsDir "traces") -Force | Out-Null
 
+    # Before any early return below - the launcher exits non-zero without a key.
+    Ensure-LiteLLMMasterKey
+
     # Copy OTEL config
     $configDest = Join-Path $AnalyticsDir "config\otel-collector.yaml"
     $configSrc = Join-Path $ScriptDir "otel-collector.yaml"
@@ -325,24 +359,21 @@ function Setup-Config {
 
     if (-not (Test-Path $litellmDest)) {
         Copy-Item $litellmSrc $litellmDest
-        Log-Success "Created LiteLLM OTEL config from template"
+        # IDE/local lane: Spotlight needs prompt content, so message logging defaults ON here.
+        # The flip happens at copy time, not in the template, because Dockerfile.litellm bakes
+        # the same template into the gateway image, which must stay metadata-only.
+        $cfg = Get-Content $litellmDest -Raw
+        $cfg = $cfg -replace '(?m)^  turn_off_message_logging: true$', '  turn_off_message_logging: false'
+        $cfg = $cfg -replace '(?m)^    message_logging: false', '    message_logging: true'
+        Set-Content -Path $litellmDest -Value $cfg -NoNewline
+        Log-Success "Created LiteLLM OTEL config from template (local Spotlight: message logging ON)"
     } else {
         Log-Success "LiteLLM OTEL config already present (user-owned)"
     }
 
-    # Keep canonical template in sync with user edits when writable.
-    if ((Test-Path $litellmSrc) -and (Test-Path $litellmDest)) {
-        $sourceHash = (Get-Sha256Hash $litellmSrc)
-        $destHash = (Get-Sha256Hash $litellmDest)
-        if ($sourceHash -ne $destHash) {
-            try {
-                Copy-Item $litellmDest $litellmSrc -Force
-                Log-Success "Synced LiteLLM OTEL config back to source template"
-            } catch {
-                Log-Info "Using user-owned LiteLLM config (source template is read-only)"
-            }
-        }
-    }
+    # Deliberately ONE-WAY (template -> user). Copying the user's config back over the shipped
+    # template wrote their edits into the installed extension / a git-tracked file, and model
+    # entries can carry a literal upstream api_key - a credential leak into source control.
 
     $hooksDest = Join-Path $AgentHomeDir "agentide_litellm_hooks_v1.py"
     $hooksSrc = Resolve-LiteLLMHooks

package/out/scripts/analytics/setup-analytics.sh

@@ -361,6 +361,53 @@ run_install() {
     fi
 }
 
+# Ensure the proxy has an auth key without ever asking the user for one.
+#
+# The shipped config sets general_settings.master_key from ${LITELLM_MASTER_KEY} and the launcher
+# refuses to start unauthenticated, so a first run with no key leaves LiteLLM dead with the real
+# error buried in a log. Generate one, persist it to the env file the launcher already sources,
+# and hand the same value to clients as AGENTHIPPO_LITELLM_API_KEY.
+ensure_litellm_master_key() {
+    local env_file="${AGENT_HOME_DIR}/.env"
+
+    if [[ -f "$env_file" ]] && grep -q '^[[:space:]]*LITELLM_MASTER_KEY=' "$env_file"; then
+        log_success "LiteLLM master key already configured"
+        return 0
+    fi
+    # Respect a key exported by the caller rather than minting a second one.
+    if [[ -n "${LITELLM_MASTER_KEY:-}" ]]; then
+        log_success "Using LITELLM_MASTER_KEY from the environment"
+        return 0
+    fi
+
+    local key=""
+    if command -v openssl >/dev/null 2>&1; then
+        key="sk-$(openssl rand -hex 24)"
+    elif command -v python3 >/dev/null 2>&1; then
+        key="sk-$(python3 -c 'import secrets; print(secrets.token_hex(24))')"
+    else
+        log_warn "Neither openssl nor python3 found; cannot generate a LiteLLM master key"
+        log_info "Set one manually:  echo 'LITELLM_MASTER_KEY=sk-...' >> ${env_file}"
+        return 1
+    fi
+
+    mkdir -p "${AGENT_HOME_DIR}"
+    touch "$env_file"
+    chmod 600 "$env_file" 2>/dev/null || true
+    # Keep a trailing newline so appends never join onto a previous line.
+    if [[ -s "$env_file" ]] && [[ -n "$(tail -c 1 "$env_file" 2>/dev/null)" ]]; then
+        echo "" >> "$env_file"
+    fi
+    {
+        echo "# Generated by setup-analytics — authenticates the local LiteLLM proxy."
+        echo "# Clients read the same value as AGENTHIPPO_LITELLM_API_KEY."
+        echo "LITELLM_MASTER_KEY=${key}"
+        echo "AGENTHIPPO_LITELLM_API_KEY=${key}"
+    } >> "$env_file"
+    export LITELLM_MASTER_KEY="$key"
+    log_success "Generated a LiteLLM master key (stored in ${env_file}, mode 600)"
+}
+
 # Setup configuration
 setup_config() {
     log_step "Setting up configuration..."
@@ -370,6 +417,9 @@ setup_config() {
     mkdir -p "${ANALYTICS_DIR}/config"
     mkdir -p "${ANALYTICS_DIR}/traces"
 
+    # Before any early return below — the launcher exits non-zero without a key.
+    ensure_litellm_master_key || true
+
     # Copy OTEL Collector config if not present
     if [[ ! -f "${ANALYTICS_DIR}/config/otel-collector.yaml" ]]; then
         if [[ -f "${SCRIPT_DIR}/otel-collector.yaml" ]]; then
@@ -406,19 +456,21 @@ setup_config() {
 
     if [[ ! -f "$litellm_config" ]]; then
         cp "$source_config" "$litellm_config"
-        log_success "Created LiteLLM OTEL config from template"
+        # IDE/local lane: Spotlight needs prompt content, so message logging defaults ON here.
+        # The flip happens at copy time, not in the template, because Dockerfile.litellm bakes
+        # the same template into the gateway image, which must stay metadata-only.
+        sed -i.bak \
+            -e 's/^  turn_off_message_logging: true$/  turn_off_message_logging: false/' \
+            -e 's/^    message_logging: false/    message_logging: true/' \
+            "$litellm_config" && rm -f "${litellm_config}.bak"
+        log_success "Created LiteLLM OTEL config from template (local Spotlight: message logging ON)"
     else
         log_success "LiteLLM OTEL config already present (user-owned)"
     fi
 
-    # Keep canonical template in sync with user edits when writable.
-    if [[ -f "$source_config" ]] && ! cmp -s "$litellm_config" "$source_config"; then
-        if cp "$litellm_config" "$source_config" 2>/dev/null; then
-            log_success "Synced LiteLLM OTEL config back to source template"
-        else
-            log_info "Using user-owned LiteLLM config (source template is read-only)"
-        fi
-    fi
+    # Deliberately ONE-WAY (template -> user). Copying the user's config back over the shipped
+    # template wrote their edits into the installed extension / a git-tracked file, and model
+    # entries can carry a literal upstream `api_key` — a credential leak into source control.
     # Install LiteLLM hook for tool order sanitizer
     local hooks_target="${AGENT_HOME_DIR}/agentide_litellm_hooks_v1.py"
     local hooks_source=""
@@ -501,9 +553,34 @@ check_litellm() {
     fi
 }
 
-# Get LiteLLM PIDs
+# Get LiteLLM PIDs.
+#
+# Prefer the PID the launcher recorded: `pgrep -f litellm` matches ANY command line containing
+# the word, so on a shared or CI host it happily returns a colleague's proxy, an editor with the
+# string in its argv, or a log tail — and stop_litellm SIGKILLs whatever it returns. The broad
+# match stays only as a fallback when no PID file exists, and is scoped to a real proxy invocation.
 get_litellm_pids() {
-    pgrep -f "litellm" 2>/dev/null || true
+    local pid_file="${AGENT_HOME_DIR}/litellm.pid"
+    if [[ -f "$pid_file" ]]; then
+        local recorded
+        recorded="$(head -n 1 "$pid_file" | tr -d '\r' | tr -d '[:space:]')"
+        if [[ "$recorded" =~ ^[0-9]+$ ]] && kill -0 "$recorded" 2>/dev/null; then
+            echo "$recorded"
+            return 0
+        fi
+    fi
+    # Fallback for an orphaned proxy with no PID file. Two filters, because "litellm --config"
+    # also appears inside the lifecycle wrapper's own script text: require the config invocation,
+    # then drop shell wrappers (and this script) so we never SIGKILL the thing that started us.
+    local pid cmd
+    for pid in $(pgrep -f "litellm.*--config" 2>/dev/null || true); do
+        [[ "$pid" == "$$" ]] && continue
+        cmd="$(ps -p "$pid" -o command= 2>/dev/null || true)"
+        case "$cmd" in
+            */sh\ -c*|*/bash\ -c*|*/zsh\ -c*|sh\ -c*|bash\ -c*|zsh\ -c*) continue ;;
+        esac
+        echo "$pid"
+    done
 }
 
 # Stop LiteLLM gracefully
@@ -558,15 +635,22 @@ start_litellm_with_otel() {
     log_info "Starting LiteLLM with OTEL config..."
     log_info "Config: $otel_config"
     # Start in background
-    LITELLM_CONFIG_PATH="$otel_config" nohup "$litellm_script" > /tmp/litellm-otel.log 2>&1 &
+    # IDE/local Spotlight defaults content capture ON (operator can still export =0 to disable);
+    # hardened serve deployments do not launch through this script and stay metadata-only.
+    LITELLM_CONFIG_PATH="$otel_config" \
+        AGENTHIPPO_EVIDENCE_CONTENT_CAPTURE="${AGENTHIPPO_EVIDENCE_CONTENT_CAPTURE:-1}" \
+        nohup "$litellm_script" > /tmp/litellm-otel.log 2>&1 &
     local litellm_pid=$!
 
     # Write PID file with OTEL flag + base URL for fast status checks
     local pid_file="${AGENT_HOME_DIR}/litellm.pid"
     local litellm_host="${LITELLM_HOST:-127.0.0.1}"
-    local tls_enabled=true
-    case "${LITELLM_ENABLE_TLS:-true}" in
-        0|false|no|off) tls_enabled=false ;;
+    # Must match agentide-litellm.sh, which defaults TLS OFF (port 4000). Defaulting to true here
+    # recorded https://…:4443 in the PID file while the proxy actually bound http://…:4000, and
+    # the extension then persisted that unreachable URL as the global litellm baseUrl.
+    local tls_enabled=false
+    case "${LITELLM_ENABLE_TLS:-false}" in
+        1|true|yes|on) tls_enabled=true ;;
     esac
     local litellm_port="${LITELLM_PORT:-}"
     if [[ -z "$litellm_port" ]]; then
@@ -593,6 +677,13 @@ start_litellm_with_otel() {
         return 0
     else
         log_error "Failed to start LiteLLM. Check /tmp/litellm-otel.log"
+        # Surface the actual reason — the IDE shows this output, and "check a
+        # log file" is a dead end for non-technical users.
+        if [[ -f /tmp/litellm-otel.log ]]; then
+            echo ""
+            log_info "Last 10 lines of log:"
+            tail -10 /tmp/litellm-otel.log 2>/dev/null || true
+        fi
         return 1
     fi
 }

package/out/scripts/analytics/start-analytics.sh

@@ -61,6 +61,25 @@ is_running() {
     return 1
 }
 
+# OTLP receiver ports, read from the collector config the daemon will run with,
+# so the preflight can never drift from what the collector actually binds.
+# Falls back to the OTLP defaults if the config is missing or unparseable.
+get_collector_ports() {
+    local ports=""
+    if [[ -f "${CONFIG_FILE}" ]]; then
+        ports=$(awk '
+            /^receivers:/ { in_receivers = 1; next }
+            /^[^[:space:]#]/ { in_receivers = 0 }
+            in_receivers && /endpoint:/ && match($0, /:[0-9]+[[:space:]]*$/) {
+                port = substr($0, RSTART + 1, RLENGTH - 1)
+                gsub(/[[:space:]]/, "", port)
+                print port
+            }
+        ' "${CONFIG_FILE}" 2>/dev/null | sort -un | tr '\n' ' ')
+    fi
+    echo "${ports:-4317 4318}"
+}
+
 # Check if port is in use (returns 0 if in use)
 port_in_use() {
     local port=$1
@@ -100,12 +119,13 @@ find_orphan_otelcol() {
 # Kill orphan collector if user confirms
 handle_orphan_collector() {
     local orphan_pid=$1
+    local port="${2:-4317}"
     local orphan_cmdline=$(ps -p "$orphan_pid" -o command= 2>/dev/null || echo "unknown")
 
     log_warn "Found orphan OTEL Collector (PID: ${orphan_pid})"
     log_warn "Command: ${orphan_cmdline}"
 
-    if [[ "${FORCE:-}" == "1" ]] || [[ "${1:-}" == "--force" ]]; then
+    if [[ "${FORCE:-}" == "1" ]]; then
         log_info "Killing orphan process..."
         kill "${orphan_pid}" 2>/dev/null || true
         sleep 1
@@ -115,7 +135,7 @@ handle_orphan_collector() {
         return 0
     fi
 
-    log_error "Port 4317 is in use by an orphan collector."
+    log_error "Port ${port} is in use by an orphan collector."
     log_error "This may be a leftover from a previous installation."
     echo ""
     echo "To fix, run one of:"
@@ -125,6 +145,37 @@ handle_orphan_collector() {
     return 1
 }
 
+# Explain, in plain language, who owns a port we need and how to free it.
+# Docker publishes container ports through its own proxy process, so name the
+# container (the thing the user can act on) rather than "com.docker.backend".
+report_port_conflict() {
+    local port=$1
+    local owner="another program"
+    local fix="Free the port (check with: lsof -i :${port}), then run Setup Spotlight again."
+
+    if command -v lsof &>/dev/null; then
+        local line=$(lsof -nP -iTCP:"${port}" -sTCP:LISTEN 2>/dev/null | awk 'NR==2 {print $1, $2}')
+        if [[ -n "$line" ]]; then
+            local cmd="${line% *}"
+            local pid="${line##* }"
+            owner="'${cmd}' (PID ${pid})"
+            fix="Stop that program (or run: kill ${pid}), then run Setup Spotlight again."
+            if [[ "$cmd" == com.docke* || "$cmd" == *docker* ]] && command -v docker &>/dev/null; then
+                local container=$(docker ps --filter "publish=${port}" --format '{{.Names}}' 2>/dev/null | head -1)
+                if [[ -n "$container" ]]; then
+                    owner="Docker container '${container}'"
+                    fix="Stop it with:  docker stop ${container}   then run Setup Spotlight again."
+                fi
+            fi
+        fi
+    fi
+
+    log_error "Cannot start Spotlight: port ${port} is already in use by ${owner}."
+    echo ""
+    echo "  To fix: ${fix}"
+    echo ""
+}
+
 # Start in foreground
 start_foreground() {
     local otelcol=$(find_otelcol)
@@ -149,12 +200,18 @@ start_daemon() {
 
     local otelcol=$(find_otelcol)
 
-    # Check for port conflicts before starting
-    if port_in_use 4317; then
+    # Check for port conflicts before starting. The collector needs every
+    # receiver port in its config — a conflict on any of them kills it at bind
+    # time with the real error buried in the log, so fail here with a clear message.
+    local port
+    for port in $(get_collector_ports); do
+        if ! port_in_use "$port"; then
+            continue
+        fi
         local orphan_pid=$(find_orphan_otelcol || true)
         if [[ -n "$orphan_pid" ]]; then
             if [[ "${FORCE:-}" == "1" ]]; then
-                log_warn "Port 4317 in use by orphan process (PID: ${orphan_pid}). Killing..."
+                log_warn "Port ${port} in use by orphan process (PID: ${orphan_pid}). Killing..."
                 kill "${orphan_pid}" 2>/dev/null || true
                 sleep 1
                 # Force kill if still running
@@ -162,16 +219,21 @@ start_daemon() {
                     kill -9 "${orphan_pid}" 2>/dev/null || true
                     sleep 1
                 fi
+                # The orphan may not have been the port owner (e.g. a container
+                # holds it) — re-check before declaring the port free.
+                if port_in_use "$port"; then
+                    report_port_conflict "$port"
+                    exit 1
+                fi
             else
-                handle_orphan_collector "$orphan_pid"
+                handle_orphan_collector "$orphan_pid" "$port"
                 exit 1
             fi
         else
-            log_error "Port 4317 is in use by another process."
-            log_error "Check with: lsof -i :4317"
+            report_port_conflict "$port"
             exit 1
         fi
-    fi
+    done
 
     # Ensure directories exist
     mkdir -p "${ANALYTICS_DIR}/traces"
@@ -260,12 +322,22 @@ show_status() {
             echo "    kill ${orphan_pid} && $0 --daemon"
             echo "  Or auto-fix with:"
             echo "    FORCE=1 $0 --daemon"
-        elif port_in_use 4317; then
-            echo -e "OTEL Collector: ${RED}Port Conflict${NC}"
-            echo -e "  ${RED}⚠ Port 4317 in use by another process${NC}"
-            echo "  Check with: lsof -i :4317"
         else
-            echo -e "OTEL Collector: ${RED}Stopped${NC}"
+            local conflict_port=""
+            local port
+            for port in $(get_collector_ports); do
+                if port_in_use "$port"; then
+                    conflict_port=$port
+                    break
+                fi
+            done
+            if [[ -n "$conflict_port" ]]; then
+                echo -e "OTEL Collector: ${RED}Port Conflict${NC}"
+                echo -e "  ${RED}⚠ Port ${conflict_port} in use by another process${NC}"
+                echo "  Check with: lsof -i :${conflict_port}"
+            else
+                echo -e "OTEL Collector: ${RED}Stopped${NC}"
+            fi
         fi
     fi
     echo ""

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

@@ -162,6 +162,32 @@ MANAGED_GATEWAY_WRAPPER_DIR="${HOME}/.local/bin"
 AGENT_ANYWHERE_PATH_MARKER_BEGIN="# >>> Agent Anywhere PATH >>>"
 AGENT_ANYWHERE_PATH_MARKER_END="# <<< Agent Anywhere PATH <<<"
 MANAGED_GATEWAY_WRAPPER_MARKER="# Managed by Agent Anywhere"
+HIPPOCLAW_NPM_PACKAGE="@agenthippo-ai/hippoclaw"
+
+# Global npm trees: scoped HippoClaw first, legacy openclaw fallback.
+global_gateway_package_dir_candidates() {
+    local npm_root="${1:-}"
+    local lib_base="${2:-}"
+    if [[ -n "$npm_root" ]]; then
+        printf '%s\n' "$npm_root/@agenthippo-ai/hippoclaw" "$npm_root/openclaw"
+    fi
+    if [[ -n "$lib_base" ]]; then
+        printf '%s\n' "$lib_base/@agenthippo-ai/hippoclaw" "$lib_base/openclaw"
+    fi
+}
+
+remove_global_gateway_package_trees() {
+    local npm_root prefix pkg_dir
+    npm_root="$(npm root -g 2>/dev/null || true)"
+    prefix="$(npm prefix -g 2>/dev/null || true)"
+    while IFS= read -r pkg_dir; do
+        [[ -n "$pkg_dir" && -e "$pkg_dir" ]] || continue
+        rm -rf "$pkg_dir"
+    done < <(
+        global_gateway_package_dir_candidates "$npm_root" "${prefix:+$prefix/lib/node_modules}"
+        global_gateway_package_dir_candidates "" "$NPM_GLOBAL_PREFIX/lib/node_modules"
+    )
+}
 
 add_path_entry() {
     local entry="$1"
@@ -514,15 +540,15 @@ resolve_managed_gateway_install() {
     if [[ -n "$current_node" ]]; then
         npm_root="$(npm root -g 2>/dev/null || true)"
         prefix="$(npm prefix -g 2>/dev/null || true)"
-        package_root="${npm_root}/openclaw"
-        if [[ -n "$npm_root" && -n "$prefix" && -d "$package_root" ]]; then
+        while IFS= read -r package_root; do
+            [[ -n "$npm_root" && -n "$prefix" && -d "$package_root" ]] || continue
             resolve_managed_gateway_install_from_root "$current_node" "$package_root" "${prefix}/bin" && return 0
-        fi
+        done < <(global_gateway_package_dir_candidates "$npm_root" "${prefix:+$prefix/lib/node_modules}")
 
-        package_root="${NPM_GLOBAL_PREFIX}/lib/node_modules/openclaw"
-        if [[ -d "$package_root" ]]; then
+        while IFS= read -r package_root; do
+            [[ -d "$package_root" ]] || continue
             resolve_managed_gateway_install_from_root "$current_node" "$package_root" "${NPM_GLOBAL_PREFIX}/bin" && return 0
-        fi
+        done < <(global_gateway_package_dir_candidates "" "$NPM_GLOBAL_PREFIX/lib/node_modules")
     fi
 
     local candidate_node candidate_dir install_dir
@@ -530,10 +556,10 @@ resolve_managed_gateway_install() {
     while IFS= read -r candidate_node; do
         candidate_dir="${candidate_node%/node}"
         install_dir="$(dirname "$candidate_dir")"
-        package_root="${install_dir}/lib/node_modules/openclaw"
-        if [[ -d "$package_root" ]]; then
+        while IFS= read -r package_root; do
+            [[ -d "$package_root" ]] || continue
             resolve_managed_gateway_install_from_root "$candidate_node" "$package_root" "$candidate_dir" && return 0
-        fi
+        done < <(global_gateway_package_dir_candidates "" "$install_dir/lib/node_modules")
     done < <(find "$NODE_BOOTSTRAP_ROOT" -maxdepth 4 -type f -path '*/bin/node' 2>/dev/null | sort -r)
     return 1
 }
@@ -845,7 +871,7 @@ install_openclaw_from_remote_git_spec() {
     }
 
     local tgz
-    tgz="$(ls -t "$work/src"/openclaw-*.tgz 2>/dev/null | head -1)"
+    tgz="$(ls -t "$work/src"/agenthippo-ai-hippoclaw-*.tgz "$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"
@@ -1047,11 +1073,15 @@ check_installed() {
     groot="$(resolve_managed_gateway_package_root_from_manifest || true)"
     if [[ -z "$groot" || ! -d "$groot" ]]; then
         npm_root="$(npm root -g 2>/dev/null || true)"
-        groot=""
-        [[ -n "$npm_root" ]] && groot="$npm_root/openclaw"
-        if [[ -z "$groot" || ! -d "$groot" ]]; then
-            groot="$NPM_GLOBAL_PREFIX/lib/node_modules/openclaw"
-        fi
+        prefix="$(npm prefix -g 2>/dev/null || true)"
+        while IFS= read -r candidate; do
+            [[ -d "$candidate" ]] || continue
+            groot="$candidate"
+            break
+        done < <(
+            global_gateway_package_dir_candidates "$npm_root" "${prefix:+$prefix/lib/node_modules}"
+            global_gateway_package_dir_candidates "" "$NPM_GLOBAL_PREFIX/lib/node_modules"
+        )
     fi
     if [[ -n "$groot" && -d "$groot" ]]; then
         if [[ -f "$groot/dist/entry.mjs" || -f "$groot/dist/entry.js" ]]; then
@@ -1119,7 +1149,11 @@ check_uninstalled() {
     local groot=""
     groot="$(resolve_managed_gateway_package_root_from_manifest || true)"
     if [[ -z "$groot" || ! -d "$groot" ]]; then
-        groot="$NPM_GLOBAL_PREFIX/lib/node_modules/openclaw"
+        while IFS= read -r candidate; do
+            [[ -d "$candidate" ]] || continue
+            groot="$candidate"
+            break
+        done < <(global_gateway_package_dir_candidates "" "$NPM_GLOBAL_PREFIX/lib/node_modules")
     fi
     if [[ -n "$groot" && -d "$groot" ]]; then
         log_warn "Managed npm openclaw package still present ($groot)"
@@ -1169,9 +1203,9 @@ install_gateway() {
 
     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"
+    if [[ -n "$_npm_root" ]]; then
+        log_info "Removing existing global gateway package trees (if present)..."
+        remove_global_gateway_package_trees
     fi
 
     # Local directory: npm links to that path (stable). Remote github:/git+: use clone+pack+tgz
@@ -1270,8 +1304,13 @@ remove_managed_openclaw_artifacts() {
     local dir install_dir pkg_root
 
     pkg_root="$NPM_GLOBAL_PREFIX/lib/node_modules/openclaw"
-    if [[ -d "$pkg_root" ]]; then
-        log_info "Removing managed openclaw package from $pkg_root"
+    if [[ -d "$NPM_GLOBAL_PREFIX/lib/node_modules/@agenthippo-ai/hippoclaw" ]]; then
+        pkg_root="$NPM_GLOBAL_PREFIX/lib/node_modules/@agenthippo-ai/hippoclaw"
+    elif [[ ! -d "$pkg_root" ]]; then
+        pkg_root=""
+    fi
+    if [[ -n "$pkg_root" && -d "$pkg_root" ]]; then
+        log_info "Removing managed gateway package from $pkg_root"
         rm -rf "$pkg_root"
     fi
     rm -f "$NPM_GLOBAL_PREFIX/bin/openclaw" "$NPM_GLOBAL_PREFIX/bin/hippoclaw" 2>/dev/null || true
@@ -1279,11 +1318,11 @@ remove_managed_openclaw_artifacts() {
     [[ -d "$NODE_BOOTSTRAP_ROOT" ]] || return 0
     while IFS= read -r dir; do
         install_dir="$(dirname "$dir")"
-        pkg_root="$install_dir/lib/node_modules/openclaw"
-        if [[ -d "$pkg_root" ]]; then
-            log_info "Removing managed openclaw package from $pkg_root"
-            rm -rf "$pkg_root"
-        fi
+        while IFS= read -r candidate; do
+            [[ -d "$candidate" ]] || continue
+            log_info "Removing managed gateway package from $candidate"
+            rm -rf "$candidate"
+        done < <(global_gateway_package_dir_candidates "" "$install_dir/lib/node_modules")
         rm -f "$dir/openclaw" "$dir/hippoclaw" 2>/dev/null || true
     done < <(
         find "$NODE_BOOTSTRAP_ROOT" -maxdepth 4 -type f -path '*/bin/node' -print 2>/dev/null \
@@ -1306,12 +1345,13 @@ remove_resolved_cli_openclaw_install() {
         node_bin_dir="$(cd "$(dirname "$cli_bin")" 2>/dev/null && pwd)" || break
         # npm global layout: <prefix>/bin/<cli> and <prefix>/lib/node_modules/openclaw.
         prefix="$(dirname "$node_bin_dir")"
-        pkg_root="$prefix/lib/node_modules/openclaw"
-        if [[ -d "$pkg_root" ]]; then
-            log_info "Removing openclaw package tree resolved via CLI on PATH: $pkg_root"
+        while IFS= read -r pkg_root; do
+            [[ -d "$pkg_root" ]] || continue
+            log_info "Removing gateway package tree resolved via CLI on PATH: $pkg_root"
             rm -rf "$pkg_root" 2>/dev/null || true
             removed_any=true
-        fi
+            break
+        done < <(global_gateway_package_dir_candidates "" "$prefix/lib/node_modules")
         rm -f "$node_bin_dir/openclaw" "$node_bin_dir/hippoclaw" 2>/dev/null || true
         # Bail if the same path still resolves (could not delete, e.g. permissions) to avoid looping.
         hash -r 2>/dev/null || true
@@ -1393,13 +1433,13 @@ uninstall_gateway() {
         log_error "npm not found"
         exit 1
     fi
-    npm uninstall -g openclaw 2>/dev/null || true
+    npm uninstall -g @agenthippo-ai/hippoclaw openclaw 2>/dev/null || true
     remove_managed_gateway_wrapper_state
     cleanup_shell_path_setup
     # Also remove the install wherever the CLI actually resolves (nvm/other Node global trees),
     # not just the active node + managed prefix that `npm uninstall -g` above covers.
     remove_resolved_cli_openclaw_install
-    log_success "Ran: npm uninstall -g openclaw (global tree removed if present)"
+    log_success "Ran: npm uninstall -g @agenthippo-ai/hippoclaw openclaw (global tree removed if present)"
     log_info "~/.openclaw was not removed (config, sessions, and credentials stay on disk)."
     local oc_after=""
     hash -r 2>/dev/null || true