第一次用iPhone跑Codex:CC Pocket最简单的连接路径与避坑清单
第一次用iPhone跑Codex:CC Pocket最简单的连接路径与避坑清单
CC Pocket 是一个开源的 Codex / Claude 移动端客户端,通过 WebSocket 桥接(Bridge Server)让你直接在 iPhone 上启动编码任务、批准操作、审查代码。你的代码始终留在自己的电脑上,不需要任何托管服务。本文给出从"零"到"手机跑通 Codex"的最短路径,并附一份新手最常踩坑的清单。
一、CC Pocket 是什么:三步理解核心架构
CC Pocket 由两部分组成,理解这一点后,后面所有连接问题都会变得简单:
CC Pocket App(手机) <-> Bridge Server(你的电脑) <-> Codex / Claude
- CC Pocket App:你手机上的操作界面,聊天、审批、看 diff 都在这里;
- Bridge Server:跑在你 Mac / Linux 电脑上的本地服务,负责连接 Codex CLI,默认监听
8765端口; - Codex / Claude:真正干活的编码代理,全程在你本机运行。
这种自托管架构的好处是:代码不出你的机器,且手机、iPad、Mac 可以无缝接续同一个会话。
二、开始前的必备清单(2分钟检查)
| 项目 | 要求 | 说明 |
|---|---|---|
| 主机 | 一台能访问你项目的 Mac / Linux | Codex 实际运行的机器 |
| Codex CLI | 已安装并已登录 | 这是新手最常漏掉的一步 |
| Node.js | ≥ 20.18.1 | Bridge Server 的运行环境 |
| CC Pocket App | App Store 安装 | 免费使用,支持 iPhone / iPad / Android |
| 网络 | 手机与电脑同一 Wi-Fi | 远程场景见下文 Tailscale 方案 |
💡 小提示:先在电脑上手动跑一次 Codex 并确认登录状态正常,再去连手机,可以省去 80% 的排查时间。
三、最快连接步骤:一条命令 + 一个二维码
1. 在电脑上启动 Bridge Server
打开终端,进入任意目录执行:
npx @ccpocket/bridge@latest
首次运行会自动下载,启动成功后终端会打印一个配对二维码。
2. 在 iPhone 上扫码连接
打开 CC Pocket App,进入连接页面扫码。App 内置了三种连接方式(扫码为官方推荐):
- 📷 扫描二维码:最快,手机和电脑同网段时通常一步到位;
- 🔍 mDNS 自动发现:同一局域网内自动搜索 Bridge;
- ✏️ 手动输入地址:输入
ws://电脑IP:8765格式的地址。
三种方式的实现可在 guide_page_connection.dart 中查看,手动输入的地址解析逻辑在 connection_url_parser.dart。
3. 选择项目,启动 Codex 会话
连接成功后,选择你的项目目录,选择 Codex 作为代理,发出第一条指令即可。任务执行中手机会实时显示流式输出,遇到需要批准的操作(如执行命令、改文件)会推送审批请求。
四、出门在外怎么办:用 Tailscale 远程跑 Codex
同网段扫码之外,官方推荐用 Tailscale 实现跨网络访问,步骤很简单:
- 在电脑和 iPhone 上都安装 Tailscale,加入同一个 tailnet;
- 在 CC Pocket 中手动输入
ws://电脑TailscaleIP:8765连接; - 从此在地铁、咖啡馆都能操作家里/公司的 Codex。
如果希望电脑长期开机托管,还可以把 Bridge 注册为后台服务(支持 macOS launchd 与 Linux systemd):
npx @ccpocket/bridge@1 setup
更多配置项(如 BRIDGE_ALLOWED_DIRS 允许访问的目录)见 packages/bridge/README.md。
五、避坑清单:新手最容易踩的 6 个坑
| # | 症状 | 原因与解法 |
|---|---|---|
| 1 | 扫码后一直连不上 | 手机和电脑不在同一 Wi-Fi(或连了 5G)。确认同网段,或改用 Tailscale |
| 2 | 提示找不到 Codex | Codex CLI 未安装或未登录。先在电脑终端跑一次 codex 确认登录态 |
| 3 | npx 报错退出 |
Node.js 版本过低。升级到 20.18.1+ 后重试 |
| 4 | Claude 会话报认证错误 | CC Pocket 默认使用 ANTHROPIC_API_KEY;想用订阅登录需显式设置 BRIDGE_ALLOW_CLAUDE_OAUTH=1 并重启 Bridge。详见 Claude 认证排查文档 |
| 5 | 怀疑环境有问题不知从哪查 | 在电脑终端执行 npx @ccpocket/bridge doctor,会像 flutter doctor 一样逐项检查本地 Bridge 环境 |
| 6 | 地铁断网,发出去的消息会丢吗 | 不会。离线期间消息会暂存、重连后自动补发;但发起新的 Agent 请求需要在线 |
⚠️ 注意:Bridge Server 启动后不要关掉那个终端窗口(除非你执行了
setup注册为后台服务),否则 App 会显示断开。
六、连上之后:手机上能做什么
- 审批中心:Codex 每次执行敏感操作都会推送审批,一键批准或拒绝;
- 回答 Agent 提问:无需打开电脑,直接在聊天里回复;
- 审查 Git 变更:逐文件看 diff,支持 stage、commit、push、revert;
- 生成媒体:用 Codex Imagegen 生成图片,视频/音频可在 App 内直接播放;
- 多设备接力:手机上开的会话,回到 Mac 或 iPad 可无缝继续,大屏上聊天、文件、Git 并排显示。
七、延伸资料
- 中文 README(完整安装说明):README.zh-CN.md
- 官方新手教程页:docs/how-to-run-codex-from-iphone-android/index.html
- 架构说明(App ↔ Bridge ↔ Agent 数据流):docs/architecture/stack.md
- 网络韧性与断线重连设计:docs/design/network-resilience-sync.md
从一条 npx @ccpocket/bridge@latest 到扫码连接,整个过程通常只要两三分钟。第一次卡住时,对照第五节的清单逐条排查,基本都能快速定位问题。



