Zedra 实战教程：用手机远程控制 AI 编码 Agent（Claude Code / Codex / OpenCode）
背景
AI 编码 Agent（Claude Code、Codex、OpenCode 等）已经成为了开发者日常工作中不可或缺的助手。但一个很现实的场景是：Agent 在跑任务，你人不在电脑前。
你可能正在通勤路上、参加站会、或者只是在另一个房间休息，但 AI Agent 任务需要你时不时查看进度、审核修改、甚至中断或调整任务方向。传统的方案是 SSH 登录回去，但手机上的终端体验太差，而且许多 Agent 的日志输出在 SSH 会话断开后就看不到了。
Zedra 正是为了解决这个问题而生——一款开源的移动端远程控制工具，让你通过手机 App 实时查看和控制 AI 编码 Agent 的运行状态。它由 Rust + GPUI（GPU 加速渲染）构建，基于 Iroh 的 P2P 隧道协议（QUIC/UDP），所有通信端到端加密（TLS 1.3），支持 Claude Code、Codex、OpenCode、Pi Agent，甚至可以与 Hermes Agent 配合使用。
Zedra 的 GitHub 仓库目前已有 107 颗星，MIT 许可证，由开发者 Tan Le 创建并维护，更新活跃。
安装与环境
Zedra 由两部分组成：桌面端守护进程（daemon）和移动端 App。桌面守护进程在你的开发机器上运行，手机 App 通过它连接你的工作空间。
安装桌面 CLI
macOS / Linux：
curl -fsSL zedra.dev/install.sh | sh
Windows（PowerShell）：
powershell -c "irm zedra.dev/install.ps1 | iex"
安装脚本会自动下载对应平台的最新二进制文件，放置在 ~/.local/bin/ 目录下。
配置 AI Agent 钩子
zedra setup zedra setup claude # Claude Code zedra setup codex # OpenAI Codex zedra setup opencode # OpenCode
zedra setup 命令会在 Agent 的配置目录中安装 Zedra 的钩子文件，负责处理连接和通知。
启动守护进程
在每个你想远程访问的项目目录中启动 daemon：
zedra start zedra start --detach
在后台模式下，二维码会写入 daemon 日志文件，你可以随时用 zedra qr --workdir <路径> 重新打印。
安装移动端 App
- iOS：App Store 搜索”Zedra”，或通过 TestFlight 加入测试
- Android：加入 Google Groups 参与内测
配对（QR 扫码）
- 在终端中启动
zedra start，终端会显示一个二维码 - 打开手机 Zedra App，点击 Scan QR
- 扫描二维码完成配对
配对是一次性的——每个工作空间扫描一次，后续重新连接不需要重新扫描。二维码携带的是机器的公钥和一次性密钥（非网络地址），即使 IP 地址变化，连接仍然保持。
实战场景 1：出门在外，用手机审核 Claude Code 的修改
这是 Zedra 最核心的用法——当你在路上时，Claude Code 正在运行代码修改，你需要看到它改了什么。
操作流程：
- 在项目目录中启动 daemon：
“`bash
cd /path/to/your/project
zedra start –detach
“`
- 在 Claude Code 中安装 Zedra 钩子：
“`bash
zedra setup claude
“`
- 在 Claude Code 中激活 Zedra：
“`
/zedra-start
“`
- 用手机 App 扫描二维码后，你会看到 Claude Code 的终端输出实时同步到手机上
- Zedra 会在 Claude Code 完成关键操作时向你的手机推送通知，无需一直盯着屏幕
实际效果：你可以在地铁上看到 Claude Code 逐行修改文件、运行测试、提交 commit。如果发现修改有误，可以随时中断任务，回到电脑前再手动调整。
实战场景 2：在会议中监视 Codex 集群任务
当你用 Codex 处理并行任务（如批量重构多个微服务）时，可以用 Zedra 同时监视多个工作空间的进度。
cd ~/projects/service-a zedra start --detach cd ~/projects/service-b zedra start --detach
每个 daemon 都会生成独立的二维码和工作空间。Zedra App 中会列出所有已配对的工作空间，你可以随时在它们之间切换，查看每个服务中的 Codex 任务进度。
Zedra 的 P2P 隧道支持多路复用，即使同时查看多个工作空间，流量也通过同一个隧道传输。如果遇到对称 NAT 或运营商级 NAT（CGNAT），隧道会自动回退到中继模式，连接仍可工作。
实战场景 3：远程开发机（Cloud VM / 服务器）上的 Agent 监控
如果你在云服务器（如 EC2、VPS、DevContainer）上运行 AI 编码 Agent，Zedra 能让你用手机实时查看远程 Agent 的状态，无需复杂的端口转发或 VPN 配置。
操作流程：
- SSH 登录到你的远程开发机
- 在项目目录中启动 daemon：
“`bash
cd ~/projects/backend-service
zedra start
“`
- 终端会显示二维码——在 SSH 会话中，二维码以 ASCII 字符显示
- 用手机 Zedra App 扫描远程终端上的二维码完成配对
Zedra 的 P2P 隧道通过 Iroh 协议自动处理 NAT 穿透，即使远程机在数据中心内部网络（无公网 IP），也能通过中继回退建立连接。
注意事项：远程开发机上 zedra start 必须保持运行。建议使用 tmux 或 screen 持久化会话，或者在 SSH 会话中使用 zedra start --detach 后台运行。如果 SSH 断开后重新连接，daemon 仍然在后台运行，只需重新打印二维码即可配对。
实际效果：你在手机上就能看到远程服务器上 Claude Code 或 Codex 的执行进度。代码在云端运行，不占用本地计算资源，适合 GPU 受限的笔记本电脑用户。
最佳实践
1. 每个项目目录单独启动 daemon
Zedra 将每个 daemon 的工作目录视为一个独立的工作空间。建议在每个项目目录中单独启动 daemon，这样在手机上能看到每个项目的独立状态，切换查看。
2. 后台启动 + 自启配置
对于常用的开发目录，建议将 zedra start --detach 配置为开机自启：
cd ~/projects/main && ~/.local/bin/zedra start --detach cd ~/projects/main && ~/.local/bin/zedra start --detach
3. 网络兼容性注意事项
Zedra 依赖 P2P 打洞技术。在家庭网络（运营商 CGNAT、对称 NAT）中可能出现无法直连的情况，此时会自动使用中继服务器回退。中继部署在新加坡、越南、美东、欧洲中部等多个区域，自动选择最低延迟的节点。
如果连接延迟较高，检查是否是中继路径而非直连路径。Zedra 在 LAN 环境和有公网 IP 的机器上表现最佳。
4. 安全第一
- 二维码包含一次性密钥，配对后失效
- 所有通信使用 TLS 1.3 加密
- Zedra 不会在服务端留存你的代码、终端输出、文件路径或按键记录
- 配对信息（公钥 + 密钥）仅存储在本地设备上
5. 用 zedra qr 重新打印二维码
如果忘记保存二维码或需要为新设备配对，使用：
zedra qr --workdir /path/to/project
总结
Zedra 解决了 AI 编码 Agent 使用中的一个真实痛点——人不在电脑前时，如何查看和控制 Agent 的运行状态。 它用 P2P 隧道技术实现了安全、低延迟的远程连接，支持的 Agent 生态宽广（Claude Code、Codex、OpenCode、Pi、Hermes），而且完全开源（MIT 许可证）。
如果你经常在非办公位使用 AI 编码 Agent，或者在需要离开电脑时担心 Agent 的执行进度，Zedra 是一个轻量且实用的解决方案。只需一行命令安装、一次扫码配对，你的 AI 编码 Agent 就能随时随地尽在掌握。
相关链接：