内容
# ChatGPT mcp Codex
作者：JNSLayer2
ChatGPT mcp Codex 是一個本地 MCP 中樞，讓 ChatGPT 透過 MCP 派任務給本機 Codex worker，結果回到 review queue。
## 為什麼要用 ChatGPT mcp Codex
ChatGPT mcp Codex 的核心邏輯，是讓使用者在 ChatGPT 裡規劃與探討任務，確認無誤後，直接在同一個聊天窗調用 Codex 執行。
這樣可以大幅減少 Codex 額度消耗，也能避免在 ChatGPT 與 Codex 兩個聊天窗之間來回溝通的精神成本。
建議先在 ChatGPT 聊天窗設定你的使用規則，例如：
```text
開啟 codex mcp 時，調用 codex mcp 必須我授權，否則一律當作正在聊天探討。
```
這樣 ChatGPT 在討論時就不會突然調用 MCP。完整說明請看 `docs/article.md`。
## 架構圖
```text
ChatGPT Web
↓
HTTPS tunnel
↓
使用者自己的 localhost MCP Hub
↓
使用者自己的 Codex worker
↓
review queue / audit / dashboard
```
## 60 秒 Quickstart / 一鍵本地安裝
Fresh clone 後先跑一條命令，會建立 `.venv`、安裝依賴、產生 ignored 的 `.env` / `.codex/config.toml`、初始化本地 SQLite/demo repo、匯出 schemas、跑 doctor 與測試：
```bash
git clone https://github.com/JNSlayer2/chatgpt-mcp-codex.git
cd chatgpt-mcp-codex
python3 -m scripts.install_local --smoke
```
`--smoke` 會臨時啟動 Hub 並跑 fake-exec roundtrip，不需要 Codex 額度；若只想安裝不跑 smoke，可省略 `--smoke`。
日常啟動仍分兩個 Terminal，方便看 log 與停止：
第一個 Terminal：
```bash
python3 -m scripts.up
```
第二個 Terminal：
```bash
python3 -m scripts.run_codex_worker --loop --fake-exec
```
第三個 Terminal，可選，只有要接 ChatGPT Web 才需要：
```bash
cloudflared tunnel --url <LOCAL_HUB_BASE_URL>
```
## 本地 URL
Dashboard:
```text
<LOCAL_HUB_BASE_URL>/
```
Health:
```text
<LOCAL_HUB_BASE_URL>/healthz
```
Local MCP URL:
```text
<LOCAL_HUB_BASE_URL>/mcp
```
實際本機位址請在你的電腦執行 `python3 -m scripts.print_mcp_info` 查看；repo 文件只保留佔位，避免把本機細節寫死在 GitHub。
## ChatGPT Connector 要填什麼
Connector name:
```text
ChatGPT mcp Codex
```
Description:
```text
Local MCP Hub for task queue, Codex worker dispatch, review queue, approval, and audit.
```
MCP Server URL:
```text
https://<YOUR_TUNNEL_URL>/mcp
```
Auth:
```text
No auth / 無驗證，僅建議用於本機 dev/test。
```
你也可以自己命名 connector，例如 `Home M4 Hub`、`Office iMac Hub`、`Personal MCP Hub`。
## HTTPS 方案怎麼選
有兩條路：
- 免費臨時網址：用 Cloudflare Quick Tunnel，最快可用，但重開 tunnel 後 URL 可能改變。
- 自備網域固定網址：用 Cloudflare named tunnel + 自己的子網域，ChatGPT connector 通常只要設定一次。
如果你有自己的網域，建議每台電腦用不同子網域，例如：
```text
https://mcp-device.<YOUR_DOMAIN>/mcp
https://mcp-home.<YOUR_DOMAIN>/mcp
https://mcp-office.<YOUR_DOMAIN>/mcp
```
不要把裝置名稱放在 URL path，也不要使用空格。裝置名稱放在 ChatGPT connector name，MCP Server URL 保持 `/mcp` 結尾。完整說明請看 `docs/tunnel-options.md`。
## 小白重點解釋
- `127.0.0.1` 是「你自己的電腦」。
- Codex worker 跑在「你自己的電腦」。
- ChatGPT Web 不能直接連你的 localhost。
- 所以 ChatGPT Web 要透過 HTTPS tunnel 連回你的電腦。
- tunnel URL 指回目前開 tunnel 的那台電腦。
- 如果你在別台電腦登入同一個 ChatGPT 帳號，仍會連到 tunnel 背後那台主機。
- 不要把 tunnel URL 分享給不信任的人。
- tunnel URL 等同臨時入口；tunnel 開著時，知道 URL 的人可能呼叫公開的 exact `GET /mcp` 與 `POST /mcp`。
- public `/mcp/*` 子路徑不開放；legacy compatibility 子路徑只保留給 localhost。
- public `/mcp` 會驗證 `Origin`：沒有 `Origin` 可通過；有 `Origin` 時只接受 ChatGPT/OpenAI 或同源 HTTPS，其他會回 `403`。
- public `/mcp` 只暴露 connector-safe allowlist：協作導覽、read-only handoff draft、精簡 dry-run handoff、狀態恢復與 read-only workspace tools。寫檔、執行命令、worker claim/result、approval、artifact/decision 直寫都只留 localhost。
- public `codex_handoff_create` 只能建立 `fake-codex` dry-run；real `codex` lane 需由本機確認 plan/task 後再啟動。
- dashboard、audit、approval token 頁面只應在本機 localhost 開啟，不要透過 public tunnel 讀取。
- 用完可以關掉 `cloudflared`，關掉後 ChatGPT Web 就連不回這台電腦。
## fake-exec 與 real Codex
建議先用 fake-exec：
```bash
python3 -m scripts.run_codex_worker --loop --fake-exec
```
fake-exec 是穩定測試路徑，不消耗 Codex 額度，會沿用正式 worker 管線完成 task claim、worktree、heartbeat、execute、submit result、review queue。
切到 real Codex worker：
```bash
python3 -m scripts.run_codex_worker --loop
```
real Codex worker 會真的呼叫 Codex CLI。若 real Codex CLI 因登入、額度、Cloudflare challenge、網路或模型輸出格式而失敗，Hub 架構不一定有錯。請先用 fake-exec 驗證整體流程，再切 real Codex。
## 常見問題
Q: 為什麼 Web ChatGPT 可以用，macOS App 找不到工具？
A: MCP / Developer Mode 目前通常以 Web 版為主，macOS App 可能尚未完整支援。請先用 chatgpt.com Web。
Q: 我在另一台電腦登入 ChatGPT，會使用哪台 Codex？
A: 會使用 connector URL 指向的那台 MCP Hub，也就是開 tunnel 的那台電腦，不會自動使用目前登入裝置的 Codex。
Q: 我能不能每台電腦都跑一套？
A: 可以。每台電腦各自跑 Hub、worker、tunnel，然後在 ChatGPT 建不同 connector 名稱，例如 Home M4 Hub、Office iMac Hub。
Q: 沒有 tunnel 能不能用？
A: 可以本地測試 Hub、worker、dashboard，但 ChatGPT Web 無法連到你的 localhost。
Q: 會不會拖慢電腦？
A: `cloudflared` 很輕；主要負載來自 Codex worker、git worktree、測試執行。
## 常用命令
```bash
python3 -m scripts.install_local --smoke
python3 -m scripts.doctor
python3 -m scripts.print_mcp_info
python3 -m scripts.smoke_local_roundtrip
python3 -m scripts.run_tests
python3 -m scripts.release_check
python3 -m scripts.github_publish
```
## ChatGPT Pro × Codex 協作
若目標是把 ChatGPT Pro 加進日常多模型協作，建議使用 ChatGPT Web/Pro 連到本機 Codex MCP Hub，讓 Pro 做規劃、研究與拆解，Codex worker 做受控執行與回報。
本版新增三個協作工具：
- `collab_guide`：讓 ChatGPT 先讀目前協作規則、URL 與安全邊界。
- `codex_handoff_draft`：read-only，不改 Hub DB；給 ChatGPT Pro read/fetch 模式產生完整 handoff packet。
- `codex_handoff_create`：把 ChatGPT Pro 的規劃整理成 plan/task/artifact refs，交給 Codex worker。
- `collab_pack_get`：用 `plan_id` 恢復共享狀態，避免 ChatGPT 與 Codex 資訊斷層。
`codex_handoff_create` 預設使用 `fake-codex` lane；public ChatGPT connector 也只允許這個 dry-run lane。安全驗證 worker 請跑：
```bash
python3 -m scripts.run_codex_worker --loop --fake-exec --lane fake-codex
```
詳細流程請看 `docs/chatgpt-pro-codex-collab.md`。
## v2 Workspace MCP Tools
Status: v2 closed. v2.1 started for ChatGPT Pro × Codex 協作膠水；只允許 handoff、context continuity、connector safety 相關改動。
v2 已在既有 `/mcp` endpoint 增加 workspace tools，讓 ChatGPT 可以在明確 allowed roots 內安全讀專案、搜尋、看 git status/diff、要求本地 approval 後寫檔或執行非 allowlisted command。
預設安全邊界：
- 沒有設定 workspace config 時，只允許 demo repo，不暴露整台電腦。
- 真實本機專案請使用 ignored 的 `mcp-workspace.config.json` 設定。
- 若你把 exact `POST /mcp` 暴露給 ChatGPT Web，no-auth 模式下的 read-only workspace tools 仍可讀 allowed roots；包含 `list_dir`、`read_file`、`read_many`、`search_files`、`git_status`、`git_diff` 與 `project://file`、`project://search`、`project://agents`。
- `write_file`、`patch_file`、非 allowlisted `run_command` 需要本地 dashboard 顯示的 one-time approval token。
- approval token 只會出現在 localhost dashboard，不會透過 MCP response/resource 回傳。
- `create_worktree`、`remove_worktree`、`mkdir`、`move_path`、`delete_path`、`git_merge`、streaming logs、OAuth/auth 重構仍留到後續版本。
- 詳細說明請看 `docs/workspace-tools-v2.md`。
## 私有 GitHub 上傳
本 repo 預設使用 GitHub CLI 的系統 keychain 登入狀態，不需要每次 push 都重新登入。第一次登入或 token 過期時才需要重新跑 `gh auth login`。
日常安全上傳：
```bash
python3 -m scripts.github_publish
```
有修改要一起 commit 並 push：
```bash
python3 -m scripts.github_publish --commit-message "Update project"
```
此腳本會先確認 GitHub repo 是 private，並執行 `release_check` 後才 push。更多細節請看 `docs/github-publish.md`。
## 給 Codex 的一鍵提示詞
若 Codex 支援 local skills，請優先使用 `$chatgpt-mcp-codex`。本 repo 也提供可見的 skill 版本在 `skills/chatgpt-mcp-codex/`；真實個人網域請只放在 ignored 的 `references/local-binding.private.md`，不要提交。
```text
請在這個 repo 中幫我安裝並啟動 ChatGPT mcp Codex。
請先用規劃模式詢問我要使用哪一種 ChatGPT HTTPS 連線方案：
A. 免費臨時網址：最快可用，但 URL 重開可能改變。
B. 自備網域固定網址：需要 Cloudflare 管理的網域，但 ChatGPT connector 通常不用每次重設。
請依序執行：
python3 -m scripts.bootstrap_local
python3 -m scripts.doctor
如果 Hub 未啟動，請告訴我在 Terminal A 執行：
python3 -m scripts.up
然後請告訴我在 Terminal B 執行：
python3 -m scripts.run_codex_worker --loop --fake-exec
最後請執行：
python3 -m scripts.print_mcp_info
並用白話告訴我：
1. Dashboard URL
2. Local MCP URL
3. ChatGPT 需要的 HTTPS connector URL 格式
4. localhost 與 HTTPS tunnel 的差異
5. 這台電腦是否就是 Codex worker 執行位置
6. 如果我選固定網址方案，請告訴我應提供哪個 hostname
```
## 更多文件
- `docs/localhost-vs-https.md`
- `docs/article.md`
- `docs/chatgpt-setup.md`
- `docs/tunnel-options.md`
- `docs/workspace-tools-v2.md`
- `docs/codex-agent-install.md`
- `docs/github-release-checklist.md`
- `docs/github-publish.md`
- `docs/local-run.md`
- `docs/security-model.md`
