nanobot Android 安装指南

本指南将帮助你在 Android 手机上安装和使用 nanobot。

📋 系统要求

Android 版本: 7.0 (API level 24) 或更高
存储空间: 至少 200 MB 可用空间
网络连接: 需要联网调用 LLM API
Termux: 从 F-Droid 安装（不要用 Google Play 版本，已过时）

🚀 安装步骤

第一步：安装 Termux

重要提示：请从 F-Droid 安装 Termux，不要从 Google Play 安装（版本已过时）。

在手机浏览器中访问 https://f-droid.org/
下载并安装 F-Droid
打开 F-Droid，搜索 "Termux"
安装 Termux

第二步：在 Termux 中安装 nanobot

有两种方式安装：

方式 1：从源码安装（推荐，开发中）

前提条件：

手机和电脑在同一网络下
或者项目已经托管到 GitHub/GitLab 等平台

步骤 1：在 Termux 中安装 git

# 更新包列表
pkg update

# 安装 git
pkg install git -y

# 验证安装
git --version
# 应该显示：git version 2.x.x

步骤 2：克隆项目到手机

方法 A：从 GitHub/GitLab 克隆（推荐）

# 进入用户主目录
cd ~

# 克隆项目（替换成你的实际仓库地址）
# 格式 1: HTTPS 方式（最简单，无需配置）
git clone https://github.com/sa1ka/nanobot-android.git

# 格式 2: SSH 方式（需要先配置 SSH 密钥）
git clone git@github.com:sa1ka/nanobot-android.git

# 进入项目目录
cd nanobot-android

# 查看项目内容
ls

方法 B：使用 USB 传输（离线方式）

# 1. 在电脑上打包项目
#    在电脑终端运行：
zip -r nanobot-android.zip nanobot-android/ -x "*/node_modules/*" "*/.git/*" "*/__pycache__/*"

# 2. 通过 USB 传输到手机
#    - 连接手机到电脑
#    - 复制 nanobot-android.zip 到手机的 Download 文件夹

# 3. 在 Termux 中解压
cd /storage/emulated/0/Download
unzip nanobot-android.zip -d ~
cd ~/nanobot-android

方法 C：使用局域网共享（快速方式）

# 1. 在电脑上启动 HTTP 服务器（在项目目录）
#    在电脑终端运行：
cd nanobot-android
python3 -m http.server 8000

# 2. 在手机浏览器中下载
#    打开 Chrome，访问：http://电脑的IP地址:8000
#    例如：http://192.168.1.100:8000
#    下载整个项目的 .zip 文件

# 3. 在 Termux 中解压并安装
cd /storage/emulated/0/Download
unzip nanobot-android-master.zip -d ~
cd ~/nanobot-android

步骤 3：安装 Python 依赖

# 确保在项目根目录（包含 pyproject.toml 的目录）
pwd
# 应该显示：/data/data/com.termux/files/home/nanobot-android

# 检查项目文件
ls pyproject.toml
# 应该显示：pyproject.toml

# 安装项目依赖（开发模式）
pip install -e .

# 如果遇到网络问题，使用国内镜像：
pip install -e . -i https://pypi.tuna.tsinghua.edu.cn/simple

# 验证安装
nanobot --version
# 应该显示：nanobot x.x.x

步骤 4：验证安装

# 检查 nanobot 命令是否可用
which nanobot
# 应该显示：/data/data/com.termux/files/usr/bin/nanobot

# 查看帮助信息
nanobot --help

# 查看状态
nanobot status

常见问题排查

问题 1：git clone 失败 - 仓库地址错误

fatal: repository 'https://github.com/xxx/xxx.git/' not found

解决：

检查仓库地址是否正确
确认仓库是公开的，或者你有访问权限
尝试在浏览器中访问仓库地址验证

问题 2：网络连接超时

fatal: unable to access 'https://github.com/...': Connection timed out

解决：

# 检查网络连接
ping -c 3 github.com

# 如果无法访问，使用 USB 传输方式（方法 B）

问题 3：pip install 缺少依赖

ERROR: Could not find a version that satisfies the requirement...

解决：

# 更新 pip
pip install --upgrade pip

# 更新包管理器
pkg update && pkg upgrade

# 再次尝试安装
pip install -e .

问题 4：权限不足

Permission denied: './gradlew'

解决：

# 给 gradlew 添加执行权限
chmod +x android/gradlew

目录结构说明

克隆后的项目结构：

~/nanobot-android/
├── nanobot/              # Python 后端核心代码
│   ├── api/             # FastAPI 服务
│   ├── agent/           # Agent 逻辑
│   ├── cli/             # 命令行工具
│   └── ...
├── android/             # Android APP 源码
│   ├── app/
│   ├── build.gradle.kts
│   └── ...
├── docs/                # 文档
├── tests/               # 测试
├── pyproject.toml       # Python 项目配置
├── README.md            # 项目说明
└── ...

方式 2：从 PyPI 安装（如果已发布）

# 更新包管理器
pkg update && pkg upgrade -y

# 安装 Python 和 termux-api
pkg install python termux-api -y

# 安装 nanobot
pip install nanobot-ai

开发提示：

✅ 当前开发阶段：建议使用方式 1从源码安装，可以实时修改和测试代码
✅ 源码安装优势：可以直接编辑代码，无需重新安装
✅ 网络问题：如果下载失败，使用 USB 传输（方式1的方法 B）
⚠️ PyPI 安装：仅当项目正式发布到 PyPI 后使用

第三步：配置 nanobot

运行配置向导：

nanobot onboard

这会创建配置文件并引导你设置 API Key。

第四步：添加 LLM API Key

编辑配置文件：

nano ~/.nanobot/config.json

添加你的 API Key。支持多种 LLM 提供商：

智谱 AI (GLM-4) - 推荐

{
  "agents": {
    "defaults": {
      "model": "glm-4"
    }
  },
  "providers": {
    "zhipu": {
      "api_key": "你的智谱API密钥"
    }
  }
}

获取 API Key: https://open.bigmodel.cn/

OpenRouter (多模型支持)

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-3-haiku"
    }
  },
  "providers": {
    "openrouter": {
      "api_key": "你的OpenRouter API密钥"
    }
  }
}

获取 API Key: https://openrouter.ai/keys

OpenAI

{
  "agents": {
    "defaults": {
      "model": "gpt-4o-mini"
    }
  },
  "providers": {
    "openai": {
      "api_key": "你的OpenAI API密钥"
    }
  }
}

保存并退出（按 Ctrl+X，然后按 Y，最后按 Enter）。

第五步：启动 nanobot API 服务器

nanobot api

你应该看到：

Starting nanobot API server on 127.0.0.1:8000...
Agent initialized with model glm-4
INFO:     Uvicorn running on 127.0.0.1:8000

重要提示：保持 Termux 在后台运行，不要关闭！

第六步：安装 Android APP

有两种方式安装：

方式 1：从源码构建（开发者）

如果你已经在开发环境：

在 Android Studio 中打开项目
连接 Android 设备或启动模拟器
点击 Run 按钮
或在命令行运行：
```
cd android
./gradlew installDebug
```

方式 2：安装 APK（普通用户）

下载 nanobot.apk
在 Android 设置中启用"允许安装未知来源应用"
打开 APK 文件进行安装

第七步：验证连接

打开 nanobot APP，它应该会自动连接到 Termux 后端。

如果连接成功，你就能看到聊天界面，可以开始与 AI 对话了！

🔧 可选配置

自动启动 API 服务（开机自启）

如果你想开机后自动启动 nanobot API 服务，可以使用 Termux:Boot。

在 Termux 中安装 termux-boot：
```
pkg install termux-boot
```
在 Android 中安装 Termux:Boot（从 F-Droid）
授予 Termux:Boot 自启动权限

创建启动脚本：

mkdir -p ~/.termux/boot
cat > ~/.termux/boot/nanobot.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/bash
nanobot api
EOF
chmod +x ~/.termux/boot/nanobot.sh

重启手机，API 服务会自动启动

创建快捷方式

使用 Termux:Widget 可以在桌面创建快捷方式：

安装 Termux:Widget（从 F-Droid）

创建快捷脚本：

mkdir -p ~/.termux/shortcuts
cat > ~/.termux/shortcuts/start-nanobot.sh << 'EOF'
#!/data/data/com.termux/files/usr/bin/bash
nanobot api
EOF
chmod +x ~/.termux/shortcuts/start-nanobot.sh

长按桌面，选择快捷方式，找到 "Termux:Widget"
选择 "start-nanobot" 创建快捷方式

❓ 故障排查

问题 1：APP 显示"连接失败"

原因：Termux 中的 API 服务没有运行

解决方案：

检查 Termux 是否在运行 nanobot api
如果 Termux 被关闭了，重新运行 nanobot api
确保没有防火墙阻止 localhost:8000

问题 2：API Key 错误

原因：配置文件中的 API Key 无效或格式错误

解决方案：

检查 ~/.nanobot/config.json 中的 API Key 是否正确
可以用命令行测试：nanobot agent -m "测试"
如果 API Key 过期，需要重新获取

问题 3：Termux 在后台被杀死

原因：Android 的电池优化杀掉了 Termux 进程

解决方案：

进入 Android 设置 → 应用 → Termux → 电池
选择"不优化"或"无限制"
也可以在 Termux 中运行：
```
termux-setup-storage
```

问题 4：安装失败或网络错误

原因：网络连接问题或包管理器源不可用

解决方案：

尝试使用国内镜像源：

sed -i 's/pkg.tuna.tsinghua.edu.cn/mirrors.tuna.tsinghua.edu.cn/g' $PREFIX/etc/apt/sources.list
pkg update

或使用 VPN
检查手机网络连接

问题 5：Python 包安装失败

原因：pip 版本过低或网络问题

解决方案：

# 升级 pip
pip install --upgrade pip

# 使用国内镜像
pip install nanobot-ai -i https://pypi.tuna.tsinghua.edu.cn/simple

💡 使用技巧

1. 保持 Termux 后台运行

Android 8.0+: 在 Termux 中按音量上键 + Q 键，保持会话
或在通知栏锁定 Termux 通知
设置电池优化为"不优化"

2. 查看日志

如果遇到问题，可以在 Termux 中查看详细日志：

nanobot api --log-level debug

3. 多会话管理

APP 支持多个会话，每个会话有独立的上下文历史：

在聊天界面点击菜单按钮
选择"新建会话"
会话会自动保存到 Termux 后端

4. 测试 API 连接

在 Termux 中测试 API 是否正常：

curl http://127.0.0.1:8000/api/health

应该返回：

{"status":"ok","version":"0.1.3.post5"}

📱 界面说明

聊天界面

顶部栏：显示 "nanobot" 标题和连接状态
消息列表：显示对话历史
- 右侧蓝色气泡：用户消息
- 左侧绿色气泡：AI 回复
输入框：底部输入消息
发送按钮：发送消息（仅在有输入时可用）

状态指示

连接中：显示加载动画
思考中：右上角显示进度圆圈
就绪：输入框可用，可以发送消息

设置向导界面

如果 APP 无法连接后端，会显示设置向导：

确认 Termux 已安装并运行 nanobot api
点击"检查连接"按钮重试
查看详细设置步骤

🔄 更新

更新 nanobot

pip install --upgrade nanobot-ai

更新 Android APP

如果从源码构建：

cd android
git pull
./gradlew installDebug

如果是 APK 安装，需要下载新版本的 APK 并重新安装。

📚 更多资源

nanobot 项目: https://github.com/yourusername/nanobot
Termux Wiki: https://wiki.termux.com/
F-Droid: https://f-droid.org/

🤝 获取帮助

如果遇到问题：

查看本文档的"故障排查"部分
在 Termux 中运行 nanobot api --log-level debug 查看详细日志
在 GitHub 上提 Issue：https://github.com/yourusername/nanobot/issues
加入社区讨论（如果有）

📄 许可证

MIT License - 详见 LICENSE 文件

FilesExpand file tree

android-install.md

Latest commit

History

android-install.md

File metadata and controls

nanobot Android 安装指南

📋 系统要求

🚀 安装步骤

第一步：安装 Termux

第二步：在 Termux 中安装 nanobot

方式 1：从源码安装（推荐，开发中）

步骤 1：在 Termux 中安装 git

步骤 2：克隆项目到手机

步骤 3：安装 Python 依赖

步骤 4：验证安装

常见问题排查

目录结构说明

方式 2：从 PyPI 安装（如果已发布）

第三步：配置 nanobot

第四步：添加 LLM API Key

智谱 AI (GLM-4) - 推荐

OpenRouter (多模型支持)

OpenAI

第五步：启动 nanobot API 服务器

第六步：安装 Android APP

方式 1：从源码构建（开发者）

方式 2：安装 APK（普通用户）

第七步：验证连接

🔧 可选配置

自动启动 API 服务（开机自启）

创建快捷方式

❓ 故障排查

问题 1：APP 显示"连接失败"

问题 2：API Key 错误

问题 3：Termux 在后台被杀死

问题 4：安装失败或网络错误

问题 5：Python 包安装失败

💡 使用技巧

1. 保持 Termux 后台运行

2. 查看日志

3. 多会话管理

4. 测试 API 连接

📱 界面说明

聊天界面

状态指示

设置向导界面

🔄 更新

更新 nanobot

更新 Android APP

📚 更多资源

🤝 获取帮助

📄 许可证