BotDrop Android GUI 设计文档

目标：用户从安装到运行 OpenClaw，全程 零命令行 核心哲学：App GUI 只负责点火，配置交给 AI 自己完成

核心理念

App 做最少的事：装好 OpenClaw → 填 API Key → 连一个频道 → 启动。之后所有进一步配置（加频道、调模型、装 skill 等）用户直接跟 BotDrop 的 TG bot / DC bot 聊天完成。

不做自己的 Web UI，不复制 OpenClaw control-ui。

当前流程（需要终端）

安装 APK → 打开 → Termux 终端 → 自动跑 first-run.sh
→ 手动 `openclaw onboard` → CLI 向导
→ 手动 `openclaw gateway start`

目标流程（纯 GUI）

安装 APK → 打开 → 自动安装（进度条，无终端）
→ 选 Provider + Auth → 用 @BotDropSetupBot 连频道（或手动）→ 启动
→ 之后跟自己的 bot 聊天做后续配置

架构

┌─────────────────────────────────────────────────────────────┐
│  App 启动 (BotDropLauncherActivity)                            │
│  ↓                                                          │
│  检查状态:                                                    │
│  - bootstrap 解压完？ → 否 → 等 TermuxInstaller               │
│  - openclaw 装好了？  → 否 → SetupActivity (自动安装)         │
│  - 配好 API Key？     → 否 → SetupActivity (填 key)          │
│  - 配好频道？         → 否 → SetupActivity (连频道)           │
│  - 全部就绪          → DashboardActivity                     │
└─────────────────────────────────────────────────────────────┘

组件清单

组件	类型	职责
`BotDropLauncherActivity`	Activity	启动路由
`SetupActivity`	Activity + ViewPager2	3 步向导
`DashboardActivity`	Activity	极简状态面板
`BotDropService`	Foreground Service	后台运行 gateway + 命令执行
`TermuxActivity`	(保留)	高级入口，从 Dashboard 进

向导页面 (SetupActivity) — 只有 3 步

Step 1: Welcome + 自动安装

┌──────────────────────────────┐
│                              │
│         🦉                   │
│      BotDrop                 │
│                              │
│  Your AI assistant,          │
│  running on your phone.      │
│                              │
│  ━━━━━━━━━━━━━━━━━━━━━━━━   │
│                              │
│  ✓ Environment ready         │
│  ● Installing OpenClaw...    │
│                              │
│  This takes about a minute   │
│                              │
└──────────────────────────────┘

Welcome + 安装合并为一页
打开即自动开始（不需要点 "Get Started"，减少一次点击）
后台静默执行：chmod → 验证 node/npm → npm install openclaw
进度步骤用 ✓/●/○ 显示
安装完成自动滑到下一步
失败 → 显示 "Retry" 按钮 + 可展开的错误详情

Step 2: AI Provider + Auth

OpenClaw 支持多种认证方式，App 需要对应处理：

认证类型	Provider 举例	App 处理方式
API Key（粘贴）	Anthropic, OpenAI, OpenRouter, Gemini, Kimi, Venice, MiniMax	文本输入框
Setup Token（粘贴）	Anthropic `claude setup-token`	文本输入框（不同提示文案）
OAuth（浏览器）	OpenAI Codex, Google, Qwen, Chutes	跳浏览器 → 回调 deep link
Device Flow	GitHub Copilot	显示 code + URL，用户手动验证

UI 设计 — 选择 Provider：

┌──────────────────────────────┐
│  ← Step 2/3                  │
│                              │
│  Choose your AI              │
│                              │
│  Popular                     │
│  ┌────────────────────────┐  │
│  │ ◉ Anthropic (Claude)   │  │
│  │   Setup Token or Key   │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │ ○ OpenAI               │  │
│  │   ChatGPT login or Key │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │ ○ Google (Gemini)      │  │
│  │   API key or OAuth     │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │ ○ OpenRouter           │  │
│  │   API key (any model)  │  │
│  └────────────────────────┘  │
│                              │
│  More providers ▼            │
│  (Kimi, MiniMax, Venice...) │
│                              │
└──────────────────────────────┘

选 Anthropic → 选认证方式：

┌──────────────────────────────┐
│  ← Anthropic                 │
│                              │
│  How to connect?             │
│                              │
│  ┌────────────────────────┐  │
│  │ ⭐ Setup Token          │  │
│  │   Easiest — paste from  │  │
│  │   claude.ai/settings    │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │    API Key              │  │
│  │   From console.         │  │
│  │   anthropic.com         │  │
│  └────────────────────────┘  │
│                              │
└──────────────────────────────┘

Setup Token 输入：

┌──────────────────────────────┐
│  ← Anthropic Setup Token     │
│                              │
│  1. Open claude.ai/settings  │
│     → "Setup Token"          │
│  2. Copy the token           │
│  3. Paste below              │
│                              │
│  Token                       │
│  ┌────────────────────────┐  │
│  │ stp_••••••••••••••     │👁│
│  └────────────────────────┘  │
│                              │
│  [  Verify & Continue  ]     │
│                              │
│  ✓ Connected!                │
│    Model: claude-sonnet-4-5  │
└──────────────────────────────┘

选 OpenAI → OAuth 流程：

┌──────────────────────────────┐
│  ← OpenAI                    │
│                              │
│  ┌────────────────────────┐  │
│  │ ⭐ Sign in with ChatGPT │  │
│  │   Use your OpenAI       │  │
│  │   account (OAuth)       │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │    API Key              │  │
│  │   From platform.        │  │
│  │   openai.com            │  │
│  └────────────────────────┘  │
│                              │
└──────────────────────────────┘

点 "Sign in with ChatGPT" →
┌──────────────────────────────┐
│                              │
│  Opening browser for         │
│  OpenAI sign-in...           │
│                              │
│  ●●● Waiting for auth        │
│                              │
│  Complete the login in your  │
│  browser, then come back.    │
│                              │
└──────────────────────────────┘
→ 打开系统浏览器 → OAuth 回调 → 自动返回 App

OAuth 回调技术要点：

注册 deep link scheme: botdrop://oauth-callback
OpenClaw OAuth flow 会启动 localhost server 监听回调
Android 上需要拦截 http://127.0.0.1:1455/oauth-callback 或 http://127.0.0.1:1456/oauth-callback
或者让 openclaw 直接处理（在 proot 环境里跑 OAuth flow，打开浏览器用 termux-open-url）

最简方案：调用 openclaw auth CLI

部分 auth 流程（尤其 OAuth）在 CLI 里已经实现完整
App 可以在后台启动一个 headless terminal session 跑 openclaw auth set
需要浏览器时调用 termux-open-url
这样不需要在 Java 侧重新实现每种 auth 逻辑

Step 3: Connect a Channel — @BotDropSetupBot 辅助

核心思路：运维一个官方 @BotDropSetupBot（TG + DC），帮用户完成最卡人的步骤。

为什么需要 Helper Bot：

创建 bot、拿 token、找 user ID 这三步对新手很卡
Helper Bot 自动检测 user ID（用户发消息就能拿到）
引导式对话比文档/截图更友好
最终生成一个 setup code 给用户粘贴到 App

流程：

┌──────────────────────────────┐
│  ← Step 3/3                  │
│                              │
│  Connect a chat platform     │
│                              │
│  ┌────────────────────────┐  │
│  │ ⭐ Use @BotDropSetupBot   │  │
│  │   Guided setup (easy)   │  │
│  └────────────────────────┘  │
│                              │
│  ┌────────────────────────┐  │
│  │   Set up manually       │  │
│  │   I have a bot token    │  │
│  └────────────────────────┘  │
│                              │
└──────────────────────────────┘

选 @BotDropSetupBot：

┌──────────────────────────────┐
│  Setup via @BotDropSetupBot    │
│                              │
│  Which platform?             │
│                              │
│  ┌────────────────────────┐  │
│  │ 📱 Telegram             │  │
│  │  → Open @BotDropSetupBot  │  │
│  └────────────────────────┘  │
│  ┌────────────────────────┐  │
│  │ 💬 Discord              │  │
│  │  → Invite Setup Bot     │  │
│  └────────────────────────┘  │
│                              │
│  After setup, paste your     │
│  code below:                 │
│                              │
│  Setup Code                  │
│  ┌────────────────────────┐  │
│  │ BOTDROP-xxxxxxxxxxxx     │  │
│  └────────────────────────┘  │
│                              │
│  [  Connect & Start  ]       │
│                              │
└──────────────────────────────┘

@BotDropSetupBot 对话流程（Telegram 示例）：

User: /start
Bot:  🦉 Welcome to BotDrop Setup!
      I'll help you set up your personal AI bot.
      
      First, let's create your bot:
      1. Open @BotFather
      2. Send /newbot
      3. Choose a name and username
      4. Copy the token and send it to me

User: 7123456789:AAF8x...（粘贴 token）

Bot:  ✅ Got it!
      
      Your info:
      • Bot token: 7123456...✓
      • Your Telegram ID: 987654321 (auto-detected)
      
      Your setup code:
      ╔════════════════════════════╗
      ║  BOTDROP-tg-A7x9Kp2mB4...  ║
      ╚════════════════════════════╝
      
      → Go back to the BotDrop app and paste this code.
      
      (Code expires in 10 minutes)

Setup Code 内容（base64 编码的 JSON）：

{
  "v": 1,
  "platform": "telegram",
  "bot_token": "7123456789:AAF8x...",
  "owner_id": "987654321",
  "created_at": 1738764000
}

App 解码后直接写入 openclaw.json 的 channels 配置。

Helper Bot 的好处：

User ID 零输入（bot 自动从 message.from.id 拿到）
Token 输入有 即时验证（bot 可以调 TG API 验证 token 有效性）
引导文案在 聊天界面 里，用户不用切来切去看文档
错误可以 对话式排查（"这个 token 看起来不对，确认是从 @BotFather 拿的吗？"）

手动模式（高级用户）保留：

┌──────────────────────────────┐
│  Manual Setup                │
│                              │
│  Platform                    │
│  ┌────────────────────────┐  │
│  │ 📱 Telegram          ▼ │  │
│  └────────────────────────┘  │
│                              │
│  Bot Token                   │
│  ┌────────────────────────┐  │
│  │ 123456:ABC-DEF...      │  │
│  └────────────────────────┘  │
│                              │
│  Your User ID (owner)        │
│  ┌────────────────────────┐  │
│  │ 987654321               │  │
│  └────────────────────────┘  │
│                              │
│  [  Connect & Start  ]       │
│                              │
└──────────────────────────────┘

Dashboard（极简）

┌──────────────────────────────┐
│  🦉 BotDrop                  │
├──────────────────────────────┤
│                              │
│     ● Running                │
│     Uptime: 2h 15m           │
│                              │
│  ─────────────────────────   │
│                              │
│  📱 Telegram  ● Connected    │
│  💬 Discord   ○ —            │
│                              │
│  ─────────────────────────   │
│                              │
│  [🔄 Restart] [⏹ Stop]      │
│                              │
│  ─────────────────────────   │
│                              │
│  💡 Chat with BotDrop on     │
│  Telegram to configure       │
│  more settings               │
│                              │
│  ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈   │
│  [🖥 Open Terminal]           │
│                              │
└──────────────────────────────┘

极简：状态 + 频道 + 重启/停止
核心引导文案："Chat with BotDrop on Telegram to configure more"
"Open Terminal" 放底部，高级用户才需要
不做 Settings 页面 — 所有配置变更通过跟 bot 聊天完成
- 用户："帮我加个 Discord"
- BotDrop："好的，把 bot token 给我"
- → BotDrop 修改 openclaw.json → 重启 gateway

技术实现

1. BotDropService（后台命令执行 + Gateway 生命周期）

public class BotDropService extends Service {
    
    // 后台执行 shell 命令
    private CommandResult exec(String cmd) {
        ProcessBuilder pb = new ProcessBuilder("sh", "-c", cmd);
        pb.environment().put("PREFIX", TERMUX_PREFIX_DIR_PATH);
        pb.environment().put("HOME", TERMUX_HOME_DIR_PATH);
        pb.environment().put("PATH", TERMUX_PREFIX_DIR_PATH + "/bin");
        pb.environment().put("TMPDIR", TERMUX_PREFIX_DIR_PATH + "/tmp");
        pb.redirectErrorStream(true);
        Process p = pb.start();
        // ... read output, wait for exit
    }
    
    // Step 1: 安装
    public void install(ProgressCallback cb) {
        cb.onStep(0, "Fixing permissions...");
        exec("chmod +x $PREFIX/bin/* && chmod +x $PREFIX/lib/node_modules/.bin/* 2>/dev/null");
        
        cb.onStep(1, "Verifying Node.js...");
        CommandResult r = exec("node --version && npm --version");
        if (!r.ok()) { cb.onError("Node.js not found"); return; }
        
        cb.onStep(2, "Installing OpenClaw...");
        r = exec("npm install -g openclaw@latest --ignore-scripts");
        if (!r.ok()) { cb.onError(r.stderr); return; }
        
        cb.onDone();
    }
    
    // Step 2: 验证 API Key
    public void verifyKey(String provider, String key, Callback cb) {
        // 用 curl 做轻量验证
        String cmd = buildVerifyCommand(provider, key);
        CommandResult r = exec(cmd);
        cb.onResult(r.ok(), parseModel(r.stdout));
    }
    
    // Step 3: 写配置 + 启动
    public void configureAndStart(Config config, Callback cb) {
        writeOpenclawJson(config);   // 直接写 JSON
        writeAuthCredentials(config); // openclaw auth set ...
        exec("termux-chroot openclaw gateway start --daemon");
        cb.onStarted();
    }
    
    // Gateway 控制
    public void restart() { exec("termux-chroot openclaw gateway restart"); }
    public void stop() { exec("termux-chroot openclaw gateway stop"); }
    public GatewayStatus status() { 
        return parseStatus(exec("termux-chroot openclaw gateway status --json")); 
    }
}

2. Auth 处理策略

不在 Java 侧重新实现 auth 逻辑。OpenClaw CLI 已经处理了所有 provider 的 auth 流程（API key、setup token、OAuth、device flow）。App 的 auth 步骤有两种实现方式：

方式 A：简单情况（API Key / Setup Token）— App 直接处理

// API Key 类型：直接写文件
void setApiKeyAuth(String provider, String key) {
    // 调用 openclaw auth set
    exec("termux-chroot openclaw auth set " + provider + " " + shellEscape(key));
}

方式 B：复杂情况（OAuth / Device Flow）— 委托给 openclaw CLI

// OAuth 类型：在后台启动 openclaw 的 auth 流程
// openclaw 内部会调用 termux-open-url 打开浏览器
// 用户在浏览器完成登录后，openclaw 自动拿到 token
void startOAuthFlow(String provider) {
    exec("termux-chroot openclaw auth set " + provider + " --interactive");
    // 监听 auth 完成事件
}

这样 App 侧的代码量最小，auth 逻辑的维护跟着 openclaw 走。

配置写入：

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5",
      "workspace": "~/botdrop"
    }
  },
  "channels": {
    "telegram": {
      "accounts": {
        "default": { "token": "<bot_token>" }
      },
      "bindings": [{ "account": "default", "agent": "main" }],
      "pairing": {
        "mode": "allowlist",
        "allowlist": ["<user_id>"]
      }
    }
  }
}

3. @BotDropSetupBot 架构

┌──────────────────────────┐     ┌──────────────────────────┐
│  @BotDropSetupBot (TG)     │     │  @BotDropSetupBot (DC)     │
│  (轻量 Node.js bot)       │     │  (轻量 Node.js bot)       │
│                          │     │                          │
│  功能：                    │     │  功能：                    │
│  - 引导创建 bot            │     │  - 引导创建 bot            │
│  - 验证 bot token         │     │  - 验证 bot token         │
│  - 自动检测 user ID       │     │  - 自动检测 user ID       │
│  - 生成 setup code        │     │  - 生成 setup code        │
└──────────────────────────┘     └──────────────────────────┘
              │                               │
              └───────────┬───────────────────┘
                          │
                   Setup Code 格式
                   BOTDROP-{platform}-{base64_payload}
                          │
              ┌───────────┴───────────────────┐
              │  BotDrop App (Android)         │
              │  解码 → 写 openclaw.json       │
              │       → 启动 gateway           │
              └───────────────────────────────┘

Setup Code：自包含，不需要服务端存储

BOTDROP-tg-eyJ2IjoxLCJ0IjoiNzEyMzQ1Njc4OTpBQUY4eC4uLiIsInUiOiI5ODc2NTQzMjEifQ==
       │    └─ base64({ "v":1, "t":"<bot_token>", "u":"<user_id>" })
       └─ platform: tg / dc

App 侧解码：

void applySetupCode(String code) {
    // BOTDROP-tg-xxxxx → 解析 platform + decode base64
    String[] parts = code.split("-", 3);
    String platform = parts[1]; // "tg" or "dc"
    String payload = new String(Base64.decode(parts[2]));
    JSONObject data = new JSONObject(payload);
    
    String botToken = data.getString("t");
    String ownerId = data.getString("u");
    
    writeChannelConfig(platform, botToken, ownerId);
}

Helper Bot 部署：

独立的轻量 Node.js 项目（不是 OpenClaw 实例）
部署在我们的服务器上
开源（可以 self-host）
代码量很小：就是收集 token + 返回 setup code

4. 前台通知保活

Gateway 运行时通过 Android Foreground Service + 通知保活：

🦉 BotDrop is running
   Connected to Telegram • Tap to manage

5. 状态检测 (BotDropLauncherActivity)

// 快速文件检测，不需要启动任何进程
boolean hasBootstrap = new File(PREFIX + "/bin/node").exists();
boolean hasOpenclaw = new File(PREFIX + "/lib/node_modules/openclaw").exists();
boolean hasConfig = new File(HOME + "/.config/openclaw/openclaw.json").exists();

if (!hasBootstrap) → 等待 TermuxInstaller
if (!hasOpenclaw)  → SetupActivity step 1
if (!hasConfig)    → SetupActivity step 2
else               → DashboardActivity (auto-start gateway if needed)

Bot 辅助配置（后续功能）

用户跟 BotDrop 聊天时可以做：

用户说	BotDrop 做
"帮我加一个 Discord bot"	要 token → 修改 openclaw.json → restart
"换成 GPT-4.5"	修改 model → restart
"更新 OpenClaw"	`npm update -g openclaw` → restart
"看看日志"	读取 gateway logs → 发送
"重启一下"	`openclaw gateway restart`

这些操作 BotDrop 通过 gateway tool 和 exec tool 就能完成。需要在 AGENTS.md / SOUL.md 里加入对应的指引。

文件结构

botdrop-android/app/src/main/java/com/termux/app/botdrop/
├── BotDropLauncherActivity.java     # 启动路由
├── SetupActivity.java             # 3 步向导
├── steps/
│   ├── InstallFragment.java       # Step 1: Welcome + 自动安装
│   ├── ApiKeyFragment.java        # Step 2: Provider + API Key
│   └── ChannelFragment.java       # Step 3: Connect TG/DC
├── DashboardActivity.java         # 极简状态面板
├── BotDropService.java              # 后台服务 (命令执行 + gateway)
└── BotDropConfig.java               # 配置读写工具类

Layouts:

res/layout/
├── activity_launcher.xml          # 启动页 (splash)
├── activity_setup.xml             # ViewPager2 容器
├── activity_dashboard.xml         # 状态面板
├── fragment_install.xml           # 安装进度
├── fragment_apikey.xml            # API key 输入
└── fragment_channel.xml           # 频道连接

里程碑

GUI-M0: 自动安装（不出现终端）

BotDropLauncherActivity + 状态检测
BotDropService 后台命令执行
SetupActivity + ViewPager2
InstallFragment（自动安装 + 进度）
修改 AndroidManifest.xml（launcher 改为 BotDropLauncherActivity）
测试：首次启动 → 自动安装 OpenClaw → 无终端

GUI-M1: Auth（多 provider 多方式）

AuthFragment（provider 列表 + auth 方式选择）
API Key / Setup Token 输入 + 验证
OAuth flow（委托 openclaw CLI + termux-open-url）
配置写入（openclaw.json + auth credentials）
测试：各 provider 的 auth 方式都能跑通

GUI-M2: @BotDropSetupBot + 频道连接

TG Helper Bot（Node.js，引导式对话 + 生成 setup code）
DC Helper Bot（同上）
ChannelFragment（输入 setup code 或手动填 token）
Setup Code 解码 + 配置写入
写完配置后自动启动 gateway
测试：通过 helper bot 拿到 code → 粘贴 → bot 上线

GUI-M3: Dashboard + 保活

DashboardActivity（状态 + 频道 + 重启/停止）
Foreground Service 通知保活
App 杀掉后 gateway 继续运行
"Open Terminal" 入口

GUI-M4: 打磨

BotDrop 品牌 theme（颜色、icon）
错误处理细化 + 重试
深色模式
引导文案优化

设计原则

最少步骤：3 步搞定，不多问
AI 做配置：App 只点火，后续配置用户跟 bot 聊天完成
不重复造轮子：不做 Settings UI，不做 Web UI，配置变更全走 bot
终端是后备：高级用户从 Dashboard 底部进入
后台常驻：Gateway 以 daemon + Foreground Service 运行

Development Notes

Implementation Strategy

Break work into small, testable milestones
Follow the component architecture defined above
Leverage existing Termux infrastructure where possible
Test thoroughly at each stage
Document any technical decisions or challenges encountered

Created: 2026-02-05 Updated: 2026-02-07 (Cleaned for open-source release) Status: Design complete, ready for implementation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

BotDrop Android GUI 设计文档

核心理念

当前流程（需要终端）

目标流程（纯 GUI）

架构

组件清单

向导页面 (SetupActivity) — 只有 3 步

Step 1: Welcome + 自动安装

Step 2: AI Provider + Auth

Step 3: Connect a Channel — @BotDropSetupBot 辅助

Dashboard（极简）

技术实现

1. BotDropService（后台命令执行 + Gateway 生命周期）

2. Auth 处理策略

3. @BotDropSetupBot 架构

4. 前台通知保活

5. 状态检测 (BotDropLauncherActivity)

Bot 辅助配置（后续功能）

文件结构

里程碑

GUI-M0: 自动安装（不出现终端）

GUI-M1: Auth（多 provider 多方式）

GUI-M2: @BotDropSetupBot + 频道连接

GUI-M3: Dashboard + 保活

GUI-M4: 打磨

设计原则

Development Notes

Implementation Strategy

FilesExpand file tree

design.md

Latest commit

History

design.md

File metadata and controls

BotDrop Android GUI 设计文档

核心理念

当前流程（需要终端）

目标流程（纯 GUI）

架构

组件清单

向导页面 (SetupActivity) — 只有 3 步

Step 1: Welcome + 自动安装

Step 2: AI Provider + Auth

Step 3: Connect a Channel — @BotDropSetupBot 辅助

Dashboard（极简）

技术实现

1. BotDropService（后台命令执行 + Gateway 生命周期）

2. Auth 处理策略

3. @BotDropSetupBot 架构

4. 前台通知保活

5. 状态检测 (BotDropLauncherActivity)

Bot 辅助配置（后续功能）

文件结构

里程碑

GUI-M0: 自动安装（不出现终端）

GUI-M1: Auth（多 provider 多方式）

GUI-M2: @BotDropSetupBot + 频道连接

GUI-M3: Dashboard + 保活

GUI-M4: 打磨

设计原则

Development Notes

Implementation Strategy