ChatGPT Web Bridge

Python MCP stdio + Chrome Manifest V3 擴充功能。版本 1.2.0。

1.2.0 Windows 新增本機自動啟動與配對，安裝固定 native host 後，Chrome 載入擴充功能即可啟動 Bridge 並交換配對資料，不必手動複製 Token。此機已安裝；重新載入擴充功能一次即可套用。自動啟動與驗收。

1.1.0 新增 Google Flow 可見 UI adapter，含 Omni 設定與費用核對、防重複提交、原生下載追蹤。需要重新載入擴充功能並由使用者授權 Flow 分頁；不處理或繞過網站驗證。Flow 更新與用法。下方原有 ChatGPT 端到端驗收限制仍適用；新增 adapter 的真實網站生成尚待驗證。

讓本機 Agents 透過使用者已登入、明確授權的 chatgpt.com 分頁送出對話與圖片要求、查詢完成狀態、下載圖片。不是 OpenAI API 包裝器，不需要 API Key，不讀取登入 Cookie，也不需要開啟 Chrome 遠端除錯連接埠。

交付狀態：完整可執行原始碼，尚未完成真實 ChatGPT 帳號端到端驗收。 Python/本機 transport/離線 DOM/模擬 Chrome API 測試結果見 驗證報告。交付環境的選擇性實際 extension 載入測試逾時；已確認 Chromium 環境政策封鎖所有 extension 與網址，不能宣稱已在真實 Chrome + ChatGPT 成功生圖。網站 DOM、下載按鈕、上傳方式可能需要依帳號當前介面調整。

服務條款： OpenAI 個人服務條款禁止自動或程式化擷取資料／輸出，並禁止繞過限制及保護措施。這個整合不是官方授權介面；逐次人工確認也不構成條款豁免。使用前必須確認適用條款與必要授權，不應視為可長期無人值守爬取的服務。官方來源與查閱範圍。

1. 已實作的功能與範圍

這裡的「圖片生成」是把要求送到正常的網頁聊天輸入框，不會呼叫未公開生圖 API。不自動選模型、不操控付費／訂閱頁面、不切換帳號繞過額度。請先在 Chrome 手動確認可用模型及生圖功能；只有文字回覆時會標示 text_only，不假裝已有圖片。

Related MCP server: google-flow-mcp

2. 架構

Codex / OpenCode / AGY / 其他支援本機 stdio MCP 的 Agent
                     │ JSON-RPC，stdin/stdout
                     ▼
           Python MCP server（每個 Agent 各自啟動）
                     │ Bearer token，本機 HTTP /call
                     ▼
           Python bridge（每組設定只執行一個）
                     │ 驗證 Origin + token 的 WebSocket
                     ▼
       Chrome extension service worker（同一個 Chrome profile）
                     │ 限制動作、隔離 content script
                     ▼
            明確授權的 chatgpt.com 分頁

Bridge、MCP Python 子程序與 Chrome 預設必須位於同一台電腦的同一本機網路環境。遠端 Codex VM 的 127.0.0.1 不是 Windows 主機；不能直接套這份本機設定。這個專案不會把服務公開到 LAN／Internet，也沒有提供跨 VM 傳檔或遠端 gateway。Node、Rust、Docker、WSL 都不是執行期必要條件。

3. Windows 安裝

需要已安裝 Python 3.11+、Chrome 120+；首次安裝需要網路下載 Python 依賴。ZIP 不含 Python 或 Chrome 安裝程式。

步驟 A：解壓縮並安裝 Python 環境

建議解壓縮至固定路徑，例如 C:\Tools\chatgpt-web-bridge；之後不要任意搬移，Chrome unpacked extension ID 與 Agent 設定均可能受路徑影響。

在該資料夾執行 install.cmd，或 PowerShell：

cd C:\Tools\chatgpt-web-bridge
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1

這會建立 .venv、.local/config.json、.local/input/ 和 .local/agent-configs/。不需要系統管理員，不永久更改 PowerShell execution policy，不覆寫現有 Agent 設定；再次安裝保留既有 token。

步驟 B：載入擴充功能及配對

Chrome 開啟 chrome://extensions，開啟「開發人員模式」，按「載入未封裝項目」，選擇本專案的 extension 資料夾，不是專案根目錄。複製顯示的 32 字元擴充功能 ID。

.\scripts\cwb.ps1 pair --extension-id 實際的32字元ID
.\scripts\cwb.ps1 show-token

打開擴充功能「選項」，填入：

Bridge URL: ws://127.0.0.1:8765/extension
Token:      剛剛 show-token 的內容
啟用:       勾選
自動送出:   初次使用保持不勾選

按儲存。Token 是本機密鑰，不是 ChatGPT 的 token；不要貼給 Agent 對話、截圖分享或提交 Git。

步驟 C：啟動 Bridge

在獨立 PowerShell 視窗執行，使用期間保留該視窗：

.\scripts\start-bridge.ps1

或雙擊 start.cmd。再開另一個視窗檢查：

.\scripts\cwb.ps1 doctor

應看到 paired: true 與 connected: true。doctor 是連線檢查，不代表 ChatGPT 生圖已驗收。任何 .ps1 被本機政策阻擋時，可使用原生 Python 等效命令，不要放寬企業政策：

.\.venv\Scripts\python.exe .\run.py --config .\.local\config.json doctor

步驟 D：登入並授權分頁

在同一個 Chrome profile 自行登入 ChatGPT。打開普通聊天頁，點擴充功能圖示，再點「授權目前分頁」。或由 Agent 用 chatgpt_open 新開受控分頁。擴充功能啟用後，Agent 可以建立受控新分頁；已存在的其他分頁不會因此被全部授權。

預設每次送出會在目標分頁顯示確認視窗，120 秒內按「允許這一次」才會送出。需要自主執行時，使用者可在擴充功能明確啟用自動送出；Agent 不能透過 tool 自行打開這個選項。自動送出可能消耗帳號額度。

步驟 E：接上 Agent

安裝程式已依實際解壓縮路徑產生設定片段：

.local/agent-configs/codex.toml
.local/agent-configs/opencode.json
.local/agent-configs/agy.json
.local/agent-configs/generic.json

把對應片段合併進 Agent 的現有 MCP 設定，不要整份覆蓋。Codex 使用 mcp_servers TOML；OpenCode 使用 mcp local server；AGY／通用格式使用 mcpServers。主機須能啟動本機 Python stdio，且接受本版支援的 MCP 協定版本。各應用不同版本的設定位置及信任設定，以其官方介面為準；本次未在這三款實際 Agent 主機內驗收。

也能重新產生片段：

.\scripts\cwb.ps1 client-config codex --python "$PWD\.venv\Scripts\python.exe" --launcher "$PWD\run.py"

Agent 應啟動的是 mcp 子命令，不是 bridge。 MCP stdout 只放協定資料，bridge 請另外啟動。

4. macOS / Linux

bash scripts/install.sh
scripts/cwb.sh pair --extension-id 實際的32字元ID
scripts/cwb.sh show-token
scripts/start-bridge.sh
# 另一個 terminal：
scripts/cwb.sh doctor

在 Chrome 載入相同 extension/、選項中填寫 token/URL，再授權分頁。需要桌面 Chrome；不是 headless 部署方案。Windows、macOS 原生安裝腳本本次未實機驗收，CI 設定提供三平台測試矩陣但不是既有綠燈證明。

5. 給 Agent 的用法

可把 skills/chatgpt-web-bridge/SKILL.md 放進 Agent 支援的 skill 目錄；MCP 自身也提供 workflow prompt 及 cwb://guide resource。

範例指示：

使用 chatgpt_web_bridge，先檢查 bridge_status。新開一個 ChatGPT 分頁，要求生成一張 16:9、無人物的古代書齋圖片。只送出一次，保存回傳的 id，等待 chatgpt_job 完成。遇到 needs_attention 或文字回覆就停止，不重新生圖。完成後先用 original 下載並查詢下載狀態；不要把 rendered 預覽說成原始解析度。

文字對話

{"name":"chatgpt_open","arguments":{"active":true}}

拿回實際 tab_id 後：

{"name":"chatgpt_send_message","arguments":{"tab_id":123,"request_id":"my-chat-0001","prompt":"請用繁體中文回覆：連線測試成功。"}}

上面是工具呼叫結構示意，123 要換成真實 ID。回傳任務物件的 id，是下一步的 job_id：

{"name":"chatgpt_job","arguments":{"job_id":"剛剛回傳的id","wait_seconds":20}}

持續查同一任務，不要再送相同提示詞。接續對話要等前一任務完成，使用同一 tab_id、新的 request_id。

圖片與參考圖

將你有權使用的參考圖放入 .local/input/reference.png：

{"name":"chatgpt_generate_image","arguments":{"tab_id":123,"request_id":"scene-0001","prompt":"請根據參考圖生成一張16:9古代書齋圖片，保留建築風格，畫面無人。","attachment_paths":["reference.png"],"timeout_seconds":900}}

單次最多 4 張，本地傳輸總量最多 16 MiB；網站本身仍可拒絕附件。只支援 PNG、JPEG、WebP。檔案必須位於設定的 input_dir 中，不能任意讀取 Agent 電腦的檔案。要改白名單資料夾：

.\scripts\cwb.ps1 set-input-dir E:\ChatGPT-Bridge-Input
# 改完設定要重啟 bridge。

下載圖片

從完成任務的 result.messages 取得含圖片的 message_id，再從其 images 取得 image_index。切勿自己猜 ID。

{"name":"chatgpt_download_image","arguments":{"tab_id":123,"message_id":"實際訊息id","image_index":0,"mode":"original"}}

original 嘗試點對應圖片的網頁原生下載控制項，網站決定下載內容與檔名。沒有按鈕、下載事件無法明確歸屬或多圖歧義時報錯，不會盲目重按。

{"name":"chatgpt_download_image","arguments":{"tab_id":123,"message_id":"實際訊息id","image_index":0,"mode":"rendered","filename":"study-scene"}}

rendered 取得當下 DOM 圖片 URL 的原始檔案位元組，不截圖、不以 canvas 重編碼。但該資源本身可能是預覽或縮圖，因此不保證網站原圖解析度。超過 16 MiB、CORS 限制或未知格式會拒絕。

下載開始不代表完成；使用回傳 download_id 查詢：

{"name":"chatgpt_download_status","arguments":{"download_id":42}}

只有 state: "complete" 才能稱為下載完成。檔案在 Chrome 電腦的下載資料夾，不是 MCP Agent VM 的 /mnt/data；設定「下載前詢問儲存位置」或網站彈出對話框時，需要人在 Chrome 完成。網站來源檔也不一定是 PNG，依實際格式處理。

不接 MCP 也能測試

examples/workflow.py 提供實際可執行的 CLI：

.\.venv\Scripts\python.exe .\examples\workflow.py --mode chat --prompt "請只回答：測試成功。" --state .\.local\first-test.json

.\.venv\Scripts\python.exe .\examples\workflow.py --mode image --prompt "生成一張16:9古代書齋，無人物、無文字。" --state .\.local\scene-001.json --download original

首次寫入 request_id；重跑相同 state 檔案只查舊任務或以相同 request_id 確認登錄，不生成第二次。請先啟動 bridge、啟用擴充功能，並在網頁允許這次操作。未知結果會停止，不自動 resume／acknowledge。

CLI 呼叫也支援 @UTF-8.json，可避免 PowerShell 多行 JSON 的跳脫問題：

.\scripts\cwb.ps1 call chatgpt_list_tabs
.\scripts\cwb.ps1 call chatgpt_generate_image '@examples/image-request.json'

最後一個範例先編輯 JSON 的 tab_id 及新的 request_id，不可照抄 123 當真實分頁。

6. 任務狀態及重試規則

queued → preparing → sending → running → succeeded
                                  ├──→ text_only
                                  ├──→ needs_attention
                                  └──→ cancelled
送出前確定失敗 → failed

needs_attention 包含：網頁／分頁改變、Bridge 中斷、超時、Stop 結果無法確認。它會保留同分頁鎖，不會因重連或 Agent 逾時而自動重送。先讀取頁面、人工確認，再選擇 chatgpt_resume_job 只觀察原任務，或人工承認未知結果後 chatgpt_acknowledge_job 釋放分頁。後者不是停止網站生圖，也不退還額度。

完成判斷需要：本輪使用者訊息、新的 assistant 訊息、沒有忙碌狀態、訊息的結束控制項與穩定期間。文字模式預設穩定 6 秒，圖片模式 12 秒；圖片模式只有文字會另等 45 秒後標示 text_only。不以固定 sleep 或看到一張既有圖片就說成功。這仍依賴 DOM，不等同官方完成事件。

7. 測試及維護

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Dev
.\.venv\Scripts\python.exe -m playwright install chromium
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe .\scripts\check_package.py

Node 只供 service-worker API mock 測試；沒有 Node 該項會跳過。Playwright 只供 DOM 測試，不是本專案操控日常 Chrome 的執行期依賴。選擇性完整 extension transport 測試：

$env:CWB_REAL_EXTENSION_TEST='1'
.\.venv\Scripts\python.exe -m pytest tests/test_extension.py -q
Remove-Item Env:CWB_REAL_EXTENSION_TEST

不得更動瀏覽器企業政策來讓測試過關。測試沒有登入帳號，也不消耗生圖額度。真實帳號驗收見 手動清單。

DOM 變更請先 chatgpt_diagnose，再在擴充功能「選項」覆寫已知 selector 群組；重設為 {} 會回到預設。只接受 CSS selector，不接受 JS 程式。修正前不要反覆送出以測試。

8. 已知不支援與非保證事項

只支援普通 /、/c/<id> 聊天頁；不支援 Projects、自訂 GPT /g/、圖片資料庫列表批次下載、Canvas、影片、帳號完整歷史、音訊串流、任意 JS、精準圖片 editor 選區、跨機遠端控制與自動解 CAPTCHA。自動化回覆內容不是可信系統指令。

本版沒有 ChatGPT API fallback、API 金鑰欄位、Rust 實作、Chrome 商店簽署版、打包 exe 或 Python 依賴離線 wheel。ZIP 含全部專案來源，不含使用者登入資料或 token。圖片辨識只證明回覆區域有符合條件的頁面圖片，不是來源或新生成的鑑定；請人工檢查成品。original/rendered 兩種下載都未經真實帳號驗收；不要把圖片數量、透明度、尺寸或生成時間當成硬保證。

文件索引

工具完整定義 · 架構及協定範圍 · 安全 · 排錯 · 驗證 · 手動驗收 · 官方來源 · MIT License