
1. 從零跑通 Codex為什么第一步是改 auth.jsonCodex 是 OpenAI 推出的一套自主軟件工程智能體工具鏈它和早期那個(gè)只做代碼補(bǔ)全的模型已經(jīng)完全不是一回事了。現(xiàn)在的 Codex 包含命令行客戶端 Codex CLI、本地沙盒應(yīng)用 Codex App以及 IDE 插件三部分協(xié)同工作。它能自己讀文件、改代碼、跑測試、看報(bào)錯(cuò)、再改直到任務(wù)完成。適合誰用適合已經(jīng)有一定命令行基礎(chǔ)、想讓 AI 真正動(dòng)手寫代碼而不是只給建議的開發(fā)者。但很多人卡在第一步裝完之后不知道身份怎么配。默認(rèn)情況下 Codex CLI 會(huì)引導(dǎo)你走 ChatGPT 賬號登錄走的是 OAuth 那一套。如果你手上用的是 API Key 方式或者想把請求指向自己的接入端點(diǎn)就必須去動(dòng)~/.codex/auth.json這個(gè)文件。這篇就按“安裝 → 改 auth.json → 驗(yàn)證調(diào)用”的完整鏈路走一遍每一步都給可復(fù)制的命令和配置片段。我試過在 macOS 和 Windows 上各跑一遍踩過的坑主要集中在 auth.json 的字段格式和 Base URL 的寫法上后面會(huì)單獨(dú)開一節(jié)講報(bào)錯(cuò)排查。你只要跟著做十分鐘內(nèi)能讓 Codex 發(fā)出第一個(gè)真實(shí)請求。先明確一個(gè)概念Codex CLI 本身是個(gè) Node.js 程序它不綁定某一家模型服務(wù)。它讀auth.json決定“用哪個(gè) Key、請求發(fā)到哪個(gè)地址、默認(rèn)用哪個(gè)模型”。所以把這三個(gè)東西配對Codex 就能跑起來。本文用 TaoToken 作為接入端點(diǎn)來演示因?yàn)樗慕涌诟袷胶?OpenAI 兼容配置起來最省事。2. 安裝 Codex CLI 與前置準(zhǔn)備npm 全局安裝與 Node 版本要求2.1 環(huán)境要求Codex CLI 基于 Node.js官方要求 Node 18 以上實(shí)測 Node 20 LTS 最穩(wěn)。先確認(rèn)版本node -v npm -v如果 node 版本低于 18先去升級。Windows 用戶建議用 nvm-windows 管理版本macOS/Linux 用 nvm 就行。這一步別跳過Node 16 裝 Codex 會(huì)在啟動(dòng)時(shí)報(bào)SyntaxError: Unexpected token ??之類的語法錯(cuò)誤因?yàn)榇a里用了空值合并運(yùn)算符。2.2 全局安裝 Codex CLInpm install -g openai/codex裝完驗(yàn)證codex --version能打印出版本號就說明 CLI 裝好了。如果提示command not found多半是 npm 全局 bin 目錄沒進(jìn) PATH。用npm config get prefix看路徑把它加到環(huán)境變量里。2.3 關(guān)于 Codex App 和 IDE 插件Codex App 是圖形客戶端主要作用是提供沙盒工作區(qū)和賬號鑒權(quán)macOS 和 Windows 都有。IDE 插件VS Code 擴(kuò)展則讓你在編輯器里直接調(diào)用。但本文聚焦 CLI auth.json 這條鏈路因?yàn)樗撬行螒B(tài)里最透明、最容易排障的。App 和插件本質(zhì)上也是讀同一份配置你把 CLI 跑通了另外兩個(gè)自然就通。2.4 準(zhǔn)備 TaoToken 的 API Key在開始改配置前先拿到 Key。訪問 https://taotoken.net/api-keys 創(chuàng)建一個(gè) API Key復(fù)制保存好。這個(gè) Key 就是后面 auth.json 里OPENAI_API_KEY字段的值。注意 Key 只在創(chuàng)建時(shí)完整顯示一次丟了就重新建一個(gè)。同時(shí)記下兩個(gè)地址后面配置要用Base URLhttps://taotoken.net/api模型對話入口用于網(wǎng)頁端驗(yàn)證https://taotoken.net/model-chat3. 可復(fù)制配置把 auth.json 指向 TaoToken 的完整寫法3.1 auth.json 在哪Codex CLI 讀取的配置文件默認(rèn)在用戶主目錄下的.codex文件夾里macOS / Linux~/.codex/auth.jsonWindowsC:\Users\你的用戶名\.codex\auth.json如果這個(gè)文件不存在手動(dòng)創(chuàng)建。目錄也要一起建mkdir -p ~/.codex3.2 auth.json 完整片段把下面這段復(fù)制進(jìn)去替換掉sk-你的TaoToken密鑰{ OPENAI_API_KEY: sk-你的TaoToken密鑰, OPENAI_BASE_URL: https://taotoken.net/api, model: gpt-5.5 }三個(gè)字段的含義字段作用取值OPENAI_API_KEY身份憑證你在 TaoToken 創(chuàng)建的 KeyOPENAI_BASE_URL請求發(fā)往的地址https://taotoken.net/apimodel默認(rèn)模型 ID如 gpt-5.5、gpt-5.4-mini注意 Base URL 結(jié)尾不要帶/v1也不要帶斜杠。Codex 內(nèi)部會(huì)自己拼接路徑你多寫一段就會(huì)變成https://taotoken.net/api/v1/v1/chat/completions這種重復(fù)路徑直接 404。3.3 用 TOML 配置默認(rèn)模型可選但推薦除了 auth.jsonCodex 還支持在~/.codex/config.toml里寫更細(xì)的偏好比如默認(rèn)模型和推理強(qiáng)度。這個(gè)文件和 auth.json 是互補(bǔ)的auth.json 管身份config.toml 管行為model gpt-5.5 model_reasoning_effort medium [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api chatwire_api chat表示走 Chat Completions 協(xié)議這是兼容性最好的選項(xiàng)。如果你用的是支持 Responses 協(xié)議的端點(diǎn)可以改成responses但先用chat跑通再說。3.4 環(huán)境變量方式備選如果你不想寫文件也可以用環(huán)境變量臨時(shí)覆蓋export OPENAI_API_KEYsk-你的TaoToken密鑰 export OPENAI_BASE_URLhttps://taotoken.net/api但環(huán)境變量在每次開新終端都要重設(shè)長期用還是寫 auth.json 省事。兩種方式同時(shí)存在時(shí)環(huán)境變量優(yōu)先級更高排查問題時(shí)記得檢查有沒有殘留的舊變量。4. 驗(yàn)證請求跑一次真實(shí)調(diào)用確認(rèn)配置生效4.1 啟動(dòng)交互式會(huì)話在任意項(xiàng)目目錄下打開終端輸入codex如果配置正確會(huì)進(jìn)入交互式界面顯示當(dāng)前模型和會(huì)話狀態(tài)。此時(shí)直接輸入一句自然語言比如用 Python 寫一個(gè)讀取 CSV 并統(tǒng)計(jì)每列缺失值的函數(shù)Codex 會(huì)把請求發(fā)到https://taotoken.net/api返回代碼。如果能看到流式輸出的代碼塊說明 Key、Base URL、模型三個(gè)字段全部生效。4.2 用單次執(zhí)行模式驗(yàn)證不想進(jìn)交互界面可以用exec子命令做一次性調(diào)用codex exec 解釋一下這段代碼的作用print([x**2 for x in range(5)])正常返回類似這行代碼生成 0 到 4 的平方列表輸出 [0, 1, 4, 9, 16]。4.3 指定模型驗(yàn)證想確認(rèn)模型切換也正常用-m參數(shù)codex -m gpt-5.4-mini exec 寫一個(gè) bash 函數(shù)判斷文件是否存在如果返回結(jié)果且沒有報(bào)模型不存在的錯(cuò)誤說明模型 ID 寫對了。模型 ID 必須和端點(diǎn)支持的列表一致寫錯(cuò)會(huì)返回model_not_found。4.4 成功結(jié)果的判斷標(biāo)準(zhǔn)一次成功的調(diào)用滿足三個(gè)條件終端有流式文字輸出、沒有紅色報(bào)錯(cuò)、退出碼為 0。你可以用echo $?檢查上一條命令的退出碼。如果輸出是 0配置就是通的。到這一步Codex 的基礎(chǔ)鏈路已經(jīng)跑通后面就是怎么用它干活的問題了。5. 常見報(bào)錯(cuò)排查401、local proxy failed 與 reading choices 怎么解5.1 401 Unauthorized報(bào)錯(cuò)長這樣Error: 401 Unauthorized - invalid_api_key原因通常是三個(gè)Key 復(fù)制時(shí)帶了空格、Key 已失效、auth.json 里字段名寫錯(cuò)。先檢查OPENAI_API_KEY的值有沒有首尾空格JSON 里字符串不能有多余空白。然后去 https://taotoken.net/api-keys 確認(rèn)這個(gè) Key 還在、沒被刪。最后確認(rèn)字段名是大寫下劃線格式寫成apiKey或openai_api_key都不認(rèn)。5.2 local proxy failed / connection refusedError: local proxy failed: dial tcp 127.0.0.1:xxxx: connect: connection refused這個(gè)報(bào)錯(cuò)說明 Codex 在嘗試連本地某個(gè)端口通常是你之前配過代理類工具留下的殘留配置。檢查~/.codex/config.toml里有沒有proxy相關(guān)字段有就刪掉。同時(shí)檢查環(huán)境變量里有沒有HTTP_PROXY、HTTPS_PROXY指向本地端口有就 unset 掉。Codex 應(yīng)該直連https://taotoken.net/api不需要經(jīng)過任何本地轉(zhuǎn)發(fā)。5.3 reading choices 相關(guān)報(bào)錯(cuò)Error: error reading choices: unexpected end of JSON input這個(gè)多半是 Base URL 寫錯(cuò)導(dǎo)致返回了非預(yù)期內(nèi)容。最常見的是結(jié)尾多寫了/v1請求打到了不存在的路徑服務(wù)端返回了 HTML 錯(cuò)誤頁Codex 按 JSON 解析就炸了。把OPENAI_BASE_URL改回https://taotoken.net/api不帶任何后綴。另一個(gè)可能是模型 ID 寫錯(cuò)服務(wù)端返回了錯(cuò)誤結(jié)構(gòu)同樣會(huì)觸發(fā)這個(gè)解析錯(cuò)誤。5.4 OAuth 登錄循環(huán)如果你之前走過賬號登錄流程auth.json 里可能殘留了 OAuth 相關(guān)字段和 API Key 模式?jīng)_突。最干凈的做法是刪掉整個(gè) auth.json 重新寫rm ~/.codex/auth.json然后按第 3 節(jié)的片段重新創(chuàng)建。Codex 啟動(dòng)時(shí)如果發(fā)現(xiàn)沒有 OAuth token 但有 API Key會(huì)直接走 Key 模式不會(huì)再彈登錄。5.5 排查順序建議遇到報(bào)錯(cuò)按這個(gè)順序查先看 Base URL 有沒有多余后綴再看 Key 是否有效再看模型 ID 是否存在最后看有沒有代理殘留。這四步能覆蓋九成以上的配置問題。如果還不行用codex --debug啟動(dòng)它會(huì)打印實(shí)際請求的 URL 和響應(yīng)狀態(tài)碼一眼就能看出請求打到哪去了。6. 長期使用建議與接入入口跑通之后日常使用還有幾個(gè)提效點(diǎn)。第一把常用模型寫進(jìn) config.toml 的model字段省得每次-m。第二項(xiàng)目根目錄放一個(gè)精簡的 README.mdCodex 需要時(shí)會(huì)自己去讀深層文件不用你把上萬行上下文全塞進(jìn) prompt。第三涉及數(shù)據(jù)庫遷移、外部 webhook 這類高危操作時(shí)Codex 會(huì)掛起等你確認(rèn)別嫌煩認(rèn)真看一眼再放行。如果你打算把 Codex 用在長期編碼任務(wù)或者 Agent 場景里可以了解下 Coding Plan它針對高頻調(diào)用做了額度優(yōu)化https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan需要管理多個(gè) Key 或者查看調(diào)用量控制臺在這里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole接入文檔含各語言 SDK 示例和字段說明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你用的是 Claude Code 那套工具鏈對應(yīng)的接入說明在https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code最后提醒一句auth.json 里存的是明文 Key別把它提交到 git。在項(xiàng)目里加一行.codex/到 .gitignore或者干脆把配置放在用戶主目錄而不是項(xiàng)目目錄從源頭避免泄露。