使用手冊

GitHub Field Manual · ChatGPT / MCP

ChatGPT Developer Mode 的本機倉庫橋

rebel0789/codexpro 繁體中文實戰手冊：本機 MCP 伺服器安裝、ChatGPT Plugins 連線、tunnel 選項、寫入與 bash 模式、handoff 執行與安全邊界。

CodexPro 是本機 MCP 伺服器。它把你的 ChatGPT 工作階段接到你明確允許的本機倉庫。ChatGPT 可讀取、搜尋、編輯、審查、驗證、匯入附件，並寫 handoff 計畫；範圍限制在這些 root 內。

rebel0789/codexpro
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
11 分
更新日期
開啟原始報告
GitHub Stars
1,887
package.json 版本
0.30.0
Node.js 最低版本
20+
開源授權
MIT
本頁章節

01這是什麼

本機 MCP 伺服器與允許的倉庫

CodexPro 是本機 MCP 伺服器。它連接你的 ChatGPT 工作階段、你的機器，以及你明確允許的倉庫。GitHub 倉庫描述為：Use ChatGPT Developer Mode as a local coding agent for your repo through MCP。

在 workspace write 模式（官方稱為常規 agent 設定）下，ChatGPT 可讀取、搜尋、檢查倉庫；用 write、edit 或受保護的 apply_patch 編輯；用 import_file 匯入 ChatGPT 附件；用 bash 跑白名單檢查；用 show_changes 審查 diff；在 .ai-bridge 寫計畫；並為不能呼叫工具的工作階段匯出 context bundle。

官方 README 列出它不是託管 SaaS、模型代理、配額繞過、帳號池或遠端 shell 服務。所有請求仍走你自己的 ChatGPT 工作階段與該帳號現有限制。

  1. Install

  2. Setup

  3. Paste Server URL

  4. Inspect

  5. Edit

  6. Verify

Give ChatGPT local coding tools for repos you explicitly allow.

— rebel0789/codexpro README

02安裝與連線

全域安裝、setup 與 Plugins

前置條件：Node.js 20+；能建立自訂 MCP 外掛的 ChatGPT 帳號；ChatGPT Web 需要指向本機的 HTTPS 位址（tunnel 或 Tailscale Funnel）。官方 FAQ 建議全域安裝一次，之後在目標倉庫跑 codexpro setup。

bash
npm install -g codexpro
cd /path/to/your/repo
codexpro setup

ChatGPT Plugins 連線欄位

路徑：Settings → Security and login，開啟 Developer mode，並保持 Enforce CSP in developer mode 開啟。再到 Settings → Plugins 的 Plugins 分頁，點搜尋框旁的 +。

名稱填 CodexPro。Connection 選 Server URL，貼上 CodexPro 複製的 URL。Authentication 選 No Authentication / None；表單可能預設 OAuth，建立前改掉。CodexPro 的認證就是該 URL 內的 token，不要分享這個 URL。

bash
# 同一倉庫日常啟動
codexpro start

# 指定倉庫根目錄
codexpro start --root /path/to/repo

更新

沒有 codexpro update。重新安裝套件後重啟連線：

bash
npm install -g codexpro@latest
codexpro --version

03指令與工具

CLI、模式與 MCP 工具面

CLI 負責安裝、啟動、診斷與本機執行器。MCP 工具面由 --tool-mode、--mode 與 bash / write 開關決定。官方網站列出預設 standard 工具包含 server_config、open_current_workspace、open_workspace、tree、search、read、view_image、write、edit、bash、show_changes、read_handoff、wait_for_handoff、export_pro_context、handoff_to_agent。

CLI · 01

codexpro setup

引導安裝

互動式設定工作區、連接埠、模式與公網 URL 策略，並把設定存進 ~/.codexpro/profiles/。

CLI · 02

codexpro start

日常啟動

從同一倉庫重用已存 profile。可加 --root、--headless、--no-bash 與各 tunnel 旗標。

CLI · 03

codexpro doctor

讀取型診斷

檢查 Node、建置產物、工作區 profile、連接埠、tunnel 前置條件、剪貼簿與瀏覽器開啟支援。

CLI · 04

codexpro connection-test

連線測試

保留 read、tree、search、load_skill；關閉寫入、bash 與 tool cards。終端機會標示請求是否到達 /mcp。

CLI · 05

codexpro settings

設定檔管理

show / set / list / delete --yes。用 --project 加入額外允許的倉庫；--clear-projects 清除。

CLI · 06

inspect / review

倉庫分析

本機建倉庫地圖，不需 language server 或向量資料庫。可加 --json；CODEXPRO_ANALYSIS=0 可關閉此層。

Mode · 07

--mode handoff

規劃專用

不對外宣告通用 write / edit / apply_patch。ChatGPT 只寫 .ai-bridge 計畫檔。

Mode · 08

--mode pro

上下文匯出

給不能呼叫 MCP 工具的模型或產品界面。CLI 後備為 codexpro pro-bundle --copy。

MCP · 09

open_current_workspace

啟動倉庫開啟

官方建議提示要求先呼叫 server_config，再以 include_tree=false 開啟啟動倉庫。

MCP · 10

open_workspace

允許專案切換

切到已允許的額外專案，作為該 MCP session 的選取。切回啟動倉庫用 open_current_workspace。

MCP · 11

write / edit / apply_patch

工作區寫入

僅在 workspace write 模式宣告。可傳 expected_sha256 擋過期覆寫。敏感路徑預設封鎖。

MCP · 12

import_file

附件匯入

只接受 ChatGPT Apps SDK 檔案物件，且來自已核准 HTTPS 主機。拒絕任意模型提供的下載 URL。

MCP · 13

bash

白名單檢查

預設 safe 模式。--no-bash 從工具清單移除。--bash full 僅適用受信任本機倉庫。

MCP · 14

show_changes

diff 審查

git status、diff 統計與可選 diff。官方建議提示：git_status / git_diff 僅在 --tool-mode full 時使用。

Local · 15

execute-handoff

本機執行器

由使用者終端機執行 .ai-bridge/current-plan.md。內建 OpenCode、Pi、Codex 與受限自訂 --command。先用 --dry-run。

Local · 16

loop-handoff

本機迴圈

在本機對計畫做有界 execute/review 迴圈。需本機 --review-command 與 --max-iters。不暴露為遠端 MCP 工具。

啟動旗標對照

你在做什麼指令
第一次把 ChatGPT Web 接到本機倉庫codexpro setup，再把複製的 Server URL 貼進 Plugins
同一倉庫日常連線codexpro start
只規劃、不改原始碼codexpro start --mode handoff
模型或產品界面不能呼叫 MCP 工具codexpro start --mode pro 或 codexpro pro-bundle --copy
不要讓 ChatGPT 觸發 shellcodexpro start --no-bash
快速 demo（URL 每次重啟會變）codexpro start --tunnel cloudflare
穩定 Server URLcodexpro ngrok --hostname … 或 codexpro stable --hostname …
一個 connector 切多個允許專案codexpro settings set --project …
兩個 ChatGPT 帳號或硬隔離兩個 CodexPro 行程，不同連接埠與不同 Server URL
Plugins 建立失敗codexpro connection-test

04官方原則

連線、token 與安全預設

以下條目來自官方 README、FAQ 與 SECURITY.md。公網 tunnel 預設要求 HTTP token（至少 24 bytes）；寫入工具只在 workspace write 模式宣告；bash 預設 safe。

保持 CSP 開啟

Enforce CSP in developer mode 維持開啟。CodexPro widget 依 CSP 路徑建置，不需要遠端 script、外部字型、iframe 或第三方圖片。

來源 · FAQ.md · Should CSP stay enabled?

不要分享 Server URL

CodexPro 認證就是 URL 內的 token。個人相容後備是 ?codexpro_token=。用戶端支援標頭時優先用 Authorization: Bearer <token>。

來源 · README · Connect in ChatGPT

固定 token 給穩定主機名稱

建立 ~/.codexpro/http-token：openssl rand -hex 32，權限 chmod 600。穩定 hostname 與穩定 token 搭配，才不必每次改 ChatGPT Server URL。

來源 · README · Public HTTPS options

依 FAQ 選 tunnel

快速 demo 用 Cloudflare quick tunnel（重啟會換 URL）。穩定 URL 優先 ngrok free dev domain。自訂網域用 Cloudflare named tunnel。Tailnet 用 Tailscale Funnel。能連 localhost 的用戶端才用 --tunnel none。

來源 · FAQ.md · Which tunnel should I choose?

連線失敗先跑 connection-test

沒有 POST /mcp received：請求沒到本機，查 Plugins 頁與 tunnel。401：貼上含 token 的完整 URL。2xx：ChatGPT 已到達 MCP endpoint。Cloudflare 530 / Error 1033 查 DNS。

來源 · FAQ.md · Something went wrong

多專案與硬隔離分開處理

同一個 connector 切專案：settings set --project，再請 ChatGPT 呼叫 open_workspace。兩個帳號、兩個 ngrok 網域或硬隔離：兩個行程、不同連接埠與不同 Server URL。

來源 · README · Multiple projects

並發寫入傳 expected_sha256

先讀檔，再把回傳的 SHA-256 傳給 write 或 edit。檔案在讀取後已變更時，操作會被拒絕。這不是協同 merge 伺服器；大範圍重疊修改仍用獨立 worktree。

來源 · FAQ.md · multiple ChatGPT sessions

safe bash 仍可跑套件指令

safe 模式允許常見檢查、git、測試、lint、typecheck 與建置指令。SECURITY.md 註明它仍可跑倉庫 package scripts；不信任的倉庫用 --no-bash。

來源 · SECURITY.md · Failure Model

持久上下文放在檔案

用 AGENTS.md 寫專案規則；.ai-bridge/decisions.md、current-plan.md、agent-status.md 保存決策、計畫與本機執行結果。不能呼叫工具時用 pro-bundle --copy。

來源 · FAQ_ZH.md · 維持上下文

先對版本再對文件

FAQ 跟隨 GitHub main。文件寫了某個功能但 codexpro --version 還沒有，代表 main 比 npm latest 新。等下一版，或從帶 tag 的 GitHub release 安裝。

來源 · FAQ.md · How do I update CodexPro?

05使用實例

從 setup 到第一次工作區編輯

下列流程依官方 README 的安裝與連線步驟，以及 repo 內 CHATGPT_PROMPT.md 的建議呼叫順序。終端機指令是 verbatim CLI；ChatGPT 側示範方法，不宣稱特定倉庫目錄內容。

/path/to/your/repo · codexpro start


$ npm install -g codexpro
$ cd /path/to/your/repo
$ codexpro setup


# [saves tunnel, hostname, port, mode, token under ~/.codexpro/profiles/]
# [copies Server URL to clipboard]


claude: ChatGPT Plugins ›
  Name: CodexPro
  Connection: Server URL
  Authentication: No Authentication / None
  hl: Paste the copied URL. Do not share it.


$ codexpro start
ok: MCP HTTP listening · public HTTPS tunnel attached
  # Enter 開啟 ChatGPT connector 設定 · c 再複製 URL · o 開本機 admin · q 停止


$ You ›
  Use CodexPro.
  Call server_config first, then open_current_workspace with include_tree=false.
  Do not call open_workspace after open_current_workspace unless I ask you to switch roots.


# [tool] server_config
# [tool] open_current_workspace { include_tree: false }
ok: workspace root = launch repo · write mode = workspace · bash = safe


$ You ›
  Inspect the existing HTTP entry. Add a JSON /healthz handler if missing.
  Keep the change scoped. Verify with search/read/bash and show_changes.


# [tool] search { query: "healthz", path: "." }
# [tool] read { path: "<existing-http-entry>" }
# [tool] edit { path: "<existing-http-entry>", expected_sha256: "<from-read>" }
# [tool] bash { command: "npm test" }
# [tool] show_changes


claude: ChatGPT ›
  Changed files: the existing HTTP entry only.
  Verification: allowlisted test script completed in this CodexPro process.
  Blocked: none. git_status/git_diff were not called (tool-mode is not full).

Call server_config first, then open_current_workspace with include_tree=false.

— rebel0789/codexpro CHATGPT_PROMPT.md

官方建議提示的呼叫順序

CHATGPT_PROMPT.md 要求先 server_config，再 open_current_workspace；未要求切 root 時不要呼叫 open_workspace。一般工作用 read、search、edit、bash、show_changes；git_status / git_diff 只在 --tool-mode full 時使用。

結束時摘要變更檔案、驗證指令，以及被擋住的項目。未明確要求規劃時，不要呼叫 handoff_to_agent 或 handoff_to_codex。

06注意事項

公網暴露與權限邊界

07進階路徑

穩定 URL、handoff 與本機執行器

預設路徑是全域安裝、在倉庫跑 setup、把 Server URL 貼進 ChatGPT Plugins。以下步驟在連線穩定後才需要。

進階地圖

**1. 固定 ChatGPT Server URL。**FAQ 建議大多數使用者用 ngrok free dev domain。有自己的網域時用 codexpro stable --hostname … --tunnel-name …。Tailnet 已開 Funnel 時用 codexpro tailscale --hostname …。細節見 DOMAIN_SETUP.md。

2. 一個 connector 允許多個專案。codexpro settings set --project ~/code/web --project ~/code/api，確認 settings show 列出額外 root，重啟 connector 後請 ChatGPT 呼叫 open_workspace。

3. 規劃與執行分開。codexpro start --mode handoff --no-bash 讓 ChatGPT 只寫 .ai-bridge/current-plan.md。本機再跑 codexpro execute-handoff --agent opencode --dry-run，確認後拿掉 --dry-run。

4. 有界本機迴圈。codexpro loop-handoff 需要本機 --review-command 與 --max-iters。先 --dry-run，並優先 --require-human-confirmation。它不自動化 ChatGPT Web，也不核准產品提示。

**5. 背景啟動。**交給 service manager 時用 codexpro start --headless。它不提問、不碰剪貼簿或瀏覽器；以 CODEXPRO_READY 回報就緒，HTTP runtime 意外退出時以非零狀態結束。

優先閱讀

① SECURITY.md — 威脅模型、fail-closed 規則與硬性限制。 ② FAQ.md — 帳號層級、tunnel 選擇、連線除錯與多專案。 ③ DOMAIN_SETUP.md — ngrok、Cloudflare named tunnel 與穩定 hostname。

Treat it like a developer tool with access to your source tree, not like a hosted SaaS app.

— rebel0789/codexpro SECURITY.md