【AI】Artemis-codex来给你的Agent配一台手机吧前言前面几篇文章主要在折腾 LangChain 和 LangGraph从最小 Agent、工具调用一直写到 RAG 和条件分支。这次给 Agent 加一个更直观的工具一台手机。电脑旁边有闲置安卓机的话接根 USB 线、打开调试就可以试着把手机上的操作交给它。查设置、搜索内容、探索一个 App 的页面或者复现一段操作流程都可以从一句自然语言开始。比如给它一句指令打开系统设置进入显示页面确认当前页面后返回设置首页。背后需要完成的事情其实不少拿到当前屏幕、找到入口、执行点击、判断有没有进入正确页面再决定下一步怎么走。遇到弹窗或者页面没加载完还得根据实际界面继续处理。这部分已经有现成的开源项目可以参考本文介绍的就是ARTEMIS。我基于 Google 的 ARTEMIS 做了一个 fork主要补了 Codex 客户端接入、视觉定位缓存以及跨平台和设备支持。最近又补上后台模型配置、页面预热、Monkey 探索和中英文界面。这篇先简单介绍原项目再结合后台界面和几个例子说说这些功能怎么用、背后怎么接。项目地址本文 forkHJunLong601/artemis-codex上游项目google/artemis单独抽出的 Codex 适配库HJunLong601/codex-client-provider本文更新于 2026-10-28对应本地最新提交a69c1d1。上游项目保留原作者署名和 Apache 2.0 许可证Flash、Pro、MCP 和原有移动端执行框架都是上游能力下面会单独说明 fork 增加了什么。一、ARTEMIS 是做什么的ARTEMIS 是一个移动端 Agent 框架可以根据自然语言任务操作 Android 真机或模拟器也提供 MCP 服务方便从支持 MCP 的开发工具里调用。从使用者的角度看可以在 Web 控制台提交任务、看设备投屏和执行记录也可以在 IDE 中让助手调用它完成页面探索、操作和诊断。它的一次交互大致是这样用户描述任务 ↓ 获取屏幕截图、UI 层级等信息 ↓ 模型判断下一步操作 ↓ ARTEMIS 执行点击、滑动、输入等动作 ↓ 重新观察页面继续执行或结束做过 Android 自动化的同学应该比较熟悉这里的难点有些控件可以通过 UI 树定位有些自绘界面拿不到完整节点还有些按钮明明点到了页面却没有按预期跳转。所以它除了执行动作还需要持续观察实际结果。页面信息能通过 UI 层级确定时优先使用元素信息遇到无法直接定位的内容再用视觉方式补上。Flash 和 Pro 怎么选上游提供了两种主要执行方式。模式执行特点比较适合的任务Flash观察当前屏幕直接决定并执行下一步打开应用、页面导航、简单操作Pro维护任务计划按需加入检查点、验证和报告多阶段探索、日志诊断、需要明确验收的任务Flash 的流程比较直接。Pro 会把任务拆成计划由 Operator 操作设备Checker 根据验证级别检查结果需要时再生成报告。这里不建议单纯按任务长短来选。一个步骤很多但路径明确的任务也可以用 Flash需要中途断言、诊断和书面报告时再考虑 Pro。二、Fork 改了哪些地方先放一张概览后面挑主要的展开。方向Fork 中的改动模型接入复用本机 Codex 客户端的 ChatGPT 登录态接入文本、图片、工具调用和结构化输出调用隔离模型负责返回决策ARTEMIS 执行设备工具临时推理会话禁用嵌套 MCP视觉缓存持久化控件位置支持整页匹配、局部校验、固定区域复用和批量学习缓存后台查看页面、控件、命中情况、耗时和失败原因支持单页清理页面预热与探索手动学习当前页或对指定 Android App 按时长和可选步数、Token 预算进行 Monkey 探索可视化模型配置在后台设置默认模型、角色覆盖、备用模型和推理参数动态读取本机 Codex 模型目录登录与界面语言后台提供 Codex 登录和独立推理验证入口支持记忆偏好的中英文切换运行优化图片压缩、Flash 短任务延迟摘要以及截图、历史加载相关优化安装与设备完善 Windows/macOS/Linux 安装诊断、真机优先选择和 AVD 发现复用iOS增加模拟器和真机驱动接入其中模拟器已完整验收真机自动点击仍待验收三、接入 Codex 客户端复用已有登录态1. 调用链怎么接这一部分是 fork 的主要改动之一。电脑上已经登录了 Codex希望 ARTEMIS 的模型调用能复用这个客户端不用再为核心流程单独配置一套 API Key。项目通过启动codex app-server子进程使用 JSONL/stdio 与客户端通信。调用过程大致如下ARTEMIS 的模型节点 ↓ CodexAppServerChatModel ↓ codex app-server ↓ initialize → thread/start → turn/start ↓ 返回文本、结构化结果或工具调用描述 ↓ 转换为 ARTEMIS 使用的 LangChain 消息这里没有去读取auth.json也没有复制客户端的 access token认证交给 Codex 客户端处理。无需额外 API Key 的前提是本机客户端已经登录且当前账号能够使用配置的模型。调用会消耗对应账号的 Codex 使用额度切换到其他 API Provider或者启用云 OCR仍然需要配置各自的 Key。具体接入说明见仓库的 Codex Provider 文档。2. 不能只把主模型换掉只替换主 Agent 的模型还不算接完。ARTEMIS 里除了 Planner、Operator、Checker还有步骤摘要、历史压缩、视觉定位、视频分析等调用。如果其中某条路径仍然写死了其他模型客户端就会出现主流程已经接入 Codex执行到一半却要求配置另一家 Key 的情况。因此这次也把相关辅助调用接到了 Provider 路由里。文本、截图和结构化输出共用适配通道各个角色可以继承默认模型也可以单独覆盖。配置统一放在config/artemis.jsonc。下面是当前分支的默认模型片段{ default: { provider: codex, model: gpt-6.1-sol, reasoning_effort: low, fallback: { provider: codex, model: gpt-6-luna, reasoning_effort: low } } }这里的模型名要以本机 Codex 客户端实际返回的目录为准不能只改一个名字就认为一定能调用。任务启动前会做轻量模型目录预检把不支持的模型尽量挡在设备操作之前。3. 模型调用与设备执行分开还有一个容易忽略的问题Codex 本身也能接工具而 ARTEMIS 已经有自己的工具执行流程。因此适配时ARTEMIS 会把工具描述交给模型再把返回结果转换成AIMessage.tool_calls由 ARTEMIS 执行。每次模型调用建立临时 thread使用只读 sandbox 和不请求审批的设置底层 App Server 进程则在对应事件循环中复用。临时推理会话中还禁用了继承来的 MCP 服务避免内层 Codex 再去启动另一套工具调用。这个覆盖只作用于当前推理会话不改用户原来的客户端配置。通用的客户端适配部分已经抽成 codex-client-providerARTEMIS 仓库保留角色路由、图片预处理、诊断和自身的集成逻辑。四、先看后台任务、模型和执行记录项目启动后默认打开本机http://localhost:8000。常用入口可以按下面几个页面来理解页面路径主要用途首页/查看环境与设备状态完成连接和登录引导工作区/workspace输入任务查看执行步骤、任务队列、历史记录和笔记页面缓存/cache查看控件缓存预热当前页创建探索学习任务模型配置/settings/models配置默认模型、角色覆盖、备用模型和凭证1. 工作区看它到底做了什么下面是仓库已有的工作区标注图方便对应各个区域。它是较早版本的界面说明图最新版本又增加了页面缓存、模型配置和语言入口。左侧展示执行过程可以看到调用了什么动作、点击或滑动的坐标以及耗时和 Token 用量。底部输入任务右侧查看任务队列、历史运行和笔记计划。需要回头排查时可以结合历史步骤和已有录屏回放看任务在哪个页面开始偏离预期。比如任务要求“进入电池页面”看到一次点击执行成功还不够还要接着看后续观察是否确认了电池页面。把这两步放在一起看更容易分清是定位错了还是页面跳转慢了。2. 模型配置常用设置放到界面上之前主要靠手改 JSONC现在后台可以直接编辑默认模型、备用模型以及 Planner、Operator、Explorer、Checker 等角色的覆盖配置。角色没有覆盖的字段会继承默认值清空覆盖字段并保存可以恢复继承。不过修改默认模型不会顺手清掉已有角色配置。如果希望所有角色统一使用一个模型需要检查各角色有没有单独设置。Codex 模型名称也支持从本机客户端动态读取后下拉选择目录读取失败时仍可手动输入已有但未在目录列出的配置也会保留。列表用于帮助选模型账号是否能实际推理需要另外验证。保存配置不会自动发起推理请求。可视化编辑使用的还是同一份有效 JSONC 配置只写入修改字段保留注释和其他设置。如果文件被另一个页面或手工编辑改过保存时会提示冲突保留当前草稿。保存后新任务读取新配置正在运行的任务继续使用启动时的配置外部 MCP 会话需要重启。模型配置页也提供 Codex 登录和推理验证入口。使用其他 Provider 时可以在凭证区域验证并保存对应 API Key页面只显示是否配置不回显原始 Key。详细说明见 后台可视化模型配置。3. 中英文即时切换顶部导航现在可以选择中文、English 或跟随系统。首次按浏览器首选语言选择手动选择后会在当前浏览器记住偏好切换不会清空未保存的编辑。任务描述、模型回答、日志和设备名称保留原文。这样查问题时原始输出还能直接对应代码和执行记录。五、视觉定位缓存同一个按钮不必每次重新找接通模型之后另一个很实际的问题是等待时间。手机自动化中会反复遇到相同页面。比如进入设置子页面后又返回首页或者列表内容更新了但底部导航栏一直没动。如果每次都把这些控件重新交给视觉模型定位会多出不少重复请求。因此增加了本地视觉位置缓存定位顺序是ADB / UI 树定位 ↓ 无法确定目标 本地视觉位置缓存 ↓ 未命中 OCR / 视觉模型定位 ↓ 保存符合条件的位置供后续复用能通过 UI 树完成的定位本来就不需要查询视觉缓存。缓存主要减少进入视觉路径后的重复识别。1. 缓存保存哪些内容每台设备默认保留 10,000 条位置记录使用 SQLite 持久化跨任务和进程重启保留。记录会区分设备、应用、Activity、屏幕尺寸、页面指纹、目标和定位策略。数据库保存位置元数据与指纹不保存截图或完整模型回复。这些记录用于复用控件位置。后续要不要点击、点完是否到达目标页面仍然由原来的执行和验证流程处理。2. 页面不能只按 Activity 区分Android 中一个 Activity 对应多个内部页面很常见尤其是 Flutter 或者其他单 Activity 应用。如果只看包名和 Activity列表页与详情页可能会混到一起如果要求每张截图完全一致状态栏时间、电量变化又会让缓存频繁失效。目前做了几层处理整页精确匹配通过主体界面像素和 UI 树判断页面是否一致。状态栏处理有明确系统边界证据时忽略状态栏变化边界不明确时回退到完整截图比较。局部校验整页变化后继续检查目标附近的图像、节点属性和布局证据。固定区域复用对符合条件的底部导航、顶部工具栏等区域单独校验减少区域外动态内容的影响。举个例子页面上的推荐列表刷新了但底部导航没有变化就可以在区域证据满足条件时复用导航位置。若出现弹窗、键盘遮挡或者目标移动、文字改变、控件被禁用则拒绝复用。这里花的工夫主要是判断旧位置还能不能用。命中率当然希望高一点但误点之后继续跑偏排查起来更麻烦。具体匹配条件和失效规则放在 视觉定位缓存文档。3. 一次定位顺带学习多个控件既然已经把页面发给模型就可以在同一次请求里顺带提取常用可见控件。目前最多额外学习 20 个控件包括名称、别名、边界和坐标。这样下一次要找同页的其他按钮也有机会直接命中缓存。多目标定位则只把未命中的部分交给模型。这会增加首次请求的输出内容首次响应耗时也可能增加所以是否开启可以配置{ agent: { visual_location_cache: { enabled: true, batch_prefetch: true, capacity_per_device: 10000 } } }4. 加一个能查问题的后台只在日志里打印“缓存命中”后面不太好维护。所以 Web 控制台增加了“页面缓存”入口路径是/cache。后台可以按设备、应用和 Activity 查询页面展开查看元素名称、坐标、边界、复用范围与最近使用情况也能看命中统计、定位耗时和失败案例并清理指定页面。后台还有一个“节省时间”估算按同设备、同应用的平均视觉定位耗时折算缓存命中的收益再扣除缓存查询开销。没有足够样本时显示“暂无估算”。图中的数值只用于展示界面。这个指标方便观察缓存是否起作用实际任务耗时还包含主 Agent 推理、设备动作和页面等待需要单独测量。5. 当前页预热与复访统计以前要等任务执行到某个页面、触发视觉定位之后才会学习。现在可以在/cache点击“选择设备并预热”明确选择一台空闲 Android 设备确认发送当前截图后直接学习这一页最多 20 个常用控件。这个入口只处理当前页面不会替你打开 App、点击或翻页。先把手机停在要学习的页面保持画面稳定即可同页已经完整学习时会跳过重复模型调用。后台也把几个容易混淆的指标拆开了指标看什么本次学习成功页面或控件信息已经写入缓存已有缓存跳过当前页面库存完整省去重复学习预热后复访命中率成功学习后再次发生的目标视觉查询实际有多少命中学习完成只是写入后面真正查到位置才能算命中。“无可复用页面记录”的累计次数也不会因为后续学会了页面而减少它记录的是历史目标查询并不是还有多少页面没学。6. 一次定位对比仓库记录了一组已通过 ARTEMIS 核实的真机截图定位结果轮次定位耗时视觉模型调用缓存命中第一次15.8241 秒10第二次0.1272 秒01这个样本使用同一张截图回放计时范围是 Explorer 定位调用不包含截图采集和设备点击。它能说明该目标第二次定位复用了缓存还不能据此推算动态页面的命中率或者整条任务的提速倍数。原始记录见 缓存基准数据。六、让它边探索 App边学习页面逐页手动预热还是有点麻烦所以最新版本在页面缓存后台加入了独立的 Monkey 探索任务。先在手机上打开目标 App然后在/cache选择“配置新任务”指定设备、已安装 App 和测试时长确认截图发送及模型使用再开始探索并学习。这里采用的是根据当前页面证据选择导航操作的方式。它会检查实际访问到的稳定页面缺少缓存时学习已有完整、可复用库存时跳过重复学习。探索使用配置的 Operator页面学习使用视觉定位模型不会静默换成另一个 Provider。1. 时长必填步数和 Token 可选有效时长必须填写范围是 1–1440 分钟。步数和 Token 默认“不限制”也可以分别设置上限。第一次体验可以先设一个较短时长再加上步数和 Token 上限观察自己设备和模型的消耗情况。下面是仓库真实验收时保留的预算卡片图中 3 次操作已累计 170,832 Token包含探索与学习请求。手机上的几次点击背后可能已经有多次截图分析和学习调用因此后台同时展示有效时长、步数和已知用量。Token 限额采用请求前预留、返回后结算的方式在途请求仍可能超额不能当成账单硬上限。2. 暂停后可以继续累计预算保留暂停会停止派发新工作等待在途请求收敛后释放设备继续时重新观察之前的时长、步数和用量不会清零。停止则结束任务保留报告与缓存。关闭网页不会停止后台任务。需要结束时要在任务里点停止后台退出后也不会自动恢复长时间探索。这个模式开放的动作主要是有证据的导航点击、受限滑动和返回。遇到登录、权限、支付等敏感窗口离开目标 App或者无法确认操作语义时会跳过或暂停。自由文本、发送、分享、删除和购买等操作不进入这个探索入口。3. 已验证到哪里仓库使用无权限、无网络的测试 App 做过真机验收记录包括有限预算任务执行了 3 次操作取得 170,832 Token 的已知用量。学习了 4 个稳定页面状态、37 个位置其中包含测试布局调整前后的不同指纹。对当前页 3 个实际目标查询得到 3/3 命中。验证了请求中暂停、同任务继续、停止和预算结束测试 App 的危险操作计数保持为 0。这些是特定测试 App 的验收结果。业务 App 的动态内容、登录态和长时间探索还需要分别验证也不能把任务结束理解为已经覆盖整个 App。功能说明和完整记录分别放在 探索与页面学习文档 和 真机验收记录。七、模型接通之后还要看时间花在哪里视觉定位只是任务中的一部分。主 Agent 的每轮决策、后台摘要、图片输入和历史加载同样会影响等待时间。图片输入压缩目前模型图片输入默认等比缩放到短边不超过 720、长边不超过 1600 像素再编码为质量 70 的 WebP字节预算为 768 KiB超过预算会继续缩小。例如1080 × 2400的竖屏截图会变为720 × 1600。这里只处理发送给模型的图片原始截图和设备坐标尺寸保持不变。涉及小字、密集控件时仍然要结合实际页面检查识别效果不能只看图片缩小了多少。短任务延迟摘要Flash 执行时会生成步骤摘要供后续历史压缩使用。长任务需要这部分信息但只有一两次导航的短任务可能还没用到摘要就结束了。因此加入了延迟策略步骤较少时先保留原图和动作暂缓生成视觉摘要达到门槛或者出现历史需求、上下文压力、动作失败等情况再提前恢复或补齐摘要。仓库里“显示 → 返回”的一组记录中旧 Flash 样本是 143.6 秒、5 次模型调用后续样本是 63.4 秒、3 次模型调用后者没有触发视觉摘要调用。能直接确认的是少了两次摘要调用。两次任务的页面位置、输入和服务延迟并不完全相同因此不能把全部耗时差都归给这项优化。详细条件见 模型调用与真机回归耗时。这部分还补了调用耗时、输入输出 token 和服务端返回的缓存读取统计。后面再调整模型、推理强度或者历史策略时至少能先看到实际调用情况。八、安装、模拟器与 iOS 支持1. 跨平台安装和客户端发现安装部分完善了 Windows、macOS 和 Linux 的依赖检测与诊断也统一了登录检查、模型预检和实际推理的 Codex 路径选择规则。自动发现时优先找桌面客户端内置的 Codex再回退到 PATH 中的 CLI显式配置路径仍然优先。Windows 还处理了带版本号的安装目录以及 MCP 启动环境缺少LOCALAPPDATA的情况。这些改动比较零碎但能减少“终端里可以用换到 MCP 环境却找不到客户端”的问题。2. Android 真机优先模拟器复用已有实例设备部分完善了真机优先选择、SDK/AVD 路径发现、运行实例识别和发现结果缓存。自动 Android 选择优先使用空闲真机再考虑空闲模拟器。多设备场景建议明确指定序列号避免任务跑到另一台设备上。模拟器则尽量复用已经运行的同名 AVD。只有一个已安装 AVD 时可以自动确定存在多个候选时需要选择不能假定设备一定叫emulator-5554。3. iOS 的当前进度Fork 也增加了 iOS 接入但需要分开看模拟器和真机。目标接入方式当前进度iOS 模拟器Appium / XCUITest已通过 ARTEMIS 完整验收iPhone 真机默认路线Device Hub CoreDevice 本地 Swift 桥接已有驱动和编译检查自动点击仍待真机验收iPhone 真机备选路线Appium / XCUITest / WDA需要签名环境现有记录中因缺少有效签名身份未跑通Device Hub 路线通过可见的设备画面校准并执行手势不需要安装 WDA但依赖 macOS 窗口和权限。目前不提供 iOS 控件层级也不支持文本输入及部分系统动作。因此现阶段要体验 iOS可以先从模拟器开始。真机部分的前置条件和已知限制见 README 的 iOS 说明。九、快速运行先准备一台开启 USB 调试并授权的 Android 手机或者一个可用的 Android 模拟器。Codex 客户端需要提前登录。Windows PowerShellgit clone https://github.com/HJunLong601/artemis-codex.git cd artemis-codex.\start.batmacOS / Linuxgitclone https://github.com/HJunLong601/artemis-codex.gitcdartemis-codex ./start.sh启动脚本会检测环境并引导补齐依赖。默认 Web 控制台地址为http://localhost:8000可以先在那里检查设备和任务状态。也可以从命令行开始codex login status adb devices-luv run artemis doctor确认环境后先跑一个简单任务uv run artemis run打开系统设置找到电池选项并告诉我当前电量--profileflash如果要从 IDE 调用可以通过项目命令安装 MCP 配置与测试规则再重新加载对应客户端uv run artemis mcp--installcodex后台保存模型配置后新任务直接读取手工修改模型或缓存配置后按对应文档重启 ARTEMIS/MCP。外部 MCP 客户端会话也需要重新加载。十、几个可以直接试的例子下面这些是任务提示词示例需要在自己的设备和应用上执行确认。前面的缓存与探索数据来自仓库已有验收记录不代表下面每个例子都已跑过。1. 查手机设置从简单、容易核对结果的任务开始比较方便判断设备连接和模型调用有没有跑通。可以在工作区输入打开系统设置进入电池页面读取当前电量和充电状态。说明你实际看到了哪些信息停留在电池页面。也可以直接运行uv run artemis run打开系统设置进入电池页面读取当前电量和充电状态停留在电池页面--profileflash2. 搜索 App 里的内容打开小红书搜索“秋日穿搭”。查看搜索结果前几条的标题或可见说明整理它们提到的搭配方向停留在结果页。不要点赞、收藏、关注、评论或发布。这类任务可以体验 App 内搜索和结果读取。返回内容应该来自屏幕实际可见信息页面没显示完整的部分就让它说明缺失。仓库已有一次相近任务的 Pro 真机验证记录完成了打开小红书、搜索及结果页确认这里的“整理搭配方向”是进一步使用示例需要另行确认效果。3. 复现页面跳转问题使用 Pro 模式探索当前测试 App。从首页进入帮助页确认标题和主要内容再返回首页。分别记录进入前、进入后和返回后的页面证据遇到空白页、崩溃弹窗或跳转不符就停止保留步骤和截图输出复现路径。开发时拿到一个“点进去白屏了”的反馈可以先让它跑一遍拿到具体停在哪个页面、做过哪些动作再结合日志排查。4. 给常用页面提前学习这个例子从后台操作即可在手机上打开目标 App停在首页。进入“页面缓存”选择设备并预热当前页。确认学习结果再创建一个明确时长和预算的探索任务。在任务报告里查看访问页面、学习成功和已有缓存跳过情况。后续普通任务再次查询这些目标时再看真实复访命中情况。先用测试 App 或熟悉的简单页面比较方便观察。预热负责学习当前页探索负责按规则访问页面两者在后台是不同入口。5. 从自己的 Agent 调用如果已经有一个支持 MCP 的 Agent可以让它通过 ARTEMIS 先观察设备再提交任务、查询状态和读取结果。大致分工是你自己的 Agent理解需求决定何时使用手机 ↓ MCP ARTEMIS观察页面执行手机操作返回状态与结果 ↓ 你自己的 Agent结合结果继续处理用户任务比如给外层助手一句话先确认连接的是哪台手机再通过 ARTEMIS 打开系统设置读取设备型号和系统版本整理成一条测试环境记录。页面上没找到的信息请标明未确认。多设备时先明确目标序列号。外层 Agent 负责组织任务手机上的具体操作交给 ARTEMIS如果后面要生成固定回归测试再把探索确认的交互路径和等待条件写进脚本。十一、后续怎么用对移动端开发来说我比较看重它在页面探索和问题复现上的用途。拿到一个操作描述后可以先让 ARTEMIS 在设备上确认页面和跳转再结合截图、日志和执行记录继续定位。已经明确的固定回归路径则可以进一步固化成脚本。仓库里的设置页回归记录也体现了这一点固定脚本不需要每一步都重新调用模型做决策在路径稳定时能省下大量推理等待。这个 fork 接下来还需要继续补真实使用中的验证尤其是动态页面缓存和 iPhone 真机自动操作。感兴趣的同学可以直接看代码跑一下自己的应用遇到具体页面的问题也方便带着执行记录讨论。项目地址HJunLong601/artemis-codex 
长河君 · 2026/10/29 2:03:36 · 阅读 1.2k 【AI】Artemis-codex：来给你的Agent配一台手机吧
【AI】Artemis-codex来给你的Agent配一台手机吧前言前面几篇文章主要在折腾 LangChain 和 LangGraph从最小 Agent、工具调用一直写到 RAG 和条件分支。这次给 Agent 加一个更直观的工具一台手机。电脑旁边有闲置安卓机的话接根 USB 线、打开调试就可以试着把手机上的操作交给它。查设置、搜索内容、探索一个 App 的页面或者复现一段操作流程都可以从一句自然语言开始。比如给它一句指令打开系统设置进入显示页面确认当前页面后返回设置首页。背后需要完成的事情其实不少拿到当前屏幕、找到入口、执行点击、判断有没有进入正确页面再决定下一步怎么走。遇到弹窗或者页面没加载完还得根据实际界面继续处理。这部分已经有现成的开源项目可以参考本文介绍的就是ARTEMIS。我基于 Google 的 ARTEMIS 做了一个 fork主要补了 Codex 客户端接入、视觉定位缓存以及跨平台和设备支持。最近又补上后台模型配置、页面预热、Monkey 探索和中英文界面。这篇先简单介绍原项目再结合后台界面和几个例子说说这些功能怎么用、背后怎么接。项目地址本文 forkHJunLong601/artemis-codex上游项目google/artemis单独抽出的 Codex 适配库HJunLong601/codex-client-provider本文更新于 2026-10-28对应本地最新提交a69c1d1。上游项目保留原作者署名和 Apache 2.0 许可证Flash、Pro、MCP 和原有移动端执行框架都是上游能力下面会单独说明 fork 增加了什么。一、ARTEMIS 是做什么的ARTEMIS 是一个移动端 Agent 框架可以根据自然语言任务操作 Android 真机或模拟器也提供 MCP 服务方便从支持 MCP 的开发工具里调用。从使用者的角度看可以在 Web 控制台提交任务、看设备投屏和执行记录也可以在 IDE 中让助手调用它完成页面探索、操作和诊断。它的一次交互大致是这样用户描述任务 ↓ 获取屏幕截图、UI 层级等信息 ↓ 模型判断下一步操作 ↓ ARTEMIS 执行点击、滑动、输入等动作 ↓ 重新观察页面继续执行或结束做过 Android 自动化的同学应该比较熟悉这里的难点有些控件可以通过 UI 树定位有些自绘界面拿不到完整节点还有些按钮明明点到了页面却没有按预期跳转。所以它除了执行动作还需要持续观察实际结果。页面信息能通过 UI 层级确定时优先使用元素信息遇到无法直接定位的内容再用视觉方式补上。Flash 和 Pro 怎么选上游提供了两种主要执行方式。模式执行特点比较适合的任务Flash观察当前屏幕直接决定并执行下一步打开应用、页面导航、简单操作Pro维护任务计划按需加入检查点、验证和报告多阶段探索、日志诊断、需要明确验收的任务Flash 的流程比较直接。Pro 会把任务拆成计划由 Operator 操作设备Checker 根据验证级别检查结果需要时再生成报告。这里不建议单纯按任务长短来选。一个步骤很多但路径明确的任务也可以用 Flash需要中途断言、诊断和书面报告时再考虑 Pro。二、Fork 改了哪些地方先放一张概览后面挑主要的展开。方向Fork 中的改动模型接入复用本机 Codex 客户端的 ChatGPT 登录态接入文本、图片、工具调用和结构化输出调用隔离模型负责返回决策ARTEMIS 执行设备工具临时推理会话禁用嵌套 MCP视觉缓存持久化控件位置支持整页匹配、局部校验、固定区域复用和批量学习缓存后台查看页面、控件、命中情况、耗时和失败原因支持单页清理页面预热与探索手动学习当前页或对指定 Android App 按时长和可选步数、Token 预算进行 Monkey 探索可视化模型配置在后台设置默认模型、角色覆盖、备用模型和推理参数动态读取本机 Codex 模型目录登录与界面语言后台提供 Codex 登录和独立推理验证入口支持记忆偏好的中英文切换运行优化图片压缩、Flash 短任务延迟摘要以及截图、历史加载相关优化安装与设备完善 Windows/macOS/Linux 安装诊断、真机优先选择和 AVD 发现复用iOS增加模拟器和真机驱动接入其中模拟器已完整验收真机自动点击仍待验收三、接入 Codex 客户端复用已有登录态1. 调用链怎么接这一部分是 fork 的主要改动之一。电脑上已经登录了 Codex希望 ARTEMIS 的模型调用能复用这个客户端不用再为核心流程单独配置一套 API Key。项目通过启动codex app-server子进程使用 JSONL/stdio 与客户端通信。调用过程大致如下ARTEMIS 的模型节点 ↓ CodexAppServerChatModel ↓ codex app-server ↓ initialize → thread/start → turn/start ↓ 返回文本、结构化结果或工具调用描述 ↓ 转换为 ARTEMIS 使用的 LangChain 消息这里没有去读取auth.json也没有复制客户端的 access token认证交给 Codex 客户端处理。无需额外 API Key 的前提是本机客户端已经登录且当前账号能够使用配置的模型。调用会消耗对应账号的 Codex 使用额度切换到其他 API Provider或者启用云 OCR仍然需要配置各自的 Key。具体接入说明见仓库的 Codex Provider 文档。2. 不能只把主模型换掉只替换主 Agent 的模型还不算接完。ARTEMIS 里除了 Planner、Operator、Checker还有步骤摘要、历史压缩、视觉定位、视频分析等调用。如果其中某条路径仍然写死了其他模型客户端就会出现主流程已经接入 Codex执行到一半却要求配置另一家 Key 的情况。因此这次也把相关辅助调用接到了 Provider 路由里。文本、截图和结构化输出共用适配通道各个角色可以继承默认模型也可以单独覆盖。配置统一放在config/artemis.jsonc。下面是当前分支的默认模型片段{ default: { provider: codex, model: gpt-6.1-sol, reasoning_effort: low, fallback: { provider: codex, model: gpt-6-luna, reasoning_effort: low } } }这里的模型名要以本机 Codex 客户端实际返回的目录为准不能只改一个名字就认为一定能调用。任务启动前会做轻量模型目录预检把不支持的模型尽量挡在设备操作之前。3. 模型调用与设备执行分开还有一个容易忽略的问题Codex 本身也能接工具而 ARTEMIS 已经有自己的工具执行流程。因此适配时ARTEMIS 会把工具描述交给模型再把返回结果转换成AIMessage.tool_calls由 ARTEMIS 执行。每次模型调用建立临时 thread使用只读 sandbox 和不请求审批的设置底层 App Server 进程则在对应事件循环中复用。临时推理会话中还禁用了继承来的 MCP 服务避免内层 Codex 再去启动另一套工具调用。这个覆盖只作用于当前推理会话不改用户原来的客户端配置。通用的客户端适配部分已经抽成 codex-client-providerARTEMIS 仓库保留角色路由、图片预处理、诊断和自身的集成逻辑。四、先看后台任务、模型和执行记录项目启动后默认打开本机http://localhost:8000。常用入口可以按下面几个页面来理解页面路径主要用途首页/查看环境与设备状态完成连接和登录引导工作区/workspace输入任务查看执行步骤、任务队列、历史记录和笔记页面缓存/cache查看控件缓存预热当前页创建探索学习任务模型配置/settings/models配置默认模型、角色覆盖、备用模型和凭证1. 工作区看它到底做了什么下面是仓库已有的工作区标注图方便对应各个区域。它是较早版本的界面说明图最新版本又增加了页面缓存、模型配置和语言入口。左侧展示执行过程可以看到调用了什么动作、点击或滑动的坐标以及耗时和 Token 用量。底部输入任务右侧查看任务队列、历史运行和笔记计划。需要回头排查时可以结合历史步骤和已有录屏回放看任务在哪个页面开始偏离预期。比如任务要求“进入电池页面”看到一次点击执行成功还不够还要接着看后续观察是否确认了电池页面。把这两步放在一起看更容易分清是定位错了还是页面跳转慢了。2. 模型配置常用设置放到界面上之前主要靠手改 JSONC现在后台可以直接编辑默认模型、备用模型以及 Planner、Operator、Explorer、Checker 等角色的覆盖配置。角色没有覆盖的字段会继承默认值清空覆盖字段并保存可以恢复继承。不过修改默认模型不会顺手清掉已有角色配置。如果希望所有角色统一使用一个模型需要检查各角色有没有单独设置。Codex 模型名称也支持从本机客户端动态读取后下拉选择目录读取失败时仍可手动输入已有但未在目录列出的配置也会保留。列表用于帮助选模型账号是否能实际推理需要另外验证。保存配置不会自动发起推理请求。可视化编辑使用的还是同一份有效 JSONC 配置只写入修改字段保留注释和其他设置。如果文件被另一个页面或手工编辑改过保存时会提示冲突保留当前草稿。保存后新任务读取新配置正在运行的任务继续使用启动时的配置外部 MCP 会话需要重启。模型配置页也提供 Codex 登录和推理验证入口。使用其他 Provider 时可以在凭证区域验证并保存对应 API Key页面只显示是否配置不回显原始 Key。详细说明见 后台可视化模型配置。3. 中英文即时切换顶部导航现在可以选择中文、English 或跟随系统。首次按浏览器首选语言选择手动选择后会在当前浏览器记住偏好切换不会清空未保存的编辑。任务描述、模型回答、日志和设备名称保留原文。这样查问题时原始输出还能直接对应代码和执行记录。五、视觉定位缓存同一个按钮不必每次重新找接通模型之后另一个很实际的问题是等待时间。手机自动化中会反复遇到相同页面。比如进入设置子页面后又返回首页或者列表内容更新了但底部导航栏一直没动。如果每次都把这些控件重新交给视觉模型定位会多出不少重复请求。因此增加了本地视觉位置缓存定位顺序是ADB / UI 树定位 ↓ 无法确定目标 本地视觉位置缓存 ↓ 未命中 OCR / 视觉模型定位 ↓ 保存符合条件的位置供后续复用能通过 UI 树完成的定位本来就不需要查询视觉缓存。缓存主要减少进入视觉路径后的重复识别。1. 缓存保存哪些内容每台设备默认保留 10,000 条位置记录使用 SQLite 持久化跨任务和进程重启保留。记录会区分设备、应用、Activity、屏幕尺寸、页面指纹、目标和定位策略。数据库保存位置元数据与指纹不保存截图或完整模型回复。这些记录用于复用控件位置。后续要不要点击、点完是否到达目标页面仍然由原来的执行和验证流程处理。2. 页面不能只按 Activity 区分Android 中一个 Activity 对应多个内部页面很常见尤其是 Flutter 或者其他单 Activity 应用。如果只看包名和 Activity列表页与详情页可能会混到一起如果要求每张截图完全一致状态栏时间、电量变化又会让缓存频繁失效。目前做了几层处理整页精确匹配通过主体界面像素和 UI 树判断页面是否一致。状态栏处理有明确系统边界证据时忽略状态栏变化边界不明确时回退到完整截图比较。局部校验整页变化后继续检查目标附近的图像、节点属性和布局证据。固定区域复用对符合条件的底部导航、顶部工具栏等区域单独校验减少区域外动态内容的影响。举个例子页面上的推荐列表刷新了但底部导航没有变化就可以在区域证据满足条件时复用导航位置。若出现弹窗、键盘遮挡或者目标移动、文字改变、控件被禁用则拒绝复用。这里花的工夫主要是判断旧位置还能不能用。命中率当然希望高一点但误点之后继续跑偏排查起来更麻烦。具体匹配条件和失效规则放在 视觉定位缓存文档。3. 一次定位顺带学习多个控件既然已经把页面发给模型就可以在同一次请求里顺带提取常用可见控件。目前最多额外学习 20 个控件包括名称、别名、边界和坐标。这样下一次要找同页的其他按钮也有机会直接命中缓存。多目标定位则只把未命中的部分交给模型。这会增加首次请求的输出内容首次响应耗时也可能增加所以是否开启可以配置{ agent: { visual_location_cache: { enabled: true, batch_prefetch: true, capacity_per_device: 10000 } } }4. 加一个能查问题的后台只在日志里打印“缓存命中”后面不太好维护。所以 Web 控制台增加了“页面缓存”入口路径是/cache。后台可以按设备、应用和 Activity 查询页面展开查看元素名称、坐标、边界、复用范围与最近使用情况也能看命中统计、定位耗时和失败案例并清理指定页面。后台还有一个“节省时间”估算按同设备、同应用的平均视觉定位耗时折算缓存命中的收益再扣除缓存查询开销。没有足够样本时显示“暂无估算”。图中的数值只用于展示界面。这个指标方便观察缓存是否起作用实际任务耗时还包含主 Agent 推理、设备动作和页面等待需要单独测量。5. 当前页预热与复访统计以前要等任务执行到某个页面、触发视觉定位之后才会学习。现在可以在/cache点击“选择设备并预热”明确选择一台空闲 Android 设备确认发送当前截图后直接学习这一页最多 20 个常用控件。这个入口只处理当前页面不会替你打开 App、点击或翻页。先把手机停在要学习的页面保持画面稳定即可同页已经完整学习时会跳过重复模型调用。后台也把几个容易混淆的指标拆开了指标看什么本次学习成功页面或控件信息已经写入缓存已有缓存跳过当前页面库存完整省去重复学习预热后复访命中率成功学习后再次发生的目标视觉查询实际有多少命中学习完成只是写入后面真正查到位置才能算命中。“无可复用页面记录”的累计次数也不会因为后续学会了页面而减少它记录的是历史目标查询并不是还有多少页面没学。6. 一次定位对比仓库记录了一组已通过 ARTEMIS 核实的真机截图定位结果轮次定位耗时视觉模型调用缓存命中第一次15.8241 秒10第二次0.1272 秒01这个样本使用同一张截图回放计时范围是 Explorer 定位调用不包含截图采集和设备点击。它能说明该目标第二次定位复用了缓存还不能据此推算动态页面的命中率或者整条任务的提速倍数。原始记录见 缓存基准数据。六、让它边探索 App边学习页面逐页手动预热还是有点麻烦所以最新版本在页面缓存后台加入了独立的 Monkey 探索任务。先在手机上打开目标 App然后在/cache选择“配置新任务”指定设备、已安装 App 和测试时长确认截图发送及模型使用再开始探索并学习。这里采用的是根据当前页面证据选择导航操作的方式。它会检查实际访问到的稳定页面缺少缓存时学习已有完整、可复用库存时跳过重复学习。探索使用配置的 Operator页面学习使用视觉定位模型不会静默换成另一个 Provider。1. 时长必填步数和 Token 可选有效时长必须填写范围是 1–1440 分钟。步数和 Token 默认“不限制”也可以分别设置上限。第一次体验可以先设一个较短时长再加上步数和 Token 上限观察自己设备和模型的消耗情况。下面是仓库真实验收时保留的预算卡片图中 3 次操作已累计 170,832 Token包含探索与学习请求。手机上的几次点击背后可能已经有多次截图分析和学习调用因此后台同时展示有效时长、步数和已知用量。Token 限额采用请求前预留、返回后结算的方式在途请求仍可能超额不能当成账单硬上限。2. 暂停后可以继续累计预算保留暂停会停止派发新工作等待在途请求收敛后释放设备继续时重新观察之前的时长、步数和用量不会清零。停止则结束任务保留报告与缓存。关闭网页不会停止后台任务。需要结束时要在任务里点停止后台退出后也不会自动恢复长时间探索。这个模式开放的动作主要是有证据的导航点击、受限滑动和返回。遇到登录、权限、支付等敏感窗口离开目标 App或者无法确认操作语义时会跳过或暂停。自由文本、发送、分享、删除和购买等操作不进入这个探索入口。3. 已验证到哪里仓库使用无权限、无网络的测试 App 做过真机验收记录包括有限预算任务执行了 3 次操作取得 170,832 Token 的已知用量。学习了 4 个稳定页面状态、37 个位置其中包含测试布局调整前后的不同指纹。对当前页 3 个实际目标查询得到 3/3 命中。验证了请求中暂停、同任务继续、停止和预算结束测试 App 的危险操作计数保持为 0。这些是特定测试 App 的验收结果。业务 App 的动态内容、登录态和长时间探索还需要分别验证也不能把任务结束理解为已经覆盖整个 App。功能说明和完整记录分别放在 探索与页面学习文档 和 真机验收记录。七、模型接通之后还要看时间花在哪里视觉定位只是任务中的一部分。主 Agent 的每轮决策、后台摘要、图片输入和历史加载同样会影响等待时间。图片输入压缩目前模型图片输入默认等比缩放到短边不超过 720、长边不超过 1600 像素再编码为质量 70 的 WebP字节预算为 768 KiB超过预算会继续缩小。例如1080 × 2400的竖屏截图会变为720 × 1600。这里只处理发送给模型的图片原始截图和设备坐标尺寸保持不变。涉及小字、密集控件时仍然要结合实际页面检查识别效果不能只看图片缩小了多少。短任务延迟摘要Flash 执行时会生成步骤摘要供后续历史压缩使用。长任务需要这部分信息但只有一两次导航的短任务可能还没用到摘要就结束了。因此加入了延迟策略步骤较少时先保留原图和动作暂缓生成视觉摘要达到门槛或者出现历史需求、上下文压力、动作失败等情况再提前恢复或补齐摘要。仓库里“显示 → 返回”的一组记录中旧 Flash 样本是 143.6 秒、5 次模型调用后续样本是 63.4 秒、3 次模型调用后者没有触发视觉摘要调用。能直接确认的是少了两次摘要调用。两次任务的页面位置、输入和服务延迟并不完全相同因此不能把全部耗时差都归给这项优化。详细条件见 模型调用与真机回归耗时。这部分还补了调用耗时、输入输出 token 和服务端返回的缓存读取统计。后面再调整模型、推理强度或者历史策略时至少能先看到实际调用情况。八、安装、模拟器与 iOS 支持1. 跨平台安装和客户端发现安装部分完善了 Windows、macOS 和 Linux 的依赖检测与诊断也统一了登录检查、模型预检和实际推理的 Codex 路径选择规则。自动发现时优先找桌面客户端内置的 Codex再回退到 PATH 中的 CLI显式配置路径仍然优先。Windows 还处理了带版本号的安装目录以及 MCP 启动环境缺少LOCALAPPDATA的情况。这些改动比较零碎但能减少“终端里可以用换到 MCP 环境却找不到客户端”的问题。2. Android 真机优先模拟器复用已有实例设备部分完善了真机优先选择、SDK/AVD 路径发现、运行实例识别和发现结果缓存。自动 Android 选择优先使用空闲真机再考虑空闲模拟器。多设备场景建议明确指定序列号避免任务跑到另一台设备上。模拟器则尽量复用已经运行的同名 AVD。只有一个已安装 AVD 时可以自动确定存在多个候选时需要选择不能假定设备一定叫emulator-5554。3. iOS 的当前进度Fork 也增加了 iOS 接入但需要分开看模拟器和真机。目标接入方式当前进度iOS 模拟器Appium / XCUITest已通过 ARTEMIS 完整验收iPhone 真机默认路线Device Hub CoreDevice 本地 Swift 桥接已有驱动和编译检查自动点击仍待真机验收iPhone 真机备选路线Appium / XCUITest / WDA需要签名环境现有记录中因缺少有效签名身份未跑通Device Hub 路线通过可见的设备画面校准并执行手势不需要安装 WDA但依赖 macOS 窗口和权限。目前不提供 iOS 控件层级也不支持文本输入及部分系统动作。因此现阶段要体验 iOS可以先从模拟器开始。真机部分的前置条件和已知限制见 README 的 iOS 说明。九、快速运行先准备一台开启 USB 调试并授权的 Android 手机或者一个可用的 Android 模拟器。Codex 客户端需要提前登录。Windows PowerShellgit clone https://github.com/HJunLong601/artemis-codex.git cd artemis-codex.\start.batmacOS / Linuxgitclone https://github.com/HJunLong601/artemis-codex.gitcdartemis-codex ./start.sh启动脚本会检测环境并引导补齐依赖。默认 Web 控制台地址为http://localhost:8000可以先在那里检查设备和任务状态。也可以从命令行开始codex login status adb devices-luv run artemis doctor确认环境后先跑一个简单任务uv run artemis run打开系统设置找到电池选项并告诉我当前电量--profileflash如果要从 IDE 调用可以通过项目命令安装 MCP 配置与测试规则再重新加载对应客户端uv run artemis mcp--installcodex后台保存模型配置后新任务直接读取手工修改模型或缓存配置后按对应文档重启 ARTEMIS/MCP。外部 MCP 客户端会话也需要重新加载。十、几个可以直接试的例子下面这些是任务提示词示例需要在自己的设备和应用上执行确认。前面的缓存与探索数据来自仓库已有验收记录不代表下面每个例子都已跑过。1. 查手机设置从简单、容易核对结果的任务开始比较方便判断设备连接和模型调用有没有跑通。可以在工作区输入打开系统设置进入电池页面读取当前电量和充电状态。说明你实际看到了哪些信息停留在电池页面。也可以直接运行uv run artemis run打开系统设置进入电池页面读取当前电量和充电状态停留在电池页面--profileflash2. 搜索 App 里的内容打开小红书搜索“秋日穿搭”。查看搜索结果前几条的标题或可见说明整理它们提到的搭配方向停留在结果页。不要点赞、收藏、关注、评论或发布。这类任务可以体验 App 内搜索和结果读取。返回内容应该来自屏幕实际可见信息页面没显示完整的部分就让它说明缺失。仓库已有一次相近任务的 Pro 真机验证记录完成了打开小红书、搜索及结果页确认这里的“整理搭配方向”是进一步使用示例需要另行确认效果。3. 复现页面跳转问题使用 Pro 模式探索当前测试 App。从首页进入帮助页确认标题和主要内容再返回首页。分别记录进入前、进入后和返回后的页面证据遇到空白页、崩溃弹窗或跳转不符就停止保留步骤和截图输出复现路径。开发时拿到一个“点进去白屏了”的反馈可以先让它跑一遍拿到具体停在哪个页面、做过哪些动作再结合日志排查。4. 给常用页面提前学习这个例子从后台操作即可在手机上打开目标 App停在首页。进入“页面缓存”选择设备并预热当前页。确认学习结果再创建一个明确时长和预算的探索任务。在任务报告里查看访问页面、学习成功和已有缓存跳过情况。后续普通任务再次查询这些目标时再看真实复访命中情况。先用测试 App 或熟悉的简单页面比较方便观察。预热负责学习当前页探索负责按规则访问页面两者在后台是不同入口。5. 从自己的 Agent 调用如果已经有一个支持 MCP 的 Agent可以让它通过 ARTEMIS 先观察设备再提交任务、查询状态和读取结果。大致分工是你自己的 Agent理解需求决定何时使用手机 ↓ MCP ARTEMIS观察页面执行手机操作返回状态与结果 ↓ 你自己的 Agent结合结果继续处理用户任务比如给外层助手一句话先确认连接的是哪台手机再通过 ARTEMIS 打开系统设置读取设备型号和系统版本整理成一条测试环境记录。页面上没找到的信息请标明未确认。多设备时先明确目标序列号。外层 Agent 负责组织任务手机上的具体操作交给 ARTEMIS如果后面要生成固定回归测试再把探索确认的交互路径和等待条件写进脚本。十一、后续怎么用对移动端开发来说我比较看重它在页面探索和问题复现上的用途。拿到一个操作描述后可以先让 ARTEMIS 在设备上确认页面和跳转再结合截图、日志和执行记录继续定位。已经明确的固定回归路径则可以进一步固化成脚本。仓库里的设置页回归记录也体现了这一点固定脚本不需要每一步都重新调用模型做决策在路径稳定时能省下大量推理等待。这个 fork 接下来还需要继续补真实使用中的验证尤其是动态页面缓存和 iPhone 真机自动操作。感兴趣的同学可以直接看代码跑一下自己的应用遇到具体页面的问题也方便带着执行记录讨论。项目地址HJunLong601/artemis-codex