PhoneClaw

一、项目背景与起源

想象一下：你在咖啡馆里，随口问手机"今天下午有什么安排？"手机立刻告诉你下午两点有个会议，并帮你新建了下午四点的提醒事项。整个过程不需要联网、不需要付费 API、甚至不需要 Wi-Fi——数据始终留在你的口袋里。

这正是 PhoneClaw 正在实现的事。

PhoneClaw 是一个开源的本地 AI Agent 框架，专为手机和端侧设备设计。它由独立开发者 kellyvv 创建，目标是将强大的 AI 推理能力直接运行在你的口袋里——不依赖云端、不上传隐私数据、完全本地化。

这个项目在 GitHub 上获得了 1200+ stars，吸引了 iOS 开发者和 AI 研究人员的关注。与大多数需要云端 API 的 AI 应用不同，PhoneClaw 从一开始就将"隐私优先"和"离线可用"作为核心设计约束，而非后期添加的功能。

二、技术架构：端侧 Agent 的工程挑战

2.1 模型层：多后端推理引擎

PhoneClaw 的模型层采用了多后端分层设计，这是它区别于其他移动端 AI 应用的关键：

LiteRT（Google）：作为主力推理后端，运行 Google Gemma 4 系列模型（E2B / E4B 量级）。Gemma 是 Google 开源的轻量级大语言模型，专为端侧场景优化。PhoneClaw 使用 Gemma 处理自然语言任务路由、Skill 匹配、工具参数提取、多轮对话和翻译等核心 Agent 逻辑。

MiniCPM-V 4.6：用于图片理解和相机实时理解场景。MiniCPM-V 是国产开源的多模态模型，在端侧设备上有着出色的视觉理解能力。PhoneClaw 通过它实现图片问答和相机模式交互。

远程推理（PhoneClawGateway）：如果你有 Mac，可以运行 PhoneClawGateway macOS 客户端，通过 Bonjour 局域网发现并配对，让 iPhone 借助 Mac 上的 Ollama、Codex CLI 或其他推理引擎处理更复杂的任务。

2.2 运行时架构：五大分流路径

PhoneClaw 的 Agent 引擎（AgentEngine.swift，约 22KB 代码）设计了一个多路分流的输入处理架构，这是项目核心的技术决策：

分流路径	触发条件	响应速度	是否调用 LLM
Light	简单问答、闲聊	<100ms	否
Preflight	高频操作（启动 App）	<100ms	否
VLM	图片输入	中等	是
Planner	多步骤任务规划	较慢	是
Agent	工具调用场景	较慢	是

这个设计的背后是一个深刻的技术洞察：端侧模型每次 LLM 调用延迟约 3-8 秒，如果把所有请求都套上统一的 ReAct 循环，即使纯聊天也会被 Skill 注入开销拖慢。Light 路径完全不注入任何 Skill 信息，节省宝贵的上下文窗口；Preflight 路径则绕过 LLM，直接执行固定操作。

架构决策记录（ADR）中明确指出，项目拒绝了"统一 ReAct 循环"方案，因为 2B 量级模型无法可靠地自主链式调用多个工具。取而代之的是"外置 CoT"策略：两步 LLM 调用（Selection → Planning），每次只让小模型做一件事。

2.3 Skill 系统：可扩展的能力插件

PhoneClaw 引入了一套文件驱动的 Skill 体系。每个 Skill 由一个 SKILL.md 定义，包含 YAML frontmatter（名称、描述、类型、允许的工具）和 Markdown 行为指令。

内置 Skills 覆盖：

• Calendar：查询日程、创建事件、分析空闲时间
• Reminders：创建和管理提醒事项
• Contacts：搜索联系人
• Health：读取健康数据（步数、心率、睡眠等），支持时间段汇总
• Clipboard：剪贴板读写
• Web Search：联网搜索（用户显式触发）
• Translate：文本翻译

Skill 按隐私边界分类为 device（读取本地 iOS 数据）、content（纯文本处理）和 network（联网访问）。每个工具型 Skill 显式声明 allowed-tools 白名单，模型只能使用当前 Skill 暴露的工具，防止越权访问。

2.4 LiveLand：灵动岛里的 AI

PhoneClaw 支持从 iOS 灵动岛（Dynamic Island）和锁屏/桌面小组件启动本地 AI 交互。AI 边听边理解、边执行边显示结果，真正做到"语音交互+实时反馈"。

任务执行过程有完整的状态反馈：接收指令 → 理解中 → 查询/执行 → 整理结果 → 完成。对于不明确的时间、标题、联系人或删除操作，系统会先询问确认，避免误操作。

2.5 运行时状态管理

PhoneClaw 近期完成了一次重大架构收敛（v1.3），将散落在多个文件中的隐式状态流转收敛为模块化架构：

• LiteRTBootstrap：负责 LiteRT 运行时的初始化，作为最高优先级硬约束
• RuntimeSessionState：区分"安装状态（per model）"和"运行时状态（per active session）"
• GenerationTransaction：管理流式输出的生命周期和安全取消
• ModelRuntimeCoordinator：统一的模型加载/切换/推理/卸载协调器
• PCLog：六个日志分类（Model/Turn/Perf/Warn/Event/Debug），Agent + LLM 层零裸 print

三、核心使用场景

3.1 日程管理

"今天下午有空吗？"——PhoneClaw 调用 Calendar Skill 查询今日和未来 7 天日程，结合空闲时间分析给出建议，并可以直接创建新事件。完全本地执行，日历数据不上传到任何服务器。

3.2 健康数据查询

"我这周跑了多少步？"——PhoneClaw 通过 HealthKit 读取步数、距离、活动能量、心率、睡眠等数据，支持按时间段汇总并生成趋势报告。所有健康数据留在设备本地。

3.3 图片理解

对着产品说明书拍张照，问"这个电器怎么操作？"——MiniCPM-V 4.6 在设备端完成图片理解，回答你的问题，无需联网。

3.4 自然语言提醒

"半小时后提醒我喝水"——PhoneClaw 理解时间语义，自动创建 Reminders。不需要记固定格式的命令，说人话就行。

3.5 Mac 远程推理

iPhone 上的本地模型处理不了的任务（比如复杂的代码分析），可以配对 Mac，使用 Mac 上的 Ollama 或 Codex CLI 进行远程推理。推理仍在本地 Mac 上完成，数据不离开局域网。

四、部署与上手门槛

PhoneClaw 是原生 iOS 应用，部署门槛较高：

必须条件：

• macOS Sonoma 14+ 的 Mac
• Xcode 15+
• Apple Developer 账号（免费即可）
• iPhone/iPad 真机（iOS/iPadOS 17+）
• 在 Apple Developer 网站注册设备

构建流程：克隆仓库 → 在 Xcode 中打开 → 选择真机 → Build & Run。首次构建需要手动配置 Signing & Capabilities。

尝鲜方案：不想自己构建的用户可以通过 TestFlight 加入测试：https://testflight.apple.com/join/YuUSwq78

Mac Gateway 客户端：可以从 GitHub Releases 下载 PhoneClawGateway-macOS-v0.1.1.zip，解压后直接运行，解压即用，无需安装。

五、技术局限与挑战

PhoneClaw 也面临端侧 AI 的共同挑战：

内存压力：iPhone 上模型权重、运行时缓冲区、Metal 内存、应用内存、操作系统和 KV 缓存争夺 RAM。项目文档明确指出"理论上下文窗口 ≠ 舒适的移动端上下文窗口"，因此主推短/中长度工作流，而非长上下文场景。

模型能力上限：2B 量级模型在 ReAct 循环中无法可靠地自主链式调用多个工具，因此 PhoneClaw 采用了五路分流的保守设计。

构建门槛：非 iOS 开发者体验成本高，需要 Mac + Xcode + 真机注册。

六、行业意义

PhoneClaw 代表了一个重要趋势：本地化 AI Agent 的工程可行性。它证明了在消费级手机上运行端侧 LLM + 工具调用 Agent 是真实可行的，而非停留在概念演示阶段。

项目的技术决策也值得关注：面对"用一个统一框架解决所有问题"的诱惑，PhoneClaw 选择了"按场景分流"的务实路线，这背后是对端侧模型能力边界的清醒认知。