站点图标 高效码农

手机秒变编码遥控器！一条命令让Pocket Server远程代理随时待命

高效码农

把 Claude 装进手机：Pocket Server 让本地/远程编码代理随时待命

“

核心问题：如何只用一个手机 App 和一条命令，就把家里的电脑变成可远程操控的“编码助理”，同时还能在手机里获得媲美桌面的终端、文件编辑与搜索体验？

”

1. 产品速写：Pocket Server 到底是什么？

一句话回答：它是跑在你电脑上的“小服务器”，通过局域网或临时公网隧道，把手机变成随身编码驾驶舱。

能力 一句话解释 典型场景
本地编码代理 在电脑执行 bash、编辑文件、搜索网页 地铁里改脚本，回到工位继续跑
移动优先终端 多标签、流式回显、触摸优化 重启 Docker 容器、tail 日志
文件浏览器+Diff 即时查看、编辑、对比文件 审核自动生成的 PR diff
云后台任务 GitHub 仓库一键上云 VM，异步跑任务 让代理夜里帮你补全单元测试
通知中心 可选推送，任务完成即提醒 长时间训练模型，手机收到 Done

2. 安装：一条脚本，Node 都不用装

官方推荐的一行命令会：

  1. 把预编译二进制下载到 ~/.pocket-server/bin
  2. 内置 Node v22.18.0，系统无 Node 也能跑
  3. 自动把 CLI 软链到 PATH，装完即可 pocket-server --help
curl -fsSL https://www.pocket-agent.xyz/install | bash

“

反思：我最初用源码起服务，结果系统 Node 版本冲突导致 WebSocket 握手失败。改用官方 Bundle 后，一切“开箱即用”——把运行时打进发布包，确实能省掉一堆“在我机器上明明可行”的锅。

”

3. 三步上手：配对→启动→连接

核心问题：手机跟电脑“第一次握手”到底要干什么？

步骤 电脑端 手机端 注意
① 配对 pocket-server pair 打开 App → 输入 6 位 PIN 必须在同一局域网
② 启动 pocket-server start App 点“连接” 默认端口 3000
③ 远程 pocket-server start --remote 粘贴 Cloudflare URL 每次重启 URL 会变

配对成功后，服务器会在 ~/.pocket-server/data 生成设备密钥，后续短寿令牌都从它派生，手机无需再输 PIN。

4. 桌面也能“蹭”终端：无配对附加

核心问题：我在自己电脑上写代码，还想把刚才手机里的终端会话捞回来，需要再扫码吗？——完全不用。

Pocket Server 在本地文件系统里留了一把“本地钥匙”：~/.pocket-server/data/runtime/local-ws.key。CLI 用它直接 WebSocket 进去，命令如下：

# 先列出会话
pocket-server terminal sessions

# 按序号或名字附加
pocket-server terminal attach 2
pocket-server terminal attach --name "Opencode"

“

场景：我在地铁上用手机跑 make test，到公司后笔记本一条 attach，终端画面瞬间同步，继续调试，无需重新执行命令，也不影响手机端标签。

”

5. 深度拆解：核心功能与事件驱动架构

核心问题：手机 App 只是“显示器”，真正的大脑在哪？——全部在服务器端，对话、文件、会话、通知都持久化到 ~/.pocket-server/data，App 只负责订阅事件流。

5.1 API 总览（REST + WebSocket）

前缀 用途 示例
/ws 主事件流 手机、桌面 CLI 均连此
/auth/* 配对与令牌 生成、校验、刷新
/agent/* 会话生命周期 新建、恢复、终止
/fs/* 文件系统 读、写、diff、搜索
/notifications/* 设备通知 推送任务结果
/cloud/* 云 VM 后台 GitHub → VM → 代理执行

5.2 事件流举例

服务器把每条 stdout、文件变更、任务状态都包装成 JSON Event，客户端订阅后即时渲染。好处：

  • 手机断网重连，服务器会把遗漏事件补推
  • 多终端同时在线，看到的终端状态完全一致
  • 无需轮询，100 ms 内延迟即可感知输出

6. 场景演练：把 GitHub 仓库扔给“云代理”跑单测

核心问题：电脑关机，也能让 Pocket 帮我在云端跑任务吗？——可以，借助 /cloud/* 接口。

操作路径（手机端可视化，背后是这些调用）：

  1. 选仓库 → 选分支 → 填入口脚本（如 npm test）
  2. 服务器调用云 VM 接口，拉镜像 → 克隆 → 执行
  3. VM 里 stdout 实时回传，手机端像看本地终端
  4. 运行完生成 diff，服务器自动评论到 PR
  5. 结果推送到手机通知中心

“

学到的教训：第一次跑时我选了 2 vCPU 的免费 VM，测试大型仓库耗时 18 min，后来改 4 vCPU，时间减半。成本与速度权衡，在移动场景下其实更贵的是“人的等待时间”。

”

7. 安全模型：本地 PIN + 短寿令牌 + 无状态 App

核心问题：手机丢了，别人是不是就能远程删我代码？——不会，因为：

  • 配对只在局域网，PIN 一次性，用完即失效
  • HTTP/WS 令牌默认 60 min 过期，服务器重启即刷新
  • 手机端不存对话数据，拿到手机也看不到历史
  • 远程隧道是 Cloudflare Quick Tunnel，随机子域名，重启即变

若仍不放心，可随时 pocket-server stop 或删目录 rm -rf ~/.pocket-server，所有会话与密钥一并清除。

8. 多平台与更新策略

平台 架构 说明
macOS arm64 / x64 含 Apple Silicon & Intel
Linux x64 测试过 Ubuntu 20+、Debian 11、Arch

更新命令与安装同一路径：

pocket-server update   # 重新拉 latest.json 并自升级

“

反思：早期我用 Homebrew 自己管理 Node，结果系统升级后 nvm 失效，服务起不来。官方把 Node 打进发布包，确实让“升级操作系统”不再等于“踩坑日”。

”

9. 常见踩坑与排查表

症状 最可能原因 快速验证/解决
手机连不上 3000 防火墙 nmap -p 3000 <host> 看是否 open
PIN 输入后仍离线 不在同网段 检查子网掩码、关闭 AP 隔离
远程 URL 突然 404 Cloudflare 隧道重启 重新 start --remote 复制新地址
attach 后无输出 会话已关 sessions 列表若状态 exited，需新建

10. 实用摘要 / 一页速览

  1. 装：curl -fsSL https://www.pocket-agent.xyz/install | bash
  2. 配：pocket-server pair → 手机输 PIN
  3. 起：pocket-server start（本地）或加 --remote（公网）
  4. 连：App 点连接 → 多标签终端、文件、搜索、通知一把抓
  5. 云：GitHub 仓库 → 云 VM → 结果回传手机 + PR 评论
  6. 桌面：terminal attach 无需再配对，直接续手机会话
  7. 升：pocket-server update 一键到最新
  8. 卸：rm -rf ~/.pocket-server 全部清退

11. FAQ（可检索短句）

  1. Pocket Server 必须一直联网吗？
    本地局域网可独立使用；远程需 Cloudflare 隧道。
  2. 手机端 App 是否开源？
    本文档仅涵盖开源的 Server 部分；App 未提及源码。
  3. 支持 Windows 吗？
    当前发布包仅 macOS & Linux；Windows 可尝试 WSL2。
  4. 可以同时几部手机配对？
    文档未限制数量，每部手机独立设备密钥。
  5. 服务器默认端口能改吗？
    可以，pocket-server start --port 8080 或设环境变量 PORT。
  6. 令牌过期能自动续吗？
    需客户端调用 /auth/refresh，App 会在后台刷新。
  7. 云 VM 费用谁承担？
    文档未说明，推测为官方托管或自带云账户。
  8. 卸载会删除代码文件吗？
    不会，只删 ~/.pocket-server 内的会话与密钥，不影响项目目录。

“

写在最后：Pocket Server 把“本地优先”与“移动体验”做了罕见结合——大脑留在电脑，交互延伸到口袋。它并不试图替代 IDE，而是让你“离开键盘”时依旧能对代码说话：查看、轻改、授权、追踪。对常在路上、又舍不得关机的开发者，这也许是目前最轻量的“随身运维”答案。

”

退出移动版