logo
shouqianceshi/buclaw
Public
0
0
WeChat Login
CodeIssuesPull requestsEventsPackagesInsights
master
buclaw/README.md
余朋飞
feat: 添加预构建 APK 安装包并更新 README 下载引导
f560171b

Buclaw

让云端 AI Agent 远程调度 Android 设备能力的智能手机客户端

Buclaw 是一款 Kotlin 原生 Android 应用，通过 双通道架构 同时接入两个独立的 AI 对话通道，使云端 Agent 能够查询设备信息、读取日历/通讯录、操作剪贴板等，实现 "AI 控制手机" 的完整链路。

✨ 核心特性

特性说明
双 AI 通道同时支持 OpenClaw Gateway（WebSocket）和 WorkBuddy Sandbox（SSE + HTTP）
设备能力开放日历读写、通讯录查询、剪贴板操作、系统通知、设备信息等
Delegate Tool通过 ACP 协议将手机本地工具注册到远端 Agent，Agent 可主动调用
Prompt 注入降级Delegate Tool 不可用时自动降级，预执行设备工具并注入 prompt
Agent Manifest28 个技能包 + MCP 服务器 + Agent 规则的一站式配置
前台服务保活WebSocket 长连接不被系统杀死
Ed25519 签名认证OpenClaw 通道使用硬件级加密身份认证
流式消息渲染支持 SSE 流式消息实时显示

🏗️ 架构概览

┌─────────────────────────────────────────────────────┐
│                   Buclaw (Android)                   │
│                                                     │
│  ┌─────────────┐              ┌──────────────────┐  │
│  │  OpenClaw   │              │    WorkBuddy     │  │
│  │  Gateway    │              │    Sandbox       │  │
│  │  通道       │              │    通道          │  │
│  │             │              │                  │  │
│  │ WebSocket   │              │  SSE + HTTP POST │  │
│  │ Protocol v3 │              │  ACP Protocol    │  │
│  │ Ed25519 认证│              │  API Key 认证    │  │
│  └──────┬──────┘              └────────┬─────────┘  │
│         │                              │            │
│         └──────────┬───────────────────┘            │
│                    │                                │
│         ┌──────────▼──────────┐                     │
│         │ DeviceCommandExecutor│ ← 共享设备命令层   │
│         │ CommandNameMapper    │ ← 命令名归一化     │
│         └─────────────────────┘                     │
└─────────────────────────────────────────────────────┘
          │                              │
          ▼                              ▼
   OpenClaw Gateway               WorkBuddy 云端沙箱
   (局域网/私有部署)               (CodeBuddy Agent)

两个通道完全独立、互不干扰，复用同一套设备命令执行器（DeviceCommandExecutor），通过 CommandNameMapper 进行命令名转换。

📁 项目结构

Bclaw-sandbox/                          # 仓库根目录
├── README.md                           # ← 本文件
├── release/                            # 预构建 APK 安装包
│   └── Buclaw-v1.0-debug.apk          # 可直接安装的 APK
├── Buclaw/                             # Android 主工程
│   ├── app/src/main/
│   │   ├── java/com/buclaw/app/        # Kotlin 源码
│   │   │   ├── *.kt                    # UI 层 (10 个文件)
│   │   │   ├── gateway/                # OpenClaw Gateway 模块 (10 个文件)
│   │   │   └── gateway/sandbox/        # WorkBuddy Sandbox 模块 (12 个文件)
│   │   ├── assets/manifest.json        # Agent Manifest 配置
│   │   ├── res/                        # Android 资源
│   │   └── AndroidManifest.xml
│   ├── docs/                           # 技术设计文档
│   │   ├── Buclaw-OpenClaw-Technical-Design.md
│   │   ├── Buclaw-WorkBuddy-Sandbox-Technical-Design.md
│   │   └── delegate-tool-implementation-plan.md
│   ├── build.gradle.kts
│   └── README.md                       # 开发环境 & 构建指南
│
├── openclaw/                           # OpenClaw 开源参考（只读，不修改）
├── buclaw-rules.md                     # Agent 规则文件
├── sandbox-agent-rules.md              # Sandbox Agent 规则
├── manifest-demo.json                  # Manifest 配置示例
├── manifest-full.json                  # 完整 Manifest 配置
└── *.py                                # 测试/演示脚本

模块说明

模块路径文件数说明
UI 层com.buclaw.app/10MainActivity、设置页面、聊天适配器、日历页面
Gateway 模块com.buclaw.app.gateway/10WebSocket 会话、OpenClaw 协议、Ed25519 身份、命令调度
Sandbox 模块com.buclaw.app.gateway.sandbox/12SSE 会话、ACP 协议、Delegate Tool、Prompt 注入
共享层gateway/2DeviceCommandExecutor + CommandNameMapper

🔧 技术栈

类别技术版本
语言Kotlin2.0.21
构建Android Gradle Plugin8.9.0
最低版本Android 8.0 (API 26)—
目标版本Android 15 (API 35)—
JVMJava 17—
网络OkHttp4.12.0
异步Kotlin Coroutines1.8.1
序列化kotlinx-serialization1.7.3
加密BouncyCastle (Ed25519)1.78.1
安全存储AndroidX Security Crypto—
UIMaterial Design 3 + ViewBinding—

🚀 快速开始

方式一：直接下载安装（推荐）

我们提供了预构建的 APK 安装包，可以直接下载安装到 Android 手机：

  1. 下载 APK：Buclaw-v1.0-debug.apk（约 11 MB）
  2. 将 APK 传输到手机（或直接在手机浏览器中下载）
  3. 在手机上打开 APK 文件进行安装

    ⚠️ 首次安装可能需要在系统设置中允许「安装未知来源应用」

  4. 安装完成后打开 Buclaw 应用

系统要求：Android 8.0（API 26）及以上

方式二：从源码构建

如果你需要自定义开发或修改代码，可以从源码构建安装：

环境要求

  • JDK 17+
  • Android SDK (compileSdk 35)
  • 真机或模拟器 (minSdk 26)
  • 命令行工具: adb, gradle

构建 & 安装

# 克隆仓库
git clone <repo-url> && cd Bclaw-sandbox/Buclaw

# Debug 构建
./gradlew assembleDebug

# 安装到设备
adb install app/build/outputs/apk/debug/app-debug.apk

📲 使用说明

安装 APK 后，需要分别配置两个 AI 通道。进入 App 后，点击顶部导航栏的 设置图标 即可进入对应通道的设置页面。

通道一：WorkBuddy Sandbox（推荐优先配置）

WorkBuddy Sandbox 通过 CodeBuddy 云端沙箱提供 AI 对话能力，使用 SSE + HTTP 通信，配置简单。

第 1 步：获取 API Key

  1. 打开浏览器，访问 CodeBuddy 预发布环境：https://staging.codebuddy.cn
  2. 登录你的账号（如果没有账号需要先注册）
  3. 进入 个人主页 → API 管理（或者直接访问 API Key 管理页面）
  4. 点击 创建 API Key，生成一个新的密钥
  5. 复制并妥善保存 API Key（只会显示一次）

第 2 步：在 App 中配置

  1. 打开 Buclaw App，进入 Sandbox 设置 页面

  2. 填写以下信息：

    字段填写内容说明
    Base URLhttps://staging.codebuddy.cn预发布环境地址（默认已填，一般不需要改）
    API Key粘贴你刚才获取的 API Key必填，用于身份认证
    Template ID留空使用默认值即可沙箱模板 ID，高级用户可自定义

  3. 点击 保存 按钮

第 3 步：连接沙箱

  1. 回到主页面，切换到 Sandbox 通道标签
  2. 点击 连接 按钮
  3. App 会自动：创建远端沙箱 → 建立 SSE 连接 → 注册手机设备工具（Delegate Tool）
  4. 看到状态变为 CONNECTED 后，即可开始对话

注意：首次连接需要等待沙箱创建，可能需要 30~60 秒。连接成功后，Agent 可以直接调用你手机上的日历、通讯录、设备信息等能力。

通道二：OpenClaw Gateway

OpenClaw Gateway 通过 WebSocket 长连接让手机作为 Companion Node 接入私有部署的 Gateway 服务。配置稍微复杂，需要在 Gateway 服务器端完成设备认证。

第 1 步：部署 Gateway 服务

确保你已经在一台机器上部署并运行了 OpenClaw Gateway 服务（参考 OpenClaw 文档）。记下 Gateway 的：

  • 地址：如 ws://192.168.3.238:18789（局域网）或公网地址
  • Token：Gateway 配置中设置的认证 Token（如果有）

第 2 步：在 App 中配置

  1. 打开 Buclaw App，进入 Gateway 设置 页面

  2. 填写以下信息：

    字段填写内容说明
    Gateway URLws://你的Gateway地址:端口WebSocket 地址，支持 ws:// 和 wss://
    TokenGateway 的认证 Token如果 Gateway 设置了 Token 认证则必填
    PasswordGateway 的认证密码如果 Gateway 设置了密码认证则必填
    Display Name自定义设备名称默认为 "Buclaw Android"，可改为你喜欢的名称

  3. 点击 保存 按钮

第 3 步：连接 Gateway

  1. 回到主页面，切换到 Gateway 通道标签
  2. 点击 连接 按钮
  3. App 会自动生成 Ed25519 密钥对（首次连接时），并向 Gateway 发起四步握手认证
  4. 此时连接会处于 等待审批 状态——因为 Gateway 需要人工批准新设备

第 4 步：在 Gateway 端审批设备（关键步骤）

手机连接后，Gateway 端不会自动信任新设备，你需要在 运行 Gateway 的机器上 执行以下命令来审批：

# 1. 查看所有已注册的设备列表
openclaw devices list

输出示例：

ID                                                                Status      Name
─────────────────────────────────────────────────────────────────────────────────────
a1b2c3d4e5f6...                                                   pending     Buclaw Android
f7e8d9c0b1a2...                                                   approved    My Laptop

找到状态为 pending 的那条记录，复制它的完整 ID，然后执行：

# 2. 审批该设备（将 ID 替换为上面查到的实际值）
openclaw devices approve a1b2c3d4e5f6...

审批成功后输出：

Device a1b2c3d4e5f6... approved successfully

第 5 步：确认连接

  • 审批通过后，手机端会自动完成握手流程，状态变为 CONNECTED
  • 如果手机端已断开，重新点击连接即可（密钥已保存，不需要重新审批）
  • 此后 Gateway 上的 AI Agent 就可以向手机下发设备指令了

提示：

  • 设备密钥持久化存储在手机本地，卸载 App 后密钥会丢失，需要重新审批
  • 如果 Gateway 在局域网，确保手机和 Gateway 在同一网络下
  • 可以在 Gateway 设置页面看到截断显示的 设备 ID 和 公钥，方便确认身份

开始对话

两个通道配置完成后，即可在 App 主页面选择通道并开始与 AI 对话。AI Agent 可以：

  • 📱 查询手机设备信息、电量、存储、网络状态
  • 📅 读取和创建日历事件
  • 👥 搜索通讯录联系人
  • 📋 读写系统剪贴板
  • 🔔 发送系统通知
  • ⚙️ 查询已安装应用、系统权限等

详细开发指南见 Buclaw/README.md

📖 技术文档

文档说明
OpenClaw Gateway 技术方案WebSocket 通道完整设计：协议、握手、会话、命令执行
WorkBuddy Sandbox 技术方案SSE 通道完整设计：ACP 协议、Delegate Tool、Prompt 注入
Delegate Tool 实现方案设备工具注册到远端 Agent 的技术细节

🔑 权限说明

权限用途
INTERNET + ACCESS_NETWORK_STATEGateway WebSocket / Sandbox SSE 连接
FOREGROUND_SERVICEWebSocket 长连接保活
READ_CALENDAR查询系统日历事件
READ_CONTACTS查询通讯录
POST_NOTIFICATIONS系统通知

📂 参考代码

openclaw/ 目录包含 OpenClaw 开源 Gateway 标准代码，仅供方案参考，不允许修改。

📊 代码统计

指标数值
Kotlin 源文件32 个
总代码量~5,600+ 行
Android 布局7 个 XML
Agent 技能包28 个
技术文档3 份
© 2026 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号