PhoneAgent

PhoneAgent 是一个实验性的移动端自动化项目，包含两种操作模式：

1. 应用内 iPhone agent（SwiftUI 应用 + XCTest runner + OpenAI Responses API）
2. 外部网桥（External bridge），用于让 Codex/OpenClaw 控制 iOS/Android 设备

该网桥支持：

• iOS（针对模拟器或实体 iPhone 的 XCTest 托管操作）
• Android（针对模拟器或设备的 adb + UiAutomator + 输入/截屏操作）

演示

• 独立的 iOS 应用
• OpenClaw 控制 iPhone
• OpenClaw 控制 Android 手机
• Codex 控制 iPhone

本仓库包含内容

• iOS 应用 UI：API key 输入、提示词输入、麦克风支持、设置、常驻唤醒词模式
• iOS 测试托管的 RPC 服务器：端口 45678 上的换行符分隔 JSON-RPC
• Android RPC 服务器：由 adb 命令支持的本地 JSON-RPC 网桥
• 辅助脚本：
  • iOS 网桥启动器 + 实体设备 localhost 转发
  • Android 网桥启动器（带 adb 自动发现）
  • 适用于两个平台的通用 RPC CLI (rpc.py)

功能特性

共享 RPC 操作接口 (iOS + Android)

• get_tree
• get_screen_image
• get_context
• set_api_key
• open_app
• tap
• tap_element
• enter_text
• scroll
• swipe
• stop

仅限 iOS 的 RPC 方法

• submit_prompt

submit_prompt 是应用内 iPhone agent 循环的核心驱动力。

应用内 iPhone agent 特性

• OpenAI API key 存储在 Keychain 中
• 通过键盘或麦克风提交提示词
• 可选的常驻（Always-on）模式，支持自定义唤醒词
• 通知完成 + 快速回复循环

环境要求

macOS 主机

• Xcode（用于 iOS 应用/UITest 网桥）
• Python 3
• Android SDK 工具（adb，用于 Android 网桥）

设备

• iOS 模拟器或实体 iPhone（需配置开发者模式）
• Android 模拟器或实体 Android 设备（需开启 USB 调试或无线调试）

快速入门（应用内 iPhone Agent）

1. 在 Xcode 中打开 /Users/rounak/Developer/PhoneAgent-cli/PhoneAgent.xcodeproj。
2. 在 iPhone/模拟器上运行 PhoneAgent scheme。
3. 出现提示时输入 OpenAI API key。
4. 通过键盘或麦克风提交任务。

快速入门（AI Agents）

若要使用 Codex/OpenClaw，请参考技能文档：

• .agents/skills/phoneagent/

发送 RPC 调用

# iOS bundle identifier 示例
./.agents/skills/phoneagent/scripts/rpc.py open-app com.apple.Preferences

# Android 包名示例
./.agents/skills/phoneagent/scripts/rpc.py open-app com.android.settings

# 获取 UI 树
./.agents/skills/phoneagent/scripts/rpc.py get-tree

# 截图（将 PNG 写入 /tmp/phoneagent-artifacts）
./.agents/skills/phoneagent/scripts/rpc.py get-screen-image --print-metadata

如果需要非默认的终端设置，CLI 支持 --host 和 --port 参数。

RPC 注意事项

• 传输协议：换行符分隔的 JSON-RPC 对象
• 端点：默认为 127.0.0.1:45678
• open_app 请求参数为 bundle_identifier：
  • iOS：传入 bundle identifier（例如 com.apple.Preferences）
  • Android：传入包名（例如 com.android.settings）
• tap_element / enter_text 使用坐标矩形，格式为 {{x, y}, {w, h}}

常用应用标识符

iOS

• 设置：com.apple.Preferences
• 相机：com.apple.camera
• 照片：com.apple.mobileslideshow
• 信息：com.apple.MobileSMS
• 主屏幕：com.apple.springboard

Android 无线连接（无需 USB）

# 配对（在无线调试屏幕中操作）
adb pair 

# 连接（在无线调试屏幕中操作）
adb connect 

# 验证
adb devices -l

然后使用该网络序列号启动 Android 网桥：

./.agents/skills/phoneagent/scripts/start_android_rpc_bridge_local.sh --serial 

安全模型

• RPC 网桥面向本地回环地址 (127.0.0.1)
• iOS 实体设备工作流使用 localhost 转发
• Android 网桥仅通过选定的 adb 序列号执行
• 应用内的 API key 存储在 iOS Keychain 中

代码库指向

• iOS 应用入口：PhoneAgent/PhoneAgentApp.swift
• iOS 应用 UI/状态：PhoneAgent/ContentView.swift, PhoneAgent/PromptView.swift, PhoneAgent/SettingsView.swift
• iOS 网桥服务器：PhoneAgentUITests/SimulatorRPCServer.swift, PhoneAgentUITests/PhoneAgent.swift
• RPC CLI：.agents/skills/phoneagent/scripts/rpc.py
• iOS 网桥启动器：.agents/skills/phoneagent/scripts/start_rpc_bridge_local.sh
• Android 网桥启动器：.agents/skills/phoneagent/scripts/start_android_rpc_bridge_local.sh
• Android 网桥服务器：.agents/skills/phoneagent/scripts/android_rpc_bridge.py

已知限制

• Android 网桥尚未实现 submit_prompt agent 循环
• 在动画过程中，UI 树快照可能会有噪声或滞后
• 键盘/文本输入的可靠性因应用程序和平台而异
• 长时间运行的任务可能需要显式的轮询或重试机制

免责声明

• 实验性项目。