1. 為什么要在本地跑 Codex從云端依賴到自主可控Codex 這個名字這兩年重新回到開發(fā)者視野里含義已經(jīng)和早年的代碼補全模型不太一樣了。現(xiàn)在大家說的 Codex更多是指一類能理解自然語言、直接生成可運行代碼、還能在終端里跟你對話式改代碼的 AI 編程助手。它可以是官方 CLI 工具也可以是接入 DeepSeek、本地大模型后自己搭出來的一套東西。核心訴求就一個讓寫代碼這件事從“我查文檔、我拼 API、我調(diào) bug”變成“我說需求、它給實現(xiàn)、我來驗收”。那為什么非要本地部署我自己的經(jīng)歷很直接。最早用云端 API圖的是省事注冊完拿個 key 就能跑。但用久了問題就冒出來第一網(wǎng)絡(luò)抖動的時候請求超時正寫到關(guān)鍵邏輯突然斷掉心態(tài)很崩第二代碼里涉及公司內(nèi)部接口、數(shù)據(jù)庫連接串、業(yè)務(wù)規(guī)則往云端一貼合規(guī)上過不去第三按 token 計費調(diào)試階段反復(fù)試錯賬單漲得比進度快。這三點加起來本地部署就從“可選項”變成了“必選項”。本地部署 Codex 的本質(zhì)是在你自己的機器上跑一個推理服務(wù)再讓 Codex 的客戶端去連這個服務(wù)。推理服務(wù)可以是 Ollama、vLLM、LM Studio 這類工具加載的開源模型也可以是 DeepSeek 這類支持本地化部署的模型?？蛻舳诉@邊Codex CLI 負(fù)責(zé)接收你的自然語言指令轉(zhuǎn)成請求發(fā)給本地服務(wù)拿到結(jié)果后再呈現(xiàn)給你。整條鏈路都在本機或者內(nèi)網(wǎng)里完成數(shù)據(jù)不出門斷網(wǎng)也能用成本從“按量付費”變成“一次性投入硬件”。適合誰來參考這套方案三類人最合適。第一類是有一定開發(fā)經(jīng)驗、想提升編碼效率但又不放心把代碼傳出去的工程師第二類是手里有閑置顯卡或者想配一臺開發(fā)機的技術(shù)愛好者第三類是在團隊里負(fù)責(zé)搭建內(nèi)部工具、想讓整個組都用上 AI 輔助但又受限于合規(guī)要求的負(fù)責(zé)人。如果你只是偶爾寫幾行腳本云端免費額度可能就夠了沒必要折騰本地。但只要你的代碼有保密要求、或者你每天都要和 AI 結(jié)對編程本地部署的投入產(chǎn)出比會非常高。這里要先說清楚一個前提Codex 本身是一個客戶端工具它不包含模型。你要么連官方服務(wù)要么連自己部署的模型服務(wù)。所謂“Codex 本地部署”準(zhǔn)確說是“Codex 客戶端 本地模型服務(wù)”的組合。理解了這一點后面的安裝和配置就不會迷路。2. 部署前的整體設(shè)計與選型思路2.1 三種典型部署形態(tài)對比在動手之前先想清楚你要走哪條路。我把常見的方案歸成三類各自的適用場景和門檻差別很大。方案類型模型運行位置硬件要求數(shù)據(jù)是否出本機適合人群純云端 API廠商服務(wù)器無是臨時試用、無保密需求本地模型 Codex CLI本機顯卡 8G 顯存起步否個人開發(fā)者、小團隊內(nèi)網(wǎng)服務(wù)器 多客戶端內(nèi)網(wǎng)服務(wù)器服務(wù)器級顯卡否僅在內(nèi)網(wǎng)團隊協(xié)作、合規(guī)要求高純云端方案不展開重點說后兩種。本地模型加 Codex CLI 是最常見的個人玩法一臺帶獨顯的機器就能跑。內(nèi)網(wǎng)服務(wù)器方案則是把模型服務(wù)部署在一臺性能較強的機器上其他同事通過內(nèi)網(wǎng)地址連接適合團隊統(tǒng)一管理模型版本和訪問權(quán)限。選哪種取決于三個問題你的代碼能不能出本機你的硬件夠不夠你是不是一個人用三個問題答案清楚了方案自然就定了。2.2 模型選型的核心考量模型是整套方案里最影響體驗的部分。選模型不能只看參數(shù)規(guī)模要看四個維度代碼能力、顯存占用、推理速度、中文支持。代碼能力方面DeepSeek 系列在代碼生成和補全上的表現(xiàn)比較均衡對 Python、JavaScript、Go 這些主流語言支持都不錯。如果你主要寫某一種語言可以優(yōu)先選在該語言上表現(xiàn)突出的模型。顯存占用方面7B 級別的模型量化后大概需要 6 到 8G 顯存14B 級別需要 12 到 16G32B 級別就要 24G 以上了。推理速度方面同樣的模型量化等級越低速度越快但質(zhì)量會下降需要權(quán)衡。中文支持這一點經(jīng)常被忽略。很多開源模型英文能力很強但中文注釋、中文需求描述理解起來會打折扣。如果你習(xí)慣用中文寫注釋、用中文描述需求選模型時一定要實際測一下中文場景。提示不要一上來就追求最大參數(shù)。先用 7B 或 14B 跑通全流程確認(rèn)鏈路沒問題、體驗?zāi)芙邮茉倏紤]換更大的模型。直接上大模型一旦顯存不夠或者速度太慢排查起來很浪費時間。2.3 容器化部署的價值用 Docker 來跑模型服務(wù)和相關(guān)組件是我強烈推薦的做法。原因有三個。第一環(huán)境隔離。模型推理依賴的 CUDA 版本、Python 版本、各種庫版本很容易沖突容器把這些問題封在里面不污染宿主機。第二遷移方便。換機器的時候把鏡像和配置一搬環(huán)境就重建了不用重新踩一遍依賴的坑。第三版本管理清晰。不同模型用不同容器互不干擾想回退就回退。Docker Desktop 在 Windows 和 macOS 上都能用Linux 上直接用 Docker Engine 就行。安裝過程不復(fù)雜但有幾個坑后面會專門講。3. 環(huán)境準(zhǔn)備與 Docker 安裝實操3.1 硬件與系統(tǒng)檢查清單動手之前先確認(rèn)你的機器滿足基本條件。這一步花五分鐘能省后面幾小時的折騰。操作系統(tǒng)Windows 10/11 64 位、macOS 12 以上、或者主流 Linux 發(fā)行版內(nèi)存至少 16G推薦 32G 以上顯卡NVIDIA 顯卡顯存 8G 起步跑 7B 量化模型推薦 12G 以上硬盤至少預(yù)留 50G 空間模型文件動輒幾個 G 到幾十個 G虛擬化BIOS 里要開啟虛擬化支持Windows 上還要確認(rèn) Hyper-V 或 WSL2 可用顯卡這塊多說一句。如果你用的是 NVIDIA 顯卡先裝好驅(qū)動用nvidia-smi命令確認(rèn)能正常輸出。這個命令會顯示顯卡型號、驅(qū)動版本、CUDA 版本和顯存占用。如果這個命令報錯后面所有 GPU 加速都無從談起先把驅(qū)動搞定。3.2 Docker Desktop 安裝與常見報錯處理Windows 上裝 Docker Desktop去官網(wǎng)下載安裝包雙擊運行一路下一步。安裝完成后重啟啟動 Docker Desktop等托盤圖標(biāo)變成穩(wěn)定狀態(tài)。這里有個高頻報錯virtualization support not detected或者docker desktop failed to start because virtualization support is not enabled。這個問題的根源是虛擬化沒開。解決辦法是進 BIOS找到 Intel VT-x 或者 AMD-V 選項設(shè)為 Enabled。不同主板 BIOS 界面不一樣但關(guān)鍵詞就這幾個。開完保存重啟再啟動 Docker Desktop 就好了。另一個常見問題是 WSL2 相關(guān)。Windows 上 Docker Desktop 默認(rèn)用 WSL2 作為后端如果 WSL2 沒裝或者版本太舊會報錯。解決辦法是打開 PowerShell運行wsl --update更新然后wsl --set-default-version 2設(shè)為默認(rèn)版本。如果還沒裝 WSL運行wsl --install會自動裝好。macOS 上裝 Docker Desktop 相對簡單下載 dmg 拖進應(yīng)用文件夾就行。但要注意macOS 上 Docker 跑 GPU 加速比較麻煩Apple Silicon 芯片可以用 Metal 加速Intel 芯片基本只能靠 CPU速度會慢不少。所以 macOS 用戶如果追求速度建議把模型服務(wù)放在別的機器上本機只跑客戶端。Linux 上直接用包管理器裝 Docker Engine 和 Docker Compose 插件就行不裝 Desktop。以 Ubuntu 為例先更新源再裝 docker.io 和 docker-compose-plugin然后把當(dāng)前用戶加入 docker 組避免每次都要 sudo。安裝完成后用docker run hello-world驗證。能正常輸出一段歡迎信息說明 Docker 裝好了。3.3 Docker 基礎(chǔ)配置優(yōu)化裝好之后別急著跑模型先做幾項配置優(yōu)化后面會順很多。第一配置鏡像加速。默認(rèn)的鏡像源在國內(nèi)拉取速度可能很慢編輯 Docker 的配置文件加上國內(nèi)可用的鏡像地址重啟 Docker 服務(wù)后拉取速度會明顯提升。第二調(diào)整資源限制。Docker Desktop 默認(rèn)給容器的內(nèi)存和 CPU 可能不夠跑模型在設(shè)置里把內(nèi)存調(diào)到 8G 以上CPU 核心數(shù)給足。如果要用 GPU還要確認(rèn) GPU 支持已開啟。第三設(shè)置數(shù)據(jù)目錄。模型文件很大默認(rèn)存在系統(tǒng)盤可能把盤撐滿。在 Docker 設(shè)置里把磁盤鏡像位置改到大容量分區(qū)。注意修改 Docker 配置后一定要重啟 Docker 服務(wù)否則配置不生效。重啟后可以用docker info查看當(dāng)前配置是否已經(jīng)應(yīng)用。4. 本地模型服務(wù)的部署與 Codex 對接4.1 用 Docker 拉起模型推理服務(wù)模型推理服務(wù)我習(xí)慣用 Ollama 來跑它對 Docker 支持好模型管理也方便。先拉取 Ollama 的鏡像然后運行容器把模型存儲目錄掛載到宿主機這樣模型文件不會隨容器刪除而丟失。docker run -d \ --name ollama \ --gpus all \ -v /your/path/ollama:/root/.ollama \ -p 11434:11434 \ ollama/ollama--gpus all是讓容器能用上宿主機的 GPU前提是宿主機裝好了 NVIDIA 驅(qū)動和容器工具包。-v把模型目錄掛出來-p把端口映射出來后面 Codex 就連這個端口。容器起來后進容器拉模型docker exec -it ollama ollama pull deepseek-coder:6.7b模型大小不同拉取時間從幾分鐘到幾十分鐘不等。拉完后用ollama list確認(rèn)模型已經(jīng)在本地。4.2 驗證模型服務(wù)是否正常模型拉好后先別急著接 Codex單獨測一下服務(wù)通不通。curl http://localhost:11434/api/generate -d { model: deepseek-coder:6.7b, prompt: 寫一個 Python 函數(shù)判斷一個數(shù)是否為質(zhì)數(shù), stream: false }如果返回一段包含代碼的 JSON說明模型服務(wù)正常。如果報連接錯誤檢查容器是否在運行、端口是否映射正確。如果返回很慢或者卡住可能是顯存不夠模型加載失敗去看容器日志docker logs ollama排查。這一步很關(guān)鍵。很多人跳過驗證直接配 Codex結(jié)果 Codex 報錯分不清是模型服務(wù)的問題還是客戶端配置的問題。先把模型服務(wù)單獨驗證通過后面排查范圍就小一半。4.3 Codex 客戶端安裝與配置Codex CLI 的安裝方式取決于你用的具體工具。如果是官方 CLI通常通過包管理器安裝比如 npm 全局安裝或者下載二進制包。安裝完成后核心是配置它去連本地的模型服務(wù)而不是官方云端。配置文件一般是一個 JSON 或者 YAML 文件放在用戶目錄下。關(guān)鍵配置項包括模型服務(wù)的地址指向http://localhost:11434、模型名稱和你在 Ollama 里拉的一致、API 格式Ollama 兼容 OpenAI 的接口格式。把這幾項配對Codex 就能把請求發(fā)到本地模型服務(wù)。配置完成后在終端里運行 Codex輸入一句自然語言指令比如“幫我寫一個讀取 CSV 并統(tǒng)計每列缺失值的腳本”看它能不能正常返回代碼。如果能整條鏈路就通了。4.4 接入 DeepSeek 等模型的注意事項如果你不想用 Ollama想直接部署 DeepSeek 的模型思路類似但要注意幾點。第一DeepSeek 官方提供了多種規(guī)格的模型選適合你顯存的版本。第二推理框架可以用 vLLM它對大模型推理做了優(yōu)化吞吐量比樸素加載高不少但配置稍復(fù)雜。第三接口格式要對齊Codex 期望的是 OpenAI 兼容格式vLLM 和 Ollama 都支持但要在啟動參數(shù)里顯式開啟。提示不同推理框架的接口路徑可能不一樣。Ollama 的生成接口是/api/generateOpenAI 兼容接口是/v1/chat/completions。Codex 配置時要用兼容接口不要用原生接口否則會報 404。5. 常見問題排查與避坑經(jīng)驗5.1 連接類問題速查現(xiàn)象可能原因排查方法Codex 報連接被拒絕模型服務(wù)沒啟動或端口不對docker ps看容器狀態(tài)curl測端口請求超時模型太大推理太慢換小模型或降低量化等級返回 404接口路徑配錯確認(rèn)用的是 OpenAI 兼容路徑返回 401鑒權(quán)配置問題本地服務(wù)一般不需要 key檢查是否誤配連接類問題占了我踩坑經(jīng)歷的一大半。最典型的是端口映射寫錯容器內(nèi)部端口和宿主機端口沒對上。還有就是容器啟動了但模型沒加載完這時候請求會掛起看起來像超時其實是模型還在加載。等幾分鐘再試或者看容器日志確認(rèn)加載進度。5.2 顯存與性能問題處理顯存不夠是最常見的性能問題。表現(xiàn)是模型加載失敗或者推理過程中報 CUDA out of memory。解決辦法有幾個換更小的模型、用量化版本、減少并發(fā)請求數(shù)、關(guān)閉其他占顯存的程序。量化版本值得單獨說。同一個模型有 fp16、int8、int4 等不同量化等級。int4 量化后顯存占用能降到 fp16 的四分之一左右速度也更快但生成質(zhì)量會有一定下降。對于代碼補全這種任務(wù)int4 量化通常夠用實測下來代碼結(jié)構(gòu)基本正確偶爾細(xì)節(jié)需要人工修正。如果顯存實在不夠可以考慮 CPU 推理。速度會慢很多但至少能跑起來。Ollama 支持 CPU 模式去掉--gpus all參數(shù)就行。適合應(yīng)急或者對速度要求不高的場景。5.3 中文與特殊字符處理中文場景下有兩個坑。第一模型對中文需求描述的理解可能不如英文建議關(guān)鍵需求用英文寫或者中英混合。第二終端編碼問題Windows 上默認(rèn)編碼可能是 GBK中文輸出會亂碼。解決辦法是在終端里設(shè)置 UTF-8 編碼或者用支持 UTF-8 的終端工具。還有一個容易被忽略的點代碼里的特殊字符。比如路徑里的反斜杠、正則表達式里的轉(zhuǎn)義字符在傳給模型和從模型返回的過程中可能被轉(zhuǎn)義處理。如果生成的代碼里有奇怪的轉(zhuǎn)義檢查一下客戶端的轉(zhuǎn)義配置。5.4 我的實操避坑清單先驗證模型服務(wù)再配客戶端順序不能反模型存儲目錄一定要掛載到宿主機否則容器一刪模型就沒了Docker 資源限制要調(diào)夠默認(rèn)配置跑模型基本不夠用量化模型是顯存不夠時的首選方案不要硬上大模型終端編碼設(shè)成 UTF-8省去中文亂碼的麻煩配置文件改完要重啟 Codex 客戶端熱加載不一定生效保留一份能跑通的配置備份折騰壞了能快速回滾6. 從跑通到好用進階優(yōu)化與擴展思路6.1 提升響應(yīng)速度的幾個手段跑通之后下一步是讓它更快。第一個手段是模型預(yù)熱服務(wù)啟動后先發(fā)一個簡單請求讓模型加載進顯存后續(xù)請求就不用等加載了。第二個手段是調(diào)整推理參數(shù)比如限制最大生成長度、調(diào)低 temperature都能減少推理時間。第三個手段是用更快的推理框架vLLM 的連續(xù)批處理和 PagedAttention 對吞吐量提升明顯。還有一個容易被忽略的點客戶端和服務(wù)器的網(wǎng)絡(luò)延遲。如果模型服務(wù)在另一臺機器上內(nèi)網(wǎng)延遲通?？梢院雎缘绻强缇W(wǎng)絡(luò)訪問延遲就會體現(xiàn)出來。盡量讓客戶端和模型服務(wù)在同一臺機器或者同一內(nèi)網(wǎng)。6.2 多模型切換與場景適配不同任務(wù)適合不同模型。寫業(yè)務(wù)代碼可以用通用代碼模型寫 SQL 可以用專門優(yōu)化過 SQL 的模型寫前端可以用對 JavaScript 和 CSS 支持好的模型。Ollama 支持同時拉多個模型Codex 配置里可以指定用哪個。切換的時候改一下配置里的模型名稱就行。如果頻繁切換可以寫個小腳本一鍵改配置并重啟客戶端?；蛘哂铆h(huán)境變量控制啟動 Codex 時指定模型名稱不用改配置文件。6.3 團隊共享部署的注意事項如果要把這套方案分享給團隊用有幾個點要注意。第一模型服務(wù)部署在一臺性能足夠的機器上其他同事通過內(nèi)網(wǎng) IP 連接。第二做好訪問控制雖然在內(nèi)網(wǎng)但也不能完全裸奔至少加個簡單的鑒權(quán)。第三統(tǒng)一模型版本避免每個人用的模型不一樣導(dǎo)致生成結(jié)果差異大。第四寫好使用文檔把連接地址、配置方法、常見問題整理清楚減少重復(fù)答疑。團隊部署的硬件投入會比個人高但攤到每個人頭上成本就低了。而且模型版本統(tǒng)一后代碼風(fēng)格和生成質(zhì)量也更一致協(xié)作起來更順。6.4 后續(xù)可以擴展的方向這套方案跑通后還能往上疊不少東西。比如接入代碼庫索引讓模型能理解你整個項目的結(jié)構(gòu)生成的代碼更貼合現(xiàn)有風(fēng)格。比如加一層緩存相同或相似的請求直接返回緩存結(jié)果省去重復(fù)推理。比如對接 CI 流程在提交代碼前自動跑一遍 AI 審查。我個人最看好的擴展方向是項目上下文注入?，F(xiàn)在的模型大多是單輪對話你給它一段需求它生成一段代碼但它不知道你項目里已經(jīng)有哪些工具類、用了什么框架、命名規(guī)范是什么。如果把項目結(jié)構(gòu)、關(guān)鍵文件摘要作為上下文一起傳給模型生成質(zhì)量會有質(zhì)的提升。這個方向?qū)崿F(xiàn)起來不難但效果很明顯值得試試。最后分享一個小技巧把常用的提示詞模板存成文件用的時候直接引用不用每次重新組織語言。比如“生成單元測試”“重構(gòu)這段代碼”“解釋這段邏輯”各存一個模板效率能再提一截。這套東西搭好之后我自己的編碼節(jié)奏明顯變了重復(fù)性的代碼基本交給它我專注在架構(gòu)和業(yè)務(wù)邏輯上整體產(chǎn)出比之前高了不少。