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