AgentPager

手机遥控你电脑上的编程 Agent。

在微信小程序里实时查看 Claude Code / Codex / Cursor 等多家编程 Agent 的会话，随时随地续聊、语音输入、发图片、任务完成时收到推送——就像给你的 Agent 配了一台传呼机。

本仓库是开源的客户端(daemon)：跑在你电脑上，负责配对、连接中继、运行 Agent、把会话流式传到手机。中继(relay)与微信小程序是托管服务(暂未开源)——安装本 CLI 后，通过微信里的「AgentPager」小程序配对即可使用。

快速开始

电脑上一条命令(macOS / Linux)：

npx @agentpager/cli@latest pair

手机上：微信打开小程序「AgentPager」→ 扫描/输入电脑上显示的配对码 → 完成。配对成功后自动转后台运行，手机立刻可用。

Requirements

• Node ≥ 18(npx 随 Node 自带)。低于 18 主力 provider(Claude Code / CodeBuddy 等,及内置 Claude SDK)无法运行。Node ≥ 18 即全功能:cursor / opencode 的会话历史用内置纯 JS SQLite 读取器,不依赖 node:sqlite(Node 22)或系统 sqlite3。
• 电脑上至少装了一个受支持的 Agent CLI(见下)。daemon 自动探测 PATH——没装会引导你装。

命令

装完之后的管理命令（-h 看全部）：

| 命令 | 作用 | |---|---| | pair | 配对 + 自动转后台运行 | | status | 运行状态 / 实例数 / 配对情况 | | start / stop / restart | 后台服务管理 | | update | 升级到最新（npx @agentpager/cli@latest update） | | doctor | 排查：中继可达 / provider 齐 / 实例数 | | uninstall | 卸载后台服务 | | -v / -h | 版本 / 帮助 |

装了全局版（npm i -g @agentpager/cli）后可直接 agentpager <命令>。

支持的 Agent

电脑上装了哪个就能遥控哪个(daemon 自动探测 PATH):

• 结构化支持(工具/diff/思考完整渲染,已有 fixture 测试):Claude Code、Codex、Qwen、CodeBuddy、Cursor(cursor-agent)。

• 基础支持(能跑、渲染朴素,backfill 完善中):Gemini、opencode —— 目前只映射文本/工具名,结构化事件待补(见 docs/refactor-todo.md A1/A2)。

• Codex 额外支持复用桌面 App / IDE 扩展自带的 codex(共享 ~/.codex 登录态)，只装 App 也能零配置用。

• Claude Code / Cursor 的桌面 App 与命令行版是两套独立登录，只装桌面 App 时会引导你装命令行版并登录一次(同账号)。

配置

daemon 开箱即用；需要时用环境变量覆盖：

| 环境变量 | 作用 | 默认 | |---|---|---| | AGENTPAGER_RELAY | 中继 WebSocket 地址(想自建中继就改这里) | wss://to50.cn/ap/ws(托管) | | AGENTPAGER_RELAY_HTTP | 中继 HTTP 基址 | https://to50.cn/ap | | AGENTPAGER_CLAUDE_BIN / AGENTPAGER_CODEX_BIN | 指定某 provider 的可执行路径 | 自动解析 | | AGENTPAGER_SESSION_IDLE_MS | 会话闲置回收阈值 | 1800000(30min) | | AGENTPAGER_CLAUDE_SANDBOX | on=给 claude 开 OS 沙箱(auto-approve 更安全;可能挡 workdir 外写盘) | 关 |

配置与配对信息存在 ~/.agentpager/。

默认连接的是维护者托管的中继。它只转发端到端加密的密封信封(见下)，看不到你的对话；但如果你更希望完全自持，把 AGENTPAGER_RELAY* 指向你自建的中继即可。

安全模型

• 端到端加密：daemon 用配对派生的通道密钥（X25519 + XSalsa20-Poly1305，基于 TweetNaCl）密封每条消息，中继只转发不透明信封、看不到也不落盘你的对话。配对密钥只在你的手机和电脑之间；~/.agentpager 目录 0700、含密钥的 config 与账本 0600。
• 🚨 配对的手机 = 本地任意执行：配对成功的手机能让 daemon 在你电脑上跑 agent，而 agent 会执行 shell / 改文件，且工具调用默认自动放行（无逐次确认）。只配对你自己的手机，配对码当密码看管。
• ⚠️ 完成推送非 E2E：任务完成通知带一小段截断请求片段（≤18 字 + 敏感过滤），为在通知里可读是明文经中继/后端/微信的。
• ⚠️ pre-1.0 安全现状：配对短码威胁模型（假定诚实中继）、重放窗口已持久化（重启保留末 1000 条;完整根治=box 内计数器,待做）等已知缺口见 SECURITY.md，尚未审计，勿托付高价值机密。

架构

手机(微信小程序)  ⇄  中继(relay, 只转发密封信封)  ⇄  daemon(本仓库, 你的电脑)  ⇄  Agent CLI

daemon 内部:core/(加密/密封信封/账本/配置/render_state reducer/传输/配对) + providers/(每家 Agent 的会话适配 + 描述符表)。服务端 reduce、客户端 dumb-render:daemon 从只增账本 reduce 出 render_state 下发,手机只渲染。详见 CONTRIBUTING.md。

开发

npm ci
npm run build          # esbuild → 单文件 dist/cli.js
npm run typecheck      # tsc --noEmit
npm run lint           # eslint
npm test               # 自洽套件(全链 e2e 见 test:integration)

贡献指南见 CONTRIBUTING.md。

License

MIT © 2026 AgentPager