Termux 持久化网关

--- name: termux-persistent-gateway description: "在 Android/Termux 上持久运行 AI agent 网关 —— 基于 tmux + wake-lock + 开机自启 + 健康监控。无需 systemd。适用场景：(1) 在 Termux/Android 上运行网关，(2) 确保网关在屏幕关闭或设备重启后仍存活，(3) 在 Termux 中配置自动重启与健康监控。" version: 1.1.0 author: kingofqin2026 license: MIT tags: [termux, android, gateway, persistent, tmux, wake-lock, auto-start] --- # Termux 持久化网关
让您的 AI agent 网关在 Android 设备上长期稳定运行（无需 systemd），可抵御屏幕关闭、应用切换及设备重启等常见中断。

## 先决条件 bash pkg install tmux termux-api termux-boot - tmux — 终端复用器，可在您关闭 Termux 应用时保持会话持续运行 - termux-api — 提供 termux-wake-lock 和 termux-notification 等命令 - termux-boot — 支持设备启动时自动执行脚本 - Android 设置：设置 > 应用 > Termux > 电池 > 不受限制（关键步骤 — 防止 Android 杀死 Termux 进程） ## 配置 首次使用前，请编辑脚本以设置以下参数： - GATEWAY_CMD — 启动网关的命令（例如：openclaw gateway run、hermes gateway run） - SESSION_NAME — tmux 会话名称（默认：agent-gw） - LOG_DIR — 日志存储路径（默认：~/.agent/logs） 所有可配置项均位于各脚本顶部 — 请查找 # === CONFIG === 区块。 ## 快速开始 ### 启动网关 bash bash /scripts/run-gateway.sh 该脚本将执行以下操作： 1. 获取 wake lock（termux-wake-lock），防止 CPU 进入休眠 2. 终止已存在的旧网关 tmux 会话 3. 在新的 tmux 会话中启动您的网关命令 4. 将输出日志写入配置指定的日志目录 ### 会话管理 | 操作 | 命令 | |------|------| | 连接会话（查看实时输出） | tmux attach -t agent-gw | | 断开连接 | Ctrl+B, D | | 检查是否正在运行 | tmux ls | | 查看最近日志 | tail -f ~/.agent/logs/gateway-termux.log | | 重启网关 | 终止当前会话后重新运行启动脚本 | ### 连接后断开连接 当您通过 tmux attach 进入会话后，按 Ctrl+B，松开后再按 D，即可安全断开而不终止会话 — 网关将继续后台运行。 ## 设备开机自启 ### 第一步：启用 Termux:Boot bash pkg install termux-boot mkdir -p ~/.termux/boot/ 从应用抽屉中至少打开一次 Termux:Boot 应用，以便向 Android 系统完成注册。 ### 第二步：创建启动脚本 复制模板并调整路径： bash cp /templates/termux-boot.sh ~/.termux/boot/agent-gateway chmod +x ~/.termux/boot/agent-gateway 编辑 ~/.termux/boot/agent-gateway，将 SCRIPT 变量指向您的 run-gateway.sh 实际路径。其中 sleep 15 用于等待 Wi-Fi 连接建立完成。 此后，每次设备重启时网关将自动启动。 ## 健康监控（Cron） （可选）定期检查网关状态，并在其异常退出时自动重启。 bash bash /scripts/healthcheck.sh 如需定时执行，请添加到 Termux 的 crontab： bash crontab -e # 添加：*/30 * * * * bash ~/.agent/scripts/healthcheck.sh 或使用您 agent 自带的 cron 系统，每 30 分钟运行一次 healthcheck。 ## 验证是否正常工作 bash # 检查网关是否运行中
tmux ls # 应显示类似：agent-gw: 1 windows (created ...)
# 检查 wake-lock 是否已获取
termux-wake-lock 2>/dev/null || echo "wake-lock not acquired (probably already held)" ## 故障排查 | 问题 | 解决方法 | |------|----------| | 屏幕关闭后网关终止 | 将 Termux 的电池优化设为 不受限制 | | 关闭 Termux 应用后网关终止 | 不要强制停止 Termux；只需从最近任务中滑掉 — tmux 会话仍将持续运行 | | 开机自启失效 | 确保已至少打开一次 Termux:Boot 应用；检查 ~/.termux/boot/ 下脚本是否具有可执行权限 | | 开机时提示 “command not found” | 启动脚本会 source .profile 来加载 PATH — 请确保您的网关二进制文件已加入 PATH | | tmux 会话显示 “(dead)” | 表明网关进程已崩溃。请检查日志后重新运行启动脚本 | | wake-lock 获取失败 | 确认已安装 termux-api，且已授予通知权限 |