OpenClaw on Android故障排查清单：12个常见失败场景诊断指南（从CANNOT LINK EXECUTABLE到Gateway端口占用）-北京尧图网络

移动开发AI 应用CLI开发工具【免费下载链接】openclaw-androidRun OpenClaw on Android with a single command — no proot, no Linux项目地址https://gitcode.com/gh_mirrors/op/openclaw-android点击查看免费下载OpenClaw on Android 是一个用一条命令就能在手机上装好 OpenClaw AI 智能体的项目——不需要 proot也不需要安装完整的 Linux 发行版。但真机上总会遇到各种报错curl 链接失败、Gateway 端口占用、进程被 Android 杀死……本文给出一份完整的 OpenClaw on Android 故障排查清单覆盖 12 个高频失败场景的成因定位与快速修复新手也能照着一步步恢复运行。如何使用这份故障排查清单复制终端里原样的报错信息一行就够在下表中找到对应编号定位场景按该场景的步骤执行修复命令如果仍未解决运行oa --status查看安装组件的整体状态。报错关键字场景编号CANNOT LINK EXECUTABLE curl场景 1gateway already running/Port 18789 is already in use场景 2gateway not connected场景 3unauthorizedDashboard 要求 token场景 4Connection refusedSSH 端口 8022场景 5openclaw --version失败 /Cannot find module glibc-compat.js场景 6spawn systemctl ENOENT场景 7Bad system call场景 8[BLOCKED]更新被拦截场景 9oa --update中途停止场景 10schema migration required/Hard-link patch: not complete场景 11Process completed (signal 9)场景 12终端里一次出现多条报错也很常见下面的典型场景截图来自项目文档可以先对照认识一下这些老朋友1.curl无法启动CANNOT LINK EXECUTABLE症状初始配置阶段安装 curl 之后执行任何网络命令都报CANNOT LINK EXECUTABLE curl: cannot locate symbol SSL_set_quic_tls_early_data_enabled ...成因在全新 Termux 上没有先做完整升级就直接pkg install curl新版 libcurl 装到了旧版 OpenSSL 之上curl 无法启动而后续的pkg upgrade也因为依赖 curl 而失败形成死锁。修复apt update apt full-upgrade -y出现配置文件询问(Y/I/N/O/D/Z) [defaultN] ?时直接按Enter保留默认值。完成后curl --version应正常输出再继续安装 OpenClaw。2. Gateway 无法启动端口 18789 被占用症状Gateway failed to start: gateway already running (pid XXXXX); lock timeout after 5000ms Port 18789 is already in use.成因上一次的 gateway 进程异常退出留下了锁文件或僵尸进程。常见诱因SSH 连接断开、误按CtrlZ挂起而非终止、Android 强杀 Termux。修复三步走ps aux | grep -E node|openclaw | grep -v grep # 1. 找到残留进程 kill -9 PID # 2. 杀掉对应进程 rm -rf $PREFIX/tmp/openclaw-* # 3. 清理锁文件然后重新启动openclaw gateway。⚠️ 停止 gateway 永远用CtrlCCtrlZ只是把进程挂到后台它仍然占着端口。若三步后仍无效完全关闭并重开 Termux或重启手机可彻底清空状态。3. Gateway 断连gateway not connected症状send failed: Error: gateway not connected disconnected | error成因gateway 进程已停止或承载它的 SSH 会话断开了。特别注意openclaw gateway必须直接在 Termux 应用里运行通过 SSH 运行时一旦 SSH 断开gateway 就会跟着停掉。修复回到运行 gateway 的 Termux 会话确认进程状态若已断开重新连接后执行openclaw gateway。如果此时报 gateway already running转场景 2 处理。4. Dashboard 未授权unauthorized症状浏览器打开 Dashboard 后提示unauthorized或要求输入 token。成因Dashboardhttp://127.0.0.1:18789/需要用 gateway token 登录而openclaw config get gateway.auth.token出于安全会隐藏密钥只显示__OPENCLAW_REDACTED__所以 token 默认看不到。修复直接从配置文件读出 tokenOpenClaw 以明文 JSON 写入node -p require(process.env.HOME /.openclaw/openclaw.json).gateway.auth.token然后把 token 粘贴到 Dashboard 的认证框或直接用带 token 的地址打开http://127.0.0.1:18789/#tokentoken。 token 等同于完全控制权切勿外泄。若命令报错多半是手动编辑过~/.openclaw/openclaw.json注释会导致 JSON 非法直接打开该文件复制gateway.auth.token的值若完全没有这个字段运行openclaw doctor --generate-gateway-token生成。5. SSH 连接被拒绝Connection refused症状ssh: connect to host 192.168.x.x port 8022: Connection refused成因Termux 的 SSH 服务sshd没在运行。关闭 Termux 应用或重启手机都会让 sshd 停止另外 Wi-Fi 重连后手机 IP 也可能变了。修复打开手机上的 Termux 应用直接输入sshd启动服务用ifconfig查看wlan0下inet后面的新 IP 地址用新 IP 从电脑重新ssh -p 8022 IP。想省事的话在~/.bashrc末尾追加sshd 2/dev/null以后每次打开 Termux 就会自动启动 SSH 服务。完整连接方法见 docs/termux-ssh-guide.md。6. 命令执行失败环境未加载症状 Aopenclaw --version失败或提示找不到命令。症状 BError: Cannot find module /data/data/com.termux/files/home/.openclaw-lite/patches/glibc-compat.js成因A 是环境变量没有加载B 是旧版1.0.0 之前的 Bionic 安装项目当时叫 OpenClaw Lite升级后~/.bashrc里的NODE_OPTIONS仍指向旧路径.openclaw-lite。修复source ~/.bashrc # 症状 A重新加载环境 oa --update source ~/.bashrc # 症状 B刷新环境变量块B 也可以手动把旧路径批量替换掉sed -i s/\.openclaw-lite/\.openclaw-android/g ~/.bashrc source ~/.bashrcglibc 兼容层本身位于 patches/glibc-compat.jsv1.0.0 之后的 glibc 版本由 node 包装脚本加载不再依赖NODE_OPTIONS。7.spawn systemctl ENOENT无害症状Gateway service check failed: Error: systemctl --user unavailable: spawn systemctl ENOENT说明这个错误无害——它只出现在旧版本v1.1.0 之前跑openclaw update的场景中。OpenClaw 想用自己的服务管理器重启 gateway但 Termux 没有 systemd自然找不到systemctl项目用 patches/systemctl 做了垫片。更新本身其实已经成功只是自动重启服务这一步失败了。修复手动启动即可openclaw gateway如果 gateway 之前就在运行需要先按场景 2 停掉旧进程再启动。8.Bad system callSIGSYS症状运行 OpenClaw 时进程直接报Bad system call退出。成因OpenClaw 的文件安全模块openclaw/fs-safe原生助手使用了openat2系统调用而 Android 的应用 seccomp 策略会在该调用上直接杀掉进程SIGSYS。node 包装脚本默认已设置FS_SAFE_TEST_NO_OPENAT21规避此问题。修复正常情况下无需任何操作。若仍出现确认环境变量值精确为1echo $FS_SAFE_TEST_NO_OPENAT2输出不是1就把它设为1。最后的手段是彻底关闭原生助手export FS_SAFE_NATIVE_MODEoff——代价是部分数据迁移可能被 OpenClaw 拒绝。9.[BLOCKED]openclaw 更新被拦截症状执行openclaw update、点击 Dashboard 的 Update 按钮或 Agent 自行发起更新时都会看到[BLOCKED] OpenClaw is pinned to the version verified by OpenClaw on Android. Run oa --update to update safely. (openclaw update status is allowed.)成因本项目把 OpenClaw 和 Node.js 固定为一对经过验证的组合版本当前为 OpenClaw 2026.9.8 Node.js 24.21.0见 platforms/openclaw/config.env#L30-L31。直接openclaw update会拉取 npm 最新版可能要求更高的 Node.js 而启动失败因此安装时写入的守卫会拦截所有绕过守卫的更新路径包括openclaw update --yes、openclaw update repair和 gateway 自动更新。修复不要点 Update 按钮改用项目自己的更新命令oa --update source ~/.bashrcopenclaw update status只读不受拦截可正常查询。10.oa --update被阻止oa --update在改任何东西之前会做多项安全检查遇到以下提示说明它保护了现有环境按提示处理后重跑即可提示成因与修复[FAIL] The OpenClaw gateway is running.更新会替换 OpenClaw 和 Node.js运行中的 gateway 跟不上。先在 gateway 所在终端按CtrlC或在 Android 设置应用 Claw 中强制停止注意从最近任务划掉 App 不会停掉前台服务再重跑oa --update。极个别误报如tail -f …gateway.log可用OA_SKIP_GATEWAY_CHECK1 oa --update[FAIL] Another update, setup or tools run is in progress.安装/更新/工具安装共用一把锁~/.openclaw-android/.tools.lock。等另一个任务结束再跑若上次运行被强杀锁的pid文件失效后会自动接管等约 1 分钟再试。确认无任何任务在跑时才可用rm -rf ~/.openclaw-android/.tools.lock兜底[FAIL] Not enough free storage ... 2000 MB needed全新安装和改版本的更新都要求2000 MB空闲空间。清理缓存、无用文件或~/.npm/_cacache后重试重试是安全的尚未做任何改动11. 更新后启动失败数据迁移与硬链接补丁state database schema migration required更新到 OpenClaw 2026.9.8 时可能需要迁移旧数据。oa --update只在自己创建了备份~/.openclaw-android/backup/pre-update/的情况下才会自动执行一次openclaw doctor --fix如果迁移失败、被跳过或更新中途被强杀gateway 可能拒绝启动。修复先停 gateway然后手动迁移再启动openclaw doctor --fix openclaw gateway出问题时oa --restore可以列出pre-update/备份回滚数据只恢复数据不恢复程序自动迁移的完整日志在~/.openclaw-android/doctor-fix.log。Hard-link patch: not complete/linkat … Permission deniedAndroid 禁止在应用数据区使用硬链接和 reflinkFICLONE而 OpenClaw 2026.9.8 依赖硬链接移动聊天历史。本项目在每次安装/更新时都会打上 platforms/openclaw/patches/openclaw-patch-hardlink.sh 补丁让其回退为普通复制。如果你用 npm 重装过 OpenClaw 导致补丁丢失重新应用即可oa --update source ~/.bashrc # 或 npm install -g openclaw2026.9.8然后用oa --status确认显示Hard-link patch: applied (…)。备份与恢复脚本见 scripts/backup.sh。12.signal 9进程被 Android 杀死症状gateway、sshd 等后台进程无征兆退出Termux 显示[Process completed (signal 9) - press Enter]成因Android 12 的Phantom Process KillerPPK会在系统层面直接 SIGKILL 后台进程任何程序都拦截不了。修复一次性设置重启后依然有效下拉通知栏在 Termux 通知中点Acquire wakelock之后会显示 wake lock held设置开发者选项开启Wireless debugging并勾选始终允许确认已装android-tools本项目已内置pkg install -y android-tools在 Wireless debugging 中点使用配对码配对设备在 Termux 执行adb pair localhost:配对端口配对码 adb connect localhost:连接端口 # 用主界面显示的端口不是配对端口关闭 PPK 并验证adb shell settings put global settings_enable_monitor_phantom_procs false adb shell settings get global settings_enable_monitor_phantom_procs # 输出 false 即成功完成后可以关闭 Wireless debugging恢复出厂设置后需要重做一遍。厂商额外的省电策略三星、小米等若仍杀进程参考 docs/disable-phantom-process-killer.md 的完整图文指引。附可以安全忽略的无害报错速查报错场景处理方式npm error gyp ERR! not oksharp 构建旧版本openclaw update期间固定版本用 photon 处理图片不需要 sharp可忽略[node-llama-cpp] Cloning ggml-org/llama.cpp/npm error 48%从源码编译 llama.cpp预编译的linux-arm64二进制已就绪且可用本地嵌入失败时会自动回退到云端服务Cannot find package undiciclawdhubTermux 的 Node.js 24 不再内置 undicioa --update或cd $(npm root -g)/clawdhub npm install undiciGateway service install not supported on android仅 1.0.0 之前的 Bionic 安装source ~/.bashrc升级到 v1.0.0glibc后process.platform报告为linux问题永久消失完整解释见 docs/troubleshooting.md#L506、docs/troubleshooting.md#L532、docs/troubleshooting.md#L556。故障排查相关文档与文件索引文件说明docs/troubleshooting.md完整故障排查文档本文蓝本含全部场景细节docs/troubleshooting.ko.md韩文版故障排查文档docs/termux-ssh-guide.mdTermux SSH 连接配置指南端口 8022docs/disable-phantom-process-killer.md进程保活与 PPK 关闭图文指南platforms/openclaw/config.env平台元数据与版本固定声明platforms/openclaw/patches/openclaw-patch-hardlink.shAndroid 硬链接/Reflink 兼容补丁patches/glibc-compat.jsNode.js 运行时兼容补丁scripts/backup.shoa --backup/oa --restore备份与恢复tests/verify-install.sh安装后校验脚本README.md安装步骤与 CLI 参考含oa命令速查表✅ 排查收尾三条黄金习惯先停 gateway再动更新——oa --update和openclaw doctor --fix都要求 gateway 处于停止状态oa --status是你的体检单——组件版本、补丁状态、异常一目了然报告问题时附上它和~/.openclaw-android/doctor-fix.log最快token 和备份要当隐私管——gateway token 等同完全控制权备份文件包含 API 密钥切勿上传公开位置。按这份清单从上往下对一遍绝大多数 OpenClaw on Android 的故障都能在一次操作内恢复。赞分享移动开发AI 应用CLI开发工具【免费下载链接】openclaw-androidRun OpenClaw on Android with a single command — no proot, no Linux项目地址https://gitcode.com/gh_mirrors/op/openclaw-android点击查看免费下载相关推荐OpenCore故障排查清单12个最常见的启动失败原因及快速解决方案OpenCore故障排查清单12个最常见的启动失败原因及快速解决方案 OpenCoreOpenCorePkg是一款开源的 UEFI 引导加载程序用于在固件操作系统嵌入式Ceph Object Gatewayradosgw故障排查实战指南从启动失败到请求阻塞的全链路诊断Ceph Object Gatewayradosgw故障排查实战指南从启动失败到请求阻塞的全链路诊断本文基于 Ceph 官方文档 doc/radosgw存储分布式文件系统对象存储后端高可用ZCF 故障排除实战指南从初始化失败到 CCR 端口占用的系统性排查方法ZCF 故障排除实战指南从初始化失败到 CCR 端口占用的系统性排查方法本篇围绕 ZCF 故障排除文档 https://link.gitcode.com/i开发工具CLIAI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

OpenClaw on Android故障排查清单：12个常见失败场景诊断指南（从CANNOT LINK EXECUTABLE到Gateway端口占用）

相关推荐

单输入框双模式：这款 3MB 浏览器的地址栏设计哲学拆解

按键精灵鼠标循环点击全攻略：坐标、延时、防漂移一次搞定

PHP+微信小程序学习交流平台：从架构到答辩的完整实战指南

更多资讯

Linux运维实战：grep统计、pkill杀进程与truncate清空日志的避坑指南

RabbitMQ死信队列实战：从概念到配置，解决消息丢失问题

Linux网络编程实战：从HTTP到自定义TCP协议的计算器重写

SpringBoot+Vue+MySQL文物征集管理系统设计与实现全解析

cmux：面向Agent与LLM应用的上下文管理中间件实践

高光谱遥感影像分类实战：Python实现(2D)²PCA降维与双通道CNN-SVM融合

今日更新

再见，SSE！你好，Streamable HTTP！轻松开发 Streamable HTTP MCP Server 并接入 TaoToken

工业软件标准化路线图：国产替代的落地施工图

VCMI安卓版实操指南：原生运行英雄无敌3的3步技术落地

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？