CodexMobile
選單

Self Hosted VPS

默認由客戶部署自己的 Relay

CodexMobile 的推薦商業交付方式是：源碼保持私有，客戶拿到安裝包和部署包。現階段優先開放自托管 VPS； 托管 Relay 暫未開放。只需要普通 Codex 遠程控制的用戶，可先使用官方 ChatGPT App 連接 Mac 上的 Codex App。

VPS 要求

  • Linux VPS，建議 Ubuntu LTS。
  • Python 3.11+ 或 3.12。
  • 推薦綁定 HTTPS 域名，例如 `api.your-domain.com`；臨時測試也可以直接用 VPS IP。
  • 防火牆只開放 SSH、HTTP、HTTPS；內部 tunnel 端口綁定 `127.0.0.1`。

部署內容

  • `codexmobile-app-api`：手機端訪問入口。
  • Relay registry：管理用戶 token 和 Mac device。
  • Nginx / Caddy：域名模式走 HTTPS 反向代理；IP 測試模式走 HTTP。
  • systemd service：開機自啟和崩潰重啟。

Step By Step

VPS 自托管部署步驟

推薦

最簡方式：上傳 VPS 安裝包後執行一條命令

對外交付時，建議提供 `codexmobile-vps-版本.tar.gz`。用戶只需要把壓縮包上傳到自己的 Ubuntu VPS， 解壓後執行安裝腳本，腳本會自動安裝依賴、建立 venv、生成 Token、寫入 `.env`、啟動 systemd，並配置 Nginx。 有域名時會自動配置 HTTPS；只有 IP 時走 HTTP 測試模式。

下載 VPS 部署包 下載 Mac 桌面端 
tar -xzf codexmobile-vps-20260512.tar.gz
cd codexmobile-vps-20260512
sudo ./deploy/vps_install/install_vps.sh \
  --domain api.your-domain.com \
  --owner-email owner@example.com

沒有域名、只想先測試時，用 VPS IP 執行下面這組命令：

tar -xzf codexmobile-vps-20260512.tar.gz
cd codexmobile-vps-20260512
sudo ./deploy/vps_install/install_vps.sh \
  --host 1.2.3.4 \
  --owner-email owner@example.com \
  --no-certbot

安裝完成後，終端會輸出 API URL、App Token、Mac Token、VPS Host 和 Tunnel Port。把這些值填入 Mac 菜單欄設定， 再用配對 QR 配置 iPhone App 即可。

1. 買 VPS 並拿到 IP

DNS
  • 系統選 Ubuntu LTS。
  • 記下 VPS 公網 IP，例如 `1.2.3.4`。
  • 確認可以用 `root` SSH 登入。
  • 不要把 Mac 反向隧道端口直接暴露到公網。
ssh root@1.2.3.4

2. 選擇域名或 IP

Domain / IP

推薦方式是使用域名。到你的域名 DNS 後台新增一條 A 記錄，把 API 子域名指向 VPS IP。

主機記錄: api
記錄類型: A
記錄值: 1.2.3.4

等待解析生效後，在本機檢查：

dig +short api.your-domain.com

如果客戶暫時沒有域名，可以直接使用 VPS IP。這種方式不用 DNS，但只能作為 HTTP 測試模式。

API URL = http://1.2.3.4

3. 上傳 VPS 安裝包

Package

在你的 Mac 終端進入安裝包所在資料夾，執行下面命令。把 IP 換成自己的 VPS IP。

scp codexmobile-vps-20260512.tar.gz root@1.2.3.4:/root/

4. 在 VPS 執行一鍵安裝

Install

登入 VPS 後，複製執行下面命令。把域名和郵箱改成自己的。

cd /root
tar -xzf codexmobile-vps-20260512.tar.gz
cd codexmobile-vps-20260512
sudo ./deploy/vps_install/install_vps.sh \
  --domain api.your-domain.com \
  --owner-email owner@example.com

如果只用 IP，不用域名，執行這組命令：

cd /root
tar -xzf codexmobile-vps-20260512.tar.gz
cd codexmobile-vps-20260512
sudo ./deploy/vps_install/install_vps.sh \
  --host 1.2.3.4 \
  --owner-email owner@example.com \
  --no-certbot

安裝器會自動生成 App Token 和 Mac Token，不需要你手動生成。

Environment

核心環境變量

VPS `.env`

CODEXMOBILE_PUBLIC_API_URL=https://api.your-domain.com
CODEXMOBILE_APP_API_HOST=127.0.0.1
CODEXMOBILE_APP_API_PORT=8787
CODEXMOBILE_APP_API_TOKEN=generate-a-long-random-token
CODEXMOBILE_RELAY_DB_PATH=./data/relay.sqlite3
CODEXMOBILE_RELAY_OWNER_EMAIL=owner@example.com
CODEXMOBILE_MAC_SERVICE_URL=http://127.0.0.1:18765
CODEXMOBILE_MAC_SERVICE_TOKEN=another-long-random-token

Mac `.env` / 菜單欄

CODEXMOBILE_PUBLIC_API_URL=https://api.your-domain.com
CODEXMOBILE_APP_API_TOKEN=generate-a-long-random-token
CODEXMOBILE_MAC_SERVICE_TOKEN=another-long-random-token
CODEXMOBILE_VPS_HOST=api.your-domain.com
CODEXMOBILE_VPS_USER=root
CODEXMOBILE_VPS_TUNNEL_PORT=18765
CODEXMOBILE_PROJECT_ROOT=/Users/you/Projects

一鍵安裝會自動生成這些值；這裡只是讓你知道每個字段的用途。App API Token 和 Mac Service Token 應分開，手機端只需要 API URL 和 App API Token。 如果使用 IP 測試模式，`CODEXMOBILE_PUBLIC_API_URL` 和 `CODEXMOBILE_VPS_HOST` 分別改成 `http://1.2.3.4` 和 `1.2.3.4`。

Systemd

啟動 VPS App API

一鍵安裝已自動完成

正常情況下不需要手動寫 `.env`，也不需要手動建立 systemd 服務。安裝腳本會自動生成 Token、寫入設定、啟動 `codexmobile-app-api`。

sudo systemctl status codexmobile-app-api --no-pager
sudo journalctl -u codexmobile-app-api -n 80 --no-pager

看到 `active (running)` 代表 API 服務已啟動。沒有帶 Token 直接訪問 API 返回 `401` 是正常現象。

Reverse Proxy

用 HTTPS 暴露手機 API

一鍵安裝會自動配置 Nginx 和 HTTPS

域名解析正確時，安裝腳本會自動申請 Let's Encrypt 憑證，並把 `https://api.your-domain.com` 轉發到 VPS 本機 API。

curl -i https://api.your-domain.com/
curl -H "Authorization: Bearer replace-with-app-token" \
  https://api.your-domain.com/relay/me

第一條不帶 Token，返回 `401` 屬於正常行為；第二條需要把 `replace-with-app-token` 改成安裝完成時輸出的 App Token。

IP 測試模式的驗證方式

沒有域名時，安裝腳本會跳過 Let's Encrypt，API URL 會是 `http://1.2.3.4`。這種方式只建議測試，不建議正式交付。

curl -i http://1.2.3.4/
curl -H "Authorization: Bearer replace-with-app-token" \
  http://1.2.3.4/relay/me

如果雲廠商有安全組或防火牆，IP 模式需要放行 80 端口。正式使用仍建議改成域名 + HTTPS。

HTTPS 沒成功時再執行

sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d api.your-domain.com

如果 certbot 仍失敗，先確認域名 A 記錄已指向 VPS IP，並確認 VPS 的 80 / 443 端口沒有被雲廠商防火牆擋住。

Mac Link

把 Mac 接到這台 VPS

Mac 端需要填什麼

  • 手機連線 API URL：`https://api.your-domain.com`。
  • 手機 App Token：VPS `.env` 裡的 `CODEXMOBILE_APP_API_TOKEN`。
  • Mac 本機 Token：VPS `.env` 裡的 `CODEXMOBILE_MAC_SERVICE_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
手機 App Token = paste-app-token-here
Mac 本機 Token = paste-mac-token-here
專案根目錄 = /Users/you/Projects

自托管需要額外確認

  • Mac 部署包中的 `.env` 需要有 `CODEXMOBILE_VPS_HOST=api.your-domain.com`。
  • `CODEXMOBILE_VPS_USER` 通常是 `root`。
  • `CODEXMOBILE_VPS_TUNNEL_PORT` 默認是 `18765`；多用戶托管時每台 Mac 應分配不同端口。
  • 菜單欄點「刷新連線」後，VPS 會看到 Mac 開出的 SSH reverse tunnel。
CODEXMOBILE_VPS_HOST=api.your-domain.com
CODEXMOBILE_VPS_USER=root
CODEXMOBILE_VPS_TUNNEL_PORT=18765

IP 測試模式改成下面這樣：

CODEXMOBILE_VPS_HOST=1.2.3.4
CODEXMOBILE_VPS_USER=root
CODEXMOBILE_VPS_TUNNEL_PORT=18765

Managed Option

托管 Relay 暫未開放

等待通知

目前不接受購買或申請

托管 Relay 不需要客戶部署 VPS，未來會由服務方提供 API URL、Token 和基礎維護。但目前收費方式、設備數、 支持範圍和服務邊界仍在整理中，因此暫不開放。

現階段請使用自己的 VPS 完成自托管部署；沒有 VPS、且只需要遠程控制 Codex 的用戶，可先使用官方 ChatGPT App 連接 Mac。 需要 CodexMobile 獨立 App 或私有 Relay 時，再等待托管 Relay 後續開放通知。

暫未開放

不需要 VPS

普通遠程控制可先走官方 ChatGPT App；需要 CodexMobile 私有 Relay 時再等待托管開放。

整理中

方案未確定

收費方式、支持範圍、設備數和故障處理規則仍在整理。

最小日志

降低責任

Relay 應盡量只轉發，不長期保存客戶代碼、截圖、附件和對話內容。