AgentPilot - 手机远程访问本机 Codex App Server

AgentPilot（npm 包 cli-link）提供一个手机端入口，把运行在个人电脑或开发机上的 Codex App Server 变成可以远程访问的工作台。你继续使用本机仓库、依赖、终端登录态和网络环境，手机上负责发任务、看输出、补充指令和查看代码变更。

它不是替代 Codex 的新 Agent，也不是把代码搬到云端运行。AgentPilot 做的是把本机 Codex App Server 的交互、状态和工作区能力延伸到手机，让你离开电脑后仍能继续遥控本机任务。

工具定位

AgentPilot 面向“本机运行、手机访问”的使用方式：

• 在本机完整开发环境里通过 codex app-server --stdio 启动 Codex agent。
• 通过手机浏览器远程查看执行进度、工具调用、命令输出和最终回复。
• 在运行中的会话里继续追加指令或排队追问。
• 在代码页面查看当前工作目录、Git 变更和文件 diff，必要时完成暂存和提交。
• 通过历史记录复盘任务，或继续向可恢复的会话追问。

只要电脑保持开机、联网且 AgentPilot 服务未退出，就可以面向远程 24 小时访问；如果是 Mac，建议接入电源，并按本文后面的防休眠说明完成系统设置。

优势

• 更全的本机环境，能力边界更大：继续使用你电脑里的仓库、依赖、命令行工具、登录态、SSH Key、内网和 VPN 环境，避免临时云环境缺依赖、缺权限、缺网络入口。
• 与 Codex App Server 的 thread 管理保持一致：任务仍由本机 Codex 执行，工作目录、会话状态和上下文管理方式保持原样，手机端只是远程交互入口。
• 扫码即用，微信里保留入口：启动后终端打印二维码，用微信扫描即可打开；把链接转发到自己的会话或文件传输助手，后续访问可以直接从微信打开。
• Token 机制降低误接入风险：NPX 启动默认生成一次性访问 token，前端页面、后端 API 和 WebSocket 都需要通过校验，降低 IP 或端口泄漏后被随意访问的风险。

快速开始

前置条件：

• Node.js 20 或更高版本
• 已安装并登录 Codex CLI，且当前版本支持 codex app-server --stdio

在要遥控的业务仓库根目录执行：

npx -y --registry=https://registry.npmmirror.com cli-link@latest

启动后：

1. 用微信扫描终端里的二维码。
2. 打开后把链接转发到自己的微信会话或文件传输助手，保留下次访问入口。
3. 后续只要电脑上的 AgentPilot 服务还在运行，就可以直接从微信里的链接打开。

如果你使用 npm 官方 registry，也可以运行：

npx -y cli-link@latest

典型场景

• 让 Codex App Server 在电脑上跑一个长任务，然后离开工位，用手机继续看进度。
• 在会议、通勤或外出时补充下一条指令，或中断当前任务。
• 远程批准或拒绝 CLI 的确认请求。
• 在多个仓库之间切换工作目录，继续处理不同项目。
• 任务结束后从历史记录里复盘 Codex 做过什么。

截图

| 对话页面 | 代码页面 | | --- | --- | | | |

| 历史记录 | 设置页面 | | --- | --- | | | |

代码页面

代码页面用于在手机上查看当前工作目录的文件和 Git 变更，适合在离开电脑时快速确认 Agent 修改了什么、是否需要继续追问或直接提交。

• 代码浏览：按当前设置的工作目录展示文件夹和文件，支持逐级进入目录、返回上级目录，并在底部弹层中预览文件内容。
• 文件预览：文本和代码文件会按扩展名做语法高亮；图片文件可直接预览；过大的文件和二进制文件会给出提示，避免在手机端加载异常内容。
• 变更查看：在 Git 仓库中显示当前分支、变更文件列表和文件状态，点开单个文件后可以查看结构化 diff，包括新增、删除和上下文行。
• 暂存控制：支持对单个文件暂存/取消暂存，也支持全部暂存/全部取消，方便在手机上整理本次提交范围。
• 代码提交：暂存文件后可以打开提交面板，手动填写 Commit 信息，或让底层 CLI 基于已暂存变更和最近提交生成提交信息，再直接执行 git commit。

启动和配置

NPX 启动

前置条件：

• Node.js 20 或更高版本
• 已安装并登录 Codex CLI，且当前版本支持 codex app-server --stdio

在要遥控的业务仓库根目录执行：

npx -y --registry=https://registry.npmmirror.com cli-link@latest

如果你使用 npm 官方 registry，可以运行 npx -y cli-link@latest。后续示例为了简洁会省略 -y、@latest 和 --registry，实际使用时可以按需补上。

启动后终端会打印本机和手机访问地址：

AgentPilot READY
Mobile-first remote console for your local agent

OPEN ON MOBILE
  Mobile   http://192.168.1.23:51258/?token=...
  Scan     use the QR code below

QR CODE
[terminal QR code]

LOCAL ACCESS
  Local    http://localhost:51258/?token=...
  Token    enabled, required for browser/API/WebSocket access

RUNTIME
  Workdir  /path/to/your-repo
  CLI      codex (codex)

MACOS LONG TASKS
  已启用 caffeinate -i，当前服务运行期间会阻止 Mac 空闲休眠。
  合盖或低电量等系统策略仍可能中断任务；长时间运行建议接入电源。

  这个机制主要防止“空闲后自动睡眠”。合盖、低电量、系统强制睡眠或断电仍可能中断任务；如果要离开电脑、从手机继续遥控长任务，建议接入电源，并按需开启 macOS 的防休眠选项：

  1. 打开 `系统设置` -> `电池` -> `选项...`。
  2. 开启“使用电源适配器供电且显示器关闭时，防止自动进入睡眠”。
  3. 点击“完成”。

  这样电脑接入电源且显示器关闭后，AgentPilot 后端和底层 CLI 更不容易被系统睡眠中断。

默认行为：

• 监听 0.0.0.0:51258，电脑访问 http://localhost:51258，手机访问终端打印的 Mobile 地址。
• 生产默认使用较小众的高位端口，降低与常见本地开发服务冲突的概率；如需固定为其它端口，可通过 --port 或 PORT 覆盖。
• 终端会为第一个 Mobile 地址打印二维码，手机扫码即可打开。
• NPX 启动默认生成一次性访问 token；缺少 token 或校验 cookie 时，前端页面、后端 API 和 WebSocket 都会返回 401。
• 使用执行 npx 时的当前目录作为工作目录。
• 同一个 server 进程内，如果在前端切换了工作目录，刷新或重新打开前端会保持最近一次切换后的目录；重启 server 后会重新以启动命令所在目录作为默认工作目录。
• 自动识别 codex；未识别到时，可以在设置页手动配置 Codex 启动命令。
• 前端、后端 API 和 WebSocket 共用同一个访问端口。

常用参数：

npx cli-link --port 51258
npx cli-link --host 0.0.0.0
npx cli-link --token your-fixed-token
npx cli-link --no-token
npx cli-link --workdir /path/to/project
npx cli-link --cli codex
npx cli-link --cli-command /path/to/codex

--token 适合需要固定访问地址的受控环境；--no-token 只建议在本机或完全可信网络中临时使用。

当前最低 Node 版本是 20，主要由运行时数据库依赖 [email protected] 决定；Node 18 不在该依赖的支持范围内。

Codex App Server 后端

默认情况下，AgentPilot 通过 Codex 官方 app-server JSON-RPC 协议创建和恢复 Codex thread：

npx -y cli-link@latest

本地仓库验证时：

pnpm serve

当前后端的边界：

• 保留 AgentPilot 现有手机入口、访问 token、HTTP API、WebSocket、工作区和 Git 页面。
• 新会话会通过 thread/start 创建 Codex thread；恢复历史会话时会通过 thread/resume 继续写入同一个 Codex thread。
• 用户消息会通过 turn/start 发送；运行中追加输入会尝试走 turn/steer；中断会走 turn/interrupt。
• App Server 的实时事件会映射回 AgentPilot 现有消息类型，包括助手消息、思考摘要、命令执行、文件变更和 token usage。
• 历史页暂时仍以 AgentPilot 本地 SQLite 为前端缓存和索引；完整切换到 thread/list、thread/read 和 thread/turns/list 会作为后续阶段。
• 默认使用 approvalPolicy=on-request 和 workspace-write，命令执行、文件变更、权限提升和用户输入请求会映射到手机端确认链路。
• 设置页可以切换到全信任模式；该模式会以 approvalPolicy=never 和 danger-full-access 运行 Codex，适合完全可信环境中的低打扰使用。

如需固定版本：

npx [email protected]

本地正式环境启动

如果要在本仓库里验证发布包形态，而不是通过 npm registry 拉取包，可以先构建前端和后端，再走本地的 cli-link 入口：

pnpm install
pnpm build
pnpm serve

pnpm serve 会运行 bin/agentpilot.js，读取 dist/client 和 dist/server 中的构建产物；如果还没有执行 pnpm build，会提示先完成构建。

默认行为与 NPX 启动一致：

• 监听 0.0.0.0:51258，电脑访问终端打印的 Local 地址，手机访问终端打印的 Mobile 地址或扫描二维码。
• 前端、后端 API 和 WebSocket 共用同一个访问端口。
• 默认生成一次性访问 token，启动链接会自动带上 ?token=...；缺少有效 token 或校验 cookie 时无法访问页面、API 或 WebSocket。
• 使用执行 pnpm serve 时的当前目录作为默认工作目录，也可以通过 --workdir 指定。

常用参数需要放在 -- 后面传给入口脚本：

pnpm serve -- --port 51258
pnpm serve -- --workdir /path/to/project --cli codex
pnpm serve -- --token your-fixed-token
pnpm serve -- --no-token
pnpm serve -- --https-key /path/to/key.pem --https-cert /path/to/cert.pem

pnpm preview 只会启动 Vite 的前端预览服务，不会完整启动 AgentPilot 后端、API 和 WebSocket；本地正式环境验证请使用 pnpm build && pnpm serve。

发布到公开 npm

一键发布 patch、minor、major 或指定版本：

pnpm release patch
pnpm release minor
pnpm release 0.1.0

发布脚本会要求 git 工作区干净，依次更新 package.json 版本、执行 pnpm build、发布到 npm，并在发布成功后提交版本变更。需要打 tag 时可以运行：

pnpm release patch -- --tag

发布命令会使用 https://registry.npmjs.org，不受本机默认 registry 配置影响。发布前需要先完成 npm 登录，或通过环境变量提供 npm token：

export NPM_TOKEN=your-npm-token
pnpm release patch

发布前确认包名、版本和打包内容：

pnpm publish:dry-run

本地开发调试

前置条件：

• Node.js 20 或更高版本
• pnpm 10.32.1
• 已安装并登录 Codex CLI，且当前版本支持 codex app-server --stdio

当前项目开发调试使用 pnpm 10.32.1；业务方通过 NPX 启动时不需要安装 pnpm。 本地开发调试默认不启用 token 校验，保持前端 5101、后端 3101 的两进程联调方式；如需临时验证 token 逻辑，可以给后端设置 AGENTPILOT_AUTH_TOKEN 后再用带 ?token=... 的前端地址打开。 pnpm dev 会把调试数据写入仓库内的 .agentpilot-dev/ 目录，避免本地调试依赖 ~/.agentpilot 的写权限；该目录已加入 Git 忽略列表。如需指定其它数据目录，可以设置 AGENTPILOT_DATA_DIR；如需精确指定 SQLite 文件，可以设置 AGENTPILOT_DB_PATH。

安装依赖：

pnpm install

启动前端和后端：

pnpm dev

脚本职责：

• pnpm dev：同时启动前端和后端，是日常联调推荐命令。
• pnpm dev:client：只启动 Vite 前端开发服务，默认监听 0.0.0.0:5101。
• pnpm dev:server：只启动后端服务，默认监听 0.0.0.0:3101，并监听 server/index.ts 变更自动重启。
• pnpm dev:all：兼容旧用法，等价于 pnpm dev。

访问地址：

• 电脑本机：http://localhost:5101
• 手机访问：先挂上公司 VPN，再打开 http://<电脑局域网 IP>:5101

开发模式下，前端默认会连接同一主机名下的后端端口 3101：

• HTTP API：http://<当前前端主机>:3101
• WebSocket：ws://<当前前端主机>:3101

如果需要连接自定义后端地址，可以设置：

VITE_API_URL=http://127.0.0.1:3101 VITE_WS_URL=ws://127.0.0.1:3101 pnpm dev:client

如果只需要改本地调试后端端口，保持前端按同一主机名连接，可以设置 VITE_DEV_SERVER_PORT；开发脚本会把后端 PORT 同步为同一个值：

VITE_DEV_SERVER_PORT=3201 pnpm dev

电脑和手机需要在同一个局域网或公司 VPN 网络内。例如电脑 IP 是 192.168.1.23，手机挂上公司 VPN 后在浏览器打开：

http://192.168.1.23:5101

如果启动后终端打印了多个 Network 地址，选择手机挂公司 VPN 后能访问的那个 IP 即可；其它地址通常是不同网卡、VPN 或虚拟网卡，可以忽略。

进入设置页后，配置 Codex 启动命令和工作目录，点击启动 CLI，然后回到会话页发送任务。

HTTPS/WSS 与 PWA

如果需要在手机上安装为 PWA，或启用 Service Worker 缓存，需要使用 HTTPS 访问前端，并让后端 WebSocket 走 WSS。NPX 启动可以直接传入证书：

npx cli-link --https-key /path/to/key.pem --https-cert /path/to/cert.pem

本地开发调试时，AgentPilot 也支持通过环境变量给前端 Vite 服务和后端服务同时启用同一套证书：

AGENTPILOT_HTTPS_KEY=/path/to/key.pem AGENTPILOT_HTTPS_CERT=/path/to/cert.pem pnpm dev

启用后访问地址会变为：

• 电脑本机：https://localhost:5101
• 手机访问：https://<电脑局域网 IP>:5101

证书需要被手机信任，并且证书的 SAN 需要包含实际访问的主机名或 IP。NPX 启动时前端、后端 API 和 WebSocket 共用同一个 HTTPS/WSS 端口；本地开发调试时前端仍在 5101，后端 API 和 WebSocket 仍在 3101。

PWA manifest 会随页面加载。Service Worker 默认只在生产构建中注册；如需在开发服务中验证 PWA 行为，可以额外加上：

VITE_ENABLE_PWA_DEV=true AGENTPILOT_HTTPS_KEY=/path/to/key.pem AGENTPILOT_HTTPS_CERT=/path/to/cert.pem pnpm dev

当前 Service Worker 只缓存应用壳层和静态资源，并显式避开 /api/*。会话、历史、文件内容、Git diff、确认/提交等动态数据不会被离线缓存或自动重放。

防止息屏后休眠

通过 npx cli-link 启动时，AgentPilot 会在 macOS 上自动运行 caffeinate -i -w <pid>，在当前服务进程存活期间阻止 Mac 空闲休眠。服务退出后，配套的 caffeinate 进程会自动结束。

这个机制主要防止“空闲后自动睡眠”。合盖、低电量、系统强制睡眠或断电仍可能中断任务；如果要离开电脑、从手机继续遥控长任务，建议接入电源，并按需开启 macOS 的防休眠选项：

1. 打开 系统设置 -> 电池 -> 选项...。
2. 开启“使用电源适配器供电且显示器关闭时，防止自动进入睡眠”。
3. 点击“完成”。

这样电脑接入电源且显示器关闭后，AgentPilot 后端和底层 CLI 更不容易被系统睡眠中断。

安全风险与使用边界

AgentPilot 的设计目标是个人开发机上的 Agent 遥控器，不是多用户协作平台，也不是可直接暴露到公网的服务。NPX 启动默认开启轻量 token 校验：启动链接会携带一次性 token，服务端校验通过后写入 HttpOnly cookie；缺少有效 token 或 cookie 的客户端不能访问前端页面、后端 API 或 WebSocket。这个机制可以降低 IP/端口泄漏带来的误接入风险，但不等价于完整登录系统，也不提供 Origin 校验、CSRF 防护或 TLS 终止。

使用时建议遵守这些边界：

• 只在可信的本机、内网或受控 VPN 中使用；不要把 NPX 启动的 51258 单端口，或本地开发调试的 5101 前端端口和 3101 后端 HTTP/WebSocket 端口直接暴露到公网。
• 如果只需要本机访问，优先把前端和后端改为监听 127.0.0.1，或者用系统防火墙限制可访问来源。
• 如果必须跨网络访问，建议放在带身份认证和 HTTPS/WSS 的反向代理或安全隧道后面，不要直接转发裸 HTTP/WebSocket 端口。
• 公司 VPN 只解决“网络可达”问题，不等于应用层鉴权；同一 VPN 或同一网段内的非预期客户端仍然可能访问。
• 项目内置的 HTTPS/WSS 只解决传输加密和 PWA 安全上下文；安装为 PWA 后仍应只在可信网络中使用。

CLI 权限风险

项目默认使用 on-request 审批和 workspace-write 沙箱运行 Codex App Server；当底层 Codex 请求执行命令、修改文件、提升权限或补充用户输入时，AgentPilot 会在手机端展示确认卡片。对可识别的同轮类似只读命令，可以选择一次授权后自动放行后续同类审批。

设置页提供全信任模式。启用后，底层 Codex 会以 approvalPolicy=never 和 danger-full-access 运行，命令和文件操作不会进入审批链路。

这仍不能把 AgentPilot 当作完整安全沙箱或权限边界。底层 Codex 仍按宿主机账号运行，获批后可能读写文件、执行命令或访问已登录服务。恶意提示词、错误操作、被他人接入的浏览器客户端，或模型误判都可能导致代码被改写、文件被删除、命令被执行、凭据被读取，或向外部服务发送敏感内容。

建议：

• 只在可信仓库和可接受回滚的工作区中运行；重要操作前保持干净的 Git 状态。
• 不要把工作目录设为整个主目录、包含生产密钥的目录，或包含大量无关敏感文件的目录。
• 高风险任务优先使用专用低权限系统用户、容器、虚拟机或临时开发环境运行。
• 不要在不可信提示词、网页内容、日志、Issue、PR 描述或第三方文件上下文中使用“同轮类似命令自动放行”。
• 如果要把项目改造成长期服务，优先接入完整登录、Origin/CSRF 防护、HTTPS 终止、审计日志和更严格的系统级隔离。

数据落盘风险

会话消息、用户输入、AI 输出、工具调用参数、命令输出、权限请求和历史任务会写入本机 SQLite 数据库：

~/.agentpilot/data.db

本地开发脚本 pnpm dev 默认使用仓库内 .agentpilot-dev/data.db，发布包和 pnpm serve 默认仍使用 ~/.agentpilot/data.db。可以通过 AGENTPILOT_DATA_DIR 或 AGENTPILOT_DB_PATH 覆盖数据落盘位置。

这些内容可能包含源码片段、文件路径、命令输出、错误栈、密钥片段或业务信息。后端 HTTP/WebSocket 可达的客户端可以读取当前会话和历史任务；README 中的“清空历史”也不应被视为安全擦除，因为底层消息记录可能仍保留在 SQLite 数据库中。

建议：

• 不要在提示词、命令输出或工具调用中粘贴长期有效的密钥、Token、Cookie、私钥或生产数据。
• 定期清理或加密备份 ~/.agentpilot/data.db；需要彻底清除敏感会话时，停止服务后手动处理该数据库文件。
• 不要把 ~/.agentpilot 目录加入同步盘、共享目录或 Git 仓库。

目录枚举与文件路径泄露

目录选择器和 @ 文件选择器会通过后端 HTTP API 读取服务端机器上的目录和文件名。当前实现会隐藏点号开头的条目，但连接者仍可向上级目录导航，并看到可读目录结构、文件名和绝对路径。这些信息本身可能暴露项目名称、用户目录、客户名称或内部代号。

建议：

• 只让可信设备连接 AgentPilot。
• 把工作目录限制在当前项目目录或临时工作区。
• 不要依赖前端选择器来隔离文件系统权限；真正的隔离应通过操作系统账号、容器或沙箱实现。

模型与供应链风险

底层 Codex App Server 可能会把提示词、选中的文件内容、命令输出和上下文发送到对应模型服务，具体取决于 Codex 配置、登录账号和工具调用行为。使用前应确认团队对源码、日志、客户数据和密钥材料进入外部模型服务的合规要求。

依赖方面，已在 2026-05-12 执行过一次 pnpm audit --prod，结果为 No known vulnerabilities found。漏洞库会持续变化，后续升级依赖或长期使用前仍应重新执行：

pnpm audit --prod