第一次用iPhone跑Codex:CC Pocket最简单的连接路径与避坑清单

原创2026-10-15 09:33:021,767 阅读
文章标签:人工智能AI Agent移动开发代码智能体后端

第一次用iPhone跑Codex:CC Pocket最简单的连接路径与避坑清单

CC Pocket 是一个开源的 Codex / Claude 移动端客户端,通过 WebSocket 桥接(Bridge Server)让你直接在 iPhone 上启动编码任务、批准操作、审查代码。你的代码始终留在自己的电脑上,不需要任何托管服务。本文给出从"零"到"手机跑通 Codex"的最短路径,并附一份新手最常踩坑的清单。

CC Pocket 安装横幅:一条命令启动 Bridge Server,扫码即可连接手机

一、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 可以无缝接续同一个会话。

CC Pocket 官网截图:用手机控制 Codex 与 Claude 编码会话

二、开始前的必备清单(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 作为代理,发出第一条指令即可。任务执行中手机会实时显示流式输出,遇到需要批准的操作(如执行命令、改文件)会推送审批请求。

CC Pocket iPad 工作区:会话聊天与 Git 代码差异并排显示

四、出门在外怎么办:用 Tailscale 远程跑 Codex

同网段扫码之外,官方推荐用 Tailscale 实现跨网络访问,步骤很简单:

  1. 在电脑和 iPhone 上都安装 Tailscale,加入同一个 tailnet;
  2. 在 CC Pocket 中手动输入 ws://电脑TailscaleIP:8765 连接;
  3. 从此在地铁、咖啡馆都能操作家里/公司的 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 并排显示。

CC Pocket 多语言应用界面截图:会话列表、编码会话与任务规划

七、延伸资料

从一条 npx @ccpocket/bridge@latest 到扫码连接,整个过程通常只要两三分钟。第一次卡住时,对照第五节的清单逐条排查,基本都能快速定位问题。

登录后查看全文
ccpocket