結論先說
- 先用
codex mcp list和會話內/mcp定位斷在哪一步:列表里根本沒有該伺服器,多半是項目未授信導致.codex/config.toml被跳過,或enabled = false。 - 本地 STDIO 服務首次拉包易超預設 10 秒:把
[mcp_servers.<名字>]裏的startup_timeout_sec調大(如30或60),並先在終端單獨跑通一次啟動命令。 - 環境變量沒傳進去會導致鑑權失敗:固定鍵值寫在
[mcp_servers.<名字>.env],轉發本機變量列進env_vars,遠程 HTTP 令牌用bearer_token_env_var。 - Windows 原生環境注意
.cmd擴展名:npx在 Windows 上實際是批處理包裝腳本,直接寫command = "npx"可能找不到可執行文件,建議改寫為npx.cmd或完整路徑。 - 改完配置必須重啟會話或點 Restart,基礎添加命令見 /guides/codex-mcp-config。
- Codex 額度升級與註冊驗證入口:Codex 配額隨 ChatGPT 付費套餐提供,國內免境外卡自助開通可見本站 ChatGPT Plus 充值頁 與重度開發首選的 ChatGPT Pro 充值頁,新號卡在手機驗證可查看 Codex 註冊驗證說明。

圖:本站根據 Codex 官方文檔:Model Context Protocol 整理的示意圖
本文根據 Codex 官方文檔《Model Context Protocol》《Configuration Reference》《Environment variables》《Config basics》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。
適用於誰
- 在
config.toml配好了[mcp_servers],但運行 Codex 時提示 MCP 啟動超時、連接失敗的人; - 會話裏輸入
/mcp顯示列表為空,或者連上了伺服器卻找不到某個工具的人; - 在 Windows 原生終端或桌面 App 下跑
npx、uvx本地 MCP 總是起不來的人。
一、第一步自檢:列表裏有沒有、項目信不信任
遇到「配好了卻看不到工具」,按下面四條順序排掉最常見的低級卡點:
- 在終端跑
codex mcp list(或加--json):看 Codex 實際解析到的配置裏有沒有你的伺服器;若 TOML 語法寫錯(例如漏引號、根級鍵寫在了[表]後面),啟動就會報錯或漏讀,結構規則見 /guides/codex-config-toml-complete-guide。 - 檢查項目信任狀態:如果你把 MCP 配在倉庫內的
.codex/config.toml,官方明確規定只有受信任(trusted)的項目才會加載.codex/層配置。未授信項目會靜默跳過項目級 MCP。 - 核對開關與白名單:檢查該伺服器下是否誤寫了
enabled = false,或者enabled_tools、disabled_tools把目標工具篩掉了。 - 重啟客戶端並在會話裏敲
/mcp:ChatGPT 桌面 App 儲存配置後要點 Restart,IDE 擴展要點 Restart extension;進會話輸入/mcp(或/mcp verbose)查看實時連接詳情。
二、超時排查:startup_timeout_sec 與 tool_timeout_sec

圖:本站根據 Codex 官方文檔:Configuration Reference 整理的示意圖
用 npx -y 或 uvx 啟動本地 STDIO 伺服器時,第一次運行往往要聯網下載依賴包,耗時很容易超過預設的 10 秒,導致 Codex 判定啟動超時放棄連接。
按官方配置參考,可在 [mcp_servers.<名字>] 裏調整超時參數:
| 配置鍵 | 預設值 | 排錯調整建議 |
|---|---|---|
startup_timeout_sec | 10(秒) | 本地 npx / uvx 冷啟動或重型服務,建議調至 30–60 |
tool_timeout_sec | 60(秒) | 查大庫、跑瀏覽器自動化等慢工具,可按需調至 120 以上 |
required | false | 設為 true 時,該 MCP 起不來會直接阻止 Codex 啟動,方便暴露錯誤 |
頂層 mcp_optional_startup_grace_ms | 1000(毫秒) | 控制構建工具列表時等待非必需伺服器的寬限時間 |
實用做法是:先把 command 和 args 拼成普通命令,在系統終端裏手動跑一遍,讓它先把包緩存到本地、確認不報缺依賴錯誤,再交由 Codex 拉起。
Codex 開發配額與團隊版提示:高頻跑本地重構與雲端任務容易耗盡基礎週期限額。需要免境外銀行卡自助升級或覆蓋升級時,可前往本站 ChatGPT Plus 自助充值 或 ChatGPT Pro 5x/20x 充值說明;團隊統一管控權限與共享帳單可定製 ChatGPT Business 團隊方案。
三、環境變量與遠程 OAuth 鑑權排錯
很多 MCP 伺服器進程雖然起來了,但因為拿不到數據庫地址或 API Token 而立刻退出或返回空工具:
- STDIO 本地伺服器傳變量:子進程不會無條件拿到另一個終端窗口裏的臨時變量。直接給該伺服器賦固定值用子表
[mcp_servers.<名字>.env];要從啟動 Codex 的宿主機環境轉發已有變量,必須把變量名寫進env_vars = ["GITHUB_PERSONAL_ACCESS_TOKEN"]。 - Streamable HTTP 遠程伺服器傳憑證:用 Bearer Token 的服務寫
bearer_token_env_var = "MY_MCP_TOKEN"(不要把明文密鑰硬編碼進會提交 Git 的配置文件);自定義請求頭可用http_headers或從環境讀取的env_http_headers。環境變量完整讀取規則見 /guides/codex-missing-environment-variable。 - 需要 OAuth 登入的遠程服務:連接後提示未授權時,運行
codex mcp login <名字>拉起瀏覽器完成授權(桌面 App 或 IDE 的 MCP 設定頁點 Authenticate);令牌失效重登前可先codex mcp logout <名字>。
四、Windows 原生環境命令啟動排錯
在 macOS 和 Linux 上直接寫 command = "npx" 通常沒問題,但在 Windows 原生環境下(非 WSL),進程創建接口直接找可執行文件時常會因為找不到 .cmd 批處理包裝器或 Node 路徑未進系統全局 PATH 而啟動失敗。
在 Windows 的用戶級 config.toml 裏,可用以下兩種寫法解決(路徑分隔符用正斜槓可免去轉義麻煩):
toml
# 寫法一:顯式指定 .cmd 擴展名與超時時間
[mcp_servers.context7]
command = "npx.cmd"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30
# 寫法二:從桌面圖標啟動讀不到 PATH 時,寫可執行程序完整路徑
[mcp_servers.local_uv]
command = "C:/Users/YourName/.local/bin/uvx.exe"
args = ["mcp-server-git"]
startup_timeout_sec = 30
若同時遇到 Windows 本機沙箱報錯,可對照 /guides/codex-windows-sandbox-setup-failed。另外官方定價頁提醒,掛載過多 MCP 伺服器會往每輪請求塞入大量工具描述、加快配額消耗,不常用的服務建議設 enabled = false;日常配額不夠用可查看本站 ChatGPT Plus 充值說明。
常見問題
問:配在 config.toml 裏的 MCP,打開 ChatGPT 網頁版為什麼看不到?
答:ChatGPT 網頁版不讀取本機 config.toml,網頁端需要通過插件(Plugins)連接遠程工具;本地這份配置僅由桌面 App、CLI 和 IDE 擴展共用。
問:為什麼運行 codex mcp-server 提示沒有這個子命令?
答:官方已移除舊的 codex mcp-server(把 Codex 自身當作 MCP 服務端暴露的模式);讓 Codex 連接外部 MCP 伺服器統一用 codex mcp 子命令管理。
問:怎麼看某個 MCP 伺服器到底報了什麼底層錯誤?
答:先在會話內運行 /mcp verbose 查看狀態,或在終端單獨復現對應的啟動命令,分享日誌前注意抹去敏感密鑰。
問:跑 Codex 額度不夠用,國內沒有外幣卡怎麼快速升級 Plus 或 Pro?
答:可在本站用支付寶、微信支付或 AlipayHK 自助購買卡密兌換 ChatGPT Plus 或 ChatGPT Pro(已有未到期 Plus 直升可選 Pro 5x 可覆蓋檔),實時價格與售後邊界(封號不在質保範圍)以頁面當天說明為準。
相關教學
- Codex 怎麼配置 MCP:codex mcp add 與 config.toml 寫法
- Codex 報「missing environment variable」怎麼辦
- Codex config.toml 完整詳解
- Codex 沙箱初始化失敗怎麼辦(Windows)
參考資料
- Codex 官方文檔:Model Context Protocol — https://learn.chatgpt.com/docs/extend/mcp
- Codex 官方文檔:Configuration Reference — https://learn.chatgpt.com/docs/config-file/config-reference
- Codex 官方文檔:Environment variables — https://learn.chatgpt.com/docs/config-file/environment-variables
- Codex 官方文檔:Config basics — https://learn.chatgpt.com/docs/config-file/config-basic
0 條評論
還沒有評論,來搶沙發~