CodexMobile

Remote Codex Workflow

用手機接續 Mac 上的 Codex Live 會話

CodexMobile 把 iPhone、Mac 菜單欄與 VPS Relay 串成同一條工作流。 你離開電腦後，仍能查看桌面端會話、補充需求、處理審批、截圖回傳，並在回到 Mac 後接續同一個 Codex 專案上下文。

開始安裝 查看 VPS 部署
  • 手機端不另起任務線，盡量與桌面端同源
  • 支援 Mac 菜單欄、桌面 Bridge、VPS App API Relay
  • 面向開源整理，附靜態網站、部署範本與說明
CodexMobile 已連線
You

幫我在 webhook 入口加上更完整的錯誤處理。

Codex 14:23
Processing steps 2.3s

我會先補 try/catch、輸入驗證與統一錯誤回應，再把修改過的檔案摘要同步到手機端。

2 個文件已更改 +19 -2
src/api/webhook.ts +8 -2
src/utils/validation.ts +11
發送訊息給 Codex…
GPT-5.4 中 完全訪問權限

Core Capabilities

不是遠端桌面，而是遠端接續同一個 Codex 工作流

同一條會話上下文

手機端以桌面 Bridge 的 thread / project / runtime 為準，不再維護一條分叉任務線。

Mac 菜單欄常駐

提供開機自啟、自動連線、重新檢查連線、保持喚醒與桌面截圖回傳等常用操作。

VPS Relay 中轉

手機先連到 App API，再由 VPS Relay 轉回 Mac 本機服務，適合帶著 MacBook 移動辦公。

文件與審批同步

手機端可查看文件變更、審批卡片、處理中的步驟資訊，並嘗試與桌面端顯示對齊。

Architecture

三段式架構：手機 App、VPS Relay、Mac 本機服務

iPhone

CodexMobile App

顯示桌面端會話、輸入訊息、處理審批、管理附件與桌面截圖預覽。

→
VPS

App API / Relay

驗證 Token、轉發手機端請求、暴露對外域名，並保持手機可從外網連回桌面端。

→
Mac

Desktop Bridge

對接 Codex app-server 與 Mac 本機服務，把 thread、runtime、檔案變更與狀態同步給手機端。

Install

本地安裝

Python 服務

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

啟動服務

source .venv/bin/activate
codexmobile
codexmobile-app-api
codexmobile-mac-service

核心環境變數包含：CODEXMOBILE_APP_API_TOKEN、 CODEXMOBILE_MAC_SERVICE_TOKEN、 CODEXMOBILE_PUBLIC_API_URL。

Deploy

VPS 部署建議

1. 代码目录

sudo mkdir -p /opt/CodexMobile
sudo chown -R $USER:$USER /opt/CodexMobile
cd /opt/CodexMobile

2. systemd

仓库已附带这些服务文件，可直接纳入部署：

  • deploy/codexmobile.service
  • deploy/codexmobile-app-api.service
  • deploy/com.codexmobile.mac-service.plist
  • deploy/com.codexmobile.desktop-bridge.plist

3. Nginx 静态站点

sudo mkdir -p /var/www/codexmobile-site
sudo rsync -av site/ /var/www/codexmobile-site/
sudo cp deploy/codexmobile-site.nginx.conf /etc/nginx/sites-available/codexmobile-site
sudo ln -s /etc/nginx/sites-available/codexmobile-site /etc/nginx/sites-enabled/codexmobile-site
sudo nginx -t && sudo systemctl reload nginx

Workflow

使用流程

  1. 在 Mac 上启动 CodexMobile 菜单栏与本机服务。
  2. 在 VPS 上启动 App API / Relay，对外暴露域名。
  3. 在手机端填入 API URL 与 Token，或直接扫描 Mac 配对 QR。
  4. 在外出时通过手机查看桌面端项目会话、追加需求、处理中断、审批与截图。
  5. 回到 Mac 后，从相同项目与 thread 继续工作。

Open Source

這個網站是靜態文件，可直接放到 VPS 或任何靜態主機

如果你準備公開倉庫，建議先清理預設路徑、Token、日誌與本機構建產物，再把這個站掛到專案域名上作為首頁與安裝說明入口。

閱讀 README 查看安裝步驟