wehub/aidanpark--openclaw-android
1
0
Fork 0
Code Issues Pull Requests Actions 2 Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default
Code Quality / ShellCheck (push) Waiting to run
Details
Code Quality / Script Sync Check (push) Waiting to run
Details
Code Quality / Markdown Lint (push) Waiting to run
Details
Code Quality / Document Freshness (push) Waiting to run
Details
Code Quality / Unit Tests (push) Waiting to run
Details
Code Quality / Kotlin Lint (push) Waiting to run
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:58:42 +00:00
parent 1bf491a920
commit 1d852f1cd4
1 changed files with 348 additions and 337 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+348 -337
View File
@@ -1,6 +1,12 @@
<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/AidanPark/openclaw-android) · [上游 README](https://github.com/AidanPark/openclaw-android/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# OpenClaw on Android
[한국어](README.ko.md) | [中文](README.zh.md)
[English](README.md) | [한국어](README.ko.md)
<img src="docs/images/openclaw_android.jpg" alt="OpenClaw on Android">
@@ -10,13 +16,13 @@
![License MIT](https://img.shields.io/github/license/AidanPark/openclaw-android)
![GitHub Stars](https://img.shields.io/github/stars/AidanPark/openclaw-android)
Because Android deserves a shell.
Android 也配拥有一个 Shell。
## No Linux install required
## 无需安装 Linux
The standard approach to running OpenClaw on Android requires installing proot-distro with Linux, adding 700MB-1GB of overhead. OpenClaw on Android eliminates this by installing just the glibc dynamic linker (ld.so), letting you run OpenClaw without a full Linux distribution.
在 Android 上运行 OpenClaw 的常规方法是通过 proot-distro 安装一个完整的 Linux 发行版，需要额外占用 700MB-1GB 的存储空间。OpenClaw on Android 只安装 glibc 动态链接器（ld.so），无需完整 Linux 发行版即可运行 OpenClaw。
**Standard approach**: Install a full Linux distribution in Termux via proot-distro.
**常规方法**：在 Termux 中通过 proot-distro 安装完整的 Linux 发行版。
```
┌───────────────────────────────────────────────────┐
@@ -34,7 +40,7 @@ The standard approach to running OpenClaw on Android requires installing proot-d
└───────────────────────────────────────────────────┘
```
**This project**: No proot-distro — just the glibc dynamic linker.
**本项目**：无需 proot-distro，只安装 glibc 动态链接器。
```
┌───────────────────────────────────────────────────┐
@@ -49,357 +55,362 @@ The standard approach to running OpenClaw on Android requires installing proot-d
└───────────────────────────────────────────────────┘
```
| | Standard (proot-distro) | This project |
| | 常规方法 (proot-distro) | 本项目 |
|---|---|---|
| Storage overhead | 1-2GB (Linux + packages) | ~200MB |
| Setup time | 20-30 min | 3-10 min |
| Performance | Slower (proot layer) | Native speed |
| Setup steps | Install distro, configure Linux, install Node.js, fix paths... | Run one command |
| 存储开销 | 1-2GB（Linux + 软件包） | ~200MB |
| 安装时间 | 20-30 分钟 | 3-10 分钟 |
| 性能 | 较慢（proot 中间层） | 原生速度 |
| 安装步骤 | 安装发行版、配置 Linux、安装 Node.js、修复路径…… | 一条命令搞定 |
## <img src="docs/images/claw-icon.svg" width="28" alt="Claw icon"> Claw App
A standalone Android app is also available. It bundles a terminal emulator and a WebView-based UI into a single APK — no Termux required.
还提供了独立的 Android 应用。它将终端模拟器和基于 WebView 的界面打包成一个 APK，无需 Termux。
- One-tap setup: bootstrap, Node.js, and OpenClaw installed from within the app
- Built-in dashboard for gateway control, runtime info, and tool management
- Works independently of Termux — installing the app does not affect an existing Termux + `oa` setup
- 一键安装：在应用内完成 bootstrap、Node.js 和 OpenClaw 的安装
- 内置仪表盘：控制网关、查看运行状态、管理工具
- 独立于 Termux 运行 — 安装此应用不会影响已有的 Termux + `oa` 环境
Download the APK from the [Releases](https://github.com/AidanPark/openclaw-android/releases) page.
前往 [Releases](https://github.com/AidanPark/openclaw-android/releases) 页面下载 APK。
## Requirements
> **中国用户**：如果无法直接从 GitHub 下载，可使用镜像链接：
> [ghfast.top 镜像下载](https://ghfast.top/https://github.com/AidanPark/openclaw-android/releases/latest/download/app-release.apk)
- Android 7.0 or higher (Android 10+ recommended)
- ~1GB free storage
- Wi-Fi or mobile data connection
## 系统要求
## What It Does
- Android 7.0 或更高版本（推荐 Android 10+）
- 约 1GB 可用存储空间
- Wi-Fi 或移动数据连接
The installer automatically resolves the differences between Termux and standard Linux. There's nothing you need to do manually — the single install command handles all of these:
## 安装内容
1. **glibc environment** — Installs the glibc dynamic linker (via pacman's glibc-runner) so standard Linux binaries run without modification
2. **Node.js (glibc)** — Downloads official Node.js linux-arm64 and wraps it with an ld.so loader script (no patchelf, which causes segfault on Android)
3. **Path conversion** — Automatically converts standard Linux paths (`/tmp`, `/bin/sh`, `/usr/bin/env`) to Termux paths
4. **Temp folder setup** — Configures an accessible temp folder for Android
5. **Service manager bypass** — Configures normal operation without systemd
6. **OpenCode integration** — If selected, installs OpenCode using proot + ld.so concatenation for Bun standalone binaries
安装程序会自动处理 Termux 与标准 Linux 之间的差异。你无需手动操作——一条安装命令会完成以下所有工作：
## Step-by-Step Setup (from a fresh phone)
1. **glibc 环境** — 安装 glibc 动态链接器（通过 pacman 的 glibc-runner），使标准 Linux 二进制文件无需修改即可运行
2. **Node.js (glibc)** — 下载官方 Node.js linux-arm64 版本，并通过 ld.so 加载脚本进行包装（不使用 patchelf，因为它会在 Android 上导致段错误）
3. **路径转换** — 自动将标准 Linux 路径（`/tmp`、`/bin/sh`、`/usr/bin/env`）转换为 Termux 路径
4. **临时目录配置** — 为 Android 配置可访问的临时文件夹
5. **服务管理绕过** — 在没有 systemd 的环境下配置正常运行
6. **OpenCode 集成** — 如果选择安装，会使用 proot + ld.so 拼接方式安装 OpenCode（用于 Bun 独立二进制文件）
1. [Prepare Your Phone](#step-1-prepare-your-phone)
2. [Install Termux](#step-2-install-termux)
3. [Initial Termux Setup](#step-3-initial-termux-setup)
4. [Install OpenClaw](#step-4-install-openclaw) — one command
5. [Start OpenClaw Setup](#step-5-start-openclaw-setup)
6. [Start OpenClaw (Gateway)](#step-6-start-openclaw-gateway)
## 从全新手机开始的详细步骤
### Step 1: Prepare Your Phone
1. [准备你的手机](#步骤一准备你的手机)
2. [安装 Termux](#步骤二安装-termux)
3. [Termux 初始设置](#步骤三termux-初始设置)
4. [安装 OpenClaw](#步骤四安装-openclaw) — 一条命令
5. [启动 OpenClaw 初始配置](#步骤五启动-openclaw-初始配置)
6. [启动 OpenClaw（网关）](#步骤六启动-openclaw网关)
Configure Developer Options, Stay Awake, charge limit, and battery optimization. See the [Keeping Processes Alive guide](docs/disable-phantom-process-killer.md) for step-by-step instructions.
### 步骤一：准备你的手机
### Step 2: Install Termux
配置开发者选项、保持唤醒、充电限制和电池优化。详细步骤请参阅 [保持进程存活指南](docs/disable-phantom-process-killer.md)。
> **Important**: The Play Store version of Termux is discontinued and will not work. You must install from F-Droid.
### 步骤二：安装 Termux
1. Open your phone's browser and go to [f-droid.org](https://f-droid.org)
2. Search for `Termux`, then tap **Download APK** to download and install
- Allow "Install from unknown sources" when prompted
> **重要提示**：Play Store 版本的 Termux 已停止维护，无法正常使用。必须从 F-Droid 安装。
### Step 3: Initial Termux Setup
1. 用手机浏览器打开 [f-droid.org](https://f-droid.org)
2. 搜索 `Termux`，然后点击 **Download APK** 下载并安装
- 提示时请允许"安装来自未知来源的应用"
Open the Termux app and paste the following command to install curl (needed for the next step).
### 步骤三：Termux 初始设置
打开 Termux 应用，粘贴以下命令安装 curl（下一步需要用到）。
```bash
pkg update -y && pkg install -y curl
```
> You may be asked to choose a mirror on first run. Pick any — a geographically closer mirror will be faster.
> 首次运行时可能会要求你选择镜像源。随便选一个就行，选地理位置较近的会更快。
### Step 4: Install OpenClaw
### 步骤四：安装 OpenClaw
> **Tip: Use SSH for easier typing**
> From this step on, you can type commands from your computer keyboard instead of the phone screen. See the [Termux SSH Setup Guide](docs/termux-ssh-guide.md) for details.
> **提示：使用 SSH 输入更方便**
> 从这一步开始，你可以用电脑键盘输入命令，而不必在手机屏幕上打字。详见 [Termux SSH 设置指南](docs/termux-ssh-guide.md)。
Paste the following command in Termux.
在 Termux 中粘贴以下命令。
```bash
curl -sL myopenclawhub.com/install | bash && source ~/.bashrc
```
Everything is installed automatically with a single command. This takes 3–10 minutes depending on network speed and device. Wi-Fi is recommended.
一条命令自动完成所有安装。根据网络速度和设备性能，大约需要 3-10 分钟。建议使用 Wi-Fi。
Once complete, the OpenClaw version is displayed along with instructions to run `openclaw onboard`.
> **中国网络优化**：脚本会自动检测网络环境。如果 GitHub 访问较慢，会自动切换到镜像站点下载；如果 npm 安装速度较慢，会自动切换到 npmmirror.com 镜像。无需手动配置。
### Step 5: Start OpenClaw Setup
安装完成后，会显示 OpenClaw 版本以及运行 `openclaw onboard` 的提示。
As instructed in the installation output, run:
### 步骤五：启动 OpenClaw 初始配置
按照安装输出中的提示，运行：
```bash
openclaw onboard
```
Follow the on-screen instructions to complete the initial setup.
按照屏幕上的指引完成初始设置。
![openclaw onboard](docs/images/openclaw-onboard.png)
### Step 6: Start OpenClaw (Gateway)
### 步骤六：启动 OpenClaw（网关）
Once setup is complete, start the gateway:
初始设置完成后，启动网关：
> **Important**: Run `openclaw gateway` directly in the Termux app on your phone, not via SSH. If you run it over SSH, the gateway will stop when the SSH session disconnects.
> **重要提示**：请直接在手机上的 Termux 应用中运行 `openclaw gateway`，不要通过 SSH。如果通过 SSH 运行，当 SSH 会话断开时网关也会停止。
The gateway occupies the terminal while running, so open a new tab for it. Tap the **hamburger icon (☰)** on the bottom menu bar, or swipe right from the left edge of the screen (above the bottom menu bar) to open the side menu. Then tap **NEW SESSION**.
网关运行时会占用当前终端，因此需要新开一个标签页。点击底部菜单栏的 **汉堡菜单图标（☰）**，或从屏幕左侧边缘向右滑动（在底部菜单栏上方区域）打开侧边菜单，然后点击 **NEW SESSION**。
<img src="docs/images/termux_menu.png" width="300" alt="Termux side menu">
<img src="docs/images/termux_menu.png" width="300" alt="Termux 侧边菜单">
In the new tab, run:
在新标签页中运行：
```bash
openclaw gateway
```
<img src="docs/images/termux_tab_1.png" width="300" alt="openclaw gateway running">
<img src="docs/images/termux_tab_1.png" width="300" alt="openclaw gateway 运行中">
> To stop the gateway, press `Ctrl+C`. Do not use `Ctrl+Z` — it only suspends the process without terminating it.
> 要停止网关，按 `Ctrl+C`。不要使用 `Ctrl+Z` — 它只会挂起进程而不会终止它。
## Keeping Processes Alive
## 保持进程存活
Android may kill background processes or throttle them when the screen is off. See the [Keeping Processes Alive guide](docs/disable-phantom-process-killer.md) for all recommended settings (Developer Options, Stay Awake, charge limit, battery optimization, and Phantom Process Killer).
Android 可能会在屏幕关闭时杀死后台进程或对其进行限制。详细的推荐设置请参阅 [保持进程存活指南](docs/disable-phantom-process-killer.md)（开发者选项、保持唤醒、充电限制、电池优化和 Phantom Process Killer）。
## Access the Dashboard from Your PC
## 从电脑访问仪表盘
See the [Termux SSH Setup Guide](docs/termux-ssh-guide.md) for SSH access and dashboard tunnel setup.
请参阅 [Termux SSH 设置指南](docs/termux-ssh-guide.md) 了解 SSH 访问和仪表盘隧道设置。
## Managing Multiple Devices
## 管理多台设备
If you run OpenClaw on multiple devices on the same network, use the <a href="https://myopenclawhub.com" target="_blank">Dashboard Connect</a> tool to manage them from your PC.
如果你在同一网络中的多台设备上运行 OpenClaw，可以使用 <a href="https://myopenclawhub.com" target="_blank">Dashboard Connect</a> 工具从电脑统一管理。
- Save connection settings (IP, token, ports) for each device with a nickname
- Generates the SSH tunnel command and dashboard URL automatically
- **Your data stays local** — Connection settings (IP, token, ports) are saved only in your browser's localStorage and are never sent to any server.
- 为每台设备保存连接设置（IP、令牌、端口），并设置昵称
- 自动生成 SSH 隧道命令和仪表盘 URL
- **数据留在本地** — 连接设置（IP、令牌、端口）仅保存在浏览器的 localStorage 中，永远不会发送到任何服务器。
## CLI Reference
## CLI 参考
After installation, the `oa` command is available for managing your installation:
安装完成后，可以使用 `oa` 命令管理你的安装：
| Option | Description |
| 选项 | 说明 |
|--------|-------------|
| `oa --update` | Update OpenClaw and Android patches |
| `oa --install` | Install optional tools (tmux, code-server, AI CLIs, etc.) |
| `oa --uninstall` | Remove OpenClaw on Android |
| `oa --backup` | Create a full backup of OpenClaw data |
| `oa --restore` | Restore from a backup |
| `oa --status` | Show installation status and all installed components |
| `oa --version` | Show version |
| `oa --help` | Show available options |
| `oa --update` | 更新 OpenClaw 和 Android 补丁 |
| `oa --install` | 安装可选工具（tmux、code-server、AI CLI 等） |
| `oa --uninstall` | 卸载 OpenClaw on Android |
| `oa --backup` | 创建 OpenClaw 数据的完整备份 |
| `oa --restore` | 从备份恢复 |
| `oa --status` | 显示安装状态和所有已安装组件 |
| `oa --version` | 显示版本 |
| `oa --help` | 显示可用选项 |
## Update
## 更新
```bash
oa --update && source ~/.bashrc
```
This single command updates all installed components at once:
一条命令更新所有已安装组件：
- **OpenClaw** — Core package (`openclaw@latest`)
- **code-server** — Browser IDE
- **OpenCode** — AI coding assistant
- **AI CLI tools** — Claude Code, Gemini CLI, Codex CLI (Termux)
- **Android patches** — Compatibility patches from this project
- **OpenClaw** — 核心包（`openclaw@latest`）
- **code-server** — 浏览器 IDE
- **OpenCode** — AI 编程助手
- **AI CLI 工具** — Claude Code、Gemini CLI、Codex CLI (Termux)
- **Android 补丁** — 本项目的兼容性补丁
Already up-to-date components are skipped. Components you haven't installed are not touched — only what's already on your device gets updated. Safe to run multiple times.
已是最新的组件会被跳过。未安装的组件不会被触及——只更新设备上已有的内容。可以多次安全运行。
> If the `oa` command is not available (older installations), run it with curl:
> 如果 `oa` 命令不可用（旧版安装），请使用 curl 运行：
> ```bash
> curl -sL myopenclawhub.com/update | bash && source ~/.bashrc
> ```
## Backup & Restore
## 备份与恢复
OpenClaw's built-in backup command (`openclaw backup create`) often fails on Android because it relies on hardlinks, which are blocked in Android's app-private storage. The `oa --backup` command works around this by using `tar` directly while maintaining full compatibility with the OpenClaw backup specification.
OpenClaw 内置的备份命令（`openclaw backup create`）在 Android 上经常失败，因为它依赖硬链接，而 Android 的应用私有存储会阻止硬链接操作。`oa --backup` 命令通过直接使用 `tar` 来解决这个问题，同时完全兼容 OpenClaw 的备份规范。
To create a backup:
创建备份：
```bash
oa --backup
```
Backups are stored in `~/.openclaw-android/backup/` with a timestamped filename (e.g., `2026-03-14T00-00-00.000Z-openclaw-backup.tar.gz`). You can also specify a custom path: `oa --backup ~/my-backups/`. Each backup includes your configuration, state, workspaces, and agents.
备份存储在 `~/.openclaw-android/backup/` 目录下，文件名带有时间戳（例如 `2026-03-14T00-00-00.000Z-openclaw-backup.tar.gz`）。你也可以指定自定义路径：`oa --backup ~/my-backups/`。每次备份包含你的配置、状态、工作区和代理。
To restore from a backup:
从备份恢复：
```bash
oa --restore
```
This command lists all available backups in the default backup directory. Simply select the number of the backup you wish to restore. The tool automatically detects the platform from the backup manifest and handles the restoration to `~/.openclaw/`. Note that this will overwrite existing data, so a confirmation is required.
此命令会列出默认备份目录中所有可用的备份。只需选择你要恢复的备份编号即可。工具会自动从备份清单中检测平台并将数据恢复到 `~/.openclaw/`。注意这会覆盖现有数据，因此需要确认。
## Troubleshooting
## 故障排除
See the [Troubleshooting Guide](docs/troubleshooting.md) for detailed solutions.
请参阅 [故障排除指南](docs/troubleshooting.md) 获取详细解决方案。
## Performance
## 性能
CLI commands like `openclaw status` may feel slower than on a PC. This is because each command needs to read many files, and the phone's storage is slower than a PC's, with Android's security processing adding overhead.
`openclaw status` 等 CLI 命令可能比在 PC 上运行时感觉更慢。这是因为每条命令需要读取大量文件，而手机存储比 PC 慢，加上 Android 安全机制带来的额外开销。
However, **once the gateway is running, there's no difference**. The process stays in memory so files don't need to be re-read, and AI responses are processed on external servers — the same speed as on a PC.
不过，**一旦网关启动后，就没有区别了**。进程驻留在内存中，无需重新读取文件，而 AI 响应由外部服务器处理——速度与 PC 上相同。
## Local LLM on Android
## Android 本地 LLM
OpenClaw supports local LLM inference via [node-llama-cpp](https://github.com/withcatai/node-llama-cpp). The prebuilt native binary (`@node-llama-cpp/linux-arm64`) is included with the installation and loads successfully under the glibc environment — **local LLM is technically functional on the phone**.
OpenClaw 通过 [node-llama-cpp](https://github.com/withcatai/node-llama-cpp) 支持本地 LLM 推理。预构建的原生二进制文件（`@node-llama-cpp/linux-arm64`）已包含在安装中，并能在 glibc 环境下成功加载——**本地 LLM 在手机上技术上是可行的**。
However, there are practical constraints:
但存在一些实际限制：
| Constraint | Details |
| 限制因素 | 详情 |
|------------|---------|
| RAM | GGUF models need at least 2-4GB of free memory (7B model, Q4 quantization). Phone RAM is shared with Android and other apps |
| Storage | Model files range from 4GB to 70GB+. Phone storage fills up fast |
| Speed | CPU-only inference on ARM is very slow. Android does not support GPU offloading for llama.cpp |
| Use case | OpenClaw primarily routes to cloud LLM APIs (OpenAI, Gemini, etc.) which respond at the same speed as on a PC. Local inference is a supplementary feature |
| 内存 | GGUF 模型至少需要 2-4GB 可用内存（7B 模型，Q4 量化）。手机内存与 Android 和其他应用共享 |
| 存储 | 模型文件大小从 4GB 到 70GB+ 不等。手机存储空间很快就会用完 |
| 速度 | ARM 上的纯 CPU 推理非常慢。Android 不支持 llama.cpp 的 GPU 加速 |
| 使用场景 | OpenClaw 主要调用云端 LLM API（OpenAI、Gemini 等），响应速度与 PC 上相同。本地推理是辅助功能 |
For experimentation, small models like TinyLlama 1.1B (Q4, ~670MB) can run on the phone. For production use, cloud LLM providers are recommended.
如需体验，可以在手机上运行 TinyLlama 1.1B（Q4，约 670MB）等小型模型。生产环境建议使用云端 LLM 服务。
> **Why `--ignore-scripts`?** The installer uses `npm install -g openclaw@latest --ignore-scripts` because node-llama-cpp's postinstall script attempts to compile llama.cpp from source via cmake — a process that takes 30+ minutes on a phone and fails due to toolchain incompatibilities. The prebuilt binaries work without this compilation step, so the postinstall is safely skipped.
> **为什么使用 `--ignore-scripts`？** 安装程序使用 `npm install -g openclaw@latest --ignore-scripts`，因为 node-llama-cpp 的 postinstall 脚本会尝试通过 cmake 从源码编译 llama.cpp——在手机上需要 30 分钟以上且会因工具链不兼容而失败。预构建的二进制文件无需此编译步骤即可工作，因此可以安全跳过 postinstall。
<details>
<summary>Technical Documentation for Developers</summary>
<summary>面向开发者的技术文档</summary>
## Installed Components
## 已安装组件
The installer sets up infrastructure, platform packages, and optional tools across multiple package managers. Core infrastructure and platform dependencies are installed automatically; optional tools are individually prompted during install.
安装程序会跨多个包管理器设置基础设施、平台包和可选工具。核心基础设施和平台依赖会自动安装；可选工具在安装过程中逐个提示。
### Core Infrastructure
### 核心基础设施
| Component | Role | Install Method |
| 组件 | 作用 | 安装方式 |
|-----------|------|----------------|
| git | Version control, npm git dependencies | `pkg install` |
| git | 版本控制，npm git 依赖 | `pkg install` |
### Agent Platform Runtime Dependencies
### Agent 平台运行时依赖
These are controlled by the platform's `config.env` flags. For OpenClaw, all are installed:
这些由平台的 `config.env` 标志控制。对于 OpenClaw，全部安装：
| Component | Role | Install Method |
| 组件 | 作用 | 安装方式 |
|-----------|------|----------------|
| [pacman](https://wiki.archlinux.org/title/Pacman) | Package manager for glibc packages | `pkg install` |
| [glibc-runner](https://github.com/termux-pacman/glibc-packages) | glibc dynamic linker — enables standard Linux binaries on Android | `pacman -Sy` |
| [Node.js](https://nodejs.org/) v22 LTS (linux-arm64) | JavaScript runtime for OpenClaw | Direct download from nodejs.org |
| python | Build scripts for native C/C++ addons (node-gyp) | `pkg install` |
| make | Makefile execution for native modules | `pkg install` |
| cmake | CMake-based native module builds | `pkg install` |
| clang | C/C++ compiler for native modules | `pkg install` |
| binutils | Binary utilities (llvm-ar) for native builds | `pkg install` |
| [pacman](https://wiki.archlinux.org/title/Pacman) | glibc 包的包管理器 | `pkg install` |
| [glibc-runner](https://github.com/termux-pacman/glibc-packages) | glibc 动态链接器 — 使标准 Linux 二进制文件能在 Android 上运行 | `pacman -Sy` |
| [Node.js](https://nodejs.org/) v22 LTS (linux-arm64) | OpenClaw 的 JavaScript 运行时 | 从 nodejs.org 直接下载 |
| python | 原生 C/C++ 扩展的构建脚本 (node-gyp) | `pkg install` |
| make | 原生模块的 Makefile 执行 | `pkg install` |
| cmake | 基于 CMake 的原生模块构建 | `pkg install` |
| clang | 原生模块的 C/C++ 编译器 | `pkg install` |
| binutils | 原生构建的二进制工具 (llvm-ar) | `pkg install` |
### OpenClaw Platform
### OpenClaw 平台
| Component | Role | Install Method |
| 组件 | 作用 | 安装方式 |
|-----------|------|----------------|
| [OpenClaw](https://github.com/openclaw/openclaw) | AI agent platform (core) | `npm install -g` |
| [clawdhub](https://github.com/AidanPark/clawdhub) | Skill manager for OpenClaw | `npm install -g` |
| [PyYAML](https://pyyaml.org/) | YAML parser for `.skill` packaging | `pip install` |
| libvips | Image processing headers for sharp build | `pkg install` (on update) |
| [OpenClaw](https://github.com/openclaw/openclaw) | AI Agent 平台（核心） | `npm install -g` |
| [clawdhub](https://github.com/AidanPark/clawdhub) | OpenClaw 的技能管理器 | `npm install -g` |
| [PyYAML](https://pyyaml.org/) | `.skill` 打包的 YAML 解析器 | `pip install` |
| libvips | sharp 构建所需的图像处理头文件 | `pkg install`（更新时） |
### Optional Tools (prompted during install)
### 可选工具（安装时提示）
Each tool is offered via an individual Y/n prompt. You choose which ones to install.
每个工具都会通过单独的 Y/n 提示。你可以选择安装哪些。
| Component | Role | Install Method |
| 组件 | 作用 | 安装方式 |
|-----------|------|----------------|
| [tmux](https://github.com/tmux/tmux) | Terminal multiplexer for background sessions | `pkg install` |
| [ttyd](https://github.com/tsl0922/ttyd) | Web terminal — access Termux from a browser | `pkg install` |
| [dufs](https://github.com/sigoden/dufs) | HTTP/WebDAV file server for browser-based file transfer | `pkg install` |
| [android-tools](https://developer.android.com/tools/adb) | ADB for disabling Phantom Process Killer | `pkg install` |
| [code-server](https://github.com/coder/code-server) | Browser-based VS Code IDE | Direct download from GitHub |
| [OpenCode](https://opencode.ai/) | AI coding assistant (TUI). Auto-installs [Bun](https://bun.sh/) and [proot](https://proot-me.github.io/) as dependencies | `bun install -g` |
| [Chromium](https://www.chromium.org/) | Browser automation for OpenClaw (~400MB) | Custom install script |
| [Playwright](https://playwright.dev/) | Browser automation library (requires Chromium). Auto-configures `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | Custom install script |
| [Claude Code](https://github.com/anthropics/claude-code) (Anthropic) | AI CLI tool | `npm install -g` |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) (Google) | AI CLI tool | `npm install -g` |
| [Codex CLI](https://github.com/DioNanos/codex-termux) (Termux fork of OpenAI Codex) | AI CLI tool | `npm install -g` |
| [tmux](https://github.com/tmux/tmux) | 终端复用器，用于后台会话 | `pkg install` |
| [ttyd](https://github.com/tsl0922/ttyd) | Web 终端 — 从浏览器访问 Termux | `pkg install` |
| [dufs](https://github.com/sigoden/dufs) | HTTP/WebDAV 文件服务器，用于浏览器文件传输 | `pkg install` |
| [android-tools](https://developer.android.com/tools/adb) | ADB，用于禁用 Phantom Process Killer | `pkg install` |
| [code-server](https://github.com/coder/code-server) | 基于浏览器的 VS Code IDE | 从 GitHub 直接下载 |
| [OpenCode](https://opencode.ai/) | AI 编程助手 (TUI)。自动安装 [Bun](https://bun.sh/) 和 [proot](https://proot-me.github.io/) 作为依赖 | `bun install -g` |
| [Chromium](https://www.chromium.org/) | OpenClaw 的浏览器自动化支持（约 400MB） | 自定义安装脚本 |
| [Playwright](https://playwright.dev/) | 浏览器自动化库（需要 Chromium）。自动配置 `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` | 自定义安装脚本 |
| [Claude Code](https://github.com/anthropics/claude-code) (Anthropic) | AI CLI 工具 | `npm install -g` |
| [Gemini CLI](https://github.com/google-gemini/gemini-cli) (Google) | AI CLI 工具 | `npm install -g` |
| [Codex CLI](https://github.com/DioNanos/codex-termux)（OpenAI Codex 的 Termux 分支） | AI CLI 工具 | `npm install -g` |
## Project Structure
## 项目结构
```
openclaw-android/
├── bootstrap.sh # curl | bash one-liner installer (downloader)
├── install.sh # Platform-aware installer (entry point)
├── oa.sh # Unified CLI (installed as $PREFIX/bin/oa)
├── post-setup.sh # Claw App post-bootstrap setup (OTA delivery)
├── update.sh # Thin wrapper (downloads and runs update-core.sh)
├── update-core.sh # Lightweight updater for existing installations
├── uninstall.sh # Clean removal (orchestrator)
├── bootstrap.sh # curl | bash 一行安装命令（下载器）
├── install.sh # 平台感知安装程序（入口点）
├── oa.sh # 统一 CLI（安装到 $PREFIX/bin/oa）
├── post-setup.sh # Claw App 引导后设置（OTA 分发）
├── update.sh # 薄包装器（下载并运行 update-core.sh）
├── update-core.sh # 轻量级更新程序（用于已有安装）
├── uninstall.sh # 完整卸载（编排器）
├── patches/
│ ├── glibc-compat.js # Node.js runtime patches (os.cpus, networkInterfaces)
│ ├── argon2-stub.js # JS stub for argon2 native module (code-server)
│ ├── termux-compat.h # C header for Bionic native builds (sharp)
│ ├── spawn.h # POSIX spawn stub header
│ ├── systemctl # systemd stub for Termux
│ ├── apply-patches.sh # Legacy patch orchestrator (v1.0.2 compat)
│ └── patch-paths.sh # Legacy path fixer (v1.0.2 compat)
│ ├── glibc-compat.js # Node.js 运行时补丁（os.cpus、networkInterfaces）
│ ├── argon2-stub.js # argon2 原生模块的 JS 桩（code-server）
│ ├── termux-compat.h # Bionic 原生构建的 C 头文件（sharp）
│ ├── spawn.h # POSIX spawn 桩头文件
│ ├── systemctl # Termux 的 systemd 桩
│ ├── apply-patches.sh # 旧版补丁编排器（v1.0.2 兼容）
│ └── patch-paths.sh # 旧版路径修复器（v1.0.2 兼容）
├── scripts/
│ ├── lib.sh # Shared function library (colors, platform detection, prompts)
│ ├── check-env.sh # Pre-flight environment check
│ ├── install-infra-deps.sh # Core infrastructure packages (L1)
│ ├── install-glibc.sh # glibc-runner installation (L2 conditional)
│ ├── install-nodejs.sh # Node.js glibc wrapper installation (L2 conditional)
│ ├── install-build-tools.sh # Build tools for native modules (L2 conditional)
│ ├── backup.sh # Backup and restore OpenClaw data (oa --backup/--restore)
│ ├── build-sharp.sh # Build sharp native module (image processing)
│ ├── install-chromium.sh # Install Chromium for browser automation
│ ├── install-playwright.sh # Install Playwright browser automation library
│ ├── install-code-server.sh # Install/update code-server (browser IDE)
│ ├── install-opencode.sh # Install OpenCode
│ ├── setup-env.sh # Configure environment variables
│ └── setup-paths.sh # Create directories and symlinks
│ ├── lib.sh # 共享函数库（颜色、平台检测、提示）
│ ├── check-env.sh # 安装前环境检查
│ ├── install-infra-deps.sh # 核心基础设施包（L1）
│ ├── install-glibc.sh # glibc-runner 安装（L2 条件安装）
│ ├── install-nodejs.sh # Node.js glibc 包装器安装（L2 条件安装）
│ ├── install-build-tools.sh # 原生模块构建工具（L2 条件安装）
│ ├── backup.sh # 备份和恢复 OpenClaw 数据（oa --backup/--restore）
│ ├── build-sharp.sh # 构建 sharp 原生模块（图像处理）
│ ├── install-chromium.sh # 安装 Chromium 用于浏览器自动化
│ ├── install-playwright.sh # 安装 Playwright 浏览器自动化库
│ ├── install-code-server.sh # 安装/更新 code-server（浏览器 IDE）
│ ├── install-opencode.sh # 安装 OpenCode
│ ├── setup-env.sh # 配置环境变量
│ └── setup-paths.sh # 创建目录和符号链接
├── platforms/
│ ├── openclaw/ # OpenClaw platform plugin
│ │ ├── config.env # Platform metadata and dependency declarations
│ │ ├── env.sh # Platform-specific environment variables
│ │ ├── install.sh # Platform package install (npm, patches, clawdhub)
│ │ ├── update.sh # Platform package update
│ │ ├── uninstall.sh # Platform package removal
│ │ ├── status.sh # Platform status display
│ │ ├── verify.sh # Platform verification checks
│ │ └── patches/ # Platform-specific patches
│ ├── openclaw/ # OpenClaw 平台插件
│ │ ├── config.env # 平台元数据和依赖声明
│ │ ├── env.sh # 平台特定环境变量
│ │ ├── install.sh # 平台包安装（npm、补丁、clawdhub）
│ │ ├── update.sh # 平台包更新
│ │ ├── uninstall.sh # 平台包卸载
│ │ ├── status.sh # 平台状态显示
│ │ ├── verify.sh # 平台验证检查
│ │ └── patches/ # 平台特定补丁
│ │ ├── openclaw-apply-patches.sh
│ │ ├── openclaw-patch-paths.sh
│ │ └── openclaw-build-sharp.sh
├── tests/
│ └── verify-install.sh # Post-install verification (orchestrator + platform)
│ └── verify-install.sh # 安装后验证（编排器 + 平台）
└── docs/
├── disable-phantom-process-killer.md # Keeping Processes Alive guide (EN)
├── disable-phantom-process-killer.ko.md # Keeping Processes Alive guide (KO)
├── termux-ssh-guide.md # Termux SSH setup guide (EN)
├── termux-ssh-guide.ko.md # Termux SSH setup guide (KO)
├── troubleshooting.md # Troubleshooting guide (EN)
├── troubleshooting.ko.md # Troubleshooting guide (KO)
└── images/ # Screenshots and images
├── disable-phantom-process-killer.md # 保持进程存活指南（EN）
├── disable-phantom-process-killer.ko.md # 保持进程存活指南（KO）
├── termux-ssh-guide.md # Termux SSH 设置指南（EN）
├── termux-ssh-guide.ko.md # Termux SSH 设置指南（KO）
├── troubleshooting.md # 故障排除指南（EN）
├── troubleshooting.ko.md # 故障排除指南（KO）
└── images/ # 截图和图片
```
## Architecture
## 架构
The project uses a **platform-plugin architecture** that separates platform-agnostic infrastructure from platform-specific code:
本项目使用**平台插件架构**，将平台无关的基础设施与平台特定代码分离：
```
┌─────────────────────────────────────────────────────────────┐
│ Orchestrators (install.sh, update-core.sh, uninstall.sh) │
│ ── Platform-agnostic. Read config.env and delegate. │
│ 编排器 (install.sh, update-core.sh, uninstall.sh) │
│ ── 平台无关。读取 config.env 并委托执行。 │
├─────────────────────────────────────────────────────────────┤
│ Shared Scripts (scripts/) │
│ ── L1: install-infra-deps.sh (always) │
│ ── L2: install-glibc.sh, install-nodejs.sh, │
│ install-build-tools.sh (conditional on config.env) │
│ ── L3: Optional tools (user-selected) │
│ 共享脚本 (scripts/) │
│ ── L1: install-infra-deps.sh（始终执行） │
│ ── L2: install-glibc.sh, install-nodejs.sh, │
│ install-build-tools.sh（根据 config.env 条件执行） │
│ ── L3: 可选工具（用户选择） │
├─────────────────────────────────────────────────────────────┤
│ Platform Plugins (platforms/<name>/) │
│ ── config.env: declares dependencies (PLATFORM_NEEDS_*) │
│ ── install.sh / update.sh / uninstall.sh / ... │
│ 平台插件 (platforms/<name>/) │
│ ── config.env: 声明依赖 (PLATFORM_NEEDS_*) │
│ ── install.sh / update.sh / uninstall.sh / ... │
└─────────────────────────────────────────────────────────────┘
```
**Dependency layers:**
**依赖层级：**
| Layer | Scope | Examples | Controlled by |
| 层级 | 范围 | 示例 | 控制方式 |
|-------|-------|----------|---------------|
| L1 | Infrastructure (always installed) | git, `pkg update` | Orchestrator |
| L2 | Platform runtime (conditional) | glibc, Node.js, build tools | `config.env` flags |
| L3 | Optional tools (user-selected) | tmux, code-server, AI CLIs | User prompts |
| L1 | 基础设施（始终安装） | git、`pkg update` | 编排器 |
| L2 | 平台运行时（条件安装） | glibc、Node.js、构建工具 | `config.env` 标志 |
| L3 | 可选工具（用户选择） | tmux、code-server、AI CLI | 用户提示 |
Each platform declares its L2 dependencies in `config.env`:
每个平台在 `config.env` 中声明其 L2 依赖：
```bash
# platforms/openclaw/config.env
@@ -408,194 +419,194 @@ PLATFORM_NEEDS_NODEJS=true
PLATFORM_NEEDS_BUILD_TOOLS=true
```
The orchestrator reads these flags and conditionally runs the corresponding install scripts. A platform that doesn't need certain dependencies simply sets the corresponding flags to `false` and those heavy dependencies are skipped entirely.
编排器读取这些标志并有条件地运行相应的安装脚本。不需要某些依赖的平台只需将对应标志设为 `false`，那些重量级依赖就会被完全跳过。
## Detailed Installation Flow
## 详细安装流程
Running `bash install.sh` executes the following 8 steps in order.
运行 `bash install.sh` 将按顺序执行以下 8 个步骤。
### [1/8] Environment Check — `scripts/check-env.sh`
### [1/8] 环境检查 — `scripts/check-env.sh`
Validates that the current environment is suitable before starting installation.
在开始安装前验证当前环境是否满足要求。
- **Termux detection**: Checks for the `$PREFIX` environment variable. Exits immediately if not in Termux
- **Architecture check**: Runs `uname -m` to verify CPU architecture (aarch64 recommended, armv7l supported, x86_64 treated as emulator)
- **Disk space**: Ensures at least 1000MB free on the `$PREFIX` partition. Errors if insufficient
- **Existing installation**: If `openclaw` command already exists, shows current version and notes this is a reinstall/upgrade
- **Node.js pre-check**: If Node.js is already installed, shows version and warns if below 22
- **Phantom Process Killer** (Android 12+): Shows an informational note about the Phantom Process Killer with a link to the [disable guide](docs/disable-phantom-process-killer.md)
- **Termux 检测**：检查 `$PREFIX` 环境变量。如果不在 Termux 中则立即退出
- **架构检查**：运行 `uname -m` 验证 CPU 架构（推荐 aarch64，支持 armv7l，x86_64 视为模拟器）
- **磁盘空间**：确保 `$PREFIX` 分区至少有 1000MB 可用空间。不足时报错
- **已有安装**：如果 `openclaw` 命令已存在，显示当前版本并提示这是重新安装/升级
- **Node.js 预检**：如果 Node.js 已安装，显示版本，低于 22 时发出警告
- **Phantom Process Killer**（Android 12+）：显示有关 Phantom Process Killer 的提示信息，附带 [禁用指南](docs/disable-phantom-process-killer.md) 链接
### [2/8] Platform Selection
### [2/8] 平台选择
Selects the platform to install. Currently hardcoded to `openclaw`. Future versions will present a selection UI when multiple platforms are available.
选择要安装的平台。目前硬编码为 `openclaw`。未来版本将在有多个平台可用时提供选择界面。
Loads the platform's `config.env` via `load_platform_config()` from `scripts/lib.sh`, which exports all `PLATFORM_*` variables for use by subsequent steps.
通过 `scripts/lib.sh` 中的 `load_platform_config()` 加载平台的 `config.env`，导出所有 `PLATFORM_*` 变量供后续步骤使用。
### [3/8] Optional Tools Selection (L3)
### [3/8] 可选工具选择（L3）
Presents 11 individual Y/n prompts (via `/dev/tty`) for optional tools:
通过 `/dev/tty` 提供 11 个单独的 Y/n 提示，用于选择可选工具：
- tmux, ttyd, dufs, android-tools
- Chromium, Playwright
- code-server, OpenCode
- Claude Code, Gemini CLI, Codex CLI (Termux)
- tmux、ttyd、dufs、android-tools
- Chromium、Playwright
- code-server、OpenCode
- Claude Code、Gemini CLI、Codex CLI (Termux)
All selections are collected upfront before any installation begins. This allows the user to make all decisions at once and walk away during the install.
所有选择在安装开始前一次性完成。这样用户可以一次做完所有决定，然后在安装期间放手不管。
### [4/8] Core Infrastructure (L1) — `scripts/install-infra-deps.sh` + `scripts/setup-paths.sh`
### [4/8] 核心基础设施（L1）— `scripts/install-infra-deps.sh` + `scripts/setup-paths.sh`
Always runs regardless of platform selection.
无论选择哪个平台都会执行。
**install-infra-deps.sh:**
- Runs `pkg update -y && pkg upgrade -y` to refresh and upgrade packages
- Installs `git` (required for npm git dependencies and repo cloning)
**install-infra-deps.sh：**
- 运行 `pkg update -y && pkg upgrade -y` 刷新并升级软件包
- 安装 `git`（npm git 依赖和仓库克隆所需）
**setup-paths.sh:**
- Creates `$PREFIX/tmp` and `$HOME/.openclaw-android/patches` directories
- Displays standard Linux path mappings (`/bin/sh`, `/usr/bin/env`, `/tmp`) to Termux equivalents
**setup-paths.sh：**
- 创建 `$PREFIX/tmp` 和 `$HOME/.openclaw-android/patches` 目录
- 显示标准 Linux 路径（`/bin/sh`、`/usr/bin/env`、`/tmp`）到 Termux 等效路径的映射
### [5/8] Platform Runtime Dependencies (L2)
### [5/8] 平台运行时依赖（L2）
Conditionally installs runtime dependencies based on the platform's `config.env` flags:
根据平台 `config.env` 标志有条件地安装运行时依赖：
| Flag | Script | What it installs |
| 标志 | 脚本 | 安装内容 |
|------|--------|-----------------|
| `PLATFORM_NEEDS_GLIBC=true` | `scripts/install-glibc.sh` | pacman, glibc-runner (provides `ld-linux-aarch64.so.1`) |
| `PLATFORM_NEEDS_NODEJS=true` | `scripts/install-nodejs.sh` | Node.js v22 LTS linux-arm64, grun-style wrapper scripts |
| `PLATFORM_NEEDS_BUILD_TOOLS=true` | `scripts/install-build-tools.sh` | python, make, cmake, clang, binutils |
| `PLATFORM_NEEDS_GLIBC=true` | `scripts/install-glibc.sh` | pacman、glibc-runner（提供 `ld-linux-aarch64.so.1`） |
| `PLATFORM_NEEDS_NODEJS=true` | `scripts/install-nodejs.sh` | Node.js v22 LTS linux-arm64、grun 风格的包装脚本 |
| `PLATFORM_NEEDS_BUILD_TOOLS=true` | `scripts/install-build-tools.sh` | python、make、cmake、clang、binutils |
Each script is self-contained with pre-checks and idempotent behavior (skips if already installed).
每个脚本都是自包含的，具有预检查和幂等行为（如果已安装则跳过）。
### [6/8] Platform Package Install (L2) — `platforms/<platform>/install.sh`
### [6/8] 平台包安装（L2）— `platforms/<platform>/install.sh`
Delegates to the platform's own install script. For OpenClaw, this:
委托给平台自身的安装脚本。对于 OpenClaw，此步骤：
1. Sets `CPATH` for glib-2.0 headers (needed for native module builds)
2. Installs PyYAML via pip (for `.skill` packaging)
3. Copies `glibc-compat.js` to `~/.openclaw-android/patches/`
4. Installs `systemctl` stub to `$PREFIX/bin/`
5. Runs `npm install -g openclaw@latest --ignore-scripts`
6. Applies platform-specific patches via `openclaw-apply-patches.sh`
7. Installs `clawdhub` (skill manager) and `undici` dependency if needed
8. Runs `openclaw update` (includes building native modules like sharp)
1. 设置 `CPATH` 以获取 glib-2.0 头文件（原生模块构建所需）
2. 通过 pip 安装 PyYAML（`.skill` 打包所需）
3. 将 `glibc-compat.js` 复制到 `~/.openclaw-android/patches/`
4. 安装 `systemctl` 桩到 `$PREFIX/bin/`
5. 运行 `npm install -g openclaw@latest --ignore-scripts`
6. 通过 `openclaw-apply-patches.sh` 应用平台特定补丁
7. 安装 `clawdhub`（技能管理器）以及 `undici` 依赖（如需要）
8. 运行 `openclaw update`（包括构建 sharp 等原生模块）
**[6.5] Environment Variables + CLI + Marker:**
**[6.5] 环境变量 + CLI + 标记文件：**
After platform install, the orchestrator:
- Runs `setup-env.sh` to write the `.bashrc` environment block
- Evaluates the platform's `env.sh` for platform-specific variables
- Writes the platform marker file (`~/.openclaw-android/.platform`)
- Installs `oa` CLI and `oaupdate` wrapper to `$PREFIX/bin/`
- Copies `lib.sh`, `setup-env.sh`, and the platform directory to `~/.openclaw-android/` for use by the updater and uninstaller
平台安装后，编排器会：
- 运行 `setup-env.sh` 写入 `.bashrc` 环境变量块
- 执行平台的 `env.sh` 获取平台特定变量
- 写入平台标记文件（`~/.openclaw-android/.platform`）
- 安装 `oa` CLI 和 `oaupdate` 包装器到 `$PREFIX/bin/`
- 将 `lib.sh`、`setup-env.sh` 和平台目录复制到 `~/.openclaw-android/` 供更新程序和卸载程序使用
### [7/8] Install Optional Tools (L3)
### [7/8] 安装可选工具（L3）
Installs the tools selected in Step 3:
安装步骤 3 中选择的工具：
- **Termux packages**: tmux, ttyd, dufs, android-tools — installed via `pkg install`
- **code-server**: Browser-based VS Code IDE with Termux-specific workarounds (replace bundled node, patch argon2, handle hard link failures)
- **OpenCode**: AI coding assistant using proot + ld.so concatenation for Bun standalone binaries
- **Chromium**: Browser automation support for OpenClaw (~400MB)
- **Playwright**: Browser automation library (`playwright-core` via npm). Auto-sets `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` and `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` environment variables. Installs Chromium automatically if not already present
- **AI CLI tools**: Claude Code, Gemini CLI, Codex CLI (Termux) — installed via `npm install -g`
- **Termux 包**：tmux、ttyd、dufs、android-tools — 通过 `pkg install` 安装
- **code-server**：基于浏览器的 VS Code IDE，带有 Termux 特定的解决方案（替换捆绑的 node、修补 argon2、处理硬链接失败）
- **OpenCode**：AI 编程助手，使用 proot + ld.so 拼接方式运行 Bun 独立二进制文件
- **Chromium**：OpenClaw 的浏览器自动化支持（约 400MB）
- **Playwright**：浏览器自动化库（通过 npm 安装 `playwright-core`）。自动设置 `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` 和 `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` 环境变量。如果未安装 Chromium 则自动安装
- **AI CLI 工具**：Claude Code、Gemini CLI、Codex CLI (Termux) — 通过 `npm install -g` 安装
### [8/8] Verification — `tests/verify-install.sh`
### [8/8] 验证 — `tests/verify-install.sh`
Runs a two-tier verification:
运行两级验证：
**Orchestrator checks (FAIL level):**
**编排器检查（FAIL 级别）：**
| Check Item | PASS Condition |
| 检查项 | 通过条件 |
|------------|---------------|
| Node.js version | `node -v` >= 22 |
| npm | `npm` command exists |
| TMPDIR | Environment variable is set |
| OA_GLIBC | Set to `1` |
| glibc-compat.js | File exists in `~/.openclaw-android/patches/` |
| .glibc-arch | Marker file exists |
| glibc dynamic linker | `ld-linux-aarch64.so.1` exists |
| glibc node wrapper | Wrapper script at `~/.openclaw-android/bin/node` |
| Directories | `~/.openclaw-android`, `$PREFIX/tmp` exist |
| .bashrc | Contains environment variable block |
| Node.js 版本 | `node -v` >= 22 |
| npm | `npm` 命令存在 |
| TMPDIR | 环境变量已设置 |
| OA_GLIBC | 设为 `1` |
| glibc-compat.js | 文件存在于 `~/.openclaw-android/patches/` |
| .glibc-arch | 标记文件存在 |
| glibc 动态链接器 | `ld-linux-aarch64.so.1` 存在 |
| glibc node 包装器 | 包装脚本位于 `~/.openclaw-android/bin/node` |
| 目录 | `~/.openclaw-android`、`$PREFIX/tmp` 存在 |
| .bashrc | 包含环境变量块 |
**Orchestrator checks (WARN level, non-critical):**
**编排器检查（WARN 级别，非关键）：**
| Check Item | PASS Condition |
| 检查项 | 通过条件 |
|------------|---------------|
| code-server | `code-server --version` succeeds |
| opencode | `opencode` command available |
| code-server | `code-server --version` 成功 |
| opencode | `opencode` 命令可用 |
**Platform verification** — delegates to `platforms/<platform>/verify.sh`:
**平台验证** — 委托给 `platforms/<platform>/verify.sh`：
| Check Item | PASS Condition |
| 检查项 | 通过条件 |
|------------|---------------|
| openclaw | `openclaw --version` succeeds |
| CONTAINER | Set to `1` |
| clawdhub | Command available |
| ~/.openclaw | Directory exists |
| openclaw | `openclaw --version` 成功 |
| CONTAINER | 设为 `1` |
| clawdhub | 命令可用 |
| ~/.openclaw | 目录存在 |
All FAIL-level items pass → PASSED. Any FAIL → shows reinstall instructions. WARN items do not cause failure.
所有 FAIL 级别项通过 → PASSED。任何 FAIL → 显示重新安装说明。WARN 项不会导致失败。
## Lightweight Updater Flow — `oa --update`
## 轻量级更新流程 — `oa --update`
Running `oa --update` (or `oaupdate` for backward compatibility) downloads the latest release tarball from GitHub and executes the following 5 steps.
运行 `oa --update`（或 `oaupdate`，用于向后兼容）会从 GitHub 下载最新的发行版 tarball，然后执行以下 5 个步骤。
### [1/5] Pre-flight Check
### [1/5] 预检查
Validates the minimum conditions for updating.
验证更新所需的最低条件。
- Checks `$PREFIX` exists (Termux environment)
- Checks `curl` is available
- Detects platform from `~/.openclaw-android/.platform` marker file
- Detects architecture: glibc (`.glibc-arch` marker) or Bionic (legacy)
- Migrates old directory name if needed (`.openclaw-lite` → `.openclaw-android` — legacy compatibility)
- **Phantom Process Killer** (Android 12+): Shows an informational note with a link to the [disable guide](docs/disable-phantom-process-killer.md)
- 检查 `$PREFIX` 存在（Termux 环境）
- 检查 `curl` 可用
- 从 `~/.openclaw-android/.platform` 标记文件检测平台
- 检测架构：glibc（`.glibc-arch` 标记）或 Bionic（旧版）
- 如需要，迁移旧目录名（`.openclaw-lite` → `.openclaw-android` — 旧版兼容）
- **Phantom Process Killer**（Android 12+）：显示提示信息，附带 [禁用指南](docs/disable-phantom-process-killer.md) 链接
### [2/5] Download Latest Release
### [2/5] 下载最新版本
Downloads the full repository tarball from GitHub and extracts to a temp directory. Validates that all required files exist:
从 GitHub 下载完整仓库 tarball 并解压到临时目录。验证所有必需文件存在：
- `scripts/lib.sh`
- `scripts/setup-env.sh`
- `platforms/<platform>/config.env`
- `platforms/<platform>/update.sh`
### [3/5] Update Core Infrastructure
### [3/5] 更新核心基础设施
Updates shared files used by the updater, uninstaller, and CLI:
更新更新程序、卸载程序和 CLI 使用的共享文件：
- Copies the latest platform directory to `~/.openclaw-android/platforms/`
- Updates `lib.sh` and `setup-env.sh` in `~/.openclaw-android/scripts/`
- Updates patch files (`glibc-compat.js`, `argon2-stub.js`, `spawn.h`, `systemctl`)
- Updates `oa` CLI and `oaupdate` wrapper in `$PREFIX/bin/`
- Updates `uninstall.sh` in `~/.openclaw-android/`
- If Bionic architecture detected, performs automatic glibc migration
- Runs `setup-env.sh` to refresh `.bashrc` environment block
- 将最新的平台目录复制到 `~/.openclaw-android/platforms/`
- 更新 `~/.openclaw-android/scripts/` 中的 `lib.sh` 和 `setup-env.sh`
- 更新补丁文件（`glibc-compat.js`、`argon2-stub.js`、`spawn.h`、`systemctl`）
- 更新 `$PREFIX/bin/` 中的 `oa` CLI 和 `oaupdate` 包装器
- 更新 `~/.openclaw-android/` 中的 `uninstall.sh`
- 如果检测到 Bionic 架构，执行自动 glibc 迁移
- 运行 `setup-env.sh` 刷新 `.bashrc` 环境变量块
### [4/5] Update Platform
### [4/5] 更新平台
Delegates to `platforms/<platform>/update.sh`. For OpenClaw, this:
委托给 `platforms/<platform>/update.sh`。对于 OpenClaw，此步骤：
- Installs build dependencies (`libvips`, `binutils`)
- Updates `openclaw` npm package to latest version
- Re-applies platform-specific patches
- Rebuilds sharp native module if openclaw was updated
- Updates/installs `clawdhub` (skill manager)
- Installs `undici` for clawdhub if needed (Node.js v24+)
- Migrates skills from `~/skills/` to `~/.openclaw/workspace/skills/` if needed
- Installs PyYAML if missing
- 安装构建依赖（`libvips`、`binutils`）
- 将 `openclaw` npm 包更新到最新版本
- 重新应用平台特定补丁
- 如果 openclaw 已更新，重新构建 sharp 原生模块
- 更新/安装 `clawdhub`（技能管理器）
- 如需要，为 clawdhub 安装 `undici`（Node.js v24+）
- 如需要，将技能从 `~/skills/` 迁移到 `~/.openclaw/workspace/skills/`
- 如缺失则安装 PyYAML
### [5/5] Update Optional Tools
### [5/5] 更新可选工具
Updates tools that are already installed:
更新已安装的工具：
- **code-server**: Runs `install-code-server.sh` in update mode. Skipped if not installed
- **OpenCode**: Updates if installed; offers to install if not. Requires glibc architecture
- **Chromium**: Updates if installed. Skipped if not installed
- **AI CLI tools** (Claude Code, Gemini CLI, Codex CLI (Termux)): Compares installed vs latest npm version, updates if needed. Tools not installed are not offered for installation
- **code-server**：以更新模式运行 `install-code-server.sh`。未安装则跳过
- **OpenCode**：已安装则更新；未安装则提供安装选项。需要 glibc 架构
- **Chromium**：已安装则更新。未安装则跳过
- **AI CLI 工具**（Claude Code、Gemini CLI、Codex CLI (Termux)）：比较已安装版本与最新 npm 版本，需要时更新。未安装的工具不会提供安装选项
</details>
## License
## 许可证
MIT