結論先說
- 排障先跑
codex doctor,不要上來就重裝卸載。它是 Codex CLI 官方內置的健康體檢工具,能一次性核查安裝版本、配置文件、認證憑據、代理與 WebSocket 握手、Git 集成及本地數據庫狀態。 - 日常速查用
--summary,腳本與工單用--json。codex doctor --summary按模組分組直出對錯標記,幾秒就能鎖定紅叉項;codex doctor --json適合自動化巡檢或脫敏後附在問題排查單裏。 - 重點盯緊
auth與websocket兩項核心檢查。auth失敗說明沒找到有效登入態或 API 密鑰;websocket告警表示未能完成HTTP 101 Switching Protocols持久握手,即便能退回 HTTPS,長對話和多工具調用也更容易斷流。 - 本地配置損壞或網絡掛載盤也能被揪出來。包括舊版廢棄配置字段、損壞的本地會話數據庫(尤其是把
~/.codex掛在 NFS 網絡文件系統上)都會在報告裏暴露。 - 確認本機環境正常後若仍受限,多半是帳號訂閱檔位或額度問題。國內若無外幣銀行卡或支付受阻,可在本站自助開通 ChatGPT Plus 或額度更高的 ChatGPT Pro,團隊集中排障與多席位採購可了解 ChatGPT Business 團隊定製。

圖:本站根據 OpenAI Codex 官方文檔:Troubleshooting 整理的示意圖
本文根據 OpenAI Codex 官方文檔《Troubleshooting》《Command line options》《Authentication》整理,資料核對於 2026-11-19。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。
適用於誰
- 運行 Codex CLI 時遇到登入不上、請求超時、流式輸出中斷或配置加載異常,想一次性摸清根因的開發者;
- 在公司代理、防火牆、自定義 TLS 證書或遠程伺服器環境下部署 Codex,需要快速驗證 WebSocket 連通性的人;
- 準備向團隊運維或開源社區反饋問題,需要導出一份結構化本機環境健康報告的工程師。
一、codex doctor 怎麼跑:三條實用指令
打開出現問題的同一終端窗口(確保沿用當前相同的環境變量與 CODEX_HOME),執行以下任意一條命令(更多常見報錯速查可結合 /guides/codex-common-errors-summary):
bash
# 1. 輸出完整環境體檢報告(含安裝、配置、認證、終端與會話庫)
codex doctor
# 2. 輸出分組摘要視圖,最快定位紅叉或黃歎號項
codex doctor --summary
# 3. 導出機器可讀 JSON(便於腳本解析或儲存排查檔案)
codex doctor --json > codex-health.json
如果在隔離目錄環境下排障,記得帶上相同的目錄前綴,例如 CODEX_HOME=~/.codex-work codex doctor --summary,否則體檢的仍是預設 ~/.codex,容易漏掉隔離環境本身的認證或配置錯誤。
二、逐項讀懂關鍵異常信號與修復動作
跑完 --summary 後,絕大多數故障都集中在下面四個模組,對照結果直接下手即可:

圖:本站根據 OpenAI Codex 官方文檔:Authentication 整理的示意圖
1. 認證異常(✗ auth)
典型提示為未檢測到有效 Codex 憑據(no Codex credentials were found)。排查順序:
- 先確認是否意外切換了
CODEX_HOME指向空目錄; - 交互環境重新執行
codex login完成瀏覽器授權;若在登入回跳階段報錯,對照 /guides/codex-token-exchange-failed-login-error 排查,若報 401 未授權則參考 /guides/codex-401-unauthorized-error; - 無頭容器或 CI 環境下,確認
CODEX_API_KEY等受支持的認證環境變量已正確傳入當前進程。
2. WebSocket 連通性異常(⚠ websocket 或 ✗ websocket)
正常狀態下該項會顯示成功建立 HTTP 101 Switching Protocols 連接。Codex 通過持久 WebSocket 訪問 Responses API,以降低多輪代理工具循環的延遲。一旦報告提示 WebSocket 失敗、可能回退到 HTTPS,常見誘因包括:
- 企業代理或安全網關攔截了 Upgrade 握手頭,或中途截斷長連接;
- 公司內網啟用了 TLS 流量審計,但本機系統或運行環境未信任企業自定義根 CA 證書;
- 本機 IPv6 路由半通或 DNS 抖動導致握手超時。
雖然 HTTPS 回退偶爾能頂一陣子,但在複雜多步改代碼任務中非常容易觸發中途掉線(關聯排查見 /guides/codex-stream-disconnected-before-completion 與 /guides/codex-slow-reconnecting-why)。本站建議聯絡網絡管理員放行目標域名的 WebSocket 協議並正確注入根 CA,從根源解決斷連。
3. 配置文件與舊版遷移異常
若 config.toml 存在 TOML 語法錯位、殘留已廢棄的內聯 [profiles.*] 區塊,或觸發企業 requirements.toml 衝突,codex doctor 會直接標出異常配置項,按提示修正後重跑驗證即可。
4. 本地線程數據庫與掛載目錄異常
在 Linux 開發機集群中,如果用戶的家目錄掛在 NFS 等網絡文件系統上,SQLite 文件鎖機制極易引發會話庫損壞或卡死。本站建議將 CODEX_HOME 顯式指向本機 SSD 本地路徑(例如 /tmp 之外的本地數據盤目錄),繞開網絡盤鎖問題。
訂閱與帳號準備提示:若codex doctor檢查全部通過,但發消息依然反覆受阻或提示配額不足,請核對當前套餐的 5 小時與每週額度狀態(規則見 /guides/codex-usage-limits)。個人重度開發可在本站升級 ChatGPT Pro 充值 或選擇 ChatGPT Pro 5x iOS 可覆蓋檔;新註冊 OpenAI 帳號若在手機短訊驗證環節卡住,可查看 Codex 註冊手機驗證服務。
三、提交工單或團隊求助前的數據脫敏建議
使用 codex doctor --json 導出排查文件準備發給同事或開源 Issue 時,本站建議先人工掃一遍文件,把其中可能出現的企業內部代理域名、私有端點路徑、本機絕對用戶名目錄以及自定義模型提供商地址替換為佔位符,只保留版本、操作系統、狀態碼與報錯摘要,避免順手泄露內網拓撲資訊。
常見問題
問:運行 codex doctor 提示沒有這個子命令,是什麼原因?
答:通常是本地安裝的 Codex CLI 版本偏舊,還未包含內置的 doctor 診斷命令。先執行 codex --version 查看當前版本並升級到最新穩定版,升級完成後重啟終端再運行即可。
問:codex doctor 顯示 websocket 告警,但我偶爾也能發消息收到回覆,還需要管嗎?
答:建議趁早處理。告警說明 WebSocket 持久通道沒打通,客戶端臨時退回了 HTTPS 流式傳輸;簡單短問答或許還能湊合,但一旦進入跨文件多輪工具調用,斷流、卡死重連和延遲飆升的概率會高很多。
問:國內沒有外幣信用卡,或者公司需要開增值稅發票報銷,怎麼開通穩定跑 Codex 的訂閱?
答:可通過本站 AI 會員充值總覽 按需選購 ChatGPT Plus或更高額度的 ChatGPT Pro,團隊多席位採購可了解 ChatGPT Business 團隊定製。支持支付寶、微信支付和 AlipayHK,支持自助兌換無需交出帳號密碼,並可開具增值稅發票;實時價格以商品頁展示為準,售後執行掉訂閱按剩餘天數折退、封號不在質保範圍的政策。
相關教學
- Codex 常見報錯彙總與快速定位指南
- Codex 報 401 Unauthorized 登入授權失敗怎麼修
- Codex 登入報 token exchange failed 解決方法
- Codex 報 stream disconnected before completion 斷流排查
參考資料
- OpenAI Codex 官方文檔:Troubleshooting — https://learn.chatgpt.com/docs/reference/troubleshooting
- OpenAI Codex 官方文檔:Command line options — https://learn.chatgpt.com/docs/developer-commands
- OpenAI Codex 官方文檔:Authentication — https://learn.chatgpt.com/docs/auth
- OpenAI Developers 文檔:Codex CLI Reference — https://developers.openai.com/codex/cli/reference
0 條評論
還沒有評論,來搶沙發~