> ## 文档索引
> 获取完整文档索引： https://fushouagent.com/docs/llms.txt
> 先阅读此索引，了解所有可用页面。
# 安装客户端能力
> 通过命令行下载客户端，并按需安装浏览器、Windows Git Bash、手机依赖与通用 AGENTS Skill。
`fushou-agent install` 用于安装测试用例功能所需的浏览器依赖、Windows Git Bash、Android ADB 与输入法依赖、HarmonyOS HDC、将客户端内置的 `fushou-agent` Skill 发布给兼容的 AGENTS 客户端，或在 macOS 上准备 iOS 真机操作能力。实际执行安装时必须且只能指定一个安装选项。该命令不需要客户端授权。
## 通过命令行下载并安装
命令行安装可以下载最新客户端，并安装浏览器功能所需的依赖及赋手智能体 Skill。手机操作能力可在安装后按需单独安装。支持 Windows 10+ x64、macOS 14+ Apple/Intel 芯片、Ubuntu 24.04+ x64。
前往[客户端下载页](/client/download)，在“命令行安装”中选择操作系统。复制命令，在对应终端中运行。
执行安装命令之前，请先确保：
1. 已安装 Node.js ≥ 22.19.0，通过 `node --version` 查看版本。
2. Windows 使用 PowerShell 5.1 或更高版本；macOS 和 Ubuntu 使用 Bash 或 zsh。Ubuntu 还需安装 curl，可通过 `curl --version` 查看版本。
3. 如果需要操作手机，确保手机已经通过 USB 连接、开发者模式已经打开。如果需要操作 iPhone，请先准备 Xcode、Homebrew，并通过 USB 连接已解锁、信任此电脑且开启开发者模式的 iPhone。iPhone 操作仅支持 macOS，详细准备步骤见下文。
`install --all` 安装 Skill、浏览器功能，以及 Windows 上的 Git Bash，然后依次进入 Android、HarmonyOS 和 macOS 上的 iPhone 安装流程。每个手机安装流程会先提示按对应文档完成设备配置，并提供直达配置章节的完整链接，再等待输入 `yes` 确认；输入 `no` 或直接回车会跳过该手机能力，继续下一项。也可以单独运行 `fushou-agent install --android`、`fushou-agent install --harmony` 或 macOS 上的 `fushou-agent install --ios`，获取同样的指引并确认安装。
命令完成安装后会自动检查登录状态；需要授权时，请按浏览器提示完成登录。安装成功后会显示本机 `fushou-agent` 程序的安装路径。你可以通过 CLI 命令行调用 Agent 能力，通过 `--help` 了解能力范围。推荐通过 codex、workbuddy 等智能体调用 "fushou-agent" Skill 执行命令。安装遇到问题时，请按终端提示处理后重新运行安装命令。
安装中途失败时，客户端和已完成的安装步骤会保留。处理错误后，在交互终端运行 `fushou-agent install --all` 继续安装；成功后运行 `fushou-agent login` 完成授权。Windows 安装命令请完整复制下载页提供的内容。
## 下载安装
在[客户端下载页](/client/download)的“下载安装”中选择 Windows、macOS M芯片、macOS Intel 或 Ubuntu，下载对应压缩包并完整解压。执行前请按上面的清单准备 Node.js；手机可在单独安装对应能力时准备。
在解压缩后的目录执行命令。先执行安装命令，再执行登录命令；需要授权时，按浏览器提示完成登录。
Windows PowerShell：
```powershell
.\fushou-agent.exe install --all
.\fushou-agent.exe login
```
macOS 或 Ubuntu：
```bash
./fushou-agent install --all
./fushou-agent login
```
## 命令格式
```bash title="Terminal"
fushou-agent install --browser
fushou-agent install --bash
fushou-agent install --skills
fushou-agent install --android
fushou-agent install --harmony
fushou-agent install --ios [--team ID]
fushou-agent install --all
```
不带选项运行 `fushou-agent install` 时，只会显示帮助并成功退出，不会修改任何内容。`fushou-agent install --help` 显示帮助。安装选项不能组合或重复使用。
## 安装选项
| 选项 | 行为 |
| --- | --- |
| `--browser` | 安装 Playwright CLI、Chromium 浏览器运行组件、FFmpeg，以及文件搜索工具 rg/fd。 |
| `--bash` | 仅 Windows：安装 Git Bash。 |
| `--skills` | 安装或更新赋手智能体Skill，供本地智能体直接调用。 |
| `--android` | 将内置 ADB 离线安装到共享缓存，同版本有效安装会复用；选中设备未授权时等待授权，再安装并启用内置 ADB Keyboard。 |
| `--harmony` | 将内置 HDC 离线安装到共享缓存，同版本有效安装会复用；选中设备未授权时等待授权。 |
| `--ios` | 仅 macOS：为已连接的 iPhone 安装并验证自动化所需组件。 |
| `--team ID` | 可选，仅当存在多个 Xcode 团队时需要指定签名团队；仅用于 `--ios`。 |
| `--all` | 安装 Skill、浏览器依赖，以及 Windows 上的 Git Bash；随后依次调用 Android、HarmonyOS、macOS iPhone 安装流程，由每项流程展示指引并请求确认，默认不安装手机能力。 |
`--all` 按 Skill、浏览器依赖、Windows Git Bash、Android、HarmonyOS、macOS iPhone 的顺序执行。手机安装指引在执行到对应步骤时输出，不在安装开始前集中选择手机类型。某一步失败时不会继续后续步骤；已经成功的步骤会保留，同时命令返回非零退出码。手机安装需要在交互终端中确认，默认不安装；Linux 和 Windows 使用 `--ios` 会报告仅支持 macOS，macOS 和 Linux 不提供 `--bash`，`--all` 不安装 Git Bash。
建议在开始任务前执行 `install --browser`，提前准备文件搜索依赖。下载优先使用国内加速源，失败后尝试官方源；已安装且校验通过的组件会直接复用。依赖缺失时，任务会提示重新安装，不会在工具调用期间等待下载。
Windows 可通过 `install --bash` 安装 Git Bash，本地 Agent 优先使用该安装。Windows 同时支持 PowerShell 工具；未使用此安装命令时，也可使用系统已安装的 Git Bash。
已检测到目标手机但尚未授权时，macOS 和 Windows 会弹出手机操作引导，Linux 会在终端提示。请在手机上确认授权；客户端最多等待 30 秒，成功后自动继续。超时会失败退出，完成授权后重新运行原命令。关闭引导窗口不会取消等待。自然语言 `exec` 准备手机时也采用此流程。
## 配置 Android 设备
Android 自动化需要电脑侧的 ADB、设备侧已授权的调试连接，以及输入中文等 Unicode 文本时使用的 ADB Keyboard。客户端优先静默完成可自动执行的步骤，通常只需要用户开启调试并确认设备上的系统授权。
> **注意：** 以下说明适用于 Android，以及仍兼容 Android ADB 的 EMUI 和 HarmonyOS 4 及更早版本。HarmonyOS 5 及以上的纯鸿蒙设备请改用 `fushou-agent harmony`。
### 开启开发者模式和 USB 调试
不同系统版本的设置名称可能略有变化。使用支持数据传输的 USB 线连接电脑，打开 USB 调试，并在设备弹窗中允许当前电脑调试。部分机型还需要开启“仅充电”模式下允许 ADB 调试，具体见下面的品牌说明。准备期间保持手机解锁；仅在使用可信电脑时勾选“始终允许”。
#### 华为
华为 EMUI 的开发者模式与 USB 调试配置流程和荣耀基本相同，**参考[荣耀手机配置](#荣耀)即可**。HarmonyOS 4 及更早版本也可参考其中的调试与授权步骤，但开启开发者模式时需要点击的版本入口可能不同，请以[华为官方说明](https://consumer.huawei.com/cn/support/content/zh-cn02842747/)为准。HarmonyOS 5 及以上请按[配置 Harmony 设备](#配置-harmony-设备)操作。
#### 荣耀
以下截图来自已连接的荣耀 X50（MagicOS 9），橙色框标出操作位置。个人账号和设备标识所在区域已裁掉；其他 MagicOS 版本的名称或位置可能略有不同。
**第一步：找到“关于手机”。** 打开手机的“设置”，向下滑动到页面底部，点击“关于手机”。“系统和更新”也是后面进入开发人员选项的入口。
**第二步：连续点击“版本号”。** 在“关于手机”中找到下图橙色框中的 **“版本号”**，连续点击约 7 次；如果要求身份验证，输入手机的锁屏密码，直到提示已进入开发者模式。要点击的是“版本号”这一行，不是下方的“基带版本”或“内核版本”。如果提示已经处于开发者模式，直接继续下一步。
**第三步：进入开发人员选项。** 返回“设置”，点击“系统和更新”，向下滑动并点击“开发人员选项”。如果没有这个入口，请返回第二步确认已成功开启开发者模式。
**第四步：确认总开关已开启。** 进入后查看页面顶部的“开发人员选项”开关；下图蓝色表示已经开启。如果关闭，按手机提示打开。
**第五步：打开 USB 调试。** 在同一页面向下滑动，找到“调试”分组，打开“USB 调试”，并确认手机显示的提示。下图蓝色表示已开启；无需点击“撤销 USB 调试授权”。
**第六步：处理仅充电模式与电脑授权。** 如果连接电脑后使用“仅充电”模式，在同一页面找到并打开 **“‘仅充电’模式下允许 ADB 调试”**。开关可能在较下方，需要继续滑动；如果机型没有此开关，按设备提示选择可传输数据的 USB 模式。
保持手机解锁并连接电脑，运行 `fushou-agent install --android`，读完终端指引后输入 `yes` 并按回车。手机弹出“允许 USB 调试”并显示电脑指纹时，确认是当前连接的电脑后点击“允许”。如果一直没有弹窗，先检查数据线和上述开关，再重新插拔 USB 线并重试安装。输入法安装的确认步骤见下文。
参考荣耀官方的 [开启 USB 调试说明](https://www.honor.com/cn/support/content/zh-cn15808494/)。
#### 小米
以下图片来自 [AirDroid 帮助中心的小米设备教程](https://help.airdroid.com/hc/zh-cn/articles/360045329413)，展示 **MIUI 11** 的中文界面。澎湃 OS 的菜单名称不同，下面同时给出对应路径；图片不代表所有新机型的界面。
**第一步：进入设备信息页。** 打开“设置”，点击“我的设备”或“关于手机”，再进入“全部参数”。澎湃 OS 中对应入口通常是“详细信息与规格”。
**第二步：点击系统版本开启开发者模式。** 在参数页连续点击 **“MIUI 版本”** 约 7 次；澎湃 OS 点击 **“OS 版本”**。按要求验证锁屏密码，直到提示已进入开发者模式。不要点击 Android 版本、基带版本或内核版本。新系统入口可参阅 [小米官方开发者选项说明](https://www.mi.com/global/support/faq/details/KA-168765/)。
**第三步：进入开发者选项。** 返回设置首页，点击“更多设置”，向下滑动找到“开发者选项”。如果没有出现，先确认第二步已经完成；部分系统优化操作会隐藏此入口，需要重新开启。
**第四步：开启 USB 调试。** 确认开发者选项总开关已开启，在“调试”分组打开“USB 调试”，阅读手机提示后点击“确定”。不要点击“撤销 USB 调试授权”。
**第五步：遇到安装或操作限制时检查额外开关。** 安装 ADB Keyboard 被拒绝时，按机型提示开启“USB 安装”；设备已连接但无法点击、输入时，检查 **“USB 调试（安全设置）”**。部分版本要求先登录本人的小米账号，再阅读倒计时提示，依次点击“下一步”和“允许”。下图展示依次确认的提示，需等待倒计时结束；这些开关不等同于普通“USB 调试”。
**第六步：授权电脑并安装。** 连接支持数据传输的 USB 线，保持手机解锁，运行 `fushou-agent install --android` 并按指引输入 `yes`。在显示电脑 RSA 指纹的弹窗中允许当前电脑，留意 ADB Keyboard 的安装确认。普通 USB 调试路径也可参阅 [小米官方说明](https://www.mi.com/global/support/article/KA-06515/)。
#### OPPO
以下图片来自 [AirDroid 帮助中心的 OPPO 设备教程](https://help.airdroid.com/hc/zh-cn/articles/360045675654)，展示 **ColorOS 7.1** 的中文界面，浅蓝框标出操作位置。新系统路径以 [OPPO 官方说明](https://support.oppo.com/au/answer/?aid=neu9332)为准。
**第一步：打开“关于本机/关于手机”。** 在设置首页向下滑动，进入“关于本机”；旧版名称为“关于手机”。
**第二步：进入版本信息。** 在关于页面点击“版本信息”或“版本”，不是 ColorOS 升级卡片。下一步下方的组合图中，从左起第三幅的浅蓝框标出入口。
**第三步：连续点击“版本号”。** 在版本信息页点击 **“版本号”** 约 7 次；需要时输入锁屏密码，直到提示已进入开发者模式。不要点下方的“基带版本”或“内核版本”。
**第四步：进入开发者选项。** 返回设置首页，按系统版本选择入口：ColorOS 14.1–16 通常为“系统与更新/系统和更新”，ColorOS 13–14 为“其他设置”，ColorOS 12 为“系统设置”，ColorOS 11 及图示版本为“其他设置”。进入后点击“开发者选项”；也可以在设置中搜索此名称。
**第五步：打开 USB 调试并确认。** 确认开发者选项总开关已开启，在“调试”分组打开“USB 调试”，出现提示后点击“确定”。下图左侧两幅展示开发者选项入口、调试开关和确认弹窗。
**第六步：授权电脑并安装。** 连接支持数据传输的 USB 线，解锁手机，运行 `fushou-agent install --android`，按指引输入 `yes`。在显示电脑指纹的弹窗中允许当前电脑。如果手机管家拦截安装，请对本次可信的 ADB Keyboard 安装按提示确认；找不到授权弹窗时，重新连接并检查 USB 调试是否仍开启。
#### VIVO（vivo）
以下图片来自 [AirDroid 帮助中心的 vivo 设备教程](https://help.airdroid.com/hc/zh-cn/articles/360045661674)，展示 **OriginOS 1.0**。不同 OriginOS、Funtouch OS 版本的布局可能不同。
**第一步：打开系统管理。** 在设置中点击“系统管理”，再进入“关于手机”。部分旧版 Funtouch OS 使用“更多设置 > 关于手机”；部分机型使用“我的设备 > 更多参数”。
**第二步：打开版本信息。** 在关于手机页点击“版本信息”。如果关于页面已经直接显示“软件版本号”，可以直接进行下一步。
**第三步：连续点击“软件版本号”。** 找到 **“软件版本号”**，连续点击约 7 次，按手机提示完成锁屏密码验证，直到显示已进入开发者模式。不要点击“硬件版本号”、“基带版本”或“内核版本”。
**第四步：找到开发者选项。** 返回“系统管理”，向下滑动，点击“开发者选项”。旧版可返回“更多设置”寻找；入口没有出现时，重新检查第三步。下一步下方的组合图中，居中的浅蓝框标出入口。
**第五步：开启 USB 调试并确认。** 确认顶部“开发者选项”总开关已开启，再找到“USB 调试”并打开。下图右侧展示开启 USB 调试后的功能确认弹窗，点击“确定”。
**第六步：授权电脑并安装。** 连接支持数据传输的 USB 线，解锁手机，运行 `fushou-agent install --android`，按指引输入 `yes`。在显示电脑 RSA 指纹的弹窗中允许当前电脑；如出现通过 USB 安装应用的额外确认，请确认本次 ADB Keyboard 安装。设备已授权但无法执行操作时，按本机提示检查是否还有 USB 安全权限或模拟点击权限。
入口及连接问题可参阅 [vivo 官方 USB 调试说明](https://kefu.vivo.com.cn/robot/imgmsgData/cb952d8b22ed41e09b32803c02982cc5/index_1.html)。
### 确认设备授权与输入法
连接一台设备，解锁手机并允许当前电脑进行 USB 调试，然后运行 `fushou-agent install --android`。如手机询问是否允许安装或启用 ADB Keyboard，请按提示确认。
ADB 工具包随客户端提供，无需另行下载。请保持完整发布包，已有兼容组件会继续使用，手机的默认输入法不会被永久更改。
安装失败时，检查数据线是否支持数据传输、USB 调试是否开启，以及手机上是否有待确认的提示。重新连接后再次运行安装命令。
## 配置 Harmony 设备
以下步骤适用于 **HarmonyOS 5 及以上的纯鸿蒙设备**。HarmonyOS 4 及更早版本如果仍使用 Android ADB，请按上面的“配置 Android 设备”操作。
开启开发者选项与 USB 授权弹窗截图来自华为开发者网站；软件版本和设置入口截图补充采用华为官方支持页的 HarmonyOS 6 实机示例。设备名称、序列号已用不透明灰色遮盖，验证码及其他无关区域已裁掉。不同机型的界面可能略有变化。
### 1. 开启开发者模式
1. 在手机上打开“设置”，进入“关于手机”或以设备名称命名的设备信息页面。
2. 找到 **“软件版本”**，连续点击 7 次。下图红色框标出点击位置；这里不是荣耀手机的“版本号”页面。
3. 手机显示“开启开发者选项？”时，点击“确认重启并开启”；如设置了锁屏密码，按提示验证。等待手机自动重启，再解锁。已经开启开发者模式的设备可以跳过此步骤。
上图来源：[华为官方支持的 USB 调试设置示例](https://consumer.huawei.com/cn/support/content/zh-cn16077659/)。
弹窗截图来源：[华为开发者网站：开发者测试](https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/intents-habit-rec-dp-self-validation)，已裁出弹窗，去除周围的设备信息。此处只需参考开启开发者模式的操作，无需执行该文档中应用测试的其他步骤。完整开启步骤可参阅 [开发者选项说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-developer-mode)。
### 2. 找到开发者选项并打开 USB 调试
1. 用支持数据传输的 USB 线连接一台目标手机，保持手机解锁。
2. 打开 **“设置 > 系统 > 开发者选项”**，确认页面顶部的“开发者选项”总开关已开启。
3. 在该页面打开 **“USB 调试”**。该选项需要手机已通过 USB 连接电脑时才能设置。
上图从左向右展示入口，来源为同一篇 [华为官方支持说明](https://consumer.huawei.com/cn/support/content/zh-cn16077659/)。右侧“USB 调试”开关呈灰色，表示截图时尚未开启；请将它打开后再继续。HarmonyOS 5 及以上无需寻找 Android 的“仅充电模式下允许 ADB 调试”开关，参阅 [华为 USB 调试说明](https://consumer.huawei.com/cn/support/content/zh-cn00407281/)。
### 3. 允许当前电脑调试并完成安装
HDC 工具包随客户端提供，无需另行下载；请保持客户端发布包完整。同版本组件完整且可用时不会重复安装。
在电脑终端运行：
```bash title="Terminal"
fushou-agent install --harmony
```
读完准备指引后输入 `yes` 并按回车。连接及安装过程中留意手机上的 **“允许‘USB调试’？”** 弹窗，确认是当前连接的电脑后点击“允许”。“始终允许使用这台计算机进行调试”仅在可信电脑上按需勾选。
弹窗截图来源：[华为开发者网站：使用本地真机运行应用](https://developer.huawei.com/consumer/cn/doc/doccenter-deveco-studio/ide-run-device)。这里仅参考设备连接与授权步骤，无需创建应用工程。
如果终端提示等待授权，请先解锁手机并确认弹窗。客户端最多等待 30 秒；超时后，完成手机授权并重新运行原安装命令即可。
普通 [`harmony exec`](/docs/client/harmony/exec) 会自动准备缺失的 HDC。Harmony MCP 和已保存脚本执行只使用已有工具；首次使用前请先完成上述安装。
### 找不到入口或连接不上时
- **没有“开发者选项”：**确认点击的是设备信息页的“软件版本”，已完成开启确认及重启；受管理的设备需确认是否允许开启开发者模式。
- **USB 调试无法打开：**先连接支持数据传输的 USB 线，确认接口连接正常，再返回“设置 > 系统 > 开发者选项”操作。
- **没有授权弹窗或安装超时：**保持手机解锁，检查是否有待确认的提示，重新连接 USB 线后重试。如果仍未识别，请按终端提示处理电脑的 USB 驱动或权限。
## 配置 iOS 设备
仅支持 macOS 和通过 USB 连接的 iPhone 真机。首次使用需要准备 Xcode、Homebrew 和自己的 Apple 账户（Apple ID）。完成下面的步骤后，再运行安装命令。
**在自己的 iPhone 上使用赋手智能体，可以使用普通 Apple 账户，无需先购买每年 99 美元的 Apple Developer Program 会员。** 已有用于 iCloud 或 App Store 的 Apple 账户可以直接在 Xcode 中登录；没有账户时，先免费创建普通 Apple 账户即可。Xcode 会为未关联付费开发者会员的账户显示 **Personal Team（个人团队）**。
免费账号有设备、应用数量及有效期限制，具体以 [Apple 的个人团队说明](https://developer.apple.com/help/account/basics/about-your-developer-account)为准。免费账号的设备安装授权通常在 7 天后到期；以后执行 iOS 任务时，客户端会自动检查并尝试重新准备，遇到登录或信任提示仍需本人确认。
下面的截图来自 Xcode 26.1.1。其他版本的名称和位置可能略有不同；截图中灰色区域已遮盖账号、姓名、个人路径及设备标识，黄色框标出需要关注的位置。
### 1. 安装并完成 Xcode 初始化
1. 在 Mac 的 App Store 中搜索 **Xcode**，确认开发者为 Apple，点击“获取”或“安装”。也可以从 [Apple 的 Xcode 下载入口](https://developer.apple.com/xcode/resources/)进入。下载和安装需要一定时间，请确保网络畅通并预留磁盘空间。
2. 从“应用程序”中打开 Xcode，按屏幕提示完成首次启动，包括协议确认、管理员密码和所需组件安装。等安装进度结束，能够进入 Xcode 欢迎页或主窗口后再继续。
3. 如果首次启动要求选择平台组件，选择 **iOS**。之后也可打开 Mac 顶部菜单 **Xcode → Settings… → Components**，检查 **Platform Support** 中的 iOS 项；若显示“Get”或“Download & Install”，点击并等待完成。部分版本将此页称为“Platforms”。
上图的 iOS 项已经安装，右侧没有“Get”按钮。平台支持的具体版本以你安装的 Xcode 为准。此步骤不需要创建工程。
如果终端仍提示“需要完整的 Xcode”，打开 **Xcode → Settings… → Locations**，在 **Command Line Tools** 下拉框中选择已安装的 Xcode，按系统提示完成确认后重试。
这里应显示 Xcode 版本。只安装 Command Line Tools 不能代替完整的 Xcode。相关操作也可参阅 [Apple 的命令行工具设置说明](https://developer.apple.com/documentation/xcode/configuring-command-line-tools-settings)。
### 2. 在 Xcode 中添加 Apple 账户
这里的“设置”指 **Mac 顶部菜单中的 Xcode 设置**，不是 iPhone 或 macOS 的系统设置。
1. 打开 **Xcode → Settings…**（快捷键 `⌘,`）。部分版本称为“Preferences…”。
2. 在左侧选择 **Apple Accounts**；部分版本称为“Accounts”，即“Settings → Accounts”。
3. 点击 **Add Apple Account…**；旧版本可能是左下角的 `+`。使用自己的 Apple 账户登录，按 Apple 提示完成双重认证。
4. 确认账号出现在列表中，点击该账号，查看 **Teams** 下的团队。按下面的账户类型说明确认自己要使用的团队。
| 账户或团队类型 | Xcode 中如何识别 | 本次配置如何选择 |
| --- | --- | --- |
| 普通 Apple 账户，未购买开发者会员 | 团队名称带有 **Personal Team**，通常同时显示你的姓名。 | 在自己的 iPhone 上使用时可选择此团队；无需付费，也无需为了本次配置另行注册 99 美元的会员。 |
| 已购买个人 Apple Developer Program 会员 | 通常显示个人姓名对应的付费团队。 | 已有会员可以使用该团队；只为个人真机操作，无需新购买会员。 |
| 已加入组织的开发者团队 | 通常显示公司或组织名称；同一个 Apple 账户可以加入多个团队。 | 如需使用组织团队，先确认管理员已授予开发与签名权限；受邀成员无需各自再购买个人会员。 |
如果 Apple 要求接受免费的开发者协议，按提示接受即可；免费注册 Apple 开发者身份即可，**无需购买** Apple Developer Program 99美元/年的会员。看到购买会员或付款页面时，本次个人真机配置不需要继续付款。账户及团队说明见 [Apple 账户说明](https://developer.apple.com/help/account/basics/about-your-developer-account)。
看到自己的账号和团队后即可继续。Apple 账户用于允许自动化组件安装到你的 iPhone，与赋手智能体的登录账号不同。密码和验证码只在 Apple 的登录界面填写。
### 3. 安装并检查 Homebrew
Homebrew 用于安装电脑连接 iPhone 所需的工具。赋手客户端会使用已有的 Homebrew，但不会代替你安装 Homebrew。
1. 在 Mac 上打开“终端”：按 `⌘空格`，搜索“终端”或“Terminal”，按回车。
2. 先运行下面的命令。如果已经显示 Homebrew 版本号，可以跳过安装。
```bash title="Terminal"
brew --version
```
3. 如果提示 `command not found: brew`，打开 [Homebrew 官网](https://brew.sh/)，复制“Install Homebrew”下的安装命令，粘贴到终端并执行，按提示完成安装。
4. 终端要求密码时，输入 **Mac 登录密码**并按回车。输入期间不会显示字符或星号，这是正常现象。
5. 安装结束后，阅读终端输出的 **Next steps**，执行其中要求添加 Homebrew 到 PATH 的命令。每台电脑显示的路径可能不同，请复制自己终端中的命令。
6. 重新打开终端，再运行 `brew --version`。显示版本号才算完成。
如果安装后仍找不到 `brew`，通常是“Next steps”尚未完成。先按 [Homebrew 的安装后步骤](https://docs.brew.sh/Installation#post-installation-steps)处理，再重试；仅关闭并重开终端不一定能解决。
### 4. 连接 iPhone，并在 Xcode 中确认
1. 使用**支持数据传输的 USB 线**连接一台目标 iPhone，保持手机解锁；准备期间请断开其他 iPhone 或 iPad。
2. 如果 Mac 显示允许连接配件的提示，按提示允许。如果 iPhone 显示“信任此电脑？”，在 **iPhone 上**点击“信任”，并输入 **iPhone 的解锁密码**。
3. 在 Xcode 中，从 Mac 顶部菜单选择 **Window → Devices and Simulators**，点击 **Devices**，再在左侧选择自己的 iPhone。无需打开或创建工程。
4. 确认右侧显示这台手机的机型和 iOS 版本。如果出现配对、准备设备或下载支持组件的提示，按提示处理并等待完成。
上图是设备已被识别的示例；首次安装前，“Installed Apps”中还没有赋手智能体也正常。如果你的 Xcode 使用 **Device Hub** 管理设备，改从 **Xcode → Open Developer Tool → Device Hub** 打开，选择自己的真机并完成右侧的配对提示。可参阅 [Apple 的设备管理说明](https://developer.apple.com/documentation/xcode/managing-your-simulated-and-physical-devices-in-device-hub)。
如果左侧没有手机，先确认手机已解锁、已信任此电脑，再拔插 USB 线、换支持数据传输的线或接口。若 Xcode 提示当前版本不支持手机系统，请按提示更新 Xcode 或安装所需的平台组件。
### 5. 开启 iPhone 的开发者模式
1. 在 **iPhone 上**打开 **设置 → 隐私与安全性 → 开发者模式**。该选项位于页面靠下的位置。
2. 打开“开发者模式”开关，按提示点击“重新启动”。
3. 手机重启后解锁，在确认弹窗中点击“开启”，并输入手机解锁密码。**重启后还需要这次确认**。
4. 再次进入该设置页，确认开关已开启，然后保持 USB 连接并解锁手机。
**找不到“开发者模式”时：**先完成上一步的 Xcode 设备连接或配对，在设备窗口中选择 iPhone 并处理提示，再重新打开手机的“隐私与安全性”页面。Apple 说明，该选项会在开始配对或曾与 Mac 配对后出现，参阅 [开启开发者模式](https://developer.apple.com/documentation/xcode/enabling-developer-mode-on-a-device)。如果仍找不到，并且设备由单位或学校管理，请向设备管理员确认是否允许开发者使用。
“信任此电脑”“开启开发者模式”和安装后可能出现的“信任开发者”是三个不同步骤，完成其中一项不会代替另外两项。
### 6. 运行安装并完成手机授权
以上准备完成后，在终端运行：
```bash title="Terminal"
fushou-agent install --ios
```
命令会先显示准备指引，再询问是否安装。输入 `yes` 并按回车才会开始；输入 `no` 或直接回车会取消安装。
安装过程中保持手机连接、解锁，并留意电脑和手机上的提示。首次准备可能耗时数分钟。只有一个 Xcode 团队时自动选择；存在多个团队且尚未选择时，命令会列出团队 ID 并退出。团队是 Apple 账户下的个人或组织身份，团队 ID 是 10 位字母或数字，**不是 Apple ID 邮箱**。
请先在 Xcode 的账户页确认要使用的团队，再按终端提示指定其 ID 后重试：
```bash
fushou-agent install --ios --team ABCDE12345
```
`ABCDE12345` 只是格式示例，请替换为自己的团队 ID，不要照抄。如果无法确认终端列出的 ID 对应哪个团队，请联系团队管理员或支持人员。团队选择会保存，后续安装和自动修复会继续使用。可以再次传入 `--team` 更换团队。
如果 iPhone 尚未信任这台 Mac，请按弹窗在手机上点击“信任”，并按提示输入手机密码。客户端等待最多 30 秒，确认后继续安装；超时请完成信任后重试。
如果手机提示“不受信任的开发者”，这是安装后的另一项授权，Mac 会显示操作引导并等待最多 30 秒。请在 iPhone 上：
1. 打开“设置 → 通用 → VPN 与设备管理”。
2. 在“开发者 App”中选择与本次 Xcode 签名账号对应的开发者，确认其中列出了赋手智能体。
3. 点击“信任”并再次确认。
如果暂时没有“开发者 App”或对应条目，先确认自动化组件已安装到手机，并查看终端是否仍在安装；不要选择无关的企业或管理描述文件。
确认成功后引导会关闭，安装或任务自动继续准备。关闭引导窗口不会取消等待。若超时，请完成信任后重试原操作。
如果手机提示“启用 UI 自动化”或要求再次输入密码，也需要在手机上按提示确认。以终端最终报告安装成功为准；遇到报错时，按下面的表格处理后重新运行安装命令。
### iPhone 准备过程中的常见卡点
| 现象 | 处理方法 |
| --- | --- |
| 不知道应输入哪个密码 | Homebrew 或 Mac 系统安装提示使用 Mac 登录密码；手机信任与开发者模式使用 iPhone 解锁密码；Apple 登录使用 Apple 账户密码和验证码。 |
| 提示“需要完整的 Xcode” | 安装 App Store 中的完整 Xcode，再到“Settings → Locations → Command Line Tools”选择它。 |
| 提示 Xcode 初始化未完成或缺少 iOS 组件 | 打开 Xcode 完成首次启动，在“Settings → Components”确认 iOS 平台组件已安装。 |
| 提示需要 Homebrew，或安装后仍找不到 `brew` | 安装 Homebrew，执行安装输出中的“Next steps”，重新打开终端并检查 `brew --version`。 |
| Xcode 账号已登录，但终端仍提示未配置开发团队 | 点击 Xcode 账户查看 Teams 是否已加载；处理 Apple 的登录提示后重试。仍然失败时联系支持人员。 |
| 找不到开发者模式 | 先在 Xcode 设备窗口选择手机并完成配对，再回到 iPhone 的“隐私与安全性”查看。 |
| 提示多个团队 | 确认要使用的团队，用终端列出的真实 ID 传入 `--team`；示例 ID 不能直接使用。 |
| 提示多个设备或找不到 USB 设备 | 仅保留一台目标手机，保持解锁，确认信任此电脑并使用数据线连接。 |
| 信任、解锁或授权等待超时 | 先完成手机上的操作，再运行 `fushou-agent install --ios`；关闭提示窗口不会取消等待。 |
## 安装 Skill
运行 `fushou-agent install --skills`，让兼容的智能体工具使用赋手客户端的测试用例、设计稿和设备操作能力。
重新安装会替换原有的赋手 Skill，自行修改的内容不会保留。移动客户端目录后请重新安装 Skill。此操作不需要联网，同时会准备 `~/.fushou-agent/skills/.system/playwright-cli`。该浏览器 Skill 仅供测试用例主智能体使用，不会加入电脑或手机执行、委派任务的 Skill 列表。
## 卸载客户端
运行以下命令，查看将删除的目录并按提示确认。默认不确认，直接回车会取消卸载。
```bash title="Terminal"
fushou-agent uninstall
```
卸载会删除当前用户的整个 `~/.fushou-agent` 目录、客户端缓存、`~/.agents/skills/fushou-agent` 以及客户端目录，包括这些目录中的登录信息、配置、工作文件和下载文件。安装时添加的 PATH 配置也会清理；其它 Skill 和终端配置会保留。
客户端缓存位置：
- Windows：`%LOCALAPPDATA%\fushou-agent`
- macOS：`~/Library/Caches/fushou-agent`
- Ubuntu：`${XDG_CACHE_HOME:-~/.cache}/fushou-agent`
如已确认需要完整卸载，可跳过确认：
```bash title="Terminal"
fushou-agent uninstall --yes
```
没有交互终端时必须使用 `--yes`。运行前请结束正在运行的赋手客户端任务。卸载完成后，请重新打开终端。
## 本地 Agent 运行要求
运行电脑、手机和测试用例 Agent 任务前，请自行安装 Node.js 22.19.0 或更新版本，并确保终端可以运行 `node` 和 `npm`。首次运行会安装所需依赖；安装期间需要联网。客户端不捆绑 Node.js。
供脚本或其他智能体使用的调用，请显式加 `-p` 或 `--prompt`；人工在终端执行时可使用默认交互模式回答澄清问题。
## 相关主题
- [概览](/docs/client/overview.md)
- [testcase exec](/docs/client/testcase/exec.md)
- [android exec](/docs/client/android/exec.md)