1. 先搞清楚 Codex CLI 與 VS Code 插件到底在解決什么問(wèn)題很多人第一次接觸 Codex會(huì)把它當(dāng)成聊天框里幫我寫個(gè)函數(shù)的工具用兩天就放下了。真正讓它變成生產(chǎn)力的是另一條路徑把它當(dāng)成一個(gè)能讀項(xiàng)目、能跑命令、能改多文件的命令行協(xié)作者。Codex CLI 是這條路徑的核心VS Code 插件則是把同一套能力搬進(jìn)編輯器側(cè)邊欄。兩者共享~/.codex/下的認(rèn)證與配置所以你在終端里調(diào)好的參數(shù)插件里基本能復(fù)用。我先把適用人群說(shuō)清楚如果你只是偶爾補(bǔ)全幾行代碼編輯器自帶的補(bǔ)全就夠了但如果你經(jīng)常面對(duì)這個(gè)報(bào)錯(cuò)在哪個(gè)文件、這個(gè)重構(gòu)要?jiǎng)訋讉€(gè)模塊、這個(gè)腳本能不能直接跑一遍驗(yàn)證這類任務(wù)Codex CLI 的--search、沙箱執(zhí)行、AGENTS.md項(xiàng)目約定就會(huì)明顯省時(shí)間。它適合后端邏輯、腳本編排、跨文件重構(gòu)也適合把重復(fù)的排查動(dòng)作寫成可復(fù)用的命令。從零上手到高階實(shí)際會(huì)卡在四個(gè)地方一是認(rèn)證方式選錯(cuò)auth.json寫錯(cuò)字段導(dǎo)致 401二是config.toml里模型名、審批策略、沙箱模式三者互相打架三是項(xiàng)目沒(méi)有AGENTS.md模型每次都要重新猜你的規(guī)范四是本地網(wǎng)絡(luò)層報(bào)local proxy failed這類錯(cuò)看著像代碼問(wèn)題其實(shí)是通道問(wèn)題。這篇就按先跑通、再調(diào)優(yōu)、再排障的順序走每一步都給可復(fù)制的片段和驗(yàn)證動(dòng)作。統(tǒng)一 Key 與 API 通道這部分我會(huì)用 TaoToken 作為示例接入點(diǎn)因?yàn)樗?Base URL 和 Key 管理比較直觀適合把 CLI 和 VS Code 兩條線一次配好。你完全可以在官網(wǎng) https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 完成注冊(cè)后拿到 Key再回到本文按步驟填。下面所有配置都以能復(fù)制、能驗(yàn)證為標(biāo)準(zhǔn)不寫空泛的連上就能用。2. TaoToken 前置準(zhǔn)備Key、Base URL 與目錄結(jié)構(gòu)一次理清在動(dòng)config.toml之前先把三樣?xùn)|西備齊API Key、Base URL、你要用的 Model ID。這三件套在后面 CLI、VS Code、auth.json里會(huì)反復(fù)出現(xiàn)先記在一個(gè)地方避免來(lái)回翻。第一步打開(kāi) https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注冊(cè)并登錄進(jìn)入控制臺(tái)。左側(cè)找到 API Keys 入口新建一個(gè) Key命名建議帶上用途比如codex-cli-mac方便以后按設(shè)備吊銷。Key 只在創(chuàng)建時(shí)完整顯示一次復(fù)制后先存到密碼管理器。控制臺(tái)地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsole API Keys 頁(yè)面是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys 兩個(gè)都帶同一套歸因參數(shù)收藏哪個(gè)都行。第二步確認(rèn) Base URL。TaoToken 的 API 根地址是https://taotoken.net/api注意這里不加任何查詢參數(shù)配置里就寫這個(gè)純地址。有些工具要求帶/v1后綴Codex 的wire_api走 responses 協(xié)議時(shí)Base URL 填根地址即可具體拼接由客戶端完成。如果你在別的工具里看到https://taotoken.net/api/v1這種寫法那是那個(gè)工具的約定不要混進(jìn) Codex 配置。第三步選 Model ID。Codex 場(chǎng)景常用的是編程向模型你在控制臺(tái)的模型列表里能看到當(dāng)前可用的名稱。把它原樣抄進(jìn)配置大小寫和連字符都不要改。模型名寫錯(cuò)最典型的報(bào)錯(cuò)是返回里choices為空或者直接 404后面排障章節(jié)會(huì)細(xì)說(shuō)。目錄結(jié)構(gòu)也要先建立認(rèn)知。Codex 的用戶級(jí)配置都在~/.codex/下auth.json存認(rèn)證config.toml存全局參數(shù)AGENTS.md可以放全局偏好。項(xiàng)目級(jí)則在倉(cāng)庫(kù)根目錄放AGENTS.md子目錄還能再放一層覆蓋。Windows 用戶如果走 WSL2路徑就是 WSL 里的家目錄不要在 Windows 側(cè)和 WSL 側(cè)各配一份容易互相覆蓋。注意Key 不要寫進(jìn)項(xiàng)目倉(cāng)庫(kù)里的任何文件auth.json和config.toml都在用戶主目錄天然不進(jìn) Git。團(tuán)隊(duì)共享的是AGENTS.md不是 Key。環(huán)境要求順帶確認(rèn)一下Node.js 18 以上macOS 12、Ubuntu 20.04 或 Windows 11 的 WSL2。裝 CLI 用npm install -g openai/codex裝完codex --version能出版本號(hào)就說(shuō)明二進(jìn)制就位。這一步不涉及任何網(wǎng)絡(luò)層特殊設(shè)置如果 npm 裝包慢換國(guó)內(nèi)鏡像源即可和后面的 API 通道是兩回事。3. 可復(fù)制配置config.toml、auth.json 與 AGENTS.md 模板這一節(jié)是全文的核心三個(gè)文件配好后面就是驗(yàn)證和排障。先給~/.codex/config.toml的完整模板字段都有注釋你按需改值。# ~/.codex/config.toml # 默認(rèn)模型填你在 TaoToken 控制臺(tái)看到的 Model ID model gpt-5-codex # 推理力度low / medium / high復(fù)雜重構(gòu)建議 high model_reasoning_effort high # 審批策略u(píng)ntrusted 每次執(zhí)行前詢問(wèn)on-failure 沙箱失敗時(shí)再問(wèn)never 全自動(dòng) approval_policy untrusted # 沙箱模式read-only 只讀workspace-write 可寫工作區(qū)danger-full-access 全盤 sandbox_mode workspace-write # 關(guān)閉響應(yīng)存儲(chǔ)減少不必要的往返 disable_response_storage true # 走 responses 協(xié)議 wire_api responses # 自定義 API 通道Base URL 用純根地址 [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY # 安全檔 profile只讀、低推理適合陌生倉(cāng)庫(kù)先摸清結(jié)構(gòu) [profiles.safe_mode] model gpt-5-codex approval_policy untrusted sandbox_mode read-only model_reasoning_effort low # 全自動(dòng)檔 profile信任的本地倉(cāng)庫(kù)做批量重構(gòu)時(shí)用 [profiles.auto_mode] model gpt-5-codex approval_policy never sandbox_mode workspace-write model_reasoning_effort high這里有個(gè)容易踩的點(diǎn)env_key指定的是環(huán)境變量名不是 Key 本身。你需要在 shell 里export TAOTOKEN_API_KEYsk-...或者寫進(jìn)~/.zshrc/~/.bashrc。另一種方式是走auth.json兩者選其一即可不要同時(shí)配導(dǎo)致來(lái)源沖突。~/.codex/auth.json模板如下字段名要和客戶端預(yù)期一致{ OPENAI_API_KEY: sk-你的TaoToken密鑰 }如果你更習(xí)慣環(huán)境變量方式auth.json可以只留空對(duì)象{}讓客戶端從TAOTOKEN_API_KEY讀取。實(shí)測(cè)下來(lái)CLI 場(chǎng)景用環(huán)境變量更靈活切換 Key 不用改文件VS Code 插件場(chǎng)景用auth.json更省心因?yàn)椴寮M(jìn)程不一定繼承你終端里的 export。接著是項(xiàng)目根目錄的AGENTS.md這是給模型看的項(xiàng)目說(shuō)明書寫得越具體它越少犯低級(jí)錯(cuò)# AGENTS.md ## 項(xiàng)目簡(jiǎn)介 Next.js TypeScript 的電商后臺(tái)包管理器用 pnpmNode 20。 ## 開(kāi)發(fā)規(guī)范 - 代碼風(fēng)格遵循 Prettier ESLint提交前必須過(guò) lint。 - 組件與變量用駝峰命名文件名用 kebab-case。 - 提交信息遵循 Conventional Commits如 feat(cart): add coupon input。 ## 常用命令 - 啟動(dòng)開(kāi)發(fā)pnpm dev - 跑測(cè)試pnpm test - 構(gòu)建pnpm build - 類型檢查pnpm tsc --noEmit ## 注意事項(xiàng) - 禁止直接改 dist/ 下任何文件。 - 新增功能必須補(bǔ)對(duì)應(yīng)單測(cè)測(cè)試文件放同目錄 __tests__。 - 改動(dòng)涉及數(shù)據(jù)庫(kù) schema 時(shí)先輸出遷移方案再動(dòng)手。子目錄可以再放一份AGENTS.md覆蓋局部規(guī)則比如src/server/AGENTS.md里寫本目錄只允許改 service 層controller 改動(dòng)需在 PR 描述說(shuō)明。全局偏好放~/.codex/AGENTS.md比如回答用中文、代碼注釋用英文。VS Code 側(cè)插件安裝后在設(shè)置里搜chatgpt.apiBase填https://taotoken.net/api再在chatgpt.config里補(bǔ)preferred_auth_method為apikey、model為你的 Model ID、wire_api為responses。插件和 CLI 共用~/.codex/auth.json所以 Key 只需配一次。如果你用 Cline 這類支持 MCP 的插件MCP server 配置里同樣要寫全 Base URL、Key、Model ID 三件套缺一個(gè)就連不上。4. 逐步驗(yàn)證從 codex --version 到一次真實(shí)請(qǐng)求的成功回顯配置寫完不算完要一步步驗(yàn)證每步都有明確的成功信號(hào)出錯(cuò)時(shí)才能定位到具體環(huán)節(jié)。第一步驗(yàn)證 CLI 就位。終端執(zhí)行codex --version能打印版本號(hào)即通過(guò)。如果提示 command not found檢查 npm 全局 bin 是否在 PATH 里npm bin -g看路徑再補(bǔ)進(jìn) shell 配置。第二步驗(yàn)證認(rèn)證讀取。執(zhí)行codex login --api-key sk-你的Key或者確認(rèn)環(huán)境變量已 export 后直接進(jìn)下一步。成功時(shí)不會(huì)有長(zhǎng)篇輸出通常只提示已保存認(rèn)證。如果這里就報(bào) 401先別懷疑配置去 TaoToken 控制臺(tái)確認(rèn) Key 沒(méi)過(guò)期、沒(méi)被吊銷、額度沒(méi)耗盡。第三步最小請(qǐng)求驗(yàn)證。在任意空目錄執(zhí)行codex -m gpt-5-codex -c model_reasoning_effortlow 用一句話說(shuō)明當(dāng)前目錄下有哪些文件成功信號(hào)是模型返回一句描述并且沒(méi)有報(bào)錯(cuò)堆棧。這一步故意用low推理和只讀意圖避免觸發(fā)寫操作審批。如果返回里出現(xiàn)choices相關(guān)錯(cuò)誤說(shuō)明模型名或協(xié)議不對(duì)如果出現(xiàn)連接類錯(cuò)誤看下一節(jié)。第四步驗(yàn)證項(xiàng)目約定生效。進(jìn)入你的倉(cāng)庫(kù)根目錄執(zhí)行codex 根據(jù) AGENTS.md 的規(guī)范告訴我跑測(cè)試的命令是什么如果它答出pnpm test而不是泛泛的npm test說(shuō)明AGENTS.md被正確加載。這一步很關(guān)鍵很多人配了文件但模型沒(méi)讀到就是因?yàn)槲募辉趥}(cāng)庫(kù)根目錄或者啟動(dòng)目錄不對(duì)。第五步驗(yàn)證沙箱與審批。執(zhí)行一個(gè)會(huì)寫文件的任務(wù)codex -c approval_policyuntrusted 在項(xiàng)目根目錄新建 notes.md寫入今天的日期untrusted策略下它應(yīng)該先向你請(qǐng)求批準(zhǔn)再寫。你批準(zhǔn)后文件出現(xiàn)說(shuō)明沙箱寫權(quán)限和審批鏈路都通。如果它直接寫了沒(méi)問(wèn)檢查config.toml里approval_policy是否被 profile 覆蓋。第六步驗(yàn)證 VS Code 插件。打開(kāi)命令面板讓插件發(fā)一條簡(jiǎn)單請(qǐng)求比如解釋當(dāng)前打開(kāi)文件的用途。成功回顯說(shuō)明插件側(cè)的 Base URL、Key、Model ID 三件套都正確。插件報(bào)錯(cuò)時(shí)優(yōu)先看輸出面板里的請(qǐng)求日志里面會(huì)帶 HTTP 狀態(tài)碼比界面提示有用得多。六步走完CLI 和插件兩條線都通了。后面再調(diào)model_reasoning_effort、切 profile、加 MCP都是在穩(wěn)定底座上做增量出問(wèn)題也容易回滾。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed、reading choices 與 OAuth 失敗排障的核心思路是先分層再看碼。Codex 的報(bào)錯(cuò)大致分四層認(rèn)證層、網(wǎng)絡(luò)層、協(xié)議層、權(quán)限層。下面按真實(shí)報(bào)錯(cuò)逐條對(duì)。401 Unauthorized。最常見(jiàn)原因通常是 Key 無(wú)效、Key 與 Base URL 不匹配、或者auth.json字段名寫錯(cuò)。先確認(rèn)auth.json里是OPENAI_API_KEY這個(gè)鍵不是api_key或token。再確認(rèn)環(huán)境變量和文件不要同時(shí)存在且值不同客戶端讀取優(yōu)先級(jí)可能讓你以為改了其實(shí)沒(méi)生效。最后去控制臺(tái)核對(duì) Key 狀態(tài)。修完后用第 4 節(jié)的第三步最小請(qǐng)求復(fù)驗(yàn)。local proxy failed / connection refused。這類錯(cuò)看著嚇人本質(zhì)是客戶端連不上你配置的 Base URL。先curl -I https://taotoken.net/api看能否拿到響應(yīng)頭如果 curl 通而 codex 不通多半是客戶端讀到了舊的代理環(huán)境變量比如HTTP_PROXY指向了一個(gè)已關(guān)閉的本地端口。清掉相關(guān)環(huán)境變量再試。如果 curl 也不通檢查本機(jī) DNS 和出站規(guī)則這一步和 Codex 配置無(wú)關(guān)。reading choices / choices 為空。說(shuō)明請(qǐng)求發(fā)出去了、也拿到了響應(yīng)但響應(yīng)結(jié)構(gòu)里沒(méi)有預(yù)期的choices字段。三個(gè)高發(fā)原因Model ID 拼錯(cuò)比如把連字符寫成下劃線、wire_api與通道不匹配responses 協(xié)議卻配了 chat 端點(diǎn)、Base URL 多寫了/v1導(dǎo)致路徑重復(fù)。逐個(gè)核對(duì)第 3 節(jié)模板里的三個(gè)值改完重啟 CLI 再驗(yàn)。OAuth 相關(guān)失敗。如果你之前用過(guò)瀏覽器登錄方式auth.json里可能殘留 OAuth 令牌和 API Key 方式?jīng)_突。處理方式是清空auth.json只留OPENAI_API_KEY或者刪掉文件重新codex login --api-key。插件側(cè)同理在設(shè)置里把認(rèn)證方式顯式設(shè)為apikey不要留自動(dòng)。權(quán)限被拒 / 沙箱寫入失敗。報(bào)錯(cuò)里帶 sandbox 字樣時(shí)看sandbox_mode。read-only下任何寫操作都會(huì)被攔這是預(yù)期行為不是 bug。需要寫就切workspace-write或者用--profile auto_mode啟動(dòng)。反過(guò)來(lái)如果你發(fā)現(xiàn)它未經(jīng)詢問(wèn)就改了文件檢查是不是 profile 把a(bǔ)pproval_policy覆蓋成了never。AGENTS.md 不生效。模型答非所問(wèn)、忽略你的命令約定時(shí)先確認(rèn)啟動(dòng)目錄就是倉(cāng)庫(kù)根目錄再確認(rèn)文件名大小寫完全一致。子目錄規(guī)則只對(duì)在該子目錄下發(fā)起的任務(wù)生效跨目錄任務(wù)讀的是根目錄那份。可以用第 4 節(jié)第四步的提問(wèn)法快速自測(cè)。把這幾類錯(cuò)和對(duì)應(yīng)層記住下次看到報(bào)錯(cuò)先歸類再動(dòng)手比盲目改配置快得多。每次改完只動(dòng)一個(gè)變量改完立刻用最小請(qǐng)求復(fù)驗(yàn)這樣能保證你始終知道是哪一處改動(dòng)起了作用。6. 把配置沉淀成團(tuán)隊(duì)資產(chǎn)從單機(jī)調(diào)優(yōu)到可復(fù)用工作流單機(jī)跑通之后真正拉開(kāi)差距的是把配置變成團(tuán)隊(duì)可復(fù)用的東西。AGENTS.md天然適合進(jìn) Git它是項(xiàng)目規(guī)范的一部分新人 clone 下來(lái)就自帶上下文。config.toml里的 profile 可以按場(chǎng)景固化safe_mode給陌生倉(cāng)庫(kù)和代碼審查用auto_mode給信任的本地批量重構(gòu)用日常開(kāi)發(fā)用默認(rèn)檔。這樣你不用每次記一長(zhǎng)串命令行參數(shù)codex --profile safe_mode ...一句話切換。模型對(duì)話入口適合做方案討論和提示詞打磨地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chat 你在 CLI 里調(diào)好的模型名可以直接在這里對(duì)照驗(yàn)證。如果你長(zhǎng)期做編碼和 Agent 類任務(wù)Coding Plan 頁(yè)面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan 有按周期計(jì)費(fèi)的方案比逐次調(diào)用更好估算成本。接入文檔在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc 遇到協(xié)議細(xì)節(jié)以文檔為準(zhǔn)。Claude Code 用戶如果要對(duì)照 Anthropic 兼容配置參考 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropic 。最后給一個(gè)我常用的習(xí)慣每次升級(jí) CLI 或插件版本后重跑第 4 節(jié)的六步驗(yàn)證尤其是第三步最小請(qǐng)求和第四步AGENTS.md生效檢查。版本升級(jí)偶爾會(huì)改配置字段名六步跑一遍比等出問(wèn)題再回滾省事。配置文件和AGENTS.md都進(jìn)版本管理Key 永遠(yuǎn)留在用戶目錄這條邊界守住團(tuán)隊(duì)協(xié)作就不會(huì)因?yàn)橐话?Key 泄露而返工。