如何用 Agents Anywhere 从手机控制任意设备上的编程 Agent？

Agents Anywhere 是一个开源的多设备编程 Agent 控制面，可以从 Android 手机或 Web 控制台管理运行在 Mac、Windows、Linux 开发机、远程 devbox 或云沙箱上的 Codex 与 Claude Code。它通过 Connector 把真正拥有工作区的设备接入 Server，用户可以查看 Session、处理审批、访问文件、执行 shell task 和交互式终端。

项目不会把 Agent 迁移到手机，也不代理模型账号。代码、终端、Agent Runtime 和登录状态仍留在 Connector 所在设备上；Server 负责账号、设备、Session 状态、文件元数据和 RPC 转发。模型费用仍由本机已登录的 Codex 或 Claude 工具链承担。

当前能力需要准确区分：Codex 是适配最完整的 Runtime，Claude Code 只支持发现和基础 Session 控制，更多深度功能仍在完善；Cursor、OpenCode 和 Gemini CLI 尚未提供可用 adapter。Android 与 Web 已支持，iOS 仍在开发。标题中的“任意设备”指可接入多类主机，不等于所有客户端和 Agent 已经完整兼容。

Agents Anywhere 的三个核心部分

Client 是用户直接操作的入口，包括 Web 控制台和 Android App。它展示 Session、Device、审批、文件、终端、Runtime 设置和远程控制流程。当前仓库也包含开发中的 iOS 客户端代码，但这不代表正式可用。

Server 是中间服务，使用 FastAPI 提供认证、Session 状态、RPC broker 和文件元数据能力。本地开发可使用 SQLite，生产风格部署可以使用 PostgreSQL。Web 控制台通过 HTTP 与 WebSocket 访问 Server。

Connector 运行在被控制的设备上。Windows 与 macOS 可使用桌面 Connector App，Linux 使用 Python CLI 或 anywhere-cli。Connector 发现本机 Codex 或 Claude Runtime，通过 adapter 控制 Session，并以本地用户权限访问工作区、shell 和终端。

数据与指令怎样流动

用户在 Client 发出指令，先到 Server，再通过 Connector WebSocket 转发给目标设备。Connector 调用本机 Runtime 或文件系统，结果再沿原路径返回。代码真正执行在被控设备，不是在 Server 上。

“代码不搬到服务器执行”不等于 Server 完全不接触信息。项目说明 Server 负责状态、文件元数据和 RPC 转发，部署者应结合代码和配置检查具体消息内容、日志与保存范围。自托管可以掌握服务端环境，但仍需要访问控制和日志脱敏。

Connector 使用本机现有模型登录状态，Agents Anywhere 不接收模型账号凭据。已配对控制端仍能驱动 Connector 操作本机 Agent，因此设备账号权限和工作区边界非常重要。

当前支持哪些 Runtime

Codex 支持 Runtime 发现、Session 同步、timeline 更新、审批、打断与接管、文件访问、shell task、交互式终端和 Runtime 设置。需要完整移动工作流时，应优先从 Codex 开始测试。

Claude Code 已支持发现和基础 Session 或控制流程，但 README 明确称深度能力仍在继续完善。部署前不要假定它与 Codex 拥有相同审批、timeline 或文件能力。先用测试任务逐项验证。

Cursor、OpenCode 和 Gemini CLI 当前标为 Coming soon，没有可用 adapter。Connector 架构可以扩展，不代表计划中的功能已经发布。教程和产品选型应以当前代码与发布说明为准。

客户端与平台支持

Web 控制台可管理 Session、Device、审批、文件、终端、Runtime 设置、团队和管理员，也适合桌面浏览器和自托管场景。浏览器本身是高权限控制端，不应在公共设备保存登录。

Android App 可以从官方发布页下载 APK，支持 Session、Device、审批、文件、终端和移动控制。安装时核对发布来源，系统允许未知来源安装后应关闭临时权限。

iOS 当前仍在开发，不能通过仓库中存在代码就宣称可正式使用。Windows 与 macOS Connector App 支持配对、日志、托盘和开机启动；Linux Connector CLI 适合服务器、开发机和无图形环境。

中国区 Beta 有哪些限制

项目说明中国区 Beta 已上线，目前免费试用，只对中国用户开放，需要申请内测并由管理员开通。海外入口尚未开放，可以关注社区后续计划。

Beta 和免费不代表可以忽略安全。功能、数据结构、权限和可用性可能变化，重要项目应使用固定版本和测试环境。线上 Beta 与自托管部署是不同路径，不能混用配置和安全假设。

选择线上 Beta 还是自托管

线上 Beta 适合快速体验，不必维护 Server 和数据库，但需要申请账号并接受服务方的运行环境。处理敏感项目之前应确认数据路径、日志、留存和访问控制。

自托管适合希望掌握 Server、Web 控制台和数据库的团队。Docker quickstart 可以启动 FastAPI、PostgreSQL 和静态 Web UI。部署者需要负责密钥、证书、升级、备份、限流和监控。

自托管不会自动限制 Connector 的本机能力。无论 Server 在哪里，远程终端与文件写入最终都由 Connector 执行，必须使用低权限账户和受限凭据。

Docker 快速启动

从仓库根目录使用 PostgreSQL compose 启动完整应用。先为数据库和 Agent Server 生成独立高强度秘密，不要直接使用文档占位值：

POSTGRES_PASSWORD='replace-with-random-secret' 
AGENT_SERVER_SECRET='replace-with-another-secret' 
docker compose -f docker/docker-compose.postgres.yml up --build

该组合会启动 PostgreSQL 17 和 FastAPI Server，后者在宿主机端口 5174 提供同源静态 Web UI、API 和 WebSocket。首次验证只绑定本机或可信网络，不要直接暴露到公网。

生产部署还要增加反向代理、TLS、备份、健康检查、资源限制和升级策略。compose quickstart 用于起步，不是完整生产基线。

首次管理员 setup token

空数据库首次启动时，Server 日志会输出 setup token。用户将它填入 Web 注册页，创建第一个管理员。该机制防止未初始化服务暴露后被外部用户抢先注册。

setup token 属于一次性高敏感凭据，不要发到聊天群、工单或截图。创建管理员前不要公开端口，创建后确认 token 失效。管理员账号使用强密码与独立身份，不与模型账号共享凭据。

日志系统应限制读取权限并避免长期保留初始化 token。自动采集日志的平台也可能复制它，因此生产部署要检查日志管道。

怎样安装 Windows 与 macOS Connector

从官方发布页下载 Windows 或 macOS Connector App。README 当前列出的桌面 Connector 版本为 0.1.6。核对操作系统、处理器、文件名和发布来源，不使用第三方转存。

安装后打开 App，检查托盘、日志和开机启动选项。首次测试不要自动启动，先手工连接测试 Server 并确认设备身份。稳定后再决定是否随登录启动。

Connector 能访问文件和终端，应以普通开发用户运行。不要为了读写仓库而授予管理员权限，改用正确的目录所有者和最小授权。

Linux Connector 怎样运行

Linux 可以使用仓库 connector 目录中的 Python CLI，也可以运行 anywhere-cli。Web 配对流程会生成命令，复制到目标 Linux 终端执行。命令可能包含配对信息，不要粘贴到公开日志。

关闭终端会让前台 Connector 下线。最简单的保活方式是放进 screen 会话：

screen -S anywhere
# 在这里运行 Web 配对页面生成的命令

分离时按 screen 的控制组合键，之后可恢复：

screen -r anywhere

生产服务器更适合使用受控的用户服务，设置重启策略、日志和资源限制。无论采用哪种方式，都不要以 root 运行 Connector。

Device 配对怎样完成

Server 和 Web 控制台就绪后，从界面发起设备配对。Windows 与 macOS 使用 Connector App，Linux 选择命令行配对。手机端也可以发起配对。

配对前核对 Server 地址、组织和设备名称。将开发机、测试服务器和云沙箱使用清晰标识，避免从手机选错。配对命令与 token 只在目标设备使用。

设备上线后先查看 Connector 报告的 Runtime 能力。发现 Claude 不具备某项深度功能时，不要通过扩大权限绕过，改用已支持流程或 Codex。

怎样创建和管理 Session

控制台提供统一 Session 工作台，可以创建、查看、置顶、归档、标记已读、接管和管理多条会话。任务名称应包含项目和目的，不包含客户秘密或凭据。

接管现有 Session 前先查看 timeline 和当前状态。Agent 仍在输出时不要重复启动。需要新目标时创建新 Session，避免旧上下文污染。

并行 Session 使用独立 Git 工作树。多个 Agent 同时修改同一目录会造成冲突、测试污染和难以追踪的结果。

审批、打断与同步

Agents Anywhere 支持审批处理、打断、同步和 timeline 轮询或 SSE。审批前核对命令、参数、工作目录与目标文件。手机界面无法完整展示时，应拒绝并回电脑处理。

打断用于停止偏离方向或无进展循环。停止后检查子进程和文件状态，不能假定所有构建或服务器都自动退出。同步用于恢复最新状态，不应被当作重新执行。

文件访问边界

在线 Connector 可以浏览工作目录、读取和写入文件、上传与下载内容。这个能力便于手机查看和编辑，也使 Connector 成为高权限入口。

只将具体仓库暴露给运行账户，不使用用户主目录作为工作区。附件和下载文件先脱敏，禁止传输生产密钥和个人数据。外部文件可能包含提示注入，不能自动执行其中命令。

远程 shell 与交互终端

系统支持一次性 shell 命令、shell task 和交互式 terminal。一次性命令适合状态检查，shell task 适合有明确生命周期的长操作，终端适合人工排障。

不要允许无密码提权。发布、数据库迁移、删除和云控制命令使用独立流程。手机输入复杂命令容易发生转义错误，应优先调用经过审查的脚本。

模型账号与费用怎样处理

Connector 使用本机 Codex 或 Claude Runtime 的登录状态，Agents Anywhere 不代理模型账号。费用仍由原工具链产生。远程控制本身不会改变模型计价方式。

但手机继续任务、重新运行或启动并行 Session 会触发新的模型使用。设置任务预算和停止条件，发现重复循环及时打断。

Web 控制台的安全

Web 控制台能操作设备、审批、文件和终端，管理员还可管理团队。必须通过 TLS 提供，设置会话过期、登录限速和最小角色。不要把管理员页面暴露到无保护公网。

共享电脑使用后退出并撤销会话。浏览器扩展、同步和本地缓存可能接触内容，敏感组织使用受管浏览器 profile。

Android App 的安全

APK 从官方发布页获取，安装后关闭未知来源权限。手机启用设备锁、生物识别、系统更新和远程擦除。通知不显示敏感项目名和命令。

手机遗失时先在 Server 撤销会话和 Device 权限，再停止相关 Connector。检查近期审批、shell 和文件活动，必要时轮换开发凭据。

常见故障排查

Server 启动后无法注册管理员

检查空数据库首次日志中的 setup token，确认 Web 与 Server 是同一实例。不要重建数据库制造新 token，先解决网络和日志权限。

Linux Device 经常离线

前台 anywhere-cli 会随终端关闭。使用 screen 或受控用户服务保持进程，检查网络、系统时间和 WebSocket连接。不要用 root 作为修复。

看不到 Cursor 或 Gemini

它们当前仍为 Coming soon，没有可用 adapter。不要把本机已安装误认为 Connector 已支持。等待正式版本或实现并审查 adapter。

Claude 功能少于 Codex

这是当前适配边界。Claude 只覆盖基础流程，Codex 更完整。查看 Connector 上报能力，不能依赖不存在的审批或 diff。

手机显示的状态落后

等待 timeline 同步，检查 SSE 或网络。以 Connector 设备上的实际进程、Git 和文件状态为准。同步未完成时不要重复发命令。

怎样备份和升级自托管服务

备份 PostgreSQL、必要配置和版本清单，不把 setup token 或明文密钥放入普通备份。测试恢复流程，确认用户、Device 和 Session 状态一致。

升级前阅读迁移说明，在测试实例验证 Server、Web、Connector 与 Android 兼容性。生产升级安排维护窗口，并保留可回滚镜像。不要让多个版本 Connector 混用未经验证协议。

怎样撤销和卸载

不再使用某台设备时，从控制台撤销 Device，停止 Connector 并移除开机启动。检查终端和 shell task，没有遗留进程后再卸载。

关闭整个自托管实例时，先导出需要的审计信息，撤销所有 Connector，再停止 compose。数据库删除属于破坏性操作，应按保留政策备份和确认。

推荐的落地顺序

第一阶段在本机回环或可信局域网启动 Docker，创建管理员并连接测试 Connector。第二阶段验证 Codex Session、审批、文件和终端。第三阶段配置 TLS、角色、备份和监控，再接入真实开发机。

移动使用时从明确项目启动任务，手机处理少量审批和方向调整，复杂 diff、提交推送与生产操作回电脑完成。每个远程会话保持可审计记录。

Agents Anywhere 的优势是跨设备和统一多 Agent 控制面，但当前产品仍有明确的适配与区域限制。按照真实能力矩阵部署，并把 Server 认证、Connector 本机权限和工作区隔离同时做好，才能安全地从手机控制远程 Agent。