已安装组件

安装程序会跨多个包管理器设置基础设施、平台包和可选工具。核心基础设施和平台依赖会自动安装；可选工具在安装过程中逐个提示。

核心基础设施

Agent 平台运行时依赖

这些由平台的 config.env 标志控制。对于 OpenClaw，全部安装：

OpenClaw 平台

可选工具（安装时提示）

每个工具都会通过单独的 Y/n 提示。你可以选择安装哪些。可选工具安装失败时只会提示警告并跳过，不会中止后续安装。

项目结构

openclaw-android/
├── 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 运行时补丁（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                  # 共享函数库（颜色、平台检测、提示）
│   ├── 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 平台插件
│   │   ├── config.env          # 平台元数据和依赖声明
│   │   ├── env.sh              # 平台特定环境变量
│   │   ├── install.sh          # 平台包安装（npm、补丁、clawdhub）
│   │   ├── update.sh           # 平台包更新
│   │   ├── openclaw-shim.sh    # 生成 `openclaw update` 版本锁定守卫
│   │   ├── uninstall.sh        # 平台包卸载
│   │   ├── limits.sh           # node/npm 调用的时间限制（update、verify、status）
│   │   ├── status.sh           # 平台状态显示
│   │   ├── verify.sh           # 平台验证检查
│   │   └── patches/            # 平台特定补丁
│   │       ├── openclaw-apply-patches.sh
│   │       ├── openclaw-patch-paths.sh
│   │       ├── openclaw-patch-hardlink.sh  # OpenClaw 的 Android 硬链接/reflink 回退处理
│   │       └── openclaw-build-sharp.sh
├── tests/
│   └── verify-install.sh       # 安装后验证（编排器 + 平台）
└── docs/
    ├── 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/                 # 截图和图片

架构

本项目使用平台插件架构，将平台无关的基础设施与平台特定代码分离：

┌─────────────────────────────────────────────────────────────┐
│  编排器 (install.sh, update-core.sh, uninstall.sh)           │
│  ── 平台无关。读取 config.env 并委托执行。                     │
├─────────────────────────────────────────────────────────────┤
│  共享脚本 (scripts/)                                         │
│  ── L1: install-infra-deps.sh（始终执行）                     │
│  ── L2: install-glibc.sh, install-nodejs.sh,                │
│         install-build-tools.sh（根据 config.env 条件执行）    │
│  ── L3: 可选工具（用户选择）                                   │
├─────────────────────────────────────────────────────────────┤
│  平台插件 (platforms/<name>/)                                │
│  ── config.env: 声明依赖 (PLATFORM_NEEDS_*)                 │
│  ── install.sh / update.sh / uninstall.sh / ...             │
└─────────────────────────────────────────────────────────────┘

依赖层级：

每个平台在 config.env 中声明其 L2 依赖：

# platforms/openclaw/config.env
PLATFORM_NEEDS_GLIBC=true
PLATFORM_NEEDS_NODEJS=true
PLATFORM_NEEDS_BUILD_TOOLS=true

编排器读取这些标志并有条件地运行相应的安装脚本。不需要某些依赖的平台只需将对应标志设为 false，那些重量级依赖就会被完全跳过。

详细安装流程

运行 bash install.sh 将按顺序执行以下 8 个步骤。

[1/8] 环境检查 — scripts/check-env.sh

在开始安装前验证当前环境是否满足要求。

• Termux 检测：检查 $PREFIX 环境变量。如果不在 Termux 中则立即退出
• 架构检查：运行 uname -m 验证 CPU 架构（推荐 aarch64，支持 armv7l，x86_64 视为模拟器）
• 磁盘空间：确保 $PREFIX 分区至少有 2000MB 可用空间。不足时报错，并显示所需空间和剩余空间
• 已有安装：如果 openclaw 命令已存在，显示当前版本并提示这是重新安装/升级
• Node.js 预检：如果 Node.js 已安装，显示版本，低于 24 时发出警告
• Phantom Process Killer（Android 12+）：显示有关 Phantom Process Killer 的提示信息，附带 禁用指南 链接

[2/8] 平台选择

选择要安装的平台。目前硬编码为 openclaw。未来版本将在有多个平台可用时提供选择界面。

通过 scripts/lib.sh 中的 load_platform_config() 加载平台的 config.env，导出所有 PLATFORM_* 变量供后续步骤使用。

[3/8] 可选工具选择（L3）

通过 /dev/tty 提供 11 个单独的 Y/n 提示，用于选择可选工具：

• tmux、ttyd、dufs、android-tools
• Chromium、Playwright
• code-server、OpenCode
• Claude Code、Gemini CLI、Codex CLI (Termux)

所有选择在安装开始前一次性完成。这样用户可以一次做完所有决定，然后在安装期间放手不管。

[4/8] 核心基础设施（L1）— scripts/install-infra-deps.sh + scripts/setup-paths.sh

无论选择哪个平台都会执行。

install-infra-deps.sh：

• 运行 pkg update -y && pkg upgrade -y 刷新并升级软件包
• 安装 git（npm git 依赖和仓库克隆所需）

setup-paths.sh：

• 创建 $PREFIX/tmp 和 $HOME/.openclaw-android/patches 目录
• 显示标准 Linux 路径（/bin/sh、/usr/bin/env、/tmp）到 Termux 等效路径的映射

[5/8] 平台运行时依赖（L2）

根据平台 config.env 标志有条件地安装运行时依赖：

每个脚本都是自包含的，具有预检查和幂等行为（如果已安装则跳过）。

Node.js 包装器的默认值： OpenClaw 2026.9.x 需要 Node.js 24.16 或更高版本。OpenClaw 的文件安全模块（@openclaw/fs-safe）的原生辅助程序使用 openat2 系统调用，而 Android 的应用 seccomp 策略会以 SIGSYS（Bad system call）终止该调用所在的进程。因此包装器默认设置 FS_SAFE_TEST_NO_OPENAT2=1，保留原生辅助程序但不让它使用 openat2（取值必须恰好为 1 才会被识别）。设置 FS_SAFE_NATIVE_MODE=off 可以完全关闭原生辅助程序，但这样 OpenClaw 的部分数据迁移可能会被拒绝。包装器还默认设置 OPENCLAW_NO_AUTO_UPDATE=1，并阻止 OpenClaw 自身的更新（参见更新）。

硬链接补丁： Android 会阻止应用数据目录中的硬链接和 reflink（FICLONE）复制（应用和 Termux 均如此，错误为 EACCES）。OpenClaw 2026.10.2 先尝试硬链接，仅在出现“不支持”错误时才改用复制，而 EACCES 不被视为“不支持”。此外，迁移对话记录后，把原文件移入归档文件夹时只使用硬链接。因此不加处理的话，从 7.35 升级上来的用户的数据迁移会失败。每次安装或更新 OpenClaw 时（应用安装、Termux 安装、oa --update，以及用 npm install -g openclaw@<锁定版本> 重新安装），OpenClaw on Android 都会通过 platforms/openclaw/patches/openclaw-patch-hardlink.sh 修补 OpenClaw 的这一部分：EACCES 也会转为复制；移入归档文件夹时，如果硬链接被拒绝，则改为在同一文件系统内重命名（rename）。这样 openclaw backup create 也可以用复制代替硬链接。oa --status 会显示 Hard-link patch: applied (…) 或 not complete (…) 一行。如果有对话记录的 7.35 用户执行会更改锁定版本的更新，更新会先检查该补丁是否适用于将要安装的 OpenClaw，不适用则不做任何更改直接停止（参见故障排除）。 此外，OpenClaw 2026.10 会为网关锁读取进程命名空间文件 /proc/self/ns/pid，而许多 Android 内核不向应用提供该文件（读取以 ENOENT 或 EACCES 失败）；同一补丁让 OpenClaw 将该文件视为不可用，而不是拒绝启动网关。

已知限制： OpenClaw 的桌面自动化工具（@trycua/cua-driver）在 Android 10 及以下（API 29 及以下）上，所需的部分系统调用被阻止，可能无法工作。

[6/8] 平台包安装（L2）— platforms/<platform>/install.sh

委托给平台自身的安装脚本。对于 OpenClaw，此步骤：

1. 设置 CPATH 以获取 glib-2.0 头文件（原生模块构建所需）
2. 通过 pip 安装 PyYAML（.skill 打包所需）
3. 将 glibc-compat.js 复制到 ~/.openclaw-android/patches/（Node.js 包装脚本读取随 Node.js 一起安装在 ~/.openclaw-android/lib/ 的副本——应用不会覆盖该位置）
4. 安装 systemctl 桩到 $PREFIX/bin/
5. 运行 npm install -g [email protected] --ignore-scripts（config.env 中锁定的版本）
6. 运行 OpenClaw 自身的 postinstall 脚本（postinstall-bundled-plugins.mjs），该脚本被 --ignore-scripts 跳过
7. 通过 openclaw-apply-patches.sh 应用平台特定补丁
8. 安装 openclaw update 守卫（openclaw-shim.sh），使锁定版本得以保持
9. 安装 clawdhub（技能管理器）以及 undici 依赖（如需要）
10. 关闭网关的 "update available" 提示（openclaw config set update.checkOnStart false），除非你已自行设置过该值

如果之前的安装被中断： 安装程序会记录安装正在进行，并且只有在安装、postinstall、补丁和检查全部通过之后才删除该记录。安装后如果 OpenClaw 仍不完整，Termux 安装程序会输出 [FAIL] OpenClaw <version> was installed but is incomplete (files are missing or it does not start). 和 Run the installer again. 并停止。Claw 应用的设置脚本（post-setup.sh）会检测到未完成的先前安装（[WARN] OpenClaw <version> is incomplete (an earlier install was cut off): installing it again），即使版本相同也会重新安装 OpenClaw；不会触及你的数据。如果之后 OpenClaw 仍不完整，设置会以如下错误停止：OpenClaw <version> is still incomplete (files are missing or it does not start). Restart the app to try again. Claw 应用（v0.4.5 及以上）会在其安装界面显示该失败，并提供重试按钮。

[6.5] 环境变量 + CLI + 标记文件：

平台安装后，编排器会：

• 运行 setup-env.sh 写入 .bashrc 环境变量块
• 执行平台的 env.sh 获取平台特定变量
• 写入平台标记文件（~/.openclaw-android/.platform）
• 安装 oa CLI 和 oaupdate 包装器到 $PREFIX/bin/
• 将 lib.sh、setup-env.sh 和平台目录复制到 ~/.openclaw-android/ 供更新程序和卸载程序使用

[7/8] 安装可选工具（L3）

安装步骤 3 中选择的工具：

• 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 安装；安装失败时只会提示警告并跳过，不会中止整个安装（Claude Code 通过 glibc 加载器运行。Codex CLI 的软件包声明了 os: android，而此 Node.js 报告的是 linux，因此在 Claw 应用中使用 --force 安装；在 Termux 中仍可能带警告被跳过）

[8/8] 验证 — tests/verify-install.sh

运行两级验证：

编排器检查（FAIL 级别）：

编排器检查（WARN 级别，非关键）：

平台验证 — 委托给 platforms/<platform>/verify.sh：

所有 FAIL 级别项通过 → PASSED。任何 FAIL → 显示重新安装说明。WARN 项不会导致失败。

轻量级更新流程 — oa --update

运行 oa --update（或 oaupdate，用于向后兼容）会从 GitHub 下载最新的发行版 tarball，然后执行以下 5 个步骤。

[1/5] 预检查

验证更新所需的最低条件。

• 检查 $PREFIX 存在（Termux 环境）
• 检查 curl 可用
• 从 ~/.openclaw-android/.platform 标记文件检测平台
• 检测架构：glibc（.glibc-arch 标记）或 Bionic（旧版）
• 如需要，迁移旧目录名（.openclaw-lite → .openclaw-android — 旧版兼容）
• Phantom Process Killer（Android 12+）：显示提示信息，附带 禁用指南 链接
• 同一时间只运行一次：安装、更新或工具安装同一时间只会运行一个。第二次运行会输出 [FAIL] Another update, setup or tools run is in progress. Try again when it has finished.，并在不更改安装内容的情况下以退出码 2 结束

[2/5] 下载最新版本

从 GitHub 下载完整仓库 tarball 并解压到临时目录。验证所有必需文件存在：

• scripts/lib.sh
• scripts/setup-env.sh
• platforms/<platform>/config.env
• platforms/<platform>/update.sh

[3/5] 更新核心基础设施

如果本次更新会更改锁定的 Node.js 或 OpenClaw 版本，则在更改任何内容之前，会先执行三项保护措施：可用空间检查（2000MB）、检查 OpenClaw 网关是否未在运行、在 ~/.openclaw-android/backup/pre-update/ 创建数据备份（参见更新）。

更新更新程序、卸载程序和 CLI 使用的共享文件：

• 检查更新脚本自身是否为最新。如果下载到的是旧的缓存副本（发布后的几分钟内可能出现），更新会在不做任何更改的情况下停止；请几分钟后重新运行 oa --update
• 将最新的平台目录复制到 ~/.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 迁移
• 将 Node.js 收敛到锁定版本（sha256 校验下载，原子替换——失败时恢复之前的安装）。除非设置 OA_ALLOW_NODE_DOWNGRADE=1，否则不会把 Node.js 降到更低的版本
• 运行 setup-env.sh 刷新 .bashrc 环境变量块
• Node 门控：如果此时 Node.js 仍未达到锁定版本，更新到此为止——不会触及 OpenClaw（[4/5]）。请重新运行 oa --update

[4/5] 更新平台

委托给 platforms/<platform>/update.sh。对于 OpenClaw，此步骤：

• 如果锁定版本发生了变化：安装后检查 OpenClaw 的配置和数据状态，仅当需要数据迁移且本次运行创建了备份时，运行一次 openclaw doctor --fix（参见更新）
• 安装后、配置检查之前，修复指向其他应用文件夹的路径（参见备份与恢复）
• 最后的数据检查（openclaw config validate 和 openclaw doctor --non-interactive）：如果网关正在使用 OpenClaw 的数据，且本次运行没有替换 OpenClaw，则跳过该检查而不是判为失败，更新继续进行，并输出 [WARN] The gateway is using the OpenClaw state, so the data check was skipped. Stop the gateway, then run: openclaw doctor
• 安装 binutils（用于原生模块构建）
• 再次检查 Node.js 锁定版本作为安全网（纵深防御——[3/5] 已经做过门控）
• 将 openclaw 收敛到锁定版本——已安装版本更低时安装锁定版本。除非设置 OA_ALLOW_OPENCLAW_DOWNGRADE=1，否则不会把 OpenClaw 降到更低的版本
• 如果 OpenClaw 不完整（先前的安装被中断，版本一致但缺少文件），即使版本已是锁定版本也会重新安装：[WARN] openclaw <version> is incomplete (an earlier install was cut off): installing it again。如果最后的数据检查报告 OpenClaw 自身的文件缺失（路径位于 OpenClaw 包内的 Cannot find module 或 Cannot find package），则重新安装一次：[WARN] OpenClaw <version> is missing some of its own files (an earlier install was cut off): installing it again。两种情况下都不会触及你的数据。如果本次运行安装之后 OpenClaw 仍不完整，更新会输出 [FAIL] OpenClaw <version> was installed but is incomplete (files are missing or it does not start). 并停止。
• 重新应用平台特定补丁
• 刷新 openclaw update 守卫（openclaw-shim.sh），保持 openclaw update/--update 持续被阻止（Node.js 包装器也会阻止 OpenClaw 自身的更新途径）
• 更新/安装 clawdhub（技能管理器）
• 如需要，为 clawdhub 安装 undici（Node.js v24+）
• 关闭网关的 "update available" 提示（update.checkOnStart=false），仅在你尚未自行设置该值时
• 如需要，将技能从 ~/skills/ 迁移到 ~/.openclaw/workspace/skills/
• 如缺失则安装 PyYAML

[5/5] 更新可选工具

更新已安装的工具：

• code-server：以更新模式运行 install-code-server.sh——保持在固定版本 4.117.0（之前安装的更新版本会被改回）。未安装则跳过
• OpenCode：已安装则更新；未安装则提供安装选项。需要 glibc 架构
• Chromium：已安装则更新。未安装则跳过
• AI CLI 工具（Claude Code、Gemini CLI、Codex CLI (Termux)）：比较已安装版本与最新 npm 版本，需要时更新。未安装的工具不会提供安装选项