Add Android (Termux) support for shell scripts

Open
#224 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
android, shell, typescript
Domain
backend, cli

Research direction

The proposed changes touch onboard.sh, openclaw.mjs, server.sh, and start-chrome-debug.sh. Read those scripts and trace their existing OS detection, Node launch, logging, browser opening, and Chrome debugging flows. Done means the Android and Termux paths described in the issue work while desktop behavior remains unchanged; the issue provides Android test evidence but no test file or command.

Written by the indexing model from the issue text.

Description

enhancement
Summary

Enable onboard.sh, server.sh, start-chrome-debug.sh, and openclaw.mjs to run correctly inside Termux on Android.

Problem to solve

The current scripts are designed exclusively for macOS, Linux, and Windows. They fail under Termux on Android because of missing OS detection, hardcoded paths (e.g., /tmp), mismatched browser launch commands, and unknown process.platform. Users who want to run OpenClaw on a phone or tablet are forced to use a separate desktop machine. This significantly degrades the mobile experience and limits adoption.

Proposed solution

· OS detection – Add an android branch in detect_os() by inspecting /proc/version and uname -a.
· Node.js memory – Automatically append --max-old-space-size=4096 (configurable via OPENCLAW_NODE_MEMORY) to prevent OOM kills in Termux’s constrained memory.
· Log paths – In tmp_log(), fall back to $SCRIPT_DIR/logs/ when /tmp is absent or not writable.
· Browser opening – Use am start on Android instead of xdg-open / open.
· Chrome debugging – In start-chrome-debug.sh, detect adb, pick the first online device, forward port 9222 via adb forward, and launch authorization URLs with adb shell am start. No local Chrome binary is required.
· Platform spoofing – In openclaw.mjs, override process.platform from 'android' to 'linux' so that Playwright and other libraries don’t reject the unknown platform.
· All changes are gated behind OS checks and do not alter behaviour on desktop platforms.

Alternatives considered

· Instructing users to edit the scripts manually – error-prone and discourages non-technical users.
· Recommending a VNC/remote desktop setup – adds hardware requirements and latency.
· Leaving the scripts unsupported on Android – prevents a growing mobile user base from ever using OpenClaw conveniently.

Impact

· Affected users: Anyone attempting to run OpenClaw inside Termux on Android.
· Severity: Medium – completely blocks the workflow on this platform but does not affect desktop users.
· Frequency: Always – every invocation of the scripts fails or misbehaves without these patches.
· Consequences: Users either give up or have to reverse-engineer the scripts; increased community support requests; missed opportunity to onboard mobile-first users.

Evidence/examples

The following files were modified and tested on Android 13 with Termux:

· onboard.sh – Android OS branch + Node memory flag.
· openclaw.mjs – process.platform spoof at the top.
· server.sh – Android-aware logging, browser launch, and memory flag.
· start-chrome-debug.sh – Complete adb device selection, port forwarding, and URL opening via am start.

Working logs and screen captures can be provided if needed.

onboard.sh
--- 原版onboard.sh
+++ onboard.sh (修改版)
@@ detect_os() {
     darwin*)  echo "mac" ;;
     msys*|cygwin*|mingw*) echo "win" ;;
     *)
       if grep -qi microsoft /proc/version 2>/dev/null; then
         echo "wsl"
+      elif [ -n "$(uname -a 2>/dev/null | grep -i android)" ]; then
+        echo "android"
       else
         echo "linux"
       fi
       ;;
@@ fi

+  # ─── Android 内存设置 ────────────────────────────────────
+  if [ "$OS" = "android" ]; then
+    NODE_MEMORY="--max-old-space-size=4096"
+    [ -n "$OPENCLAW_NODE_MEMORY" ] && NODE_MEMORY="--max-old-space-size=$OPENCLAW_NODE_MEMORY"
+  else
+    NODE_MEMORY=""
+  fi
+
@@ case "${1:-}" in
     webauth)
       ...
-      "$NODE" "$SCRIPT_DIR/openclaw.mjs" onboard webauth
+      $NODE $NODE_MEMORY "$SCRIPT_DIR/openclaw.mjs" onboard webauth
     ...
     onboard)
-      "$NODE" "$SCRIPT_DIR/openclaw.mjs" onboard "${@:2}"
+      $NODE $NODE_MEMORY "$SCRIPT_DIR/openclaw.mjs" onboard "${@:2}"
     ...
     gateway)
-      "$NODE" "$SCRIPT_DIR/openclaw.mjs" gateway "${@:2}"
+      $NODE $NODE_MEMORY "$SCRIPT_DIR/openclaw.mjs" gateway "${@:2}"
     ...
     *)
-      "$NODE" "$SCRIPT_DIR/openclaw.mjs" "$@"
+      $NODE $NODE_MEMORY "$SCRIPT_DIR/openclaw.mjs" "$@"
openclaw.mjs
--- 原版openclaw.mjs
+++ openclaw.mjs (修改版)
@@ #!/usr/bin/env node

+  // Termux / Android: 伪装为 Linux,让 Playwright 等库正常工作
+  if (process.platform === 'android') {
+    Object.defineProperty(process, 'platform', { value: 'linux' });
+  }
+
   import module from "node:module";
   ...
server.sh
--- 原版server.sh
+++ server.sh (修改版)
@@ detect_os() {
     darwin*)  echo "mac" ;;
     msys*|cygwin*|mingw*) echo "win" ;;
     *)
       if grep -qi microsoft /proc/version 2>/dev/null; then
         echo "wsl"
+      elif [ -n "$(uname -a 2>/dev/null | grep -i android)" ]; then
+        echo "android"
       else
         echo "linux"
       fi
       ;;
@@ open_browser() {
     mac) open "$url" ;;
     win) start "" "$url" 2>/dev/null || ... ;;
     wsl) cmd.exe /c start "" "$url" 2>/dev/null ;;
+    android)
+      if command -v am >/dev/null 2>&1; then
+        am start -a android.intent.action.VIEW -d "$url" >/dev/null 2>&1 &
+        echo "已通过 am 命令打开浏览器访问 Gateway"
+      else
+        echo "请在手机浏览器中手动打开: $url"
+      fi
+      ;;
     linux)
       if command -v xdg-open >/dev/null 2>&1; then
         xdg-open "$url" 2>/dev/null &
@@ tmp_log() {
-   if [ -d /tmp ]; then
-     echo "/tmp/openclaw-upstream-gateway.log"
+   if [ "$OS" = "android" ] || ! [ -d /tmp ] || ! [ -w /tmp ]; then
+     echo "$SCRIPT_DIR/logs/openclaw-upstream-gateway${OPENCLAW_INSTANCE_SUFFIX:-}.log"
    else
-     echo "$SCRIPT_DIR/logs/openclaw-upstream-gateway.log"
+     echo "/tmp/openclaw-upstream-gateway${OPENCLAW_INSTANCE_SUFFIX:-}.log"
    fi
@@ start_gateway() {
    ...
+   # Android 内存优化
+   if [ "$OS" = "android" ]; then
+     NODE_MEMORY="--max-old-space-size=4096"
+     [ -n "$OPENCLAW_NODE_MEMORY" ] && NODE_MEMORY="--max-old-space-size=$OPENCLAW_NODE_MEMORY"
+   else
+     NODE_MEMORY=""
+   fi
+
-   nohup "$NODE" "$SCRIPT_DIR/openclaw.mjs" gateway --port "$PORT" > "$TMP_LOG" 2>&1 &
+   nohup "$NODE" $NODE_MEMORY "$SCRIPT_DIR/openclaw.mjs" gateway --port "$PORT" > "$TMP_LOG" 2>&1 &
start-chrome-debug.sh
--- 原版start-chrome-debug.sh
+++ start-chrome-debug.sh (修改版)
@@ detect_os() {
     Darwin*)  echo "mac" ;;
     MINGW*|MSYS*|CYGWIN*) echo "win" ;;
     *)
+      if [ -n "$(uname -o 2>/dev/null | grep -i android)" ] || \
+         [ -n "$(uname -a 2>/dev/null | grep -i android)" ]; then
+        echo "android"
       if grep -qi microsoft /proc/version 2>/dev/null; then
         echo "wsl"
       else
@@ detect_chrome() {
+   if [ "$OS" = "android" ]; then
+     command -v adb >/dev/null 2>&1 && echo "adb-chrome" || echo ""
+     return
+   fi
    ...
@@ detect_user_data_dir() {
+   if [ "$OS" = "android" ]; then
+     echo ""
+     return
+   fi
    case "$OS" in
@@ # ─── 单实例管理(Android 下不杀 Chrome)────────────────────
+ if [ "$OS" != "android" ]; then
    if pgrep -f "chrome.*remote-debugging-port=9222" > /dev/null 2>&1; then
      ...
    fi
+ fi
@@ # ─── 启动 Chrome 并设置转发(Android)/直接启动(桌面)────────
+ if [ "$OS" = "android" ]; then
+   echo "正在启动手机 Chrome..."
+   adb -s "$ADB_DEVICE" shell am start -n com.android.chrome/org.chromium.chrome.browser.ChromeTabbedActivity
+   sleep 2
+   echo "正在设置 adb 转发 (tcp:9222 -> localabstract:chrome_devtools_remote)..."
+   adb -s "$ADB_DEVICE" forward --remove tcp:9222 2>/dev/null
+   if adb -s "$ADB_DEVICE" forward tcp:9222 localabstract:chrome_devtools_remote; then
+     echo "✓ 转发设置成功"
+   else
+     ...
+     exit 1
+   fi
+ else
    "$CHROME_PATH" \
      --remote-debugging-port=9222 \
      ... &
+ fi
@@ # ─── 打开网页(Android 分支)───────────────────────────────
    WEB_URLS=(...)
+   if [ "$OS" = "android" ]; then
+     for url in "${WEB_URLS[@]}"; do
+       echo "  打开: $url"
+       adb -s "$ADB_DEVICE" shell am start -a android.intent.action.VIEW -d "$url" -n com.android.chrome/org.chromium.chrome.browser.ChromeTabbedActivity >/dev/null 2>&1 &
+       sleep 0.5
+     done
+   else
      for url in "${WEB_URLS[@]}"; do
        "$CHROME_PATH" --remote-debugging-port=9222 --user-data-dir="$USER_DATA_DIR" "$url" > /dev/null 2>&1 &
        sleep 0.5
      done
+   fi
@@ # ─── 停止提示 ─────────────────────────────────────────────
+   if [ "$OS" = "android" ]; then
+     echo "停止调试(移除转发):"
+     echo "  adb -s $ADB_DEVICE forward --remove tcp:9222"
+   else
      echo "停止调试模式:"
      echo "  pkill -f 'chrome.*remote-debugging-port=9222'"
+   fi

onboard.sh.txt
openclaw.mjs.txt
server.sh.txt
start-chrome-debug.sh.txt

Additional information

· All new code paths are strictly opt-in for the android OS identifier and do not touch existing logic.
· The changes follow the repository’s existing style and shell conventions.
· The modifications have been running stably for multiple days without side effects on both Android and desktop (macOS/Linux) machines.

Dominant language
TypeScript
Stars
5.2k
Forks
1.2k
PR merge metrics
No merged PRs in 30d

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from linuxhsj/openclaw-zero-token

All issues in linuxhsj/openclaw-zero-token

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.