：從配置到識圖 Skill 完整指南)
很多用 Codex 寫代碼的開發(fā)者第一反應(yīng)是“裝好就能用”。真正上手后你會發(fā)現(xiàn)環(huán)境搭好只是開始模型選型、接口兼容、多模態(tài)擴展每一步都可能卡住你半天。尤其是想用 DeepSeek 這類高效模型替換默認模型時很多人會在配置層反復(fù)試錯最后發(fā)現(xiàn) Codex 的接入?yún)f(xié)議和模型能力邊界才是關(guān)鍵。這篇教程要解決的就是這件事把 DeepSeek-V4-Pro 原生接入 Codex跑通一個真實的編碼任務(wù)再配一個識圖 Skill 補齊視覺理解能力。整個過程我會按“概念 → 環(huán)境 → 配置 → 代碼 → 驗證 → 排錯 → 建議”的順序拆開講最后附上一些容易踩坑的細節(jié)。無論你是剛接觸 AI 編程助手的新手還是已經(jīng)在用 Codex 但想換成更順手的模型這篇文章都能給你一份可以直接照做的路徑。1. 為什么要折騰“換模型”這件事Codex 作為編程助手底層模型決定了它理解代碼、生成代碼、執(zhí)行命令的上限。默認模型雖然綜合表現(xiàn)不錯但開發(fā)者在實際項目中往往有更具體的訴求有的希望降低調(diào)用成本有的希望中文理解更自然有的希望代碼風(fēng)格更貼近國內(nèi)團隊規(guī)范。這時候把模型替換成 DeepSeek-V4-Pro 就是一種很自然的解法。不過這里要先給一個判斷Codex 和 DeepSeek 的對接核心不在 Codex 本身而在“它們之間使用什么協(xié)議溝通”。Codex 官方支持 OpenAI 兼容的接口協(xié)議DeepSeek 對外提供的 API 同樣兼容這一協(xié)議。所以表面上是“換模型”實際上是在 Codex 的配置層指定一個新的模型提供方。這意味著你不需要修改 Codex 的源碼也不需要寫復(fù)雜的適配層只需要在配置文件里告訴 Codex“去哪個地址、用哪個 Key、調(diào)哪個模型”。這個思路一旦建立后續(xù)不管是接 DeepSeek 還是接其他模型你都能快速遷移。還有一類開發(fā)者的需求是“視覺”。DeepSeek-V4-Pro 作為文本模型本身不直接處理圖片輸入。但在真實開發(fā)里你經(jīng)常需要給 AI 看設(shè)計圖、截圖、報錯界面、手繪圖讓 AI 理解后生成代碼。這個能力不能靠模型憑空變出來要靠一個額外的 Skill 來補位。所以這篇文章真正的價值是幫你建立一套可組合的 AI 編程環(huán)境主模型負責(zé)理解和生成代碼Skill 負責(zé)擴展模型不具備的能力。兩者配合Codex 才不是“一個聊天框”而是“一個能看圖、能寫代碼、能執(zhí)行命令的工程助手”。2. DeepSeek-V4-Pro 與 Codex 的核心概念2.1 DeepSeek-V4-Pro 是什么DeepSeek 系列模型來自深度求索特點是代碼能力強、中文理解好、性價比高。V4-Pro 這個版本在標題里被標記為“正式發(fā)布”如果你想驗證它的實際表現(xiàn)核心不是聽宣傳而是跑一組你自己的測試任務(wù)。比如讓它讀一段倉庫代碼、改一個 bug、寫一個單元測試觀察它的生成質(zhì)量和速度。這里要特別提醒不同版本模型在 API 里的名稱可能不同比如模型 ID 可能是deepseek-chat或類似名稱。配置時必須以你實際拿到的 API 文檔為準不要照搬別人文章里的模型名。2.2 Codex 是什么Codex 是 OpenAI 推出的編程智能體它不是在網(wǎng)頁里對話的助手而是跑在終端里的工程工具。它能做這些事情讀取你本地項目里的代碼文件理解你提出的編碼任務(wù)生成代碼補丁執(zhí)行 shell 命令運行測試并讀取結(jié)果根據(jù)測試失敗信息反復(fù)修正代碼它的工作流非常接近一個真實工程師先看代碼再改代碼然后跑測試驗證最后交付改動。Codex 的可配置性來自“模型提供方”model provider機制。它可以調(diào)用 OpenAI 默認模型也可以通過配置切換到其他兼容服務(wù)。這個機制就是 DeepSeek 接入的依據(jù)。2.3 Skill 機制是什么Skill 是 Codex 生態(tài)里的擴展機制可以理解成給 AI 編程助手加“職業(yè)技能”。Codex 默認的文本模型不會直接“看”圖片但如果你給它掛一個“識圖 Skill”它就能在需要的時候調(diào)用這個工具完成圖像理解。Skill 一般包含兩部分描述信息告訴模型什么時候該使用這個技能執(zhí)行邏輯實際調(diào)用視覺模型把圖片變成文本描述從架構(gòu)上看這非常像函數(shù)調(diào)用function calling。Codex 在主流程里發(fā)現(xiàn)任務(wù)涉及圖片就會調(diào)用 SkillSkill 內(nèi)部請求視覺模型再把結(jié)果返回給主模型繼續(xù)編碼。這種組合方式讓文本模型和視覺模型各司其職不用為了“能看圖”而犧牲代碼能力。3. 環(huán)境準備與前置條件開始之前先把環(huán)境梳理清楚。下面的清單以通用情況為例具體版本以你本機為準。3.1 基礎(chǔ)環(huán)境要求項目推薦要求說明操作系統(tǒng)macOS / Linux / WindowsWindows 建議使用 PowerShell 或 WSLNode.js較新穩(wěn)定版本Codex CLI 基于 Node.js 構(gòu)建npm隨 Node.js 安裝用于安裝 Codex CLIGit建議安裝便于管理項目代碼和補丁API KeyDeepSeek 平臺申請用于調(diào)用 DeepSeek 模型接口版本檢查命令node --version npm --version git --version如果提示command not found先安裝對應(yīng)工具再繼續(xù)。3.2 安裝 Codex CLICodex 的官方安裝方式是通過 npm。打開終端執(zhí)行npm install -g codex安裝完成后驗證codex --version如果這一步輸出版本號說明 Codex CLI 已經(jīng)裝好。這里需要說明版本號會持續(xù)更新你本地拿到的最新版本即為當前可用版本不需要刻意追求教程里的某個數(shù)字。3.3 準備 DeepSeek API Key想要在 Codex 里調(diào)用 DeepSeek你需要一個有效的 DeepSeek API Key。這個 Key 一般是在 DeepSeek 開放平臺上創(chuàng)建創(chuàng)建時需要實名認證并充值少量金額。拿到 Key 后先保存好下一步配置時要用。從安全角度出發(fā)不要把 Key 寫死在項目代碼里更不要提交到 Git 倉庫。推薦使用環(huán)境變量或 Codex 提供的配置管理機制來保存。4. 核心流程拆解DeepSeek-V4-Pro 接入 Codex 的完整流程可以分為六個步驟。4.1 明確接入?yún)f(xié)議DeepSeek 的 API 兼容 OpenAI 接口格式這意味著 Codex 不需要額外插件只需要把請求的 base_url 指向 DeepSeek 的 API 地址把模型名稱改成 DeepSeek 對應(yīng)的模型 ID。這一步是整個接入的架構(gòu)基礎(chǔ)。4.2 初始化 Codex 配置Codex CLI 安裝后會自動創(chuàng)建配置文件目錄。配置文件一般位于用戶目錄下的.codex文件夾中常見文件名是config.toml。如果你的電腦上沒有這個文件可以通過codex init命令生成。codex init執(zhí)行后檢查配置文件是否存在ls ~/.codex/config.toml4.3 配置模型提供方在config.toml中你需要聲明一個模型提供方并指定 base_url 和 API Key 對應(yīng)的環(huán)境變量名。下面是一份參考配置。# 文件路徑~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY配置說明model實際調(diào)用的模型 ID。請以 DeepSeek 官方文檔為準如果文檔里的模型名不是deepseek-chat替換成真實名稱即可。model_provider指定使用哪個提供方對應(yīng)下方[model_providers.deepseek]配置塊。base_urlDeepSeek API 的基礎(chǔ)地址末尾/v1一般不能漏。env_keyCodex 會讀取這個環(huán)境變量名來獲得 API Key。也就是說你需要在系統(tǒng)環(huán)境變量里設(shè)置DEEPSEEK_API_KEY。然后設(shè)置環(huán)境變量export DEEPSEEK_API_KEY你的DeepSeek API Key為了讓環(huán)境變量長期生效可以把它寫入 shell 的配置文件中例如~/.bashrc或~/.zshrc。生產(chǎn)環(huán)境或團隊協(xié)作時推薦使用密鑰管理工具。4.4 驗證 API 連通性配置完成后先不急著啟動 Codex先用 curl 驗證 API 能否連通。這一步能快速定位問題在網(wǎng)絡(luò)層還是配置層。curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY如果返回一段 JSON里面包含模型列表說明 Key 有效、網(wǎng)絡(luò)連通、地址正確。如果返回 401說明 Key 無效或鑒權(quán)頭不對如果返回超時說明網(wǎng)絡(luò)不通或者地址錯誤。4.5 啟動 Codex 并測試基礎(chǔ)對話確認 API 連通后啟動 Codexcodex進入交互界面后先給一個簡單任務(wù)比如“請用 Python 寫一個函數(shù)判斷一個字符串是否是回文。”這一步的目的是驗證 Codex 能否成功請求 DeepSeek 模型。如果模型返回結(jié)果并且速度正常說明接入成功。4.6 跑一個真實編碼任務(wù)基礎(chǔ)驗證通過后再跑一個貼近實際的任務(wù)。建議在你自己的項目里操作這樣 Codex 能讀取真實代碼上下文。比如讓它修復(fù)一個測試失敗或者新增一個接口。這類任務(wù)能驗證三件事模型是否能理解項目結(jié)構(gòu)、是否能修改正確文件、是否能運行測試驗證結(jié)果。5. 完整示例與代碼實現(xiàn)下面給出一套可以完整跑通的示例流程。為了演示清晰我們創(chuàng)建一個臨時項目目錄里面放一個簡單的 Python 文件和一個測試文件。5.1 創(chuàng)建測試項目mkdir -p ~/codex-demo cd ~/codex-demo創(chuàng)建calculator.py# 文件路徑~/codex-demo/calculator.py def add(a, b): return a b def subtract(a, b): return a - b創(chuàng)建test_calculator.py# 文件路徑~/codex-demo/test_calculator.py from calculator import add, subtract def test_add(): assert add(2, 3) 5 def test_subtract(): assert subtract(5, 2) 35.2 啟動 Codex 執(zhí)行任務(wù)在項目目錄下啟動 Codexcodex輸入任務(wù)“閱讀 calculator.py 和 test_calculator.py運行測試然后新增一個 multiply 函數(shù)和對應(yīng)測試。”Codex 會讀取文件、修改代碼、執(zhí)行測試。你需要觀察的是它是否自動完成了“改代碼 → 跑測試 → 根據(jù)結(jié)果修正”的完整循環(huán)。5.3 識圖 Skill 的代碼實現(xiàn)現(xiàn)在來寫識圖 Skill。這個 Skill 的目標是Codex 遇到需要理解圖片內(nèi)容的任務(wù)時調(diào)用一個視覺模型把圖片轉(zhuǎn)換成文本描述再交給主模型處理。我們先創(chuàng)建一個 Skill 目錄mkdir -p ~/.codex/skills/image-ocr在目錄下創(chuàng)建SKILL.md# 文件路徑~/.codex/skills/image-ocr/SKILL.md name: image-ocr description: 當用戶需要理解圖片內(nèi)容、截圖、設(shè)計圖、OCR文字識別時使用此技能。再創(chuàng)建一個執(zhí)行腳本run.py# 文件路徑~/.codex/skills/image-ocr/run.py import os import sys import base64 from openai import OpenAI def encode_image(image_path): with open(image_path, rb) as image_file: return base64.b64encode(image_file.read()).decode(utf-8) def analyze_image(image_path): api_key os.environ.get(VISION_API_KEY) base_url os.environ.get(VISION_BASE_URL, https://api.openai.com/v1) model os.environ.get(VISION_MODEL, gpt-4o-mini) client OpenAI(api_keyapi_key, base_urlbase_url) base64_image encode_image(image_path) response client.chat.completions.create( modelmodel, messages[ { role: user, content: [ {type: text, text: 請描述這張圖片的內(nèi)容提取所有文字信息并總結(jié)界面結(jié)構(gòu)。}, {type: image_url, image_url: {url: fdata:image/png;base64,{base64_image}}} ] } ] ) return response.choices[0].message.content if __name__ __main__: image_path sys.argv[1] result analyze_image(image_path) print(result)這段代碼的用途是調(diào)用視覺模型。如果你選擇其他支持視覺的模型只需要改環(huán)境變量VISION_MODEL和VISION_BASE_URL核心邏輯不變。5.4 在 Codex 中調(diào)用識圖 Skill實際使用時你不需要手動運行run.py。更好的方式是在 Codex 對話中描述任務(wù)讓它自動判斷是否需要識圖。比如“請查看 design.png 這張設(shè)計圖然后根據(jù)圖中的布局生成一個 HTML 頁面?！盋odex 檢測到任務(wù)涉及圖片理解會通過 Skill 機制執(zhí)行run.py把圖片描述結(jié)果拿回來再生成代碼。如果 Codex 沒有自動調(diào)用你可以顯式說明“請使用 image-ocr 技能處理這張圖片”。5.5 模型配置的完整參考整合 DeepSeek 主模型和識圖 Skill 之后完整配置如下# 文件路徑~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY注意視覺模型的配置是通過環(huán)境變量在 Skill 腳本中獨立管理的和 Codex 主模型配置互不干擾。這就保持了架構(gòu)上的解耦。6. 運行結(jié)果與效果驗證配置完成后用下面幾個命令驗證整個鏈路是否正常。6.1 驗證 Codex 主模型運行codex對話中輸入“請寫一句話說明你是通過什么模型運行的?！比绻祷亟Y(jié)果正常說明 DeepSeek 已經(jīng)作為 Codex 的主模型生效。6.2 驗證識圖 Skill準備一張測試圖片test.png然后在 Codex 中輸入“請使用 image-ocr 技能查看 test.png描述圖片內(nèi)容。”觀察是否輸出圖片的文字和結(jié)構(gòu)信息。如果上一步 Codex 不會自動調(diào)用 Skill可以手動在終端驗證腳本本身python ~/.codex/skills/image-ocr/run.py test.png如果腳本能正確輸出圖片描述說明視覺鏈路是通的問題只在于 Codex 是否識別到了這個 Skill。6.3 判斷成功與失敗現(xiàn)象判斷Codex 能正常對話且回復(fù)有代碼風(fēng)格主模型接入成功Codex 報錯權(quán)限或 401API Key 無效或環(huán)境變量未設(shè)置Codex 能對話但回復(fù)很慢檢查網(wǎng)絡(luò)延遲或模型負載Skill 腳本單獨運行正常但 Codex 不調(diào)用檢查 SKILL.md 描述是否足夠清晰圖片生成代碼時完全忽略圖片可能沒有觸發(fā) Skill需要顯式指定7. 常見問題與排查思路問題現(xiàn)象可能原因排查方式解決方案啟動 Codex 提示找不到模型model 名稱配置錯誤查看 DeepSeek 官方模型列表替換為正確的模型 ID請求返回 401API Key 錯誤或環(huán)境變量未加載執(zhí)行echo $DEEPSEEK_API_KEY重新導(dǎo)出環(huán)境變量檢查 shell 配置文件請求返回 404base_url 地址錯誤用 curl 手動請求驗證確認/v1路徑是否完整Codex 不執(zhí)行 shell 命令權(quán)限或安全策略限制查看 Codex 配置的權(quán)限項調(diào)整命令執(zhí)行權(quán)限注意合規(guī)識圖 Skill 無法觸發(fā)SKILL.md 描述不夠明確檢查 Skill 目錄位置和格式重寫 description明確觸發(fā)條件視覺模型返回結(jié)果為空圖片過大或格式不支持檢查圖片格式和大小壓縮圖片或轉(zhuǎn)換格式Codex 生成的代碼無法運行模型上下文不足或需求描述不清查看生成代碼的錯誤信息細化任務(wù)描述分步執(zhí)行群里很多朋友問的第一個問題其實是“為什么我的 Codex 一直用默認模型”。這種時候我一般會讓他們先跑一次codex --version再檢查config.toml是否存在。大多數(shù)情況是配置文件根本沒有生效或者環(huán)境變量沒有寫入當前 shell。還有一種很常見的情況是配置文件改了但 Codex 沒有重啟。配置文件的改動必須重啟 Codex 進程才會重新加載這個細節(jié)容易忽略。8. 最佳實踐與工程建議8.1 API Key 不落盤不要把 Key 寫在config.toml里也不要把 Key 提交到 Git 倉庫。使用環(huán)境變量或?qū)I(yè)的密鑰管理服務(wù)能顯著降低泄露風(fēng)險。如果懷疑 Key 泄露第一時間在平臺后臺輪換。8.2 配置文件納入版本管理~/.codex/config.toml這種配置文件適合保存一份模板到 Git 倉庫但模板中不要包含真實 Key。團隊協(xié)作時新人拉取模板后只需要配置自己的環(huán)境變量就能快速接入。8.3 Skill 拆分原則識圖 Skill 的腳本不應(yīng)該綁定某一個具體視覺模型。通過環(huán)境變量傳入模型名稱和地址能讓你在后續(xù)換模型時不需要修改腳本代碼。這個原則叫“配置與代碼分離”在 AI 工程化中很重要。8.4 任務(wù)描述要具體Codex 生成代碼的質(zhì)量很大程度上取決于任務(wù)描述的清晰度。不要只寫“優(yōu)化這段代碼”要寫清楚“這個函數(shù)在并發(fā)場景下偶發(fā)死鎖請分析可能原因并修復(fù)”。模型能理解的信息越多輸出越靠譜。8.5 先小步驗證再批量執(zhí)行在生產(chǎn)項目中使用 Codex 改代碼時建議每次只讓它處理一個小任務(wù)檢查生成的 diff再決定是否采納。不要讓它一次改動十幾個文件否則一旦出現(xiàn)問題回滾成本很高。8.6 定期檢查模型更新DeepSeek 模型版本更新后API 模型名稱和參數(shù)可能變化。升級版本前先閱讀官方文檔確認模型名、上下文長度、計費方式的變化再決定是否切換。8.7 理解 Skill 的邊界Skill 不是萬能插件它只是讓 Codex 多了一項工具調(diào)用能力。識圖 Skill 的準確度取決于底層視覺模型如果視覺模型本身識別不了復(fù)雜圖表Skill 再完善也無濟于事。選視覺模型時建議在真實任務(wù)中測試不要只看宣傳。9. 總結(jié)與后續(xù)學(xué)習(xí)方向這篇教程主要解決了三個問題。第一DeepSeek-V4-Pro 接入 Codex 的原理是協(xié)議兼容不是源碼改造。理解這一層你就不會被各種花哨的接入教程迷惑。第二完整跑通了一個編碼項目從創(chuàng)建文件到讓 Codex 自動改代碼、跑測試、生成補丁讓你感受到真實工作流下的 Codex。第三通過識圖 Skill 補齊了文本模型的視覺短板。這個能力組合的思路比單純“會安裝”重要得多它能幫你應(yīng)對更多真實開發(fā)場景。接下來可以繼續(xù)深入的方向包括研究 Codex 的命令執(zhí)行權(quán)限管理學(xué)習(xí)如何編寫更復(fù)雜的 Skill了解多模型路由與按任務(wù)自動選擇模型的架構(gòu)。建議你新建一個專門測試 Codex 的倉庫把常用任務(wù)整理成任務(wù)清單逐步驗證不同模型的代碼能力差異。實踐是檢驗?zāi)Ｐ湍芰ψ钣行У姆绞揭彩翘嵘?AI 工程化能力最快的路徑。 Codex 接入 DeepSeek-V4-Pro 實戰(zhàn)：從配置到識圖 Skill 完整指南
很多用 Codex 寫代碼的開發(fā)者第一反應(yīng)是“裝好就能用”。真正上手后你會發(fā)現(xiàn)環(huán)境搭好只是開始模型選型、接口兼容、多模態(tài)擴展每一步都可能卡住你半天。尤其是想用 DeepSeek 這類高效模型替換默認模型時很多人會在配置層反復(fù)試錯最后發(fā)現(xiàn) Codex 的接入?yún)f(xié)議和模型能力邊界才是關(guān)鍵。這篇教程要解決的就是這件事把 DeepSeek-V4-Pro 原生接入 Codex跑通一個真實的編碼任務(wù)再配一個識圖 Skill 補齊視覺理解能力。整個過程我會按“概念 → 環(huán)境 → 配置 → 代碼 → 驗證 → 排錯 → 建議”的順序拆開講最后附上一些容易踩坑的細節(jié)。無論你是剛接觸 AI 編程助手的新手還是已經(jīng)在用 Codex 但想換成更順手的模型這篇文章都能給你一份可以直接照做的路徑。1. 為什么要折騰“換模型”這件事Codex 作為編程助手底層模型決定了它理解代碼、生成代碼、執(zhí)行命令的上限。默認模型雖然綜合表現(xiàn)不錯但開發(fā)者在實際項目中往往有更具體的訴求有的希望降低調(diào)用成本有的希望中文理解更自然有的希望代碼風(fēng)格更貼近國內(nèi)團隊規(guī)范。這時候把模型替換成 DeepSeek-V4-Pro 就是一種很自然的解法。不過這里要先給一個判斷Codex 和 DeepSeek 的對接核心不在 Codex 本身而在“它們之間使用什么協(xié)議溝通”。Codex 官方支持 OpenAI 兼容的接口協(xié)議DeepSeek 對外提供的 API 同樣兼容這一協(xié)議。所以表面上是“換模型”實際上是在 Codex 的配置層指定一個新的模型提供方。這意味著你不需要修改 Codex 的源碼也不需要寫復(fù)雜的適配層只需要在配置文件里告訴 Codex“去哪個地址、用哪個 Key、調(diào)哪個模型”。這個思路一旦建立后續(xù)不管是接 DeepSeek 還是接其他模型你都能快速遷移。還有一類開發(fā)者的需求是“視覺”。DeepSeek-V4-Pro 作為文本模型本身不直接處理圖片輸入。但在真實開發(fā)里你經(jīng)常需要給 AI 看設(shè)計圖、截圖、報錯界面、手繪圖讓 AI 理解后生成代碼。這個能力不能靠模型憑空變出來要靠一個額外的 Skill 來補位。所以這篇文章真正的價值是幫你建立一套可組合的 AI 編程環(huán)境主模型負責(zé)理解和生成代碼Skill 負責(zé)擴展模型不具備的能力。兩者配合Codex 才不是“一個聊天框”而是“一個能看圖、能寫代碼、能執(zhí)行命令的工程助手”。2. DeepSeek-V4-Pro 與 Codex 的核心概念2.1 DeepSeek-V4-Pro 是什么DeepSeek 系列模型來自深度求索特點是代碼能力強、中文理解好、性價比高。V4-Pro 這個版本在標題里被標記為“正式發(fā)布”如果你想驗證它的實際表現(xiàn)核心不是聽宣傳而是跑一組你自己的測試任務(wù)。比如讓它讀一段倉庫代碼、改一個 bug、寫一個單元測試觀察它的生成質(zhì)量和速度。這里要特別提醒不同版本模型在 API 里的名稱可能不同比如模型 ID 可能是deepseek-chat或類似名稱。配置時必須以你實際拿到的 API 文檔為準不要照搬別人文章里的模型名。2.2 Codex 是什么Codex 是 OpenAI 推出的編程智能體它不是在網(wǎng)頁里對話的助手而是跑在終端里的工程工具。它能做這些事情讀取你本地項目里的代碼文件理解你提出的編碼任務(wù)生成代碼補丁執(zhí)行 shell 命令運行測試并讀取結(jié)果根據(jù)測試失敗信息反復(fù)修正代碼它的工作流非常接近一個真實工程師先看代碼再改代碼然后跑測試驗證最后交付改動。Codex 的可配置性來自“模型提供方”model provider機制。它可以調(diào)用 OpenAI 默認模型也可以通過配置切換到其他兼容服務(wù)。這個機制就是 DeepSeek 接入的依據(jù)。2.3 Skill 機制是什么Skill 是 Codex 生態(tài)里的擴展機制可以理解成給 AI 編程助手加“職業(yè)技能”。Codex 默認的文本模型不會直接“看”圖片但如果你給它掛一個“識圖 Skill”它就能在需要的時候調(diào)用這個工具完成圖像理解。Skill 一般包含兩部分描述信息告訴模型什么時候該使用這個技能執(zhí)行邏輯實際調(diào)用視覺模型把圖片變成文本描述從架構(gòu)上看這非常像函數(shù)調(diào)用function calling。Codex 在主流程里發(fā)現(xiàn)任務(wù)涉及圖片就會調(diào)用 SkillSkill 內(nèi)部請求視覺模型再把結(jié)果返回給主模型繼續(xù)編碼。這種組合方式讓文本模型和視覺模型各司其職不用為了“能看圖”而犧牲代碼能力。3. 環(huán)境準備與前置條件開始之前先把環(huán)境梳理清楚。下面的清單以通用情況為例具體版本以你本機為準。3.1 基礎(chǔ)環(huán)境要求項目推薦要求說明操作系統(tǒng)macOS / Linux / WindowsWindows 建議使用 PowerShell 或 WSLNode.js較新穩(wěn)定版本Codex CLI 基于 Node.js 構(gòu)建npm隨 Node.js 安裝用于安裝 Codex CLIGit建議安裝便于管理項目代碼和補丁API KeyDeepSeek 平臺申請用于調(diào)用 DeepSeek 模型接口版本檢查命令node --version npm --version git --version如果提示command not found先安裝對應(yīng)工具再繼續(xù)。3.2 安裝 Codex CLICodex 的官方安裝方式是通過 npm。打開終端執(zhí)行npm install -g codex安裝完成后驗證codex --version如果這一步輸出版本號說明 Codex CLI 已經(jīng)裝好。這里需要說明版本號會持續(xù)更新你本地拿到的最新版本即為當前可用版本不需要刻意追求教程里的某個數(shù)字。3.3 準備 DeepSeek API Key想要在 Codex 里調(diào)用 DeepSeek你需要一個有效的 DeepSeek API Key。這個 Key 一般是在 DeepSeek 開放平臺上創(chuàng)建創(chuàng)建時需要實名認證并充值少量金額。拿到 Key 后先保存好下一步配置時要用。從安全角度出發(fā)不要把 Key 寫死在項目代碼里更不要提交到 Git 倉庫。推薦使用環(huán)境變量或 Codex 提供的配置管理機制來保存。4. 核心流程拆解DeepSeek-V4-Pro 接入 Codex 的完整流程可以分為六個步驟。4.1 明確接入?yún)f(xié)議DeepSeek 的 API 兼容 OpenAI 接口格式這意味著 Codex 不需要額外插件只需要把請求的 base_url 指向 DeepSeek 的 API 地址把模型名稱改成 DeepSeek 對應(yīng)的模型 ID。這一步是整個接入的架構(gòu)基礎(chǔ)。4.2 初始化 Codex 配置Codex CLI 安裝后會自動創(chuàng)建配置文件目錄。配置文件一般位于用戶目錄下的.codex文件夾中常見文件名是config.toml。如果你的電腦上沒有這個文件可以通過codex init命令生成。codex init執(zhí)行后檢查配置文件是否存在ls ~/.codex/config.toml4.3 配置模型提供方在config.toml中你需要聲明一個模型提供方并指定 base_url 和 API Key 對應(yīng)的環(huán)境變量名。下面是一份參考配置。# 文件路徑~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY配置說明model實際調(diào)用的模型 ID。請以 DeepSeek 官方文檔為準如果文檔里的模型名不是deepseek-chat替換成真實名稱即可。model_provider指定使用哪個提供方對應(yīng)下方[model_providers.deepseek]配置塊。base_urlDeepSeek API 的基礎(chǔ)地址末尾/v1一般不能漏。env_keyCodex 會讀取這個環(huán)境變量名來獲得 API Key。也就是說你需要在系統(tǒng)環(huán)境變量里設(shè)置DEEPSEEK_API_KEY。然后設(shè)置環(huán)境變量export DEEPSEEK_API_KEY你的DeepSeek API Key為了讓環(huán)境變量長期生效可以把它寫入 shell 的配置文件中例如~/.bashrc或~/.zshrc。生產(chǎn)環(huán)境或團隊協(xié)作時推薦使用密鑰管理工具。4.4 驗證 API 連通性配置完成后先不急著啟動 Codex先用 curl 驗證 API 能否連通。這一步能快速定位問題在網(wǎng)絡(luò)層還是配置層。curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY如果返回一段 JSON里面包含模型列表說明 Key 有效、網(wǎng)絡(luò)連通、地址正確。如果返回 401說明 Key 無效或鑒權(quán)頭不對如果返回超時說明網(wǎng)絡(luò)不通或者地址錯誤。4.5 啟動 Codex 并測試基礎(chǔ)對話確認 API 連通后啟動 Codexcodex進入交互界面后先給一個簡單任務(wù)比如“請用 Python 寫一個函數(shù)判斷一個字符串是否是回文。”這一步的目的是驗證 Codex 能否成功請求 DeepSeek 模型。如果模型返回結(jié)果并且速度正常說明接入成功。4.6 跑一個真實編碼任務(wù)基礎(chǔ)驗證通過后再跑一個貼近實際的任務(wù)。建議在你自己的項目里操作這樣 Codex 能讀取真實代碼上下文。比如讓它修復(fù)一個測試失敗或者新增一個接口。這類任務(wù)能驗證三件事模型是否能理解項目結(jié)構(gòu)、是否能修改正確文件、是否能運行測試驗證結(jié)果。5. 完整示例與代碼實現(xiàn)下面給出一套可以完整跑通的示例流程。為了演示清晰我們創(chuàng)建一個臨時項目目錄里面放一個簡單的 Python 文件和一個測試文件。5.1 創(chuàng)建測試項目mkdir -p ~/codex-demo cd ~/codex-demo創(chuàng)建calculator.py# 文件路徑~/codex-demo/calculator.py def add(a, b): return a b def subtract(a, b): return a - b創(chuàng)建test_calculator.py# 文件路徑~/codex-demo/test_calculator.py from calculator import add, subtract def test_add(): assert add(2, 3) 5 def test_subtract(): assert subtract(5, 2) 35.2 啟動 Codex 執(zhí)行任務(wù)在項目目錄下啟動 Codexcodex輸入任務(wù)“閱讀 calculator.py 和 test_calculator.py運行測試然后新增一個 multiply 函數(shù)和對應(yīng)測試。”Codex 會讀取文件、修改代碼、執(zhí)行測試。你需要觀察的是它是否自動完成了“改代碼 → 跑測試 → 根據(jù)結(jié)果修正”的完整循環(huán)。5.3 識圖 Skill 的代碼實現(xiàn)現(xiàn)在來寫識圖 Skill。這個 Skill 的目標是Codex 遇到需要理解圖片內(nèi)容的任務(wù)時調(diào)用一個視覺模型把圖片轉(zhuǎn)換成文本描述再交給主模型處理。我們先創(chuàng)建一個 Skill 目錄mkdir -p ~/.codex/skills/image-ocr在目錄下創(chuàng)建SKILL.md# 文件路徑~/.codex/skills/image-ocr/SKILL.md name: image-ocr description: 當用戶需要理解圖片內(nèi)容、截圖、設(shè)計圖、OCR文字識別時使用此技能。再創(chuàng)建一個執(zhí)行腳本run.py# 文件路徑~/.codex/skills/image-ocr/run.py import os import sys import base64 from openai import OpenAI def encode_image(image_path): with open(image_path, rb) as image_file: return base64.b64encode(image_file.read()).decode(utf-8) def analyze_image(image_path): api_key os.environ.get(VISION_API_KEY) base_url os.environ.get(VISION_BASE_URL, https://api.openai.com/v1) model os.environ.get(VISION_MODEL, gpt-4o-mini) client OpenAI(api_keyapi_key, base_urlbase_url) base64_image encode_image(image_path) response client.chat.completions.create( modelmodel, messages[ { role: user, content: [ {type: text, text: 請描述這張圖片的內(nèi)容提取所有文字信息并總結(jié)界面結(jié)構(gòu)。}, {type: image_url, image_url: {url: fdata:image/png;base64,{base64_image}}} ] } ] ) return response.choices[0].message.content if __name__ __main__: image_path sys.argv[1] result analyze_image(image_path) print(result)這段代碼的用途是調(diào)用視覺模型。如果你選擇其他支持視覺的模型只需要改環(huán)境變量VISION_MODEL和VISION_BASE_URL核心邏輯不變。5.4 在 Codex 中調(diào)用識圖 Skill實際使用時你不需要手動運行run.py。更好的方式是在 Codex 對話中描述任務(wù)讓它自動判斷是否需要識圖。比如“請查看 design.png 這張設(shè)計圖然后根據(jù)圖中的布局生成一個 HTML 頁面?！盋odex 檢測到任務(wù)涉及圖片理解會通過 Skill 機制執(zhí)行run.py把圖片描述結(jié)果拿回來再生成代碼。如果 Codex 沒有自動調(diào)用你可以顯式說明“請使用 image-ocr 技能處理這張圖片”。5.5 模型配置的完整參考整合 DeepSeek 主模型和識圖 Skill 之后完整配置如下# 文件路徑~/.codex/config.toml model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY注意視覺模型的配置是通過環(huán)境變量在 Skill 腳本中獨立管理的和 Codex 主模型配置互不干擾。這就保持了架構(gòu)上的解耦。6. 運行結(jié)果與效果驗證配置完成后用下面幾個命令驗證整個鏈路是否正常。6.1 驗證 Codex 主模型運行codex對話中輸入“請寫一句話說明你是通過什么模型運行的?！比绻祷亟Y(jié)果正常說明 DeepSeek 已經(jīng)作為 Codex 的主模型生效。6.2 驗證識圖 Skill準備一張測試圖片test.png然后在 Codex 中輸入“請使用 image-ocr 技能查看 test.png描述圖片內(nèi)容。”觀察是否輸出圖片的文字和結(jié)構(gòu)信息。如果上一步 Codex 不會自動調(diào)用 Skill可以手動在終端驗證腳本本身python ~/.codex/skills/image-ocr/run.py test.png如果腳本能正確輸出圖片描述說明視覺鏈路是通的問題只在于 Codex 是否識別到了這個 Skill。6.3 判斷成功與失敗現(xiàn)象判斷Codex 能正常對話且回復(fù)有代碼風(fēng)格主模型接入成功Codex 報錯權(quán)限或 401API Key 無效或環(huán)境變量未設(shè)置Codex 能對話但回復(fù)很慢檢查網(wǎng)絡(luò)延遲或模型負載Skill 腳本單獨運行正常但 Codex 不調(diào)用檢查 SKILL.md 描述是否足夠清晰圖片生成代碼時完全忽略圖片可能沒有觸發(fā) Skill需要顯式指定7. 常見問題與排查思路問題現(xiàn)象可能原因排查方式解決方案啟動 Codex 提示找不到模型model 名稱配置錯誤查看 DeepSeek 官方模型列表替換為正確的模型 ID請求返回 401API Key 錯誤或環(huán)境變量未加載執(zhí)行echo $DEEPSEEK_API_KEY重新導(dǎo)出環(huán)境變量檢查 shell 配置文件請求返回 404base_url 地址錯誤用 curl 手動請求驗證確認/v1路徑是否完整Codex 不執(zhí)行 shell 命令權(quán)限或安全策略限制查看 Codex 配置的權(quán)限項調(diào)整命令執(zhí)行權(quán)限注意合規(guī)識圖 Skill 無法觸發(fā)SKILL.md 描述不夠明確檢查 Skill 目錄位置和格式重寫 description明確觸發(fā)條件視覺模型返回結(jié)果為空圖片過大或格式不支持檢查圖片格式和大小壓縮圖片或轉(zhuǎn)換格式Codex 生成的代碼無法運行模型上下文不足或需求描述不清查看生成代碼的錯誤信息細化任務(wù)描述分步執(zhí)行群里很多朋友問的第一個問題其實是“為什么我的 Codex 一直用默認模型”。這種時候我一般會讓他們先跑一次codex --version再檢查config.toml是否存在。大多數(shù)情況是配置文件根本沒有生效或者環(huán)境變量沒有寫入當前 shell。還有一種很常見的情況是配置文件改了但 Codex 沒有重啟。配置文件的改動必須重啟 Codex 進程才會重新加載這個細節(jié)容易忽略。8. 最佳實踐與工程建議8.1 API Key 不落盤不要把 Key 寫在config.toml里也不要把 Key 提交到 Git 倉庫。使用環(huán)境變量或?qū)I(yè)的密鑰管理服務(wù)能顯著降低泄露風(fēng)險。如果懷疑 Key 泄露第一時間在平臺后臺輪換。8.2 配置文件納入版本管理~/.codex/config.toml這種配置文件適合保存一份模板到 Git 倉庫但模板中不要包含真實 Key。團隊協(xié)作時新人拉取模板后只需要配置自己的環(huán)境變量就能快速接入。8.3 Skill 拆分原則識圖 Skill 的腳本不應(yīng)該綁定某一個具體視覺模型。通過環(huán)境變量傳入模型名稱和地址能讓你在后續(xù)換模型時不需要修改腳本代碼。這個原則叫“配置與代碼分離”在 AI 工程化中很重要。8.4 任務(wù)描述要具體Codex 生成代碼的質(zhì)量很大程度上取決于任務(wù)描述的清晰度。不要只寫“優(yōu)化這段代碼”要寫清楚“這個函數(shù)在并發(fā)場景下偶發(fā)死鎖請分析可能原因并修復(fù)”。模型能理解的信息越多輸出越靠譜。8.5 先小步驗證再批量執(zhí)行在生產(chǎn)項目中使用 Codex 改代碼時建議每次只讓它處理一個小任務(wù)檢查生成的 diff再決定是否采納。不要讓它一次改動十幾個文件否則一旦出現(xiàn)問題回滾成本很高。8.6 定期檢查模型更新DeepSeek 模型版本更新后API 模型名稱和參數(shù)可能變化。升級版本前先閱讀官方文檔確認模型名、上下文長度、計費方式的變化再決定是否切換。8.7 理解 Skill 的邊界Skill 不是萬能插件它只是讓 Codex 多了一項工具調(diào)用能力。識圖 Skill 的準確度取決于底層視覺模型如果視覺模型本身識別不了復(fù)雜圖表Skill 再完善也無濟于事。選視覺模型時建議在真實任務(wù)中測試不要只看宣傳。9. 總結(jié)與后續(xù)學(xué)習(xí)方向這篇教程主要解決了三個問題。第一DeepSeek-V4-Pro 接入 Codex 的原理是協(xié)議兼容不是源碼改造。理解這一層你就不會被各種花哨的接入教程迷惑。第二完整跑通了一個編碼項目從創(chuàng)建文件到讓 Codex 自動改代碼、跑測試、生成補丁讓你感受到真實工作流下的 Codex。第三通過識圖 Skill 補齊了文本模型的視覺短板。這個能力組合的思路比單純“會安裝”重要得多它能幫你應(yīng)對更多真實開發(fā)場景。接下來可以繼續(xù)深入的方向包括研究 Codex 的命令執(zhí)行權(quán)限管理學(xué)習(xí)如何編寫更復(fù)雜的 Skill了解多模型路由與按任務(wù)自動選擇模型的架構(gòu)。建議你新建一個專門測試 Codex 的倉庫把常用任務(wù)整理成任務(wù)清單逐步驗證不同模型的代碼能力差異。實踐是檢驗?zāi)Ｐ湍芰ψ钣行У姆绞揭彩翘嵘?AI 工程化能力最快的路徑。