# CodexMobile

`CodexMobile` 是一个面向手机远程控制桌面 Codex Live 会话的移动端与桌面桥接产品。

目标：
- 你在电脑前时继续直接用 Codex
- 你离开电脑后，通过 iPhone App 连接 Mac 桌面端继续工作
- 任务状态、进度、补充要求都保存在独立项目里

## 当前商业交付方式

CodexMobile 当前不按“公开源码项目”发布。推荐交付形态是：

- 源码保持私有
- iPhone App 通过 TestFlight / App Store / 受控测试安装方式交付
- Mac 菜单栏客户端通过 `.dmg` 或 `.pkg` 安装包交付
- VPS Relay 默认由客户自托管
- 客户没有 VPS 或不想维护服务器时，可购买托管 Relay，由服务方提供 API URL 和 Token

用户侧核心配置入口：

- 手机端设置：API URL、Token、默认项目文件夹
- Mac 菜单栏设置：API URL、App Token、Mac Service Token、项目根目录、默认 Live 目录、开机启动、自动连接、保持唤醒

官网内容位于 `site/`，当前文案按“安装包交付 + 自托管优先 + 可选托管 Relay”撰写。

## Remodex 方向可靠性基线

CodexMobile 现在按「手机端远程控制桌面 agent」方向收敛，核心原则是：手机端不另起一条孤立任务线，而是尽量保持与桌面 Codex live 会话同源、同 thread、同 runtime state。

已经纳入自动化契约测试的能力包括：

- QR 配对与托管 relay 配置
- Mac 菜单栏 trusted reconnect
- 附件作为同一轮 turn input 发送
- 桌面端模型、推理、权限、额度、时区同步到手机端
- snapshot merge 防止自动跳项目、旧内容覆盖和 optimistic 消息丢失
- handoff to Mac app
- 处理中追加消息和 follow-up queue
- 停止、修改并重送、删除最近一轮
- 任务清单、文件变更、审批卡片同步显示

详细验收清单见：

- `docs/remodex_parity_checklist.md`
- `docs/codexmobile_multi_user_relay.md`

商业交付检查见：

- `docs/COMMERCIAL_DISTRIBUTION.md`
- `SECURITY.md`

发布或打包前建议执行：

```bash
node scripts/test_snapshot_merge.mjs
node scripts/test_mobile_runtime_contract.mjs
node scripts/test_remodex_parity_contract.mjs
cd mobile && npm run typecheck
cd .. && python3 -m compileall src
```

## 第一版范围

第一版先建立这些能力的骨架：
- Telegram 命令入口
- 任务状态持久化
- worker 调度循环
- 安全边界明确的执行器接口

当前命令预留：
- `/help`
- `/start`
- `/help_zh`
- `/help_voice`
- `/diagnose_zh`
- `/status`
- `/status GlobeRelay`
- `/continue`
- `/tasks`
- `/newtask`
- `/switchtask`
- `/pause`
- `/note`
- `/run`
- `/confirmrun`
- `/cancelrun`
- `/approve`
- `/reject`
- `/setworkdir`
- `/settitle`
- `/notes`
- `/queue`
- `/progress`
- `/history`
- `/tail`
- `/agent`
- `/reset`

也支持：
- 直接发送普通文字
- 直接发送 Telegram 语音消息
- 中文自然语言不要加 `/`
- 常见繁体中文说法也支持

## 目录结构

```text
CodexMobile/
  src/codexbot/
    config.py
    main.py
    models.py
    state_store.py
    worker.py
    telegram_bot.py
  data/
  .env.example
  README.md
```

## 启动

1. 创建虚拟环境并安装：

```bash
cd <repo-root>
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .
```

要求：
- Python 3.11+

2. 复制环境变量：

```bash
cp .env.example .env
```

3. 填入：
- `TELEGRAM_BOT_TOKEN`
- `TELEGRAM_ALLOWED_USER_IDS`
- `OPENAI_API_KEY`

4. 启动：

```bash
codexmobile
```

## VPS 部署

项目里附带了一个 `systemd` 服务文件：
- `deploy/codexmobile.service`
- `deploy/codexmobile-app-api.service`
- `deploy/com.codexmobile.mac-service.plist`
- `deploy/com.codexmobile.mac-tunnel.plist`
- `deploy/com.codexmobile.desktop-bridge.plist`

推荐部署目录：
- `/opt/CodexMobile`

部署后可用：

```bash
systemctl daemon-reload
systemctl enable --now codexmobile
systemctl status codexmobile
```

更新凭证：

```bash
cd /opt/CodexMobile
vim .env
systemctl restart codexmobile
```

## Mac 常驻服务

本项目现在支持一个 Mac 本地常驻控制服务：

- 运行入口：`codexmobile-mac-service`
- 认证：`CODEXMOBILE_MAC_SERVICE_TOKEN`
- 监听地址：`CODEXMOBILE_MAC_SERVICE_HOST` + `CODEXMOBILE_MAC_SERVICE_PORT`
- VPS 侧接入地址：`CODEXMOBILE_MAC_SERVICE_URL`

推荐流程：

1. 在 Mac 上复制 `.env.example` 为 `.env`
2. 设置：
   - `CODEXMOBILE_MAC_SERVICE_TOKEN`
   - `CODEXMOBILE_MAC_SERVICE_HOST`
   - `CODEXMOBILE_MAC_SERVICE_PORT`
3. 本地启动：

```bash
cd <repo-root>
source .venv/bin/activate
codexmobile-mac-service
```

4. 在 VPS 的 `/root/CodexMobile/.env` 设置：
   - `CODEXMOBILE_MAC_SERVICE_URL`
   - `CODEXMOBILE_MAC_SERVICE_TOKEN`

说明：
- 如果 VPS 需要访问 Mac，本地服务必须对 VPS 可达
- 可通过内网、Tailscale、端口映射或反向代理暴露该地址
- 当前仓库也提供了一个基于 SSH 反向隧道的 `launchd` 模板，把 Mac 的 `127.0.0.1:8765` 转发到 VPS 的 `127.0.0.1:18765`

如果你经常带着 MacBook 切换网络，建议使用新的 Mac 客户端：

- 命令入口：`codexmobile-mac-client`
- 查看状态：

```bash
cd <repo-root>
source .venv/bin/activate
codexmobile-mac-client status
```

- 换网络后刷新：

```bash
cd <repo-root>
source .venv/bin/activate
codexmobile-mac-client refresh
```

这个命令会一起重启：

- `com.codexmobile.mac-service`
- `com.codexmobile.mac-tunnel`
- `com.codexmobile.desktop-bridge`

也就是说，你换到新的 Wi‑Fi 或热点后，只要在 Mac 上执行一次 `codexmobile-mac-client refresh`，就能把本地服务和反向隧道一并拉起来。

现在也提供了带图标的 Mac 菜单栏客户端：

- 应用位置：`dist/CodexMobile Menu Client.app`
- 菜单项：
  - `開機自動啟動`
  - `自動連線`
  - `保持 Mac 醒著（防止斷線）`
  - `手動關停連線`
  - `刷新連線`
  - `設定`
  - `查看狀態`

说明：

- `開機自動啟動`：控制这个菜单栏应用是否会在重开 Mac 后自动载入
- `自動連線`：控制换网络后是否自动检查并恢复 Mac 本地服务与 SSH 反向隧道
- `保持 Mac 醒著（防止斷線）`：在 `自動連線` 开启期间向 macOS 请求防止闲置睡眠和屏幕睡眠，减少手机端远程连接中断；MacBook 合盖后的行为仍以 macOS 当前硬件、电源和合盖策略为准
- `手動關停連線`：会停止当前本地服务和隧道，并同步关闭 `自動連線`
- `設定`：可以直接修改 `.env` 裡的 CodexMobile API URL、App API Token、Mac Service Token、專案根目錄與預設 Live 目錄；保存後會自動刷新連線

推荐用法：

1. 平时打开 `開機自動啟動`
2. 需要长期保持可远程连接时打开 `自動連線` 和 `保持 Mac 醒著（防止斷線）`
3. 临时不想让它继续重连时，先关闭 `自動連線`，或直接点 `手動關停連線`

## 手机 App 第一版

仓库里现在也附带了一个 React Native 手机端：

- 目录：`mobile/`
- 入口：`mobile/App.tsx`
- 目标：通过聊天式界面继续 Mac 端任务，而不是只靠 Telegram 命令

配套的移动端 API：

- 启动入口：`codexmobile-app-api`
- 部署服务文件：`deploy/codexmobile-app-api.service`
- 认证：`CODEXMOBILE_APP_API_TOKEN`
- 监听地址：`CODEXMOBILE_APP_API_HOST` + `CODEXMOBILE_APP_API_PORT`

当前 App 第一版包含：

- 对话页
- 任务页
- 状态页
- 连接配置（API URL / API Token）

## 现在这版是什么状态

这版是“可扩展骨架”，已经具备：
- 启动 Telegram bot
- 读取/保存任务状态
- 接收基础命令
- 维护当前任务的运行状态
- 后台轮询处理 note
- 通过 `cmd: ...` 执行 allowlist 内命令
- 对 allowlist 外命令进入审批流
- 对自然语言 note 调用 OpenAI planner 生成下一步命令
- 对部分复合中文请求调用 OpenAI 意图解析器拆成多步操作

命令执行约定：
- `/note cmd: pwd`
- `/run pwd`
- `/note cmd: ls -la`
- `/note cmd: python3 -m pytest`
- `/note 帮我先看一下当前目录结构并总结项目状态`
- `/setworkdir /root/CodexMobile`
- `/agent on`
- `/newtask 重构 Telegram 命令流`
- `/switchtask abc12345`
- `/switchtask openclaw`
- `/queue`
- `/progress`
- 直接发语音：“帮我先检查一下当前目录”
- 直接发语音：“运行 pwd”
- 直接发语音：“查看当前路径”
- 直接发语音：“列出目录”
- 直接发语音：“运行测试”
- 直接发语音：“看看任务状态”
- 直接发文字：“查看 GlobeRelay 的状态”
- 直接发语音：“新建任务 重构 worker”
- 直接发语音：“切换到任务 abc12345”
- 直接发语音：“确认执行”
- 直接发语音：“看看最近输出”
- 直接发语音：“看看历史”
- 直接发语音：“看看待审批命令”
- 直接发语音：“批准命令”
- 支持一部分复合中文请求，例如：“看看最近输出，如果有报错就总结一下”
- 语音识别成命令后，需要 `/confirmrun` 才会真正执行
- allowlist 外命令会进入 `waiting_approval`
- 发送 `/approve` 后会执行刚才那条待审批命令
- 发送 `/reject` 可丢弃待审批命令

额外行为：
- worker 在关键事件上会主动发 Telegram 通知
- 状态存储支持多任务切换，当前活跃任务由 `/switchtask` 决定
- `/switchtask` 除了支持 task id，也支持按任务标题匹配，例如 `openclaw`
- `/status` 也支持直接查询指定任务，例如 `/status GlobeRelay` 或 “查看 GlobeRelay 的状态”

还没有接入真正的“持续编码代理”。下一步会补：
- 模型调用
- 自动规划多步任务
- 更细的权限策略
- 流式进度回报
- 更完整的审批流
