CodexMobile
選單

Install

安裝手機端和 Mac 菜單欄

Codex 現在可以通過官方 ChatGPT 手機 App 連接 Mac 端。CodexMobile 仍以安裝包方式交付， 主要服務於自托管 VPS Relay、私有 Token、獨立 App 和客戶化部署。托管 Relay 暫未開放，後續另行通知。

Step 1

選擇連接方式

普通遠程控制可走官方 ChatGPT App；需要自托管、私有 Relay 或獨立 App 時，走 CodexMobile。

Step 2

安裝 Mac 客戶端

安裝 CodexMobile 菜單欄，檢查 Codex App、保持 Mac 醒著，並配置自托管 Relay 參數。

Step 3

安裝 iPhone App

通過公開 TestFlight 連結安裝，掃描 Mac 配對 QR 或手動輸入 API URL / Token 後測試連線。

加入 TestFlight 下載 Mac 桌面端 下載 VPS 部署包 查看使用流程

Downloads

桌面端下載

Mac

CodexMobile Mac 桌面端安裝包

下載後解壓，把整個資料夾移到固定位置，例如 `~/CodexMobile`。第一次使用先雙擊 `install_mac.command`， 它會建立 Python 環境、安裝本機服務、建立 LaunchAgent，再打開菜單欄 App。

使用前請先確認 Mac 已安裝最新版 Codex App。菜單欄會檢查 Codex CLI、Codex App、Remote Control 和 ChatGPT Remote Ready； 也會保留 CodexMobile 自托管所需的 app-server、desktop bridge 和 VPS Relay 診斷。

下載 Mac 桌面端 ZIP 下載 VPS 部署包 
下載文件: codexmobile-mac-20260515.zip
解壓位置: ~/CodexMobile
首次執行: install_mac.command
打開 App: dist/CodexMobile Menu Client.app

如果 macOS 提示無法打開未驗證開發者的 App，進入「系統設定」→「隱私與安全性」，允許打開 CodexMobile。

Mac Client

Mac 菜單欄需要配置什麼

連線參數

  • API URL：推薦使用 `https://api.your-domain.com`；臨時測試也可以使用 `http://1.2.3.4`。
  • App API Token：手機端也會使用的 token，用於 Relay 認證。
  • Mac Service Token：Mac 本機服務專用 token，應與 App Token 分開。
  • 公開 API URL：生成手機配對 QR 時寫入手機端，通常與 API URL 一致。

本機參數

  • 專案根目錄：手機端顯示項目和新建項目的桌面根位置，例如 `/Users/you/Projects`。
  • OpenAI API Key：只用於手機端語音轉文字等輔助能力，不替代桌面 Codex 登入狀態。
  • Codex 診斷：檢查 Codex CLI、Codex App、Remote Control 和 ChatGPT Remote Ready。
  • 開機自啟、自動連線與保持喚醒：同時服務 CodexMobile 和官方 ChatGPT 遠程連接。

官方 ChatGPT 連接

  • 打開最新版 Codex App，並登入同一個 ChatGPT 帳號和 workspace。
  • 在 Codex App 側邊欄選「Set up Codex mobile」。
  • 用手機掃 QR，跳到 ChatGPT App 完成連接。
  • Mac 必須保持醒著、在線，且 Codex App 持續運行。

配對手機

  • 在 Mac 菜單欄點「顯示手機配對 QR」。
  • 用 iPhone 系統相機掃描 QR。
  • 手機 App 會自動填入 API URL 和 Token。
  • 點「測試連線」，確認手機能連到 Relay。

日常控制

  • 刷新連線：換 Wi-Fi 或手機連不上時使用。
  • 保持 Mac 醒著：長時間外出遠程使用時打開。
  • 查看狀態：定位是 VPS、Mac service、desktop bridge 還是 Codex 版本出問題。
  • 檢查 Codex 版本與 Remote Control：確認本機 Codex 是否已具備新版遠程控制能力。
  • 手動關停連線：不需要遠程接入時關閉本機服務。

Desktop Setup

桌面端菜單欄安裝步驟

第一次使用時，先拿到 VPS 安裝完成後輸出的 5 個值：API URL、App Token、Mac Token、VPS Host、Tunnel Port。 下面每一步都可以直接照做。

1. 保存 VPS 輸出的資料

Info

VPS 一鍵安裝完成後會顯示這些值。先保存，後面要填到 Mac 和 iPhone。

API URL: https://api.your-domain.com
App Token: paste-app-token-here
Mac Token: paste-mac-token-here
VPS Host: api.your-domain.com
VPS User: root
Tunnel Port: 18765

如果客戶暫時沒有域名，只用 VPS IP 測試，保存下面這組值：

API URL: http://1.2.3.4
App Token: paste-app-token-here
Mac Token: paste-mac-token-here
VPS Host: 1.2.3.4
VPS User: root
Tunnel Port: 18765

2. 安裝 Mac 菜單欄

Mac
  • 把 CodexMobile 桌面部署包解壓到固定位置，例如 `~/CodexMobile`。
  • 打開 `CodexMobile Menu Client.app`。
  • 如果 macOS 阻擋未公證 App，按系統提示到「隱私與安全性」允許打開。
  • 第一次打開後，菜單欄會出現 CodexMobile 圖標。
  • 點「檢查 Codex 版本與 Remote Control」，確認 Codex CLI、Codex App 和 ChatGPT Remote Ready 狀態。
  • 如果要使用官方 ChatGPT 遠程連接，點「打開 Codex App」後按 Codex App 內的手機連接流程操作。

3. 打開設定並填資料

Settings
  • 點菜單欄 CodexMobile 圖標。
  • 點「設定」。
  • 把 VPS 安裝器輸出的 API URL、App Token、Mac Token 填進去。
  • 專案根目錄填你放代碼項目的資料夾，例如 `/Users/you/Projects`。
手機連線 API URL = https://api.your-domain.com
手機 App Token = paste-app-token-here
Mac 本機 Token = paste-mac-token-here
專案根目錄 = /Users/you/Projects

IP 測試模式時，手機連線 API URL 改成 `http://1.2.3.4`。

手機連線 API URL = http://1.2.3.4
手機 App Token = paste-app-token-here
Mac 本機 Token = paste-mac-token-here
專案根目錄 = /Users/you/Projects

4. 自托管 VPS 補三行

Self Host

如果桌面包沒有預先寫好 VPS Host，點「打開 .env」，確認或補上下面三行。

CODEXMOBILE_VPS_HOST=api.your-domain.com
CODEXMOBILE_VPS_USER=root
CODEXMOBILE_VPS_TUNNEL_PORT=18765

IP 測試模式時，VPS Host 直接填 IP。

CODEXMOBILE_VPS_HOST=1.2.3.4
CODEXMOBILE_VPS_USER=root
CODEXMOBILE_VPS_TUNNEL_PORT=18765

5. 啟動桌面連線

Connect
  • 打開「自動連線」。
  • 需要長時間用手機接續工作時，打開「保持 Mac 醒著」。
  • 點「刷新連線」，菜單欄會啟動 Mac service、desktop bridge 和 SSH reverse tunnel。
  • 點「查看狀態」確認本機服務、Relay、桌面橋接與 Codex 版本診斷均正常。

6. 配對 iPhone

Pair
  • 在菜單欄點「顯示手機配對 QR」。
  • 用 iPhone 系統相機掃描 QR，CodexMobile 會自動帶入 API URL 和 Token。
  • 進入手機 App 設定頁，點「測試連線」。
  • 測試通過後即可在手機端查看項目、對話、圖片和文件預覽。

如果「查看狀態」顯示 tunnel 異常，先確認 VPS Host、VPS User、Tunnel Port 是否填對，再點一次「刷新連線」。 托管 Relay 暫未開放；目前對外測試建議先使用自己的 VPS 完成自托管部署。

iPhone App

手機端只保留必要設置

連線與設定

  • API URL：自托管 VPS Relay 地址。
  • Token：自托管部署時生成。
  • Face ID：可選開啟，每次重新打開 App 時先驗證再進入。
  • 測試連線：保存前先確認 token 和網路可用。

使用能力

  • 查看和接續 Mac Codex Live 會話。
  • 發送補充需求、追加消息、停止當前回合。
  • 查看任務清單、文件變更、審批卡片、生成圖片和桌面截圖。
  • 回到 Mac 後打開同一個項目和 thread。

After Install

下一步：部署自己的 VPS

如果客戶有 VPS，按部署頁配置自托管 Relay。托管 Relay 暫未開放，後續會在官網公布開放時間和方案。

查看 VPS 部署 查看完整使用流程