Holon

在自己的电脑或服务器上创建和运行开源 AI 助手。分配任务、查看进展、持续跟进工作。面向个人和团队。
跳到正文
浏览文档
本页提纲

使用 Android 客户端连接

将 Android 设备连接到 Holon 运行时，向 Agent 发送请求并阅读产出结果。客户端在本地维护历史记录缓存，但在确认运行时的最新状态时，依然需要处于在线连接状态。

前置条件

  • 已启动并启用 HTTP 的 Holon 守护进程（默认端口 7878）。
  • 运行 Android 8.0（API 级别 26）或更高版本的实体设备或模拟器。
  • 到该守护进程的网络通路，并持有配对邀请、控制 Token 或组织单点登录入口。
  • 如需通过 USB 安装或端口转发：电脑上需安装好 adb。

安装客户端

下载官方发布包

在 Holon GitHub Releases 页面查找对应版本的 Android APK。.apk 可直接安装；.aab 是分发打包格式，并非直接可安装文件。

用手机下载 .apk 文件，打开后按系统提示安装。如 Android 要求授权，请允许本次使用的浏览器或文件管理器安装应用，安装后可关闭该权限。无需加入内测群组。

如果从电脑通过 adb 安装：

adb install /path/to/downloaded-holon.apk

从源码构建

本地源码构建与安装步骤已整理至构建移动端客户端。

连接方案

目标网络环境默认 API 基准 URL主机端设置
Tailscale / 局域网https://<tailnet-host>/api 或 http://<lan-ip>:7878/api启用 Tailscale Serve 或绑定局域网 IP
Android 模拟器http://10.0.2.2:7878/api默认配置直接可用
实体设备（USB）http://127.0.0.1:7878/api执行 adb reverse tcp:7878 tcp:7878

安全提示： 生产环境建议使用 HTTPS。Tailscale Serve 可以为你的 tailnet 自动配置有效证书。跨网络使用未加密的 HTTP 连接会弹出显式确认提示。

连接到守护进程

方案 A：二维码扫码配对（推荐）

  1. 在电脑浏览器中打开 Holon Web GUI，进入 Settings -> Device Pairing（或在 macOS 菜单栏中点击 Pair Device）。
  2. 打开 Android 上的 Holon 应用，点击 Scan QR Code。
  3. 对准扫描屏幕上展示的一次性配对二维码。

应用会向 /api/auth/pairing/redeem/native 兑换该凭据，换取会话密钥安全存储在 Android Keystore 中，并立即建立连接。

方案 B：手动配置连接

  1. 打开 Holon 应用。服务器地址默认留空，系统未内置默认云端服务器。
  2. 输入你的 Holon 地址（例如 http://10.0.2.2:7878 或 https://<your-host>），如果使用 HTTP 请确认信任网络风险。
  3. 点击 Next。应用会自动检测服务器支持的认证方式。
  4. 若服务器采用本地 Token 认证，输入 Bearer Token 或 Bootstrap Secret 并点击 Sign in。

应用会调用 /api/auth/session/exchange/native，将换取的会话凭据加密存入 Android Keystore，同时从内存中彻底清除明文 Token。

方案 C：使用 OIDC 组织单点登录

若守护进程启用了 OIDC 认证：

  1. 打开 Holon 应用并输入 Holon 地址。
  2. 点击 Next。应用会检测到该服务器启用了 OIDC。
  3. 应用会自动调起系统浏览器完成身份提供商（IdP）的登录。如果在未完成前返回，可点击 Use organization browser sign-in 重新发起。
  4. 认证成功后，浏览器会通过 run.holon.android://oidc/callback 深度链接重定向回 Holon。

应用将一次性 Bootstrap 票据换取为可吊销的会话凭据，在 Android Keystore 中完成加密存储并建立连接。

管理网络配置文件（Profile）

应用支持在 Settings 中保存多个网络配置文件（例如“家庭 Tailscale”、“办公室局域网”或“USB 调试”）。保存后只需单击即可无缝切换不同环境，无需反复输入凭据。你也可以随时在列表中滑动删除无用的配置文件；删除时会立即清理配置项及 Keystore 中的凭据信息。

删除配置文件同时会清空该环境下的本地缓存、草稿、未发送的待发箱条目、附件以及诊断日志。删除前请确认待发队列；已成功提交给运行时的主线记录不受影响。

验证连接与执行结果

  1. 确认已选中正确的网络配置文件与服务器地址，进入该运行时中已有的某个 Agent。
  2. 发送一条安全的测试消息，例如：请回复“Android connection verified”，不要修改任何文件。
  3. 确认消息从发件箱离开并收到最新的回复。仅浏览历史缓存内容并不代表网络已连通。
  4. 对于跟踪的任务，进入该 Agent 的工作视图（Work view），区分工作项进度（WorkItem）与具体任务执行状态（Task）。在确认工作完成前，先阅读完整的完成摘要（Brief）。
  5. 退出并重新打开应用，刷新对话列表，验证已保存的配置文件能否自动恢复重连。

移动端特色功能

  • 对话优先与本地缓存： Agent 对话列表秒开。历史记录缓存在设备本地，在弱网或离线环境下也能查阅历史轮次与关键产物。
  • 按日导航与任务状态卡片： 快速在每日活动流之间跳转，直观查看后台运行任务卡片，并在时间线中直接预览子 Agent 状态。
  • 以简报（Brief）为核心： 重点展示完成简报、活动工作项与清单进度，无需在冗长的执行日志中反复滑动翻找结论。
  • 折叠后台操作： 运行中与排队中的后台消息自动折叠收起，保证主线对话清爽。
  • 模型切换： 在移动界面中直接查看或覆盖任意 Agent 的当前模型，自动过滤不可用或未配置的模型选项，选择器中仅展示当前可调用的有效候选。
  • 系统分享面板打通： 从其他 Android 应用（如浏览器、文件管理器）中直接通过系统分享功能将文字、链接或文档投递给 Agent。
  • 离线待发箱： 离线时编辑的提示词会先排队，连接恢复后自动发送，不会重复提交。
  • 内置浏览器： Local App 路由与文档链接在应用内打开，并保持已认证会话。
  • 单文件诊断日志导出： 诊断信息可一键导出为单一整合文件，按网络环境归类，便于排查与日志分享。
  • 举报 AI 内容： 长按助手回复可举报不准确、有害或不恰当的内容。运行时会保存所选回复的有界快照。提交前请确认内容；回复本身可能包含敏感信息。

语言设置

应用界面完整支持英文与简体中文。默认跟随系统语言，但你也可以在登录界面或 Settings 中手动指定显示语言。

故障排查

  • 无法连接运行时： 确认手机网络能否解析并访问该地址。在实体手机上，localhost 指向手机自身；请使用主机的局域网 IP、tailnet 域名，或配置 USB 端口映射。
  • 配对失败： 重新生成一张有效的一次性邀请二维码，并核对其访问主机。tailnet 邀请要求手机本身也加入同一 tailnet 并具备访问权限。
  • 登录过期或拒绝访问： 重新登录目标环境。对于启用了 OIDC 的服务器，请使用组织登录而非输入本地 Token。
  • 能看到旧消息但收不到新回复： 检查网络连接状态和本地待发箱。本地展示的历史记录不代表请求已成功抵达守护进程。
  • 反复连接失败： 在“设置”中导出诊断日志。分享前先检查有无隐私数据；提供客户端与运行时版本号及出错步骤即可，切勿泄露 Token 或配对票据。

后续阅读