一个可被云端 AI Agent 调度的 Android 原生应用，基于 Kotlin + Material Design 3 构建。
支持双通道调度：WorkBuddy Sandbox (ACP) 和 OpenClaw Gateway (Protocol v3)。
完全使用 CodeBuddy / VSCode + 命令行 进行开发、构建和调试，无需 Android Studio。

---

功能	说明
🐾 OpenClaw Gateway 集成	基于官方 Companion Node App 标准协议（Protocol v3），WebSocket 连接、Ed25519 签名、四步握手、设备配对
💬 双频道聊天	WorkBuddy Sandbox 频道 + OpenClaw 频道，独立消息列表，底部 Tab 切换
📅 日历事件展示	读取安卓系统自带日历，展示未来 30 天内的事件
⚙️ Gateway 设置	可配置 Gateway 地址、Token/Password 认证、设备显示名
🔧 Node 命令执行	接收 Gateway 下发的 invoke 命令，执行 Android API，回传结果
🔐 Ed25519 设备身份	自动生成/持久化密钥对，v3 签名载荷，设备配对
📡 前台服务保活	Foreground Service 维持 WebSocket 长连接

---

默认 Gateway 地址为 ws://9.135.96.56:18789，可通过以下方式修改：

1. App 内设置：点击主页右上角 ⚙ 图标 → Gateway 设置 → 修改地址
2. 代码配置：修改 GatewayConfig.kt 中的 DEFAULT_GATEWAY_URL

// app/src/main/java/com/buclaw/app/gateway/GatewayConfig.kt
const val DEFAULT_GATEWAY_URL = "ws://9.135.96.56:18789"

Buclaw 支持 OpenClaw 官方的多种认证方式（优先级从高到低）：

认证方式	说明	配置位置
Device Token	首次配对后 Gateway 自动颁发，App 自动保存和使用	自动管理
Shared Token	用户显式设置的共享令牌	Gateway 设置 → Token
Password	密码认证	Gateway 设置 → Password
无认证	Token 和 Password 均为空时	留空即可

1. 在 App 的 Gateway 设置页面填写 Gateway 地址
2. 如果 Gateway 配置了认证，填写 Token 或 Password
3. 点击"保存并连接"
4. App 会通过 WebSocket 连接并完成四步握手：
   • ① WebSocket 连接建立
   • ② 收到 connect.challenge 事件（含 nonce）
   • ③ 用 Ed25519 签名 nonce，发送 connect 请求（含 caps/commands/permissions）
   • ④ 收到 hello-ok 响应（含 deviceToken）
5. 首次连接需在 Gateway 服务端审批设备配对：

# 在 Gateway 服务器上执行
openclaw devices list          # 查看待审批的设备
openclaw devices approve <id>  # 审批设备

App 首次运行时自动生成 Ed25519 密钥对并持久化。签名载荷格式（v3）：

v3|{deviceId}|{clientId}|{clientMode}|{role}|{scopes}|{signedAt}|{authToken}|{nonce}|{platform}|{deviceFamily}

• deviceId = SHA-256(公钥原始 32 字节) 的十六进制
• 公钥传输使用 Base64URL 无填充编码
• 密钥存储位置：app/files/openclaw/identity/device.json

连接时 App 声明以下能力（三级结构）：

Caps（能力类别）：device, calendar, contacts, notifications, system

Commands（具体指令）：

命名空间	命令	说明
device	device.info	获取设备基本信息（型号、系统版本）
device	device.status	获取设备状态（电量、网络）
device	device.health	获取设备健康（内存、存储）
device	device.permissions	获取权限状态
calendar	calendar.events	获取日历事件
calendar	calendar.add	添加日历事件
contacts	contacts.search	搜索联系人
contacts	contacts.add	添加联系人
notifications	notifications.list	获取通知列表
system	system.notify	发送系统通知

---

Buclaw/
├── app/
│   ├── build.gradle.kts          # App 模块构建配置
│   └── src/main/
│       ├── AndroidManifest.xml    # 权限声明 + Activity + Service 注册
│       ├── java/com/buclaw/app/
│       │   ├── MainActivity.kt           # 主页面（双频道聊天 + Gateway 集成）
│       │   ├── GatewaySettingsActivity.kt # Gateway 设置页面
│       │   ├── CalendarActivity.kt        # 日历事件页面
│       │   ├── ChatMessage.kt            # 消息数据类 + 频道枚举
│       │   ├── ChatAdapter.kt            # 聊天 RecyclerView 适配器
│       │   ├── CalendarHelper.kt          # 系统日历读取工具
│       │   ├── CalendarEvent.kt           # 日历事件数据模型
│       │   ├── CalendarEventAdapter.kt    # RecyclerView 适配器
│       │   ├── HelloDialogActivity.kt     # Hello World 对话框页面
│       │   └── gateway/                   # ← OpenClaw Gateway 集成模块
│       │       ├── GatewayConfig.kt       #   可配置的连接参数（地址、认证）
│       │       ├── GatewaySession.kt      #   WebSocket 会话（四步握手、RPC）
│       │       ├── GatewayManager.kt      #   高层管理器（单例门面）
│       │       ├── OpenClawProtocol.kt    #   Protocol v3 帧构建/解析
│       │       ├── DeviceIdentity.kt      #   Ed25519 密钥 + 签名
│       │       ├── NodeCapabilities.kt    #   能力声明（caps/commands）
│       │       ├── InvokeDispatcher.kt    #   命令调度器（执行 Android API）
│       │       └── NodeForegroundService.kt # 前台服务保活
│       └── res/                   # 布局、颜色、字符串、主题
├── build.gradle.kts               # 根构建配置（AGP 8.9 + Kotlin 2.0）
├── settings.gradle.kts            # 项目设置
├── gradle/wrapper/                # Gradle Wrapper（已包含 JAR）
├── gradlew                        # 构建入口脚本（macOS/Linux）
└── local.properties               # 本地 SDK 路径

项	值
语言	Kotlin 2.0.21
构建	Gradle 8.11.1 + AGP 8.9.0
UI	Material Design 3 + ViewBinding
网络	OkHttp 4.12 (WebSocket + HTTP)
协程	kotlinx.coroutines 1.8.1
序列化	kotlinx-serialization-json 1.7.3
加密	BouncyCastle 1.78.1 (Ed25519)
安全存储	AndroidX Security Crypto
Min SDK	26 (Android 8.0)
Target SDK	35 (Android 15)

---

工具	最低版本	检查命令
JDK	17	java -version
Android SDK	platforms/android-35	ls ~/Library/Android/sdk/platforms
ADB	任意	~/Library/Android/sdk/platform-tools/adb version

Gradle 无需单独安装，项目已包含 Gradle Wrapper（gradlew），会自动下载正确版本。

在 ~/.zshrc 中添加以下内容（一次性配置）：

# Android SDK
export ANDROID_HOME=~/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/emulator

使其生效：

source ~/.zshrc

在 CodeBuddy / VSCode 扩展市场安装：

扩展	作用
Kotlin Language	Kotlin 语法高亮 + 基础补全
Gradle for Java	Gradle 任务面板
XML (Red Hat)	XML/布局文件智能提示
Material Icon Theme	更好的文件图标

# 在 CodeBuddy / VSCode 中打开项目根目录
code /Users/yupengfei/Documents/040_软件工程/Bclaw-sandbox/Buclaw

直接在编辑器中修改 .kt、.xml 文件即可。核心文件：

app/src/main/java/com/buclaw/app/   ← Kotlin 源码
app/src/main/res/layout/             ← 界面布局 XML
app/src/main/res/values/             ← 字符串/颜色/主题
app/src/main/AndroidManifest.xml     ← 应用清单

所有构建操作都通过 终端 完成。在 CodeBuddy / VSCode 中按 Ctrl+` 打开终端：

cd /Users/yupengfei/Documents/040_软件工程/Bclaw-sandbox/Buclaw

./gradlew assembleDebug

成功后 APK 位于：

app/build/outputs/apk/debug/app-debug.apk   (约 5.6 MB)

./gradlew clean assembleDebug

./gradlew tasks

./gradlew compileDebugKotlin

---

品牌	开启方法
小米/Redmi	设置 → 我的设备 → 全部参数 → 连击 MIUI 版本 7 次
华为/荣耀	设置 → 关于手机 → 连击 版本号 7 次
OPPO/一加	设置 → 关于手机 → 连击 版本号 7 次
vivo	设置 → 更多设置 → 关于手机 → 连击 软件版本号 7 次
三星	设置 → 关于手机 → 软件信息 → 连击 编译编号 7 次
Pixel	设置 → 关于手机 → 连击 Build number 7 次

然后进入 开发者选项，开启 USB 调试。

# 用数据线连接手机，手机弹窗选择"允许 USB 调试"
adb devices
# 应显示:
# List of devices attached
# XXXXXXXX    device

# 构建并安装到设备
./gradlew installDebug

# 启动应用
adb shell am start -n com.buclaw.app/.MainActivity

或者分步操作：

# 仅安装已构建的 APK
adb install app/build/outputs/apk/debug/app-debug.apk

# 启动应用
adb shell am start -n com.buclaw.app/.MainActivity

# 手机和 Mac 连同一个 WiFi
# 手机：开发者选项 → 无线调试 → 使用配对码配对设备
# 记下 IP:端口 和 配对码

adb pair 192.168.x.x:xxxxx
# 输入配对码

adb connect 192.168.x.x:xxxxx

# 验证
adb devices

# 查看 Buclaw 应用的日志（按包名过滤）
adb logcat --pid=$(adb shell pidof com.buclaw.app) 2>/dev/null || adb logcat | grep -i buclaw

# 只看错误
adb logcat *:E | grep buclaw

# 清空日志后重新开始
adb logcat -c && adb logcat --pid=$(adb shell pidof com.buclaw.app)

# 一条命令完成：构建 → 安装 → 启动
./gradlew installDebug && adb shell am start -n com.buclaw.app/.MainActivity

💡 提示：可以在 CodeBuddy / VSCode 中配置 Task 来快速触发，见下文。

---

如果没有安卓真机，可以使用 Android 模拟器：

# 列出可用的系统镜像
~/Library/Android/sdk/emulator/emulator -list-avds

# 如果没有 AVD，使用 avdmanager 创建
~/Library/Android/sdk/cmdline-tools/latest/bin/avdmanager create avd \
  -n Buclaw_Test \
  -k "system-images;android-35;google_apis_playstore;arm64-v8a" \
  -d pixel_6

如果没有 cmdline-tools，需要先安装：

~/Library/Android/sdk/bin/sdkmanager "cmdline-tools;latest"

~/Library/Android/sdk/emulator/emulator -avd Buclaw_Test &

# 等模拟器完全启动后
./gradlew installDebug
adb shell am start -n com.buclaw.app/.MainActivity

---

在 .vscode/tasks.json 中配置快捷构建任务：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "🔨 Build Debug APK",
      "type": "shell",
      "command": "./gradlew assembleDebug",
      "group": { "kind": "build", "isDefault": true },
      "problemMatcher": []
    },
    {
      "label": "🚀 Install & Run on Device",
      "type": "shell",
      "command": "./gradlew installDebug && adb shell am start -n com.buclaw.app/.MainActivity",
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "🧹 Clean Build",
      "type": "shell",
      "command": "./gradlew clean assembleDebug",
      "group": "build",
      "problemMatcher": []
    },
    {
      "label": "📋 View Logs",
      "type": "shell",
      "command": "adb logcat --pid=$(adb shell pidof com.buclaw.app)",
      "group": "test",
      "isBackground": true,
      "problemMatcher": []
    }
  ]
}

使用方式：Cmd+Shift+P → Tasks: Run Task → 选择任务。

---

日历功能首次打开时会弹出系统权限对话框：

Buclaw 请求访问您的日历
[拒绝]  [允许]

如果误拒，可在手机 设置 → 应用管理 → Buclaw → 权限 中手动开启。

---

问题	解决方案
./gradlew: Permission denied	执行 chmod +x gradlew
SDK location not found	检查 local.properties 中 sdk.dir 路径
adb: command not found	执行 export PATH=$PATH:~/Library/Android/sdk/platform-tools
adb devices 显示空列表	1. 换 USB 线/接口 2. 手机重新授权 3. adb kill-server && adb start-server
日历页面无数据	确保手机上有日历账户且有事件，检查权限已授予
构建失败 JAVA_HOME	确认 JDK 17 已安装：java -version
构建慢	首次构建需下载依赖（约 2 分钟），后续增量构建约 10-20 秒
安装失败	手机设置中允许"安装未知应用"

---

# 1. 生成签名密钥（首次）
keytool -genkey -v -keystore buclaw-release-key.jks \
  -keyalg RSA -keysize 2048 -validity 10000 -alias buclaw

# 2. 在 app/build.gradle.kts 中配置 signingConfigs
# 3. 构建 Release 版本
./gradlew assembleRelease

---

• 主页面：两张功能卡片（日历 📅 / 对话框 💬），Material 3 风格
• 日历页面：卡片列表展示事件（标题、时间、地点、所属日历）
• 对话框页面：Hello World 大标题 + 三个按钮触发不同类型对话框