TopoClaw

项目定位

TopoClaw 是你的 AI 数字助手。它不只是一个聊天助手——而是一个能替你操作电脑和手机、代你与他人沟通协作、在你不在时主动盯着事情推进的助手，并在每次交互中持续学习你的偏好，越来越像你。

本仓库将手机端 TopoMobile 与电脑端 TopoDesktop 等产品组合在一起，你可以直接使用默认助手，也可以创建自己的助手与技能，在多端、多人场景里完成复杂任务。

TopoClaw具备以下核心能力：

🖥️📱 跨设备执行：手机与电脑组成统一执行面，任务可拆解、并行、链式跨端执行，上一步输出自动流入下一步

👥 社交协作：TopoClaw 拥有可分享的社交身份，可被邀请进群参与协商办事，亦能自动组建多用户多助手群组协作解决问题；可帮你自动过滤并回复群组与好友消息，关键决策仍由你掌控

⚡ 主动感知推进：能感知手机通知、检测日程冲突、主动汇报关键结论，不用你反复追问

🔒 安全兜底：三级文件权限 + 操作空间隔离 + 命令审计，能力强但不失控

🧩 开放可扩展：技能社区 + 助手广场 + 多渠道接入，能力可复用、可分享、可定制

Demo 演示

Demo 视频的加速、裁剪和配音均由 TopoClaw 自身完成。

能力对比

核心能力

数字助手像用户本人一样办事，需要三项关键能力：跨设备执行、跨用户执行、主动感知推进。

跨设备执行

• 同一账号下手机和电脑组成统一执行面，会话与结果可以跨端延续
• 可按场景调用电脑侧能力（Code、工具调用、GUI 等）与手机侧能力（GUI、DeepLink 等）
• 支持任务编排、并行子任务与链式执行，上一步输出自动流入下一步
• 电脑文件系统可以作为数据中枢，手机侧执行结果能够回传并汇总

跨用户执行

• 数字助手会持续学习用户偏好与习惯，逐步承担建群、协商、办事等日常事务
• 通过分级行为协议划定边界：日常咨询可自动回复，关键决策必须经授权，敏感事项回交用户
• 群组与助手广场场景下，多个用户与多个助手可以通过建群、任务分工、工作流编排来协同完成任务

主动感知推进

• 可过滤重要手机通知，并结合记忆上下文做进一步判断，例如识别日程冲突
• 在关键结论已经形成时主动汇报，而不是等待用户反复追问
• 可以与长期记忆、定时任务、渠道通知配合，降低多轮往返成本

具体能力会随产品版本和配置有所差异。

配套能力

安全机制

TopoClaw 的能力包含电脑代码执行、手机 GUI 操控和代用户沟通，因此 README 中把安全架构单独作为重点模块说明：

快速开始

一键安装

• 来自社区的安装包：https://github.com/huanggangyyd/topoclaw-thirdparty-builds/releases/tag/v2.1.0-thirdparty.1

基础配置

1. 下载并安装
   下载手机端 APK 与电脑端 EXE，分别在 Android 和 Windows 上完成安装。
2. 部署中转服务
   下载并部署原仓库中的 customer_service，用于建立跨设备、跨用户的中转服务。部署完成后，请分别在手机端与电脑端接入该服务：
   • 手机端绑定入口：我 -> 服务 -> 下滑到底部将服务地址填写到“人工客服/跨设备/好友聊天地址”
   • 电脑端绑定入口：在 IMEI 输入框随意输入几位数字 -> 点击绑定 -> 应用打开后点击左下角设置 -> 将服务地址填写到“跨设备/好友聊天服务地址”
3. 绑定设备
   电脑端返回登录页后，点击手机端右上角“扫一扫”，扫描电脑端二维码完成连接。
4. 模型配置
   电脑端进入助手广场，点击编辑 TopoClaw 配置模型。模型分为两类：
   • Chat：面向通用任务
   • GUI：面向电脑端/手机端 GUI 任务（多模态大模型）
     配置完成后，返回与 TopoClaw 的会话，即可在下图所示位置选择模型。

至此，基础配置完成。

手机端额外重要权限

• 无障碍权限、截图权限：用于手机 GUI 模拟点击，仅在执行相关任务时需要，无需提前授权。
• TopoClaw 键盘：手机 GUI 模拟点击专用键盘，在执行 GUI 任务时，请根据提示进行切换。
• 悬浮窗权限：授权后请开启“任务允许悬浮窗”与“开启伴随模式”（默认开启，用于保持助手在前台待命并提供悬浮控件，便于快速接管任务），桌面会出现悬浮球，点击即可发起任务。
• 设备和应用通知权限：用于通知栏监视能力，详见后文“主动能力”部分。

核心能力

• 跨设备执行：绑定手机和电脑后，点击 TopoClaw 聊天输入框下方“状态检测”；检测通过后即可发起跨设备任务。
  注意：涉及 GUI 的任务可能需要在手机端手动授权相关权限。
• 跨用户执行
  • 数字分身：在与电脑端好友的私聊页，点击右上角可开启“数字分身”。开启后，TopoClaw 会自动处理好友消息、进行回复，并在需要你介入时及时求助。
  • 群组：群组由多用户、多助手组成，可由用户或 TopoClaw 发起。支持三种编排方式，可在群组主页配置：
    1. 自由发言模式：所有用户与助手均可基于上下文自由发言。
    2. 群组管理助手模式：取消勾选“工作流编排”“自由发言”“助手禁言”后进入；由群组管理助手统一编排消息流程。群组管理助手可由用户指定，或由 TopoClaw 自动设置。
    3. 工作流编排模式：点击群组会话页右上角进入工作流编排；可由用户手动编排，或由 TopoClaw 代为编排。完成后，群内助手将按工作流协同执行。

主动能力

• 手机通知栏监视：在手机端“服务”页面开启“监视通知栏”，并在“设置通知监视白名单”中选择目标用户后，TopoClaw 可基于通知自动响应。
• 主动结论反馈：TopoClaw 会将其接触到的重要信息（如其他好友、群组、IM 消息）主动同步到你与 TopoClaw 的会话中，帮助你更高效地处理繁杂消息。

页面与其他功能

• 通讯录（显示手机+电脑图标）：展示你的助手、群组、好友列表。
• 技能（显示电脑图标）：
  我的技能：当前 TopoClaw 可使用的技能；
  技能社区：可通过搜索并从开源社区直接获取技能。
  注意：手机端暂不支持技能配置。
• 助手（显示手机+电脑图标）：
  我的助手：编辑已创建助手（含模型配置），也可新建自定义助手；
  助手广场：查看并使用好友分享的助手。
• 定时任务（显示手机+电脑图标）：查看、编辑、新建定时任务。
• 随手记（显示电脑图标）：备忘录功能，可随时记录并总结电脑屏幕的任意区域（快捷键 Ctrl + Alt + Q），以及你与助手的聊天信息。
  注意：随手记当前仅支持电脑端。

自部署与开发者入口

以下命令用于本地开发联调，默认在仓库根目录 TopoClaw/ 下执行。
说明：TopoClaw 与 GroupManager 在编译 TopoDesktop 时会被合入 TopoDesktop，常规桌面端使用无需单独部署这两个服务。

Step 1 — customer_service（通讯后端服务）

会话中转与状态管理服务，负责绑定、消息路由、好友/群组关系、多端同步等，是手机端与电脑端通信的桥梁。

cd customer_service
pip install -r requirements.txt
python app.py
# 或使用 uvicorn
uvicorn app:app --host 0.0.0.0 --port 8001

Step 2 — TopoMobile（Android 客户端）

移动端应用，提供聊天交互、任务执行 GUI、轨迹采集与回放、通知感知等能力，是 AI 助手在手机上的执行入口。

推荐使用 Android Studio 打开 TopoMobile/，连接手机后直接 Run（Shift + F10）。详细步骤见 TopoMobile/README.md。

Step 3 — TopoDesktop（桌面端，Windows CMD）

桌面客户端，与手机端共享聊天记录，支持 IMEI / 扫码绑定。内嵌 TopoClaw 与 GroupManager 后端，开箱即用。

cd TopoDesktop
build-desktop-core-plus-browser.cmd

该命令会一键执行桌面端完整打包流程（安装依赖、同步内置资源、配置内嵌 Python、安装 browser-use、执行 Electron 打包）。 更多安装与打包方式可参考 TopoDesktop/README.md。

参考文档

Roadmap

已发布

• 跨设备执行：统一手机与电脑执行面，支持任务编排、并行子任务和链式跨端执行
• 跨用户执行：数字助手、群组协作与助手广场能力已经形成基础闭环
• 主动感知推进：支持通知监听、智能判断、主动汇报与异常预警
• 技能系统：覆盖技能创建、社区安装与自动调用
• 安全架构：提供三级文件权限、操作空间隔离与命令执行审计

计划中

• 工作流灵活性增强
• 多异构设备管理
• 更多平台支持，包括 macOS、Linux 桌面端与 iOS 移动端
• 团队协作与权限管理增强

FAQ

Q: 必须同时部署所有模块吗？*

A: 不需要。常规使用场景下，TopoDesktop 已内嵌 TopoClaw 与 GroupManager，无需再单独部署 TopoClaw。其余模块按需组合：

1. 只需桌面端体验：仅 TopoDesktop 即可
2. 需要社交协作：TopoDesktop + customer_service
3. 需要跨设备执行：TopoDesktop + TopoMobile + customer_service 如需二次开发或独立调试服务，再手动启动 TopoClaw / GroupManager。

Q: 支持哪些平台？

A: 目前桌面端仅支持 Windows，手机端仅支持 Android。macOS / Linux 桌面端及 iOS 移动端支持已在 Roadmap 中，敬请期待。

Q: 数据存在哪里？安全吗？

A: 使用本地内置环境时，核心数据优先在本地处理；安全架构从数据流转到操作权限逐层保障：

1. 跨设备执行、社交协作等场景的部分数据会通过通讯后端服务（customer_service）中转，该服务可由用户自行部署
2. 其余数据均在本地存储与处理
3. 对于非工作区的文件删除、写入等操作，系统会弹出确认提示，需用户明确许可后才会执行

更多安全机制详见安全板块。

Q: TopoClaw 支持哪些大模型？

A: 支持所有兼容 OpenAI API 协议的模型服务（如 OpenRouter、DashScope、Azure OpenAI 等），也支持 OAuth 登录 OpenAI Codex 和 GitHub Copilot。具体配置见 TopoClaw/README.md。

Q: 为什么跨设备连不通？

A: 请按以下顺序排查：

1. 在 TopoClaw 会话页先点击输入框下方的状态检测按钮。
2. 若检测失败，确认手机端和电脑端都已成功绑定 customer_service，并确认网络满足以下任一条件：
   • customer_service 对手机和电脑均可公网访问（已做 IP 穿透/映射）；或
   • customer_service、手机、电脑在同一局域网（同一 Wi-Fi）下。
3. 检查 customer_service/outputs/custom_assistants/custom_assistants.json：
   • 当前 IMEI 对应的 topoclaw.baseUrl 应为 topoclaw://relay；
   • 对应的 custom_topoclaw.baseUrl 应为当前电脑端应用内置服务的可访问 IP 地址。
4. 重启手机端应用、电脑端应用和 customer_service 服务后再次测试。
5. 如仍失败，请随时联系我们并附上状态检测结果与关键日志，便于快速定位问题。

参与贡献与许可证

• 贡献方式：Fork 仓库、创建特性分支、提交更改、推送分支并发起 Pull Request
• 开源协议：Apache License 2.0，详见 LICENSE