---
title: 连接 iOS 客户端
summary: 安装并配置原生 iOS 客户端，与运行中的 Holon 守护进程配对，在 iPhone 和 iPad 上浏览成果、阅读文件并举报 AI 内容。
order: 38
---

# 连接 iOS 客户端

Holon 提供面向 iPhone 与 iPad 的原生 SwiftUI 客户端，支持 iOS 18 及更高版本。客户端具备结果优先的会话界面、按身份隔离的离线缓存、快速扫码配对、大文件分页阅读以及系统分享集成。

本指南介绍安装步骤、连接配置、日常导航、文件阅读、系统集成以及 AI 内容举报流程。

## 前置条件

- 已启动并开启 HTTP 访问的 Holon 守护进程（默认端口 `7878`）。
- 运行 iOS 18.0 或更高版本的 iPhone/iPad，或兼容的 Xcode 模拟器。
- 可访问守护进程的网络连接（局域网、反向代理或 Tailscale 虚拟网）。

## 安装

### 安装官方发布版本

通过 Apple TestFlight 或 App Store 安装官方构建版本。收到邀请后，在设备上打开兑换链接即可下载安装。

### 从源码构建

使用 Xcode 本地编译并运行 iOS 客户端：

```bash
open apps/ios/Holon.xcodeproj
```

在 Xcode 顶部选择目标设备或模拟器，按 `Cmd + R` 运行工程。

## 连接守护进程

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

1. 在 Holon Web GUI 中打开 **设置** -> **设备配对**（或在 macOS 菜单栏中选择 **配对设备**）。
2. 打开 iOS 上的 Holon 应用。
3. 在首次引导页点击 **扫描连接二维码**。
4. 使用摄像头对准 Web GUI 或终端中展示的二维码。

应用读取邀请票据（`/login#pair=<ticket>`），调用 `POST /api/auth/pairing/redeem/native` 完成兑换，将会话凭据安全保存在 iOS Keychain 中，并直接打开 Agent 列表。

若摄像头不可用或未授予权限，可点击手动输入选项，将配对链接粘贴到票据输入框中完成兑换。

### 方式 B：手动配置连接

1. 在引导界面点击 **手动连接**。
2. 输入完整的 API 基础地址（例如 `https://holon.example.com/api` 或 `http://192.168.1.50:7878/api`）。
3. 输入 Bearer 令牌或初始化密钥。
4. 确认数据共享说明并点击 **连接**。

应用请求 `POST /api/auth/session/exchange/native`，将取得的会话凭据加密存入 Keychain，并从内存中清除原始令牌。

### 方式 C：组织单点登录（OIDC）

当守护进程已接入 OpenID Connect 身份认证：

1. 输入 API 基础地址。
2. 点击 **通过组织登录**。
3. 在系统弹出的浏览器窗口中完成身份认证。
4. 浏览器通过自定义 URL 回调返回 Holon 应用，应用自动将颁发的会话凭据存入 Keychain。

## 网络与安全注意事项

- **优先使用 HTTPS：** 生产环境应始终使用 HTTPS 连接。如果连接明文 HTTP 地址，应用会在兑换或登录前弹出二次确认，提示明文传输风险。
- **本地网络权限：** 在家庭或办公 Wi-Fi 局域网直连时，需要允许系统弹出的“本地网络（Local Network）”访问权限。
- **回环地址限制：** 在真机上，`127.0.0.1` 和 `localhost` 指向手机本机，无法访问电脑上的服务。请使用电脑的局域网 IP 或 Tailscale 分配的域名。

## 移动端界面与交互体验

- **可搜索的 Agent 列表：** 首页展示当前可访问的 Agent 及其状态摘要。支持按最近活跃度、回复状态或名称快速检索。
- **结果优先的会话时间线：** 对话列表优先呈现最终 Markdown Brief 与交付成果。中间的工具调用和执行活动折叠进轮次中，方便快速审查结果，无需翻阅长日志。
- **后台任务状态卡片：** 正在运行的后台任务或子 Agent 调度以轻量卡片形式展示，实时反馈执行进度。
- **模型切换与随时停止：** 在输入框旁可查看并切换当前 Agent 绑定的模型路由，遇异常长任务可一键中止当前轮次。

## 原生文件与成果查看

在 Agent 会话界面点击动作菜单中的文件或文件夹图标，即可浏览该 Agent 关联的工作区文件与生成物：

- **大文件分页阅读：** 阅读器采用分块磁盘分页加载，即便是体积庞大的 Markdown 报告、代码 Diff 或日志文件，滚动依然流畅。
- **文本搜索与代码高亮：** 支持实时字面匹配高亮，并内置常见编程语言的语法高亮。
- **图片缩放与 PDF 预览：** 生成的图像支持手势双指缩放，PDF 文件提供静态分页预览。
- **精准原文复制：** 长按富文本区域并选择 **选取原文（Select source text）**，即可直接复制未经格式化渲染的原始 Markdown 片段。

## 系统分享与分享收件箱

- **系统分享扩展（Share Extension）：** 在 Safari 或文件等其他 App 中选中文本、网页链接或照片，调出 iOS 系统分享菜单，选择 Holon 并指定目标 Agent，点击 **发送** 即可直接投递。
- **离线暂存（Share Inbox）：** 无网络连接时分享的内容会自动存入 **设置** -> **分享收件箱（Share inbox）**，网络恢复后再确认发送或放弃。

## AI 内容举报（Report AI Content）

若发现模型生成的回复存在事实错误、违法违规或偏离安全规范的内容，可直接在手机端发起举报：

1. 长按问题回复或该轮对话容器。
2. 在弹出菜单中选择 **举报 AI 内容（Report AI content）**。
3. 选择对应的违规类型（如有害信息、严重不实、版权侵权等）。
4. 可在文本框中补充具体描述。
5. 点击 **提交举报**。

客户端会向服务端的 `POST /api/content-reports` 提交认证后的独立回复快照。服务端仅保存该条回复的上下文证据以供管理员审计，不会上传整个会话历史或工作区敏感数据。

## 连接管理与系统诊断

- **管理多套连接：** 在 **设置** -> **连接** 中查看已保存的服务器列表，左滑即可删除失效节点。
- **导出诊断报告：** 在 **设置** -> **诊断** 中可生成脱敏后的诊断日志（包含网络状态、系统版本和统计计数器），用于排查同步与连接问题。

## 下一步

- [连接远程 Holon 运行时](/zh-CN/guides/connect-remote-runtime.md)：了解通过 Tailscale 和反向代理的安全网络配置。
- [配置 OIDC 身份认证](/zh-CN/guides/configure-oidc-authentication.md)：了解企业单点登录与会话令牌管理。
- [连接 Android 客户端](/zh-CN/guides/connect-android-client.md)：了解原生 Android 客户端的配置与使用。