★ FEATURED ARTICLE 1. 手机远程操控 AI Agent 这件事到底解决了什么问题第一次看到“一个手机就能远程操控所有 AI Agent”这个说法我脑子里冒出来的第一个念头是这不就是把终端塞进手机里吗但真正动手折腾过 Claude Code、各种开源 Agent 框架之后我才意识到事情没那么简单。手机远程操控 AI Agent 的核心价值不是“用手机敲命令”而是把 Agent 从工位上解放出来让它变成一个随时在线、随时可指挥的“远程执行单元”。先说清楚这个项目大概是什么。它本质上是一套“控制端 执行端”的架构执行端跑在你家里或公司的电脑、服务器、甚至树莓派上负责真正运行 AI Agent比如 Claude Code、基于 Rust 写的 Agent、各种开源 Agent 框架控制端就是你手里的手机通过一个轻量的 Web 界面或者 App把指令发过去、把结果收回来。GitHub 上这类开源项目最近冒出来不少像 diplay、jizura 这类名字在热搜里反复出现说明大家对“手机管 Agent”这件事的需求是真实存在的。它能做什么简单说你在地铁上、在咖啡馆、在床上躺着都能给家里的 Agent 派活让它跑一段代码、整理一份文档、爬一批数据、生成一份报告。Agent 干完活结果推回手机你扫一眼就知道成没成。这解决的核心痛点是“Agent 必须有人盯着”——很多 Agent 任务跑起来要几分钟到几十分钟你不可能一直坐在电脑前等但你又怕它中途卡住、报错、或者跑偏。手机远程操控把“盯梢”这件事变成了“随时抽查”效率提升是实打实的。适合谁看三类人。第一类是把 Claude Code 当日常生产力工具的人你已经习惯了用 Agent 写代码、改 bug但被“必须坐在电脑前”绑住了第二类是折腾开源 Agent 的开发者你想给自己的 Agent 加一个远程控制层但不想从零造轮子第三类是对 AI Agent 感兴趣但还没入门的新手你想先看看“Agent 到底能干嘛”手机操控这种低门槛入口正好适合你。我自己的使用场景很典型白天在公司用 Claude Code 处理代码任务晚上回家不想开电脑但有些任务又必须跑。以前的做法是远程桌面体验极差手机屏幕小、操作别扭、还容易断。换成手机远程操控 Agent 之后我只需要在手机上发一句“把昨天那个脚本再跑一遍结果发我”剩下的交给执行端。这个体验差异用过就回不去了。提示手机远程操控 Agent 的前提是执行端必须保持在线。如果你用的是笔记本合盖休眠就会断连建议用一台常开的小主机或者云服务器做执行端。2. 整体架构怎么设计控制端、执行端、通信层三件套2.1 为什么是“控制端 执行端”而不是“全塞进手机”很多人第一反应是能不能直接在手机上跑 Agent技术上不是完全不行但体验会很差。AI Agent 尤其是 Claude Code 这类依赖完整的运行环境、文件系统、网络请求能力手机端要么跑不动要么跑起来各种权限限制。更关键的是Agent 的任务往往涉及大量文件读写和长时间运行手机不适合做这种重活。所以合理的架构一定是分离的执行端负责“干活”控制端负责“指挥”和“看结果”。这个思路和很多开源项目的设计是一致的比如热搜里提到的 diplay、jizura基本都是这个路子。执行端可以是一台 Ubuntu 服务器、一台 Mac mini、一台树莓派甚至是你主力电脑上开的一个常驻进程。控制端就是一个网页或者 App通过 WebSocket 或者 HTTP 长连接和执行端通信。这样设计的好处有三个。第一执行端算力不受限你想跑多大的模型、多重的任务都行第二控制端极轻量手机浏览器就能用不需要装一堆依赖第三两者解耦执行端挂了不影响控制端控制端换设备也不影响执行端。2.2 通信层选型WebSocket 还是轮询通信层是整个项目的命脉。我试过两种方案HTTP 轮询和 WebSocket。轮询的实现最简单控制端每隔几秒问一次“有结果了吗”执行端有结果就返回。但问题是延迟高、请求量大Agent 输出是流式的轮询根本追不上。WebSocket 是更合适的选择。它建立一条长连接执行端有输出就主动推给控制端延迟低、体验流畅。Claude Code 这类 Agent 的输出本身就是流式的用 WebSocket 能把“打字机效果”完整还原到手机上看起来就像 Agent 在你手机里跑一样。具体实现上执行端跑一个 WebSocket 服务控制端连上去之后双方约定一套简单的消息协议。比如{ type: command, payload: 帮我整理一下今天的日志 }执行端收到后把指令喂给 AgentAgent 的输出再通过{ type: output, payload: 正在处理日志文件... }推回控制端。这套协议不需要复杂够用就行。2.3 执行端怎么接 Agent进程调用还是 SDK 集成执行端接 Agent 有两种方式。一种是进程调用直接spawn一个 Claude Code 进程把指令通过 stdin 传进去stdout 读出来。这种方式最通用任何命令行 Agent 都能接。另一种是 SDK 集成如果 Agent 提供了编程接口直接调用更可控。我个人的选择是进程调用为主、SDK 为辅。原因是 Claude Code 这类工具本身就是命令行优先的进程调用最贴近它的原生用法不容易出幺蛾子。SDK 集成虽然优雅但版本一变接口就可能不兼容维护成本高。进程调用有个坑要注意Agent 的输出可能是带 ANSI 颜色码的直接推到手机端会显示一堆乱码。解决办法是在执行端做一层清洗把 ANSI 转义序列过滤掉或者转成 HTML 标签。这个细节看起来小但不处理的话手机端体验会很糟糕。注意执行端调用 Agent 进程时一定要设置超时和资源限制。Agent 跑飞了把服务器内存吃满的情况我遇到过不止一次加个timeout和内存上限能救命。3. 核心细节拆解从指令下发到结果回传的完整链路3.1 指令下发怎么把一句话变成 Agent 能懂的活手机端发出去的指令不能直接原样丢给 Agent。原因很简单Agent 需要上下文。比如你发“再跑一遍”Agent 根本不知道“再”指的是什么。所以执行端需要维护一个会话状态把历史指令和结果存起来每次新指令都带上必要的上下文。我的做法是在执行端维护一个轻量的会话管理器每个会话有一个 ID记录最近的 N 条指令和输出。手机端发指令时带上会话 ID执行端把上下文拼好再喂给 Agent。这样即使用户在手机上只发了半句话Agent 也能理解。指令格式上我建议用结构化的方式而不是纯文本。比如{ session_id: abc123, command: 重新运行昨天的数据清洗脚本, context: { last_task: data_clean.py, last_result: success } }这样执行端解析起来明确不容易出错。3.2 执行端任务调度单任务还是队列如果你只有一个 Agent单任务模式就够了来一个指令跑一个。但实际使用中你很可能同时派多个活这时候就需要队列。我试过最简单的做法执行端维护一个 FIFO 队列指令进来先排队Agent 空闲了就取下一个。队列的好处是避免并发冲突。Agent 任务往往涉及文件读写两个任务同时跑很容易互相干扰。队列虽然牺牲了一点并发性但稳定性提升明显。如果确实需要并发可以起多个 Agent 实例每个实例配一个队列但这就复杂了新手不建议一上来就搞。队列还有一个隐藏好处你可以看到“排队中”的状态。手机端显示“你的任务排在第 3 位”比干等着不知道发生了什么要好得多。3.3 结果回传流式输出怎么在手机上优雅展示Agent 的输出是流式的手机端展示要处理好几个问题。第一是滚动输出不断追加页面要自动滚到底部但用户手动往上翻的时候不能强制拉回来。第二是格式Agent 输出里可能有代码块、列表、表格手机端要能正确渲染。第三是长度一次输出可能几千字全塞进一个页面会卡需要做分页或者虚拟滚动。我的做法是手机端用 Markdown 渲染输出代码块单独处理长输出分块加载。具体来说执行端每收到一段输出就推给手机端手机端追加到当前消息里同时判断用户是否在底部在底部就自动滚动不在就不动。这个逻辑不复杂但体验差异很大。还有一个细节Agent 跑完任务后最好给一个明确的“完成”信号而不是让用户猜。执行端在 Agent 进程退出后推一条{type: done}的消息手机端收到后把状态从“运行中”改成“已完成”用户一眼就知道可以看结果了。3.4 断线重连手机网络不稳定怎么办手机网络切换WiFi 转 4G、进电梯、地铁隧道是常态WebSocket 断线几乎必然发生。如果不处理用户会看到“连接已断开”然后一脸懵。处理方案是执行端维护一个消息缓冲区控制端重连后先拉取断线期间的消息。具体实现上每条消息带一个递增的序号控制端重连时带上自己收到的最大序号执行端把之后的消息补发过去。这样即使断线几分钟重连后也能看到完整输出。这个机制我强烈建议加上因为手机场景下断线太频繁了没有重连补发的远程控制基本不可用。提示断线重连的缓冲区要有上限比如只保留最近 1000 条消息否则长时间断线会占满内存。4. 实操过程从零搭一套手机操控 Agent 的环境4.1 执行端环境准备Ubuntu 上的基础配置我以 Ubuntu 22.04 为例这是最常见的执行端环境。首先装好基础依赖sudo apt update sudo apt install -y python3 python3-pip nodejs npm git然后装 Claude Code。Claude Code 的安装方式最近变化比较快我建议直接看官方文档但核心步骤是npm install -g anthropic-ai/claude-code装完之后验证一下claude --version能输出版本号就说明装好了。接下来是 Agent 的运行目录我建议单独建一个工作区不要和系统目录混在一起mkdir -p ~/agent-workspace cd ~/agent-workspace这个目录就是 Agent 干活的地方所有文件读写都在这里方便管理也方便清理。4.2 控制服务搭建一个最小的 WebSocket 服务执行端需要一个 WebSocket 服务来接收手机指令。我用 Python 写一个最小实现依赖websockets库pip install websockets然后写服务端import asyncio import websockets import subprocess import json async def handle_command(websocket): async for message in websocket: data json.loads(message) cmd data.get(command, ) # 调用 Claude Code process await asyncio.create_subprocess_exec( claude, -p, cmd, stdoutasyncio.subprocess.PIPE, stderrasyncio.subprocess.PIPE, cwd/home/user/agent-workspace ) # 流式读取输出 async for line in process.stdout: await websocket.send(json.dumps({ type: output, payload: line.decode(utf-8, errorsignore) })) await process.wait() await websocket.send(json.dumps({type: done})) async def main(): async with websockets.serve(handle_command, 0.0.0.0, 8765): await asyncio.Future() asyncio.run(main())这段代码的核心逻辑是收到指令起一个 Claude Code 进程把输出流式推回去。cwd指定工作目录-p是 Claude Code 的 prompt 参数。跑起来python3 server.py服务就监听在 8765 端口了。4.3 手机端访问一个极简的 HTML 页面手机端不需要复杂的 App一个 HTML 页面就够。核心是 WebSocket 连接和消息展示!DOCTYPE html html head meta nameviewport contentwidthdevice-width, initial-scale1 titleAgent 控制台/title /head body div idoutput/div input idinput placeholder输入指令... button onclicksend()发送/button script const ws new WebSocket(ws://你的服务器IP:8765); const output document.getElementById(output); ws.onmessage (event) { const data JSON.parse(event.data); if (data.type output) { output.innerHTML data.payload.replace(/\n/g, br); window.scrollTo(0, document.body.scrollHeight); } else if (data.type done) { output.innerHTML brb[完成]/bbr; } }; function send() { const input document.getElementById(input); ws.send(JSON.stringify({command: input.value})); output.innerHTML brb input.value /bbr; input.value ; } /script /body /html把这个 HTML 放到执行端的某个目录用 Python 起一个静态服务python3 -m http.server 8080手机浏览器访问http://你的服务器IP:8080就能看到控制界面了。4.4 内网穿透与安全让手机在外网也能连上上面的方案只在同一局域网内可用。要在外网访问需要做内网穿透。常见方案有 frp、ngrok 这类工具配置思路是把执行端的 8765 和 8080 端口映射到公网。但这里有个安全问题必须重视一旦暴露到公网任何人都可能连上你的 Agent。所以至少要加一层认证。最简单的做法是在 WebSocket 握手时校验 tokenasync def handle_command(websocket, path): token websocket.request_headers.get(Authorization) if token ! 你的密钥: await websocket.close(1008, Unauthorized) return # ... 正常处理手机端连接时带上这个 token。虽然简单但能挡住绝大部分扫描。注意不要把 Agent 控制服务直接暴露在公网而不加认证。Agent 能执行任意命令一旦被滥用后果很严重。至少加 token有条件的话再加 IP 白名单。4.5 参数调优超时、并发、缓冲区怎么设几个关键参数我踩过坑这里直接给建议值参数建议值说明Agent 超时300 秒太短任务跑不完太长卡死占资源消息缓冲区1000 条断线重连补发用太多占内存WebSocket 心跳30 秒检测连接是否还活着并发任务数1新手先用单任务稳定后再考虑并发输出分块大小4KB太大手机端渲染卡太小请求频繁这些值不是绝对的但作为起点很稳。我一开始超时设了 60 秒结果稍微大点的任务就被砍了后来调到 300 秒才够用。5. 常见问题与排查技巧实录5.1 Agent 没反应从进程到网络逐层排查手机发了指令Agent 没反应这是最常见的问题。排查顺序应该是先看执行端进程有没有起来再看 WebSocket 有没有收到消息最后看 Agent 本身有没有输出。具体操作在执行端ps aux | grep claude看进程在不在。如果不在说明指令没传到执行端检查 WebSocket 连接。如果在但没输出可能是 Agent 卡住了看它的日志。我遇到过 Claude Code 因为网络问题卡在初始化阶段加个超时就能自动恢复。还有一个隐蔽问题工作目录权限。如果 Agent 没有工作目录的写权限它会静默失败。检查一下ls -la ~/agent-workspace确保当前用户有读写权限。5.2 输出乱码ANSI 转义序列的清洗Agent 输出里经常带颜色码比如\x1b[32m这种。手机端直接显示就是一堆乱码。解决办法是在执行端清洗import re ansi_escape re.compile(r\x1b\[[0-9;]*m) clean_output ansi_escape.sub(, line)这个正则能去掉大部分 ANSI 转义序列。如果还有残留可以再加一层过滤只保留可打印字符。5.3 连接频繁断开心跳和重连策略手机端 WebSocket 断线频繁通常是两个原因一是网络切换二是服务端没有心跳。心跳的做法是客户端每隔 30 秒发一个 ping服务端回 pong超过一定时间没收到就重连。重连策略我建议用指数退避第一次断线 1 秒后重连第二次 2 秒第三次 4 秒最多到 30 秒。这样既能快速恢复又不会在服务端挂掉时疯狂重试。5.4 常见问题速查表现象可能原因解决方法手机连不上防火墙/端口未开放检查ufw status开放对应端口指令发出无响应WebSocket 未连接手机端看连接状态重连Agent 输出为空工作目录权限问题chmod确保读写权限输出乱码ANSI 转义序列执行端正则清洗任务卡死Agent 超时未设加timeout参数断线后丢消息无缓冲区加消息序号和补发机制手机端卡顿输出太长分块加载虚拟滚动5.5 几个我踩过的坑第一个坑是路径问题。执行端用subprocess调 Agent 时工作目录默认是服务进程的目录不是你想的那个。一定要显式指定cwd否则 Agent 会在错误的地方读写文件。第二个坑是编码问题。Agent 输出可能是 UTF-8也可能是系统默认编码解码时用errorsignore能避免崩溃但会丢字符。更好的做法是统一用 UTF-8执行端设置PYTHONIOENCODINGutf-8。第三个坑是资源泄漏。Agent 进程如果没正常退出会一直占着内存。我加了一个定时清理超过一定时间还在跑的进程直接 kill。这个逻辑虽然粗暴但很有效。第四个坑是手机端输入法。手机输入中文时回车键行为可能和预期不一样导致指令提前发送。解决办法是在输入框上监听keydown只有ShiftEnter才换行单独Enter才发送。6. 进阶玩法让 Agent 主动汇报而不是等你问基础版是“你问它答”进阶版是“它主动汇报”。比如 Agent 跑完一个长任务主动推一条消息到手机“任务完成结果如下”。这个体验比你自己去查要好得多。实现方式是在执行端的任务完成回调里主动发一条 WebSocket 消息。如果手机不在线就存到离线消息队列下次上线补发。这个机制加上之后Agent 就从“工具”变成了“助手”。再进一步可以加定时任务。比如每天早上 9 点Agent 自动跑一遍数据汇总结果推到手机。你起床就能看到。这个用cron或者 Python 的schedule库都能实现。还有一个玩法是多 Agent 协同。执行端起多个 Agent 实例一个负责代码一个负责文档一个负责数据。手机端发指令时指定目标 Agent各干各的。这个复杂度高一些但思路是一样的执行端管调度控制端管指挥。我自己最常用的场景是睡前派活。躺床上用手机发一句“把今天的代码提交整理成日报”Agent 跑完推回来我看一眼就睡。第二天早上再派一个“跑一遍测试”结果到公司再看。这种碎片化利用时间的方式是手机远程操控 Agent 最大的价值。最后分享一个小技巧手机端加一个“常用指令”快捷按钮把高频指令存起来点一下就发。比每次打字快得多。我存了“跑测试”“整理日志”“生成日报”三个日常够用了。
阅读完成 · 觉得有帮助？
