okooooooo/PhoneClaw

0 Fork 0

Files

T

Kellyvv 2a3d14402d docs: remove app icon from README header

2026-04-06 05:51:18 +08:00

9.2 KiB

Raw Blame History

PhoneClaw

本地运行的私人 iPhone AI Agent，不联网，不上传，完全离线。

English · 报告问题 · 功能建议

PhoneClaw 是一个运行在 iPhone 上的本地 AI Agent。它使用 Gemma 4 在设备端完成推理，不依赖云端，不上传聊天内容。

当前已经打通的原生能力：

能力	说明
图片理解	拍照或选图后直接提问，支持多模态输入
剪贴板	读写系统剪贴板
设备信息	读取设备名称、系统版本、内存等
文本处理	哈希计算、文本翻转等
日历	创建日历事件
提醒事项	创建提醒，准时弹出通知
通讯录	创建或更新联系人，按手机号去重

项目特点

完全离线运行，默认不联网
支持图片输入（多模态）
基于文件的 Skill 系统，新增能力不需要重写整个 Agent
支持多轮工具调用
默认可空壳安装 App，再在手机端下载 E2B / E4B
已内置权限管理、System Prompt 编辑、模型切换
针对 iPhone 内存上限做了缓存清理和历史裁剪

运行要求

macOS + Xcode 16 或更新版本
iOS 17.0 或更新版本
CocoaPods
真机调试账号（Apple ID）

模型建议：

模型	适用场景
Gemma 4 E2B	更稳，更适合默认分发，A16 及以上
Gemma 4 E4B	效果更强，但更吃内存，建议 iPhone 15 Pro 及以上

5 分钟快速开始

1. 克隆项目

git clone https://github.com/kellyvv/phoneclaw.git
cd phoneclaw

2. 安装依赖

pod install

3. 可选：预下载模型到本地

默认推荐方式已经变成：

先通过 Xcode 把空壳 App 安装到手机
打开 App
进入 模型设置 / Model Settings
在手机上直接下载 Gemma 4 E2B 或 Gemma 4 E4B

只有你想把模型一起打包进 App 时，才需要在电脑上先下载到 Models/ 目录。

PhoneClaw 识别的目录名必须和下面保持一致。推荐先安装 Hugging Face CLI：

brew install hf
# 或
pip install -U "huggingface_hub"

只下载 E2B（推荐）：

mkdir -p ./Models/gemma-4-e2b-it-4bit
hf download mlx-community/gemma-4-e2b-it-4bit --local-dir ./Models/gemma-4-e2b-it-4bit

只下载 E4B：

mkdir -p ./Models/gemma-4-e4b-it-4bit
hf download mlx-community/gemma-4-e4b-it-4bit --local-dir ./Models/gemma-4-e4b-it-4bit

两个都下载：

mkdir -p ./Models/gemma-4-e2b-it-4bit ./Models/gemma-4-e4b-it-4bit
hf download mlx-community/gemma-4-e2b-it-4bit --local-dir ./Models/gemma-4-e2b-it-4bit
hf download mlx-community/gemma-4-e4b-it-4bit --local-dir ./Models/gemma-4-e4b-it-4bit

下载完成后目录结构如下：

Models/
├── gemma-4-e2b-it-4bit/
│   ├── config.json
│   ├── tokenizer.json
│   ├── processor_config.json
│   ├── chat_template.jinja
│   ├── model.safetensors
│   └── model.safetensors.index.json
└── gemma-4-e4b-it-4bit/

Models/ 已在 .gitignore 中忽略，不会被提交到仓库。
Hugging Face 模型页显示的仓库体积：E2B 约 3.58 GB，E4B 约 5.22 GB。
如果不想用 CLI，也可以直接从模型页面手动下载后放到对应目录。

4. 打开工程

open PhoneClaw.xcworkspace

不要打开 .xcodeproj，请始终打开 .xcworkspace

5. 配置签名并运行

在 Xcode 中选择 PhoneClaw target
打开 Signing & Capabilities
选择你的 Team
把 Bundle Identifier 改成你自己的唯一值
连接 iPhone，按 ⌘R

首次安装后，如果系统要求信任开发者证书，请在手机里完成信任：设置 → 通用 → VPN 与设备管理 → 信任

6. 首次使用

打开 App 后：

右上角拼图按钮：Skill 管理
右上角滑杆按钮：模型设置 / 系统提示词 / 权限
如果当前是空壳安装，在模型设置页点击 下载 / Download

建议先下载一个模型，再在权限页开启日历、提醒事项、通讯录，然后试试：

这台手机的设备信息是什么
提醒我今晚八点发文件
帮我存一下王总的电话 13812345678

默认安装方式与模型打包

方案 A — 空壳安装，手机端下载模型

这是当前默认推荐方式。

优点：

Xcode 安装包更小
电脑端首次安装更快
可以在手机里自由切换下载 E2B 或 E4B

默认工程已经不会把 Models/ 里的模型自动打进 App 包。安装后直接去配置页下载即可。

方案 B — 只打包 E2B

保留 Models/gemma-4-e2b-it-4bit，移除 Models/gemma-4-e4b-it-4bit
在 Xcode 的 Project Navigator 里删除不用的模型 folder reference，选择 Remove Reference
在 PhoneClaw > Build Phases > Copy Bundle Resources 里手动把要打包的模型加回去，并确认只剩要分发的模型
修改 LLM/MLXLocalLLMService.swift 里的 availableModels，只保留实际会随 App 分发的模型（否则配置页仍然会显示不存在的选项）

方案 C — 同时打包 E2B + E4B

保留两个目录，并把两个模型 folder reference 都手动加回 Copy Bundle Resources。用户可在 App 的模型设置页里切换。

自定义 Skill

新增一个 Skill 的最小成本方式，是在应用目录里增加一个 SKILL.md：

Application Support/PhoneClaw/skills/<skill-id>/SKILL.md

---
name: MySkill
name-zh: 我的能力
description: 这个 Skill 的作用
version: "1.0.0"
icon: star
disabled: false

triggers:
  - 关键词1

allowed-tools:
  - my-tool-name

examples:
  - query: "用户会怎么说"
    scenario: "什么场景会触发"
---

# Skill 指令

告诉模型何时调用工具、如何组织参数、何时直接回答。

如果这个 Skill 需要真正调用系统能力，再去 Skills/ToolRegistry.swift 注册对应工具。

常见问题

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

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

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

后续计划

PhoneClaw 接下来的方向，不只是"多加几个工具"，而是把它逐步做成一个真正可用的本地 iPhone Agent。

1. 扩展更多 iOS 原生 API

文件与目录操作
照片读取、整理、描述、检索
备忘录 / Notes
本地通知
地图 / 位置相关能力
Safari / URL 打开与上下文传递
更多通讯录、日历、提醒事项的读写能力

2. 扩展更多 Skill

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

文件管理
照片理解与整理
日程规划
个人信息管理
本地知识库检索
语音输入 / 语音播报

3. 串联更多本地模型

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

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

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

4. 跨 App 自动化

PhoneClaw 不会假设自己能像桌面系统那样任意操控所有 App，而是优先走 iOS 真正允许的能力：

App Intents / Shortcuts
URL Scheme / Deep Link
Share Sheet / 分享扩展
剪贴板中转
系统通知与唤起

更现实的目标是：在 App 之间传递内容、拉起指定 App 到指定页面、把多步操作压缩成一条自然语言命令。

5. 外部硬件与视觉扩展

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

优先建议

如果按"最容易尽快做出体验差异"的顺序：

文件 / 照片 / 备忘录三类高频 API
Shortcuts / App Intents 集成
OCR + 语音识别
本地知识库检索
更细的自动化 Skill 编排

参考链接

License

MIT

9.2 KiB Raw Blame History Unescape Escape