1. Windows 上跑 Codex為什么卡在“能裝不能用”Codex 在 Windows 上已經(jīng)提供原生支持不需要 WSL、不需要虛擬機(jī)直接在 PowerShell 或 CMD 里就能跑起來。這對習(xí)慣 Windows 工作流的開發(fā)者來說是個好消息不用再為了一個命令行工具去折騰子系統(tǒng)也不用在文件系統(tǒng)之間來回拷貝。但真正上手之后很多人會發(fā)現(xiàn)“裝是裝上了第一次調(diào)用卻過不去”——要么是 Key 沒配好要么是 config.toml 路徑寫錯要么是終端環(huán)境變量沒生效。這篇內(nèi)容聚焦的就是這個環(huán)節(jié)Windows 原生環(huán)境下 Codex 的接入配置重點(diǎn)放在統(tǒng)一 Key/API 通道的 config.toml 骨架以及從安裝到首次調(diào)用的完整閉環(huán)。適合需要在本地快速跑通 Codex、并且希望用一個統(tǒng)一 Key 管理多個模型通道的開發(fā)者。下面會給出可直接復(fù)制的配置骨架、啟動驗證命令以及我實(shí)際踩過的幾類報錯和排查動作。2. TaoToken 前置統(tǒng)一 Key 與接入地址在配置 Codex 之前先把 TaoToken 這一側(cè)準(zhǔn)備好。TaoToken 提供的是統(tǒng)一的 API 通道你只需要一個 Key就可以在 Codex 里調(diào)用不同的模型不用為每個模型單獨(dú)維護(hù)一套鑒權(quán)信息。對 Windows 本地開發(fā)來說這能省掉不少環(huán)境變量來回切換的麻煩。你需要先拿到兩樣?xùn)|西一個是 API Key一個是接入地址。Key 在控制臺的 API Keys 頁面創(chuàng)建地址使用https://taotoken.net/api。創(chuàng)建 Key 的時候建議按用途命名比如codex-win-local方便后面在多個工具之間區(qū)分。注意Key 只在創(chuàng)建時完整顯示一次復(fù)制后先存到安全的地方不要直接寫進(jìn)會提交到 Git 的配置文件里。如果你還沒有 Key可以先到控制臺創(chuàng)建創(chuàng)建和管理 Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodex_windows_config接入文檔參考https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodex_windows_config拿到 Key 之后先不要急著改 Codex 的配置。建議先用一個最簡單的請求驗證 Key 本身是通的這樣后面如果 Codex 報錯就能快速判斷是 Key 的問題還是配置的問題。驗證方式可以用 curl也可以用 PowerShell 的Invoke-RestMethod下一節(jié)會給出具體命令。3. 可復(fù)制配置config.toml 骨架與 Windows 路徑寫法Codex 在 Windows 上的配置文件默認(rèn)放在%USERPROFILE%\.codex\config.toml。如果你之前沒有這個目錄先手動創(chuàng)建。下面是一個可以直接復(fù)制修改的骨架重點(diǎn)是把統(tǒng)一 Key 和接入地址填進(jìn)去。# %USERPROFILE%\.codex\config.toml # Windows 原生環(huán)境 Codex 配置骨架 model gpt-4o-mini model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY [windows] sandbox unelevated sandbox_private_desktop true這里有幾個點(diǎn)需要說明。base_url填的是 TaoToken 的 API 地址注意不要在后面多加/v1之類的路徑Codex 會自己拼接。env_key指定的是環(huán)境變量名也就是說 Key 不直接寫在 config.toml 里而是通過環(huán)境變量注入這樣配置文件可以安全地放在項目里或者備份。接下來設(shè)置環(huán)境變量。在 PowerShell 里執(zhí)行# 當(dāng)前會話生效 $env:TAOTOKEN_API_KEY 你的Key # 永久生效寫入用戶環(huán)境變量 [Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY, 你的Key, User)如果你用的是 CMD對應(yīng)寫法是set TAOTOKEN_API_KEY你的Key setx TAOTOKEN_API_KEY 你的Keysetx寫入的是持久環(huán)境變量但只對之后新開的終端生效當(dāng)前窗口不會立刻更新。所以設(shè)置完之后建議關(guān)掉終端重新開一個再繼續(xù)后面的驗證。關(guān)于 Windows 路徑config.toml 里如果涉及路徑建議統(tǒng)一用正斜杠或者雙反斜杠。比如日志目錄寫成C:/Users/YourName/.codex/log或者C:\\Users\\YourName\\.codex\\log不要寫成單反斜杠否則 TOML 解析會把它當(dāng)成轉(zhuǎn)義字符。4. 驗證請求從 Key 連通到 Codex 首次調(diào)用配置寫完之后先驗證 Key 本身能不能通。用 PowerShell 發(fā)一個最小請求$headers { Authorization Bearer $env:TAOTOKEN_API_KEY Content-Type application/json } $body { model gpt-4o-mini messages ({ role user; content ping }) } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri https://taotoken.net/api/chat/completions -Method Post -Headers $headers -Body $body如果返回里有正常的choices字段說明 Key 和網(wǎng)絡(luò)都是通的。這一步過了再回到 Codex 做首次調(diào)用。啟動 Codex 并執(zhí)行一個非交互命令codex exec 用一句話說明當(dāng)前目錄下有哪些文件如果配置正確你會看到 Codex 讀取當(dāng)前目錄、調(diào)用模型、返回結(jié)果。第一次調(diào)用可能會稍慢因為要初始化沙箱和終端環(huán)境。實(shí)測下來Windows 原生模式下 unelevated 沙箱啟動比較快也不需要管理員權(quán)限。如果你想在交互模式里測試直接運(yùn)行codex進(jìn)入 TUI 后輸入問題即可。交互模式更適合調(diào)試多輪對話和工具調(diào)用。5. 本篇常見錯排查啟動失敗、Key 不生效、中文路徑5.1 Codex 啟動報“無法加載配置”最常見的原因是 config.toml 語法錯誤。TOML 對引號和反斜杠比較敏感尤其是 Windows 路徑。排查動作把 config.toml 里的路徑先注釋掉只保留 model 和 provider 部分看是否能啟動。如果能啟動再逐行加回路徑定位到具體哪一行有問題。另一個原因是文件編碼。Windows 上某些編輯器默認(rèn)保存為 GBKCodex 讀取時可能解析失敗。建議用 VS Code 或 Notepad 把 config.toml 保存為 UTF-8 無 BOM。5.2 Key 設(shè)置了但 Codex 說未授權(quán)先確認(rèn)環(huán)境變量在當(dāng)前終端里真的存在echo $env:TAOTOKEN_API_KEY如果輸出為空說明環(huán)境變量沒生效。用setx設(shè)置的需要新開終端用$env:設(shè)置的只對當(dāng)前會話有效。另外注意 config.toml 里的env_key名字要和實(shí)際設(shè)置的環(huán)境變量名完全一致大小寫敏感。還有一種情況是 Key 復(fù)制時帶了空格或換行。重新復(fù)制一次確保前后沒有多余字符。5.3 PowerShell 命令不執(zhí)行或中文路徑異常Codex 在 Windows 上會調(diào)用 PowerShell 執(zhí)行命令。如果 PowerShell 不在 PATH 里或者執(zhí)行策略限制過嚴(yán)命令會失敗。檢查方式Get-ExecutionPolicy如果是Restricted可以改成RemoteSignedSet-ExecutionPolicy -Scope CurrentUser RemoteSigned中文路徑方面Codex 本身支持 Unicode但舊版終端可能顯示異常。建議用 Windows Terminal 而不是老版 CMD 窗口。如果項目路徑里有中文盡量確保終端編碼是 UTF-8chcp 650015.4 日志位置與查看方式Windows 下 Codex 的日志在%USERPROFILE%\.codex\log\codex-tui.log啟動失敗時先看這個日志的最后幾十行通常能看到具體的錯誤原因。用 PowerShell 查看Get-Content $env:USERPROFILE\.codex\log\codex-tui.log -Tail 506. 接入之后統(tǒng)一 Key 的日常用法與 CTA配置跑通之后日常使用就是保持環(huán)境變量可用、config.toml 不變。如果你需要在多個模型之間切換只需要改 config.toml 里的model字段Key 和接入地址都不用動。這就是統(tǒng)一 Key 的便利之處一個 Key 管多個模型通道Windows 本地開發(fā)不用反復(fù)改鑒權(quán)信息。如果你在接入過程中遇到 Key 或配置問題優(yōu)先看 API Keys 頁面和接入文檔API Keys 管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodex_windows_config接入文檔https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodex_windows_config想先驗證模型對話是否正常可以直接用模型對話頁面發(fā)一條消息測試模型對話https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodex_windows_config如果你打算長期在 Windows 上用 Codex 做編碼和 Agent 任務(wù)可以了解 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcodex_windows_config最后提醒一個實(shí)際經(jīng)驗Windows 原生模式下Codex 的沙箱和終端集成已經(jīng)比較穩(wěn)定但如果你同時裝了 WSL 版本注意兩者的配置目錄是分開的不要混用同一個 config.toml。原生版本用%USERPROFILE%\.codexWSL 里是~/.codex各自獨(dú)立維護(hù)更省心。