手机爪AI代理

2. 安装依赖

pod install

快速开始

推荐安装方式：TestFlight。安装后在「模型设置」下载模型，再按需开启 Skill 权限。

源码构建环境要求：macOS + Xcode 16，iOS 17+，CocoaPods，真机 + Apple ID

3. 选择模型安装方式

方案 A（推荐）— 空壳安装，手机端下载

直接用 Xcode 把 App 安装到手机，打开后进入「模型设置」，在手机上直接下载 E2B 或 E4B。默认工程不会把 Models/ 里的文件打入包，安装包更小，安装更快。

方案 B — 打包 E2B 进 App

Gemma 4 现在用 LiteRT-LM 推理，模型是单个 .litertlm 文件（不再是 MLX 权重目录）。

1. 先在电脑下载模型文件到 Models/（推荐用 Hugging Face CLI）：

brew install hf
mkdir -p ./Models
hf download litert-community/gemma-4-E2B-it-litert-lm gemma-4-E2B-it.litertlm --local-dir ./Models

1. 在 Xcode 里把 Models/gemma-4-E2B-it.litertlm 拖进工程，确认它出现在 Build Phases > Copy Bundle Resources（作为单个文件加入，不是 folder reference）
2. 修改 LLM/Models/PredefinedModels.swift 里的 allModels，只保留要分发的模型

E2B 约 2.4 GB，E4B 约 3.4 GB。国内用户可设 HF_ENDPOINT=https://hf-mirror.com 加速，或从 ModelScope 镜像下载同名文件。Models/ 已在 .gitignore 中忽略，不会提交到仓库。

方案 C — 同时打包 E2B + E4B

下载两个模型文件：

brew install hf
mkdir -p ./Models
hf download litert-community/gemma-4-E2B-it-litert-lm gemma-4-E2B-it.litertlm --local-dir ./Models
hf download litert-community/gemma-4-E4B-it-litert-lm gemma-4-E4B-it.litertlm --local-dir ./Models

然后把 gemma-4-E2B-it.litertlm 和 gemma-4-E4B-it.litertlm 两个文件都加入 Xcode 的 Copy Bundle Resources。

LIVE 模式（语音交互）额外模型

如果你需要使用 LIVE 模式的语音识别和语音合成，需要额外下载 ASR 和 TTS 模型：

```bash

演示视频

PhoneClaw 是一个运行在 iPhone 上的本地私人 Agent。内置 Gemma 4 和 MiniCPM-V 多个本地模型，在端侧完成推理和 Skill 调用，无需云端 API 或外部模型接入，不上传聊天内容。

内置 Skill 示例

日历：用自然语言创建日历事件，支持指定标题、时间、地点。

"明天下午两点，在高科技园区约了个会，帮我加到日历"

"我今天有哪些日程?"

"帮我分析一下这周忙不忙"

提醒事项：创建定时提醒，准时弹出系统通知，不会遗漏。

"提醒我今晚八点发给老板那份文件"

通讯录：查询、保存、更新或删除联系人，支持姓名、手机号、公司、邮箱、备注，按手机号自动去重。

"帮我存一下王总的电话 13812345678，字节跳动的"

"检查下联系人张晓霞的电话多少"

剪贴板：读写系统剪贴板，可作为多步任务的数据中转。

"把刚才那段文字复制到剪贴板"

翻译：任意语种互译，自动识别源语言。

"把刚才那段话翻译成日语"

健康数据：读取 HealthKit 步数、距离、卡路里、心率、睡眠、运动记录。用户授权后在本地处理，不上传。

"我今天走了多少步"

"昨晚睡了多久"

"本周步数怎么样"

"我的静息心率是多少"

联网搜索：用户明确要求时搜索公开网页或读取 URL，把实时信息整理成回答。

"联网搜索今天的 AI 新闻"

"读取这个网页并总结: https://example.com"

5. 配置签名并运行

1. 选择 PhoneClaw target → Signing & Capabilities
2. 选择 Team，把 Bundle Identifier 改成你自己的唯一值
3. 连接 iPhone，按 ⌘R

首次安装后如系统提示信任证书：设置 → 通用 → VPN 与设备管理 → 信任

6. 首次使用

• 右上角拼图：Skill 管理
• 右上角滑杆：模型设置 / 系统提示词 / 权限
• 空壳安装时，先在模型设置页下载模型，再开启权限，然后试试：

提醒我今晚八点发文件
帮我存一下王总的电话 13812345678
把刚才那段话翻译成英文

7. 使用 Mac 客户端远程推理

Mac 客户端用于把同一局域网内的 Mac 作为 iPhone 的远程推理源。手机端仍然使用 PhoneClaw 的聊天界面和 Skill 系统，模型推理请求会发到你配对的 Mac。

方式 A：下载 release（推荐）

1. 下载 PhoneClawGateway-macOS-v0.1.1.zip
2. 解压后打开 PhoneClawGateway.app
3. 首次打开时，macOS 会询问「本地网络」权限，请选择允许
4. 如果 macOS 阻止首次启动，请在 Finder 里右键 PhoneClawGateway.app，选择「打开」

Gateway 默认监听 18080 端口，并通过 Bonjour 广播 _phoneclaw-llm._tcp 服务。

方式 B：从源码构建

cd MacGateway
bash build-app.sh
open PhoneClawGateway.app

从源码构建后同样需要允许 macOS 的「本地网络」权限。

配置 Mac 端运行源

1. 打开 PhoneClawGateway.app
2. 在主窗口里选择运行源：Ollama、Codex CLI 或 Antigravity CLI
3. 如果使用 Ollama，先安装并启动 Ollama，再下载一个模型，例如：

ollama pull gemma3:4b

1. 回到 Gateway 点扫描，确认模型出现在列表里

在 iPhone 上配对并使用

1. 确保 iPhone 和 Mac 在同一个局域网
2. 打开 PhoneClaw → 右上角滑杆 →「Mac 远程推理」
3. 点局域网内的 Mac，在 Mac 客户端弹窗里点「允许」
4. 配对成功后选择 Mac 上的模型，回到聊天页即可使用

远程模型会出现在模型选择器的「远程模型」分组里。若手机搜不到 Mac，优先检查：Mac 客户端是否正在运行、本地网络权限是否允许、两台设备是否在同一 Wi-Fi、系统防火墙是否允许 PhoneClawGateway.app 接收局域网连接。

1. 扩展更多 iOS 原生 API

• [ ] 文件与目录操作
• [x] 图片选择、描述与问答
• [ ] 照片库读取、整理与检索
• [ ] 备忘录 / Notes
• [x] 提醒事项到期提醒
• [ ] 通用本地通知
• [ ] 地图 / 位置相关能力
• [x] URL 网页读取与内容传递
• [ ] Safari / URL Scheme 打开外部 App
• [x] 通讯录查询、创建、更新与删除
• [x] 日历创建、日程读取、忙闲和空闲时间分析
• [x] 提醒事项创建
• [x] HealthKit 健康数据只读分析

2. 扩展更多 Skill

后续会继续把能力拆成更清晰的 Skill，而不是把所有逻辑都堆在一个大 Prompt 里。适合继续追加的方向：

• [ ] 文件管理
• [x] 图片理解
• [ ] 照片整理
• [x] 日程创建、查询与忙闲分析
• [x] 个人信息管理：通讯录、日历、提醒事项、剪贴板、健康数据
• [ ] 本地知识库检索
• [x] 语音输入 / 语音播报
• [x] 联网搜索 / 网页读取
• [x] 翻译

3. 串联更多本地模型

除了主聊天模型之外，后续适合接入的本地模型：

• [x] 视觉 / 多模态模型
• [ ] OCR 模型
• [x] 语音识别模型
• [x] 语音合成模型
• [ ] Embedding / Reranker 模型
• [ ] 更小的工具参数提取模型
• [ ] 更强的规划模型或多模型协作链路

这会让 PhoneClaw 从"一个大模型做所有事"，逐渐演进成"多个本地模型协同工作"的架构。

5. 外部硬件与视觉扩展

• [x] LIVE 摄像头实时识别
• [ ] 外部视频输入
• [ ] 屏幕画面理解
• [ ] 外部硬件联动

探索把外部视频输入、屏幕画面理解和本地模型串起来，让 PhoneClaw 不只是"在手机里回答问题"，而是逐步具备更强的现实世界感知与调度能力。

常见问题

为什么安装后看不到权限弹窗？ 通常是因为对应 Skill 还没有真正执行到系统 API。如果之前已经拒绝过一次，iOS 也不会反复弹框，需要到系统设置里手动开启。

为什么切模型后加载失败？ 先确认：模型文件名和 LLM/Models/PredefinedModels.swift 里的 allModels 一致；如果你走的是空壳安装，模型已经在手机端下载完成；如果你走的是内置分发，该模型确实被打进了 App 包；设备内存足够。

为什么提醒事项创建失败？ 最新代码会先尝试复用现有提醒列表；如果系统里没有可写列表，会再尝试自动创建一个 PhoneClaw 提醒列表。如果这一步仍失败，通常是系统提醒源本身不可写。

为什么 iPhone 搜不到 Mac 客户端？ 先确认 PhoneClawGateway.app 正在运行，并且 macOS 已允许本地网络权限；iPhone 和 Mac 需要在同一个局域网。若仍搜不到，检查 macOS 防火墙是否允许该 App 接收连接，或者重新运行 bash MacGateway/build-app.sh 后再打开生成的 App。