shouqianceshi/buclaw

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

master

docs: 新增审计网关技术方案设计文档

.codebuddy
Buclaw
docs
release
.DS_Store
.gitignore
README.md

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 Manifest	28 个技能包 + 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/`	10	MainActivity、设置页面、聊天适配器、日历页面
Gateway 模块	`com.buclaw.app.gateway/`	10	WebSocket 会话、OpenClaw 协议、Ed25519 身份、命令调度
Sandbox 模块	`com.buclaw.app.gateway.sandbox/`	12	SSE 会话、ACP 协议、Delegate Tool、Prompt 注入
共享层	`gateway/`	2	DeviceCommandExecutor + CommandNameMapper

🔧 技术栈

类别	技术	版本
语言	Kotlin	2.0.21
构建	Android Gradle Plugin	8.9.0
最低版本	Android 8.0 (API 26)	—
目标版本	Android 15 (API 35)	—
JVM	Java 17	—
网络	OkHttp	4.12.0
异步	Kotlin Coroutines	1.8.1
序列化	kotlinx-serialization	1.7.3
加密	BouncyCastle (Ed25519)	1.78.1
安全存储	AndroidX Security Crypto	—
UI	Material Design 3 + ViewBinding	—

🚀 快速开始

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

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

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

⚠️ 首次安装可能需要在系统设置中允许「安装未知来源应用」
安装完成后打开 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

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

第 2 步：在 App 中配置

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

填写以下信息：

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

点击保存按钮

第 3 步：连接沙箱

回到主页面，切换到 Sandbox 通道标签
点击连接按钮
App 会自动：创建远端沙箱 → 建立 SSE 连接 → 注册手机设备工具（Delegate Tool）
看到状态变为 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 中配置

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

填写以下信息：

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

点击保存按钮

第 3 步：连接 Gateway

回到主页面，切换到 Gateway 通道标签
点击连接按钮
App 会自动生成 Ed25519 密钥对（首次连接时），并向 Gateway 发起四步握手认证
此时连接会处于 等待审批 状态——因为 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_STATE`	Gateway WebSocket / Sandbox SSE 连接
`FOREGROUND_SERVICE`	WebSocket 长连接保活
`READ_CALENDAR`	查询系统日历事件
`READ_CONTACTS`	查询通讯录
`POST_NOTIFICATIONS`	系统通知