最近好幾個(gè)技術(shù)群都在討論同一件事VS Code 里到底怎么把 Claude Code 用起來最好還不走官方那個(gè)模型而是接 DeepSeek 之類的自定義模型。我前后折騰了一周多把命令行版、VS Code 插件、模型網(wǎng)關(guān)全試了一遍期間還翻過幾次車。這篇文章就把完整過程寫清楚——從為什么要在 VS Code 里接 Claude Code到模型網(wǎng)關(guān)怎么搭、環(huán)境變量怎么配、踩了哪些坑一次性說完。1. 為什么在 VS Code 里接 Claude Code先弄清楚它解決什么問題1.1 它和聊天式 AI 助手不是一回事很多人在搜vs code 接入 claude code 并使用自定義模型之前其實(shí)已經(jīng)用過 Copilot、Cursor 這類工具了。但 Claude Code 跟它們有一個(gè)本質(zhì)區(qū)別它不是你問我答的聊天框而是一個(gè)跑在終端里的 agent 程序。怎么理解這個(gè)區(qū)別Copilot 的 Chat 面板也好Cursor 的對(duì)話框也好通常是你把代碼片段粘進(jìn)去它給一個(gè)回答。上下文靠你手動(dòng)貼它很少主動(dòng)去翻你的項(xiàng)目目錄。Claude Code 的行為是另一套邏輯你在終端里輸入claude 幫我把這個(gè)模塊的內(nèi)存泄漏修一下它會(huì)自己讀項(xiàng)目結(jié)構(gòu)定位可疑代碼改完跑測(cè)試測(cè)試掛了再翻日志繼續(xù)改整個(gè)過程會(huì)持續(xù)很多輪直到它覺得自己完成了或者確認(rèn)沒法繼續(xù)下去。所以它更像一個(gè)能獨(dú)立接活的人而不是一個(gè)提供答案的工具。它也正因如此才值得專門集成到 VS Code 這種日常編輯器里。1.2 集成到 VS Code 的實(shí)際收益有人說Claude Code 本來就是命令行工具直接在終端跑不就行了為什么非要在 VS Code 里再搞一次我實(shí)際用了兩周體會(huì)比較深的有三點(diǎn)。第一不用在終端和編輯器之間來回切換。VS Code 的集成終端可以直接跑claude左側(cè)是代碼、右側(cè)是 agent 輸出選中一段代碼可以快速加進(jìn)上下文。單獨(dú)開一個(gè)終端窗口再切來切去效率會(huì)明顯低一截。第二插件提供了可視化的改動(dòng)確認(rèn)。Claude Code 修改完文件之后VS Code 插件可以像 review 同事代碼一樣把每個(gè)文件的 diff 列出來你可以逐個(gè)查看、接受或駁回。這點(diǎn)比終端里的字符對(duì)比舒服太多了尤其是一次改動(dòng)十幾個(gè)文件的場(chǎng)景。第三跟現(xiàn)有工作流融為一體。你在 VS Code 里本來就裝了一堆插件有調(diào)試器、Git 面板、任務(wù) runner。Claude Code 進(jìn)來之后相當(dāng)于多了一個(gè)會(huì)寫代碼的同事寫代碼、跑測(cè)試、看 diff、提交 Git 都在一個(gè)窗口完成。1.3 自定義模型需求從哪來說完集成再談自定義模型。為什么那么多人想把 Claude Code 的底模換掉原因很現(xiàn)實(shí)。官方模型確實(shí)強(qiáng)但有配額限制按量計(jì)費(fèi)不便宜有些人還希望跟團(tuán)隊(duì)已有的模型基礎(chǔ)設(shè)施統(tǒng)一管理。而且 Claude Code 在設(shè)計(jì)上留了一個(gè)很有意思的口子它連接模型時(shí)用的是 Anthropic Messages API 協(xié)議但這個(gè) API 的地址和認(rèn)證令牌都支持用環(huán)境變量覆蓋。這意味著只要有一個(gè)接口兼容 Anthropic 格式的模型服務(wù)你就可以把底層模型換成 DeepSeek、通義、Kimi、GLM甚至本地跑的模型。當(dāng)然自定義模型不是填個(gè) Key 就完事中間有一個(gè)協(xié)議轉(zhuǎn)換的關(guān)卡。這個(gè)我放在第 3 章詳細(xì)說先記住一個(gè)結(jié)論Claude Code 不認(rèn)識(shí)DeepSeekQwen這些型號(hào)它只知道我連接的那個(gè)端點(diǎn)是 Anthropic 兼容的。誰(shuí)在端點(diǎn)背后響應(yīng)完全由你的配置決定。2. 環(huán)境準(zhǔn)備、安裝與首次認(rèn)證把基礎(chǔ)跑通2.1 前置條件Node.js、VS Code 版本、賬號(hào)先把最基礎(chǔ)的東西列出來缺一個(gè)都會(huì)在后續(xù)某一步突然卡住。Node.js 18 或更高版本推薦直接用 20 LTS。Claude Code 和它的 VS Code 插件都依賴 Node 運(yùn)行時(shí)版本太老了裝不上裝上了也可能報(bào)語(yǔ)法錯(cuò)誤。VS Code 1.85 以上太舊的話插件市場(chǎng)可能搜不到擴(kuò)展或者裝完不顯示入口。一個(gè)終端環(huán)境。Windows 用 PowerShell 5.1 或 Git Bash 都可以macOS 和 Linux 用系統(tǒng)自帶終端就行。模型賬號(hào)或 API Key。如果你暫時(shí)只接自定義模型官方賬號(hào)可以放在后面再處理如果你要先試官方模型就得準(zhǔn)備好 Claude 賬號(hào)或 Anthropic Console 里的 API Key。檢查 Node 版本很簡(jiǎn)單node -v npm -v如果node -v沒輸出先去 Node 官網(wǎng)裝 LTS 版本。這里我的建議是不要圖新裝 22 或 24很多 npm 全局包在奇數(shù)大版本環(huán)境下容易冒出莫名其妙的兼容問題20 LTS 是目前最穩(wěn)的選擇。2.2 安裝 CLI 與 VS Code 插件Claude Code 的命令行工具通過 npm 全局安裝npm install -g anthropic-ai/claude-code裝完驗(yàn)證一下claude --version claude doctorclaude doctor會(huì)檢查環(huán)境里的常見問題包括 Node 版本、登錄狀態(tài)、權(quán)限配置等。如果這條命令能順利跑完并列出綠色狀態(tài)說明基礎(chǔ)環(huán)境基本沒問題。VS Code 插件在擴(kuò)展市場(chǎng)直接搜 Claude Code認(rèn)準(zhǔn)發(fā)布者是 Anthropic 的那個(gè)。安裝后左側(cè)活動(dòng)欄會(huì)出現(xiàn)對(duì)應(yīng)的圖標(biāo)點(diǎn)開后能直接發(fā)起會(huì)話也能看到當(dāng)前登錄狀態(tài)。這里有兩個(gè)很容易踩的細(xì)節(jié)。一個(gè)是安裝渠道務(wù)必認(rèn)準(zhǔn)官方不要用來路不明的安裝包尤其是網(wǎng)上那種綠色版整合版保不齊里面夾了私貨。另一個(gè)是插件和 CLI 版本不能差太多。插件本質(zhì)上是在包裝調(diào)用命令行工具如果兩邊版本差距大很容易出現(xiàn) CLI version mismatch 或類似報(bào)錯(cuò)。遇到這種問題升級(jí)/重裝 CLI 通常能一并解決。2.3 登錄認(rèn)證與連通性檢查安裝完成后在終端運(yùn)行claude第一次會(huì)進(jìn)入登錄流程。兩種方式用 Claude 賬號(hào)掃碼/跳瀏覽器授權(quán)或者用 Anthropic Console 生成的 API Key。用 API Key 的場(chǎng)景可以在啟動(dòng)前手動(dòng)設(shè)置環(huán)境變量export ANTHROPIC_API_KEYsk-ant-你的key claude這里說一個(gè)比較現(xiàn)實(shí)的注意點(diǎn)如果你在瀏覽器登錄頁(yè)遇到地區(qū)不支持之類的提示先冷靜確認(rèn)是否在官方支持范圍里。對(duì)于一心想接自定義模型的人來說其實(shí)可以跳過官方認(rèn)證這步直接進(jìn)入第 3 章的網(wǎng)關(guān)配置。Claude Code 在自定義模型模式下連接的是你自己的端點(diǎn)認(rèn)證邏輯完全由該端點(diǎn)決定不一定非要持有官方賬號(hào)。登錄狀態(tài)可以用斜杠命令查看。進(jìn)入 Claude Code 會(huì)話后輸入/status它會(huì)列出當(dāng)前模型、賬號(hào)、工作目錄等信息。這一步確認(rèn)通過基礎(chǔ)就沒有問題了。3. 自定義模型的接入原理關(guān)鍵在協(xié)議轉(zhuǎn)換3.1 Claude Code 是怎么找到模型的要講明白自定義模型怎么接得先看看 Claude Code 啟動(dòng)時(shí)讀哪些環(huán)境變量。它們決定了請(qǐng)求發(fā)到哪、認(rèn)證用什么、模型叫什么。環(huán)境變量作用ANTHROPIC_BASE_URL覆蓋 API 根地址指向你的自定義端點(diǎn)ANTHROPIC_AUTH_TOKEN覆蓋認(rèn)證令牌常用于自定義網(wǎng)關(guān)場(chǎng)景ANTHROPIC_API_KEY官方 API Key走官方地址時(shí)使用ANTHROPIC_MODEL設(shè)置主模型名稱ANTHROPIC_SMALL_FAST_MODEL設(shè)置后臺(tái)快速模型用于標(biāo)題生成、上下文壓縮等小任務(wù)ANTHROPIC_DEFAULT_SONNET_MODEL覆蓋默認(rèn) Sonnet 檔位ANTHROPIC_DEFAULT_HAIKU_MODEL覆蓋默認(rèn) Haiku 檔位Claude Code 發(fā)起的每個(gè)請(qǐng)求本質(zhì)上是 POST 到{BASE_URL}/v1/messages請(qǐng)求體里帶 model、messages、system、tools 這些字段。默認(rèn)情況下 BASE_URL 是https://api.anthropic.com你換成自己的端點(diǎn)后它就把那里當(dāng)成官方來對(duì)話。理解這條邏輯特別重要Claude Code 不關(guān)心端點(diǎn)背后是 DeepSeek 還是本地模型它只認(rèn)協(xié)議。所以自定義模型成功與否取決于兩端格式是不是匹配。3.2 方案一直接用 Anthropic 兼容端點(diǎn)最省事的情況是模型服務(wù)商直接提供 Anthropic 兼容接口?，F(xiàn)在不少云平臺(tái)都同時(shí)提供 OpenAI 格式和 Anthropic 格式的 API你只需要在配置里填三樣?xùn)|西ANTHROPIC_BASE_URL填對(duì)方給的消息接口根地址ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY填對(duì)方的令牌ANTHROPIC_MODEL填對(duì)方支持的模型名然后啟動(dòng)claude就能用。那為什么很多人還是繞了一圈因?yàn)榇罅繜衢T模型只開放 OpenAI 格式也就是/v1/chat/completions不直接兼容 Anthropic 協(xié)議。這時(shí)候就需要第三種方案。3.3 方案二用模型網(wǎng)關(guān)做協(xié)議轉(zhuǎn)換網(wǎng)關(guān)是自定義模型場(chǎng)景里最常用的組件。它的核心工作只有一件把 Anthropic 格式的/v1/messages請(qǐng)求翻譯成 OpenAI 格式的/v1/chat/completions再把返回結(jié)果翻譯回去。Claude Code 說的話是Anthropic 方言模型服務(wù)那邊聽的是OpenAI 方言網(wǎng)關(guān)就是那個(gè)同聲傳譯。常見的網(wǎng)關(guān)有 LiteLLM、one-api、new-api 等。用 LiteLLM 舉個(gè)最小可跑的流程pip install litellm[proxy]準(zhǔn)備一個(gè)config.yamlmodel_list: - model_name: deepseek/deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的deepseek key啟動(dòng)litellm --config config.yaml --port 4000然后驗(yàn)證網(wǎng)關(guān)是否活著curl http://localhost:4000/v1/models有模型列表返回就說明網(wǎng)關(guān)起來了。接下來把 Claude Code 的環(huán)境變量指過去即可。需要提醒的是網(wǎng)關(guān)本身不產(chǎn)生模型能力它只是個(gè)翻譯和路由層。真正的算力還是由后端模型服務(wù)商提供。所以選網(wǎng)關(guān)時(shí)重點(diǎn)看三件事協(xié)議轉(zhuǎn)換是否完整、工具調(diào)用function calling是否保真、有沒有日志方便排錯(cuò)。3.4 方案三只換官方模型檔位不動(dòng)端點(diǎn)如果你不是想換供應(yīng)商只是覺得官方模型太貴、或者想讓小任務(wù)用便宜檔位那不需要碰網(wǎng)關(guān)。直接在會(huì)話里輸入/model可以切換模型也可以在環(huán)境變量里指定默認(rèn)檔位。export ANTHROPIC_MODELclaude-sonnet-4-20250514 export ANTHROPIC_SMALL_FAST_MODELclaude-haiku-4-5-20251001這里后一個(gè)變量容易被人忽視。SMALL_FAST_MODEL是給后臺(tái)高頻小任務(wù)用的模型比如生成會(huì)話標(biāo)題、總結(jié)歷史上下文、壓縮對(duì)話。只要把這些小任務(wù)指到便宜快速檔位整體開銷會(huì)明顯降下來。對(duì)于官方按量計(jì)費(fèi)的用戶這個(gè)變量比主模型更能省成本。4. 實(shí)操把 DeepSeek 接進(jìn) VS Code 里的 Claude Code4.1 第一步本地起一個(gè)模型網(wǎng)關(guān)以 DeepSeek 為例完整跑通一次。先確認(rèn)你有 DeepSeek 的 API Key然后安裝并啟動(dòng) LiteLLM。pip install litellm[proxy]創(chuàng)建~/litellm-config/config.yamlmodel_list: - model_name: deepseek/deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的deepseek key啟動(dòng)litellm --config ~/litellm-config/config.yaml --port 4000啟動(dòng)后最好單獨(dú)開一個(gè)終端跑一次 curl 確認(rèn)網(wǎng)關(guān)真的能通curl http://localhost:4000/v1/models這一步如果 404 或者 connection refused先檢查端口有沒有被占、配置文件路徑是否正確。不要急著去動(dòng) Claude Code 那邊網(wǎng)關(guān)沒通后面全是白搭。4.2 第二步配置環(huán)境變量Windows / Linux / macOSLinux 和 macOS 在終端里臨時(shí)生效export ANTHROPIC_BASE_URLhttp://localhost:4000 export ANTHROPIC_AUTH_TOKENsk-你的deepseek key export ANTHROPIC_MODELdeepseek/deepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek/deepseek-chat claudeWindows 的 PowerShell 寫法不同$env:ANTHROPIC_BASE_URLhttp://localhost:4000 $env:ANTHROPIC_AUTH_TOKENsk-你的deepseek key $env:ANTHROPIC_MODELdeepseek/deepseek-chat $env:ANTHROPIC_SMALL_FAST_MODELdeepseek/deepseek-chat claude想要永久生效Linux 寫進(jìn)~/.bashrc或~/.zshrcWindows 用系統(tǒng)設(shè)置里的環(huán)境變量面板。這里有個(gè)很多人搞混的地方既然網(wǎng)關(guān)地址是 localhost那 ANTHROPIC_AUTH_TOKEN 填什么如果網(wǎng)關(guān)本身沒有額外鑒權(quán)Claude Code 在自定義模式下依然需要一個(gè) token 才不會(huì)報(bào) auth 錯(cuò)誤。最簡(jiǎn)單的做法就是填你后端模型的 Key網(wǎng)關(guān)會(huì)讀這個(gè)字段做轉(zhuǎn)發(fā)或者不細(xì)究它、反正真實(shí)請(qǐng)求到達(dá)后端時(shí)用的是網(wǎng)關(guān) config 里的 api_key。兩種都能跑通。4.3 第三步把配置固化到項(xiàng)目 .claude/settings.json環(huán)境變量寫全局有個(gè)壞處你同時(shí)看好幾個(gè)項(xiàng)目每個(gè)項(xiàng)目想接的模型可能不一樣。官方提供了項(xiàng)目級(jí)配置在項(xiàng)目根目錄創(chuàng)建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: http://localhost:4000, ANTHROPIC_AUTH_TOKEN: sk-你的deepseek key, ANTHROPIC_MODEL: deepseek/deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek/deepseek-chat }, permissions: { defaultMode: acceptEdits } }這個(gè)文件放進(jìn) Git 倉(cāng)庫(kù)后團(tuán)隊(duì)里所有人打開項(xiàng)目都自動(dòng)帶上這套配置不用每個(gè)人都去設(shè)一遍系統(tǒng)環(huán)境變量。這也是我最推薦的實(shí)踐方式比全局 export 干凈得多。4.4 第四步驗(yàn)證請(qǐng)求確實(shí)走到了自定義模型配置完如何確認(rèn)我真的在用 DeepSeek而不是官方模型三種辦法可以交叉驗(yàn)證。第一種進(jìn)入 Claude Code 會(huì)話輸入/status看 Model 行。第二種觀察網(wǎng)關(guān)日志LiteLLM 啟動(dòng)后每次請(qǐng)求都會(huì)打日志能看到請(qǐng)求來自哪個(gè)進(jìn)程、模型名是什么。第三種故意在配置里寫一個(gè)不存在的模型名如果立刻報(bào)錯(cuò)說明請(qǐng)求確實(shí)到達(dá)了你的網(wǎng)關(guān)。我在這一步遇到過最典型的翻車情況是終端里 export 了變量但 VS Code 插件里啟動(dòng)的 Claude Code 沒有讀到。原因是插件啟動(dòng)進(jìn)程時(shí)不一定繼承你的 shell 環(huán)境。所以如果你發(fā)現(xiàn)終端能用、插件不能用優(yōu)先去檢查插件的設(shè)置項(xiàng)或者干脆把環(huán)境變量寫進(jìn).claude/settings.json讓插件自己完整地讀那個(gè)文件。4.5 網(wǎng)關(guān)部署的選型本地跑還是團(tuán)隊(duì)共用自己一個(gè)人折騰本地localhost:4000足夠。但如果是團(tuán)隊(duì)協(xié)作每臺(tái)電腦各跑一個(gè)網(wǎng)關(guān)很浪費(fèi)而且 Key 散落在各人配置里不好管理。更合理的做法是把網(wǎng)關(guān)部署到一臺(tái)服務(wù)器或容器里加一層訪問令牌然后 Claude Code 的ANTHROPIC_BASE_URL指向那臺(tái)服務(wù)器的地址。團(tuán)隊(duì)共用網(wǎng)關(guān)還有一個(gè)好處可以在網(wǎng)關(guān)這一層做模型路由、配額統(tǒng)計(jì)、成本審計(jì)。誰(shuí)用了多少 token、調(diào)用的是哪個(gè)模型日志里全都有。對(duì)負(fù)責(zé)基建的人來說這套體系比讓每個(gè)開發(fā)自己填不同模型的 Key 容易管理得多。5. 接入后的日常使用與進(jìn)階玩法5.1 換模型后要注意的性格差接上 DeepSeek 之后你會(huì)發(fā)現(xiàn) Claude Code 的表現(xiàn)跟官方模型不完全一樣就像團(tuán)隊(duì)里來了個(gè)新實(shí)習(xí)生能力不差但做事風(fēng)格不同。具體表現(xiàn)有哪些官方 Claude 對(duì)工具調(diào)用的遵循非常穩(wěn)定規(guī)劃步驟基本不會(huì)漏部分開源或第三方模型在長(zhǎng)任務(wù)里可能突然忘掉系統(tǒng)提示里的約束或者工具調(diào)用格式偶爾出錯(cuò)。另外不同模型對(duì) CLAUDE.md 指令的執(zhí)行嚴(yán)格度差別很大同一句話在官方模型下會(huì)被嚴(yán)格執(zhí)行在自定義模型下可能被當(dāng)成背景信息忽略掉。所以我的建議是換自定義模型后把任務(wù)拆小一點(diǎn)一次不要讓它干太多事。比如重構(gòu)整個(gè)模塊這種任務(wù)很容易半路失憶不如拆成先梳理依賴再改接口最后跑測(cè)試三個(gè)小步驟。同時(shí)保留 diff 確認(rèn)的習(xí)慣不要在自定義模型下輕易開全自動(dòng)權(quán)限。5.2 權(quán)限模式的選擇與自動(dòng)執(zhí)行邊界Claude Code 有幾種權(quán)限模式理解它們的適用場(chǎng)景能避免不少麻煩。默認(rèn)模式每次執(zhí)行敏感命令前先問你要不要繼續(xù)。acceptEdits自動(dòng)接受文件編輯但執(zhí)行命令仍需確認(rèn)。bypassPermissions什么都不問直接干活。plan模式只出計(jì)劃不動(dòng)手改代碼。在自定義模型場(chǎng)景下我從不開bypassPermissions。原因很簡(jiǎn)單非官方模型對(duì)哪些命令是安全的判斷并不一定可靠。它可能覺得rm -rf沒問題也可能在改配置時(shí)把無關(guān)文件一并動(dòng)掉。保留一個(gè)確認(rèn)環(huán)節(jié)是成本最低的安全策略。5.3 手動(dòng)安裝 GitHub 上的 Skills很多人會(huì)搜claude code 怎么手動(dòng)裝 github 上的 skills。其實(shí) Skill 的本質(zhì)就是一個(gè)目錄里面放一個(gè) SKILL.md 文件用 Markdown 描述這個(gè)技能是干什么的、怎么用再配上一些腳本或資源。手動(dòng)安裝很簡(jiǎn)單。把倉(cāng)庫(kù)克隆到用戶級(jí) skills 目錄mkdir -p ~/.claude/skills git clone skill倉(cāng)庫(kù)地址 ~/.claude/skills/你的技能名項(xiàng)目級(jí)安裝則放到項(xiàng)目根目錄的.claude/skills/下。裝完后重啟 Claude Code 會(huì)話輸入/skills看看技能是否被加載。SKILL.md 的開頭有 YAML front matter基本格式是--- name: 技能名 description: 什么時(shí)候使用這個(gè)技能 ---這里有個(gè)很多人不知道的細(xì)節(jié)description 會(huì)被模型用來做技能檢索。如果描述寫得含糊模型可能永遠(yuǎn)都不會(huì)主動(dòng)調(diào)用它。寫得越具體越好比如當(dāng)用戶要求將項(xiàng)目部署到服務(wù)器時(shí)使用此技能而不是泛泛的部署相關(guān)。5.4 MCP 擴(kuò)展讓 agent 讀寫外部工具M(jìn)CP 是 Claude Code 連接外部工具的標(biāo)準(zhǔn)方式。通過 MCP 服務(wù)器它可以查詢數(shù)據(jù)庫(kù)、調(diào)用瀏覽器、讀寫文件、操作第三方服務(wù)。配置一般放在項(xiàng)目根目錄的.mcp.json里{ mcpServers: { fetch: { command: npx, args: [-y, mcp-server-fetch] } } }配置完成后重啟 Claude Code 它會(huì)自動(dòng)加載并告訴你可用的工具。自定義模型環(huán)境下MCP 有一個(gè)需要特別注意的坑工具返回的數(shù)據(jù)會(huì)占用上下文窗口。如果后端模型窗口比官方模型小一次大表查詢可能直接把上下文塞爆后面的對(duì)話就失憶了。所以接 MCP 后盡量讓查詢帶上明確的 LIMIT 和 WHERE少拉全表。5.5 用 CLAUDE.md 調(diào)教自定義模型Claude Code 啟動(dòng)時(shí)會(huì)自動(dòng)讀項(xiàng)目根目錄的 CLAUDE.md把它作為長(zhǎng)期記憶。這個(gè)文件對(duì)自定義模型的影響很大因?yàn)樗喈?dāng)于唯一穩(wěn)定的人設(shè)說明書。我的寫法一般是四段式# 項(xiàng)目概述 這個(gè)服務(wù)是做什么的、技術(shù)棧、關(guān)鍵目錄結(jié)構(gòu)。 # 常用命令 如何跑測(cè)試、如何啟動(dòng)開發(fā)服務(wù)器、如何構(gòu)建。 # 編碼規(guī)范 命名風(fēng)格、目錄組織、錯(cuò)誤處理約定。 # 需要避免的事 不要?jiǎng)幽男┠夸洝⒉灰哪男┪募?、不要?zhí)行哪些命令。自定義模型對(duì)長(zhǎng)文檔的理解不如官方模型強(qiáng)所以 CLAUDE.md 要短、明確、條目化。超過兩頁(yè)紙的規(guī)范文檔模型大概率會(huì)漏讀后半部分。把最重要的約束放在前幾行比放在末尾管用得多。6. 踩坑記錄我配自定義模型時(shí)的五個(gè)翻車現(xiàn)場(chǎng)6.1 坑一模型不在允許列表請(qǐng)求直接被攔這是我第一次切網(wǎng)關(guān)時(shí)遇到的。配置全都填好啟動(dòng)claude立刻報(bào)錯(cuò)說當(dāng)前模型不在允許列表里。原因是 Claude Code 內(nèi)部有一套模型名校驗(yàn)它認(rèn)識(shí)的名字通常是claude-開頭的。你直接填deepseek/deepseek-chat它會(huì)覺得這是非法模型。解決辦法是給模型取一個(gè)它認(rèn)識(shí)的名字在網(wǎng)關(guān)里把入口模型名配成claude-sonnet-4-20250514實(shí)際轉(zhuǎn)發(fā)到 DeepSeek。LiteLLM 里是這樣改的model_list: - model_name: claude-sonnet-4-20250514 litellm_params: model: deepseek/deepseek-chat api_key: sk-你的deepseek key然后ANTHROPIC_MODEL也填claude-sonnet-4-20250514。這樣 Claude Code 校驗(yàn)通過網(wǎng)關(guān)再把請(qǐng)求轉(zhuǎn)發(fā)給 DeepSeek。6.2 坑二一直轉(zhuǎn)圈 / 網(wǎng)關(guān)返回格式錯(cuò)誤另一種常見現(xiàn)象是 Claude Code 一直轉(zhuǎn)圈沒有任何輸出網(wǎng)關(guān)日志里出現(xiàn) BadRequestError 之類的報(bào)錯(cuò)。我遇到的情況基本都出在工具調(diào)用上。Claude Code 會(huì)用 tools 字段要求模型具備函數(shù)調(diào)用能力如果自定義模型本身不支持 function calling或者返回的工具調(diào)用內(nèi)容格式不規(guī)范兩邊就僵住了。這時(shí)先去網(wǎng)關(guān)的測(cè)試頁(yè)或者寫一個(gè)最小請(qǐng)求驗(yàn)證同一個(gè)模型能否正確返回帶工具調(diào)用的響應(yīng)。確認(rèn)模型支持 function calling 之后再回 Claude Code 重試。如果模型確實(shí)不支持可以考慮換一個(gè)模型版本或者限制 Claude Code 不使用工具——但那樣 agent 能力基本就廢了不太推薦。6.3 坑三上下文被截?cái)嗳蝿?wù)做到一半失憶用某個(gè)模型跑長(zhǎng)任務(wù)時(shí)它突然忘了最初的指令或者開始重復(fù)做已經(jīng)完成的事。剛開始我以為是自己提示詞沒寫好后來才發(fā)現(xiàn)是上下文窗口問題。自定義模型的上下文窗口可能比官方模型小而 Claude Code 默認(rèn)會(huì)維護(hù)一個(gè)比較大的對(duì)話上下文包括讀取過的文件、執(zhí)行過的命令、中間結(jié)果。窗口被塞滿后要么截?cái)嘁磯嚎s但壓縮邏輯是基于 Anthropic 模型設(shè)計(jì)的換到別的模型上表現(xiàn)不一定好。應(yīng)對(duì)方式有三個(gè)。一是縮小任務(wù)的顆粒度每次只讓它處理幾個(gè)文件不要整個(gè)項(xiàng)目一把梭。二是在 CLAUDE.md 里明確寫清不要讀哪些目錄避免無關(guān)文件占用窗口。三是用/compact手動(dòng)壓縮上下文在關(guān)鍵節(jié)點(diǎn)主動(dòng)瘦身而不是等它滿到爆。6.4 坑四VS Code 插件與終端表現(xiàn)不一致終端里 Claude Code 一切正常一用 VS Code 插件就報(bào)Auth error或者模型沒生效這類問題我排查了很久。原因基本是插件執(zhí)行 Claude Code 時(shí)用的環(huán)境變量跟你終端里 export 的不一樣。插件有自己?jiǎn)?dòng)進(jìn)程的方式不一定會(huì)繼承你的 shell profile。解決思路也簡(jiǎn)單不要依賴 export把配置寫進(jìn).claude/settings.json。插件每次啟動(dòng)都會(huì)讀這個(gè)文件里的 env 字段等于給每個(gè)項(xiàng)目綁定了固定的模型和端點(diǎn)繞開了 shell 環(huán)境差異。如果還是不行檢查插件設(shè)置里的 CLI path 是否正確確保它調(diào)用的是你全局安裝的那個(gè)claude。6.5 坑五卸載殘留與重裝陷阱卸載 Claude Code 不是只有一條命令。npm 全局卸載npm uninstall -g anthropic-ai/claude-code但配置和緩存目錄~/.claude不會(huì)自動(dòng)刪除。如果想留 skills 和項(xiàng)目配置可以只刪日志和臨時(shí)文件rm -rf ~/.claude/logs ~/.claude/tmp如果徹底不用了直接刪整個(gè)~/.claude也沒問題。VS Code 插件在擴(kuò)展面板卸載即可卸載后如果還彈身份錯(cuò)誤檢查一下工作區(qū)信任管理里殘留的 Claude Code 授權(quán)記錄。重裝時(shí)有個(gè)我踩過的坑舊版 CLI 沒卸載干凈claude命令指向的還是舊文件新裝的版本始終沒生效。所以重裝前先claude --version確認(rèn)版本號(hào)再執(zhí)行安裝命令。最后說一點(diǎn)個(gè)人體會(huì)。Claude Code 真正值錢的地方不是它某一次回答有多聰明而是它愿意把改動(dòng)方案攤開給你看讓你逐個(gè) diff 確認(rèn)后再?zèng)Q定是否落地。自定義模型的接入本質(zhì)上解決的是模型選型權(quán)問題把 agent 的底模換成你熟悉、可控、便宜的模型代價(jià)是你得自己處理協(xié)議差異和模型質(zhì)量波動(dòng)。我的建議是新手先按官方模型把整個(gè)流程跑通再切自定義模型。這樣出現(xiàn)問題時(shí)你至少能判斷官方能通那問題就出在網(wǎng)關(guān)或模型參數(shù)上而不是在一個(gè)全黑的盒子里猜。 VS Code 接入 Claude Code 并切換 DeepSeek 自定義模型完整指南
最近好幾個(gè)技術(shù)群都在討論同一件事VS Code 里到底怎么把 Claude Code 用起來最好還不走官方那個(gè)模型而是接 DeepSeek 之類的自定義模型。我前后折騰了一周多把命令行版、VS Code 插件、模型網(wǎng)關(guān)全試了一遍期間還翻過幾次車。這篇文章就把完整過程寫清楚——從為什么要在 VS Code 里接 Claude Code到模型網(wǎng)關(guān)怎么搭、環(huán)境變量怎么配、踩了哪些坑一次性說完。1. 為什么在 VS Code 里接 Claude Code先弄清楚它解決什么問題1.1 它和聊天式 AI 助手不是一回事很多人在搜vs code 接入 claude code 并使用自定義模型之前其實(shí)已經(jīng)用過 Copilot、Cursor 這類工具了。但 Claude Code 跟它們有一個(gè)本質(zhì)區(qū)別它不是你問我答的聊天框而是一個(gè)跑在終端里的 agent 程序。怎么理解這個(gè)區(qū)別Copilot 的 Chat 面板也好Cursor 的對(duì)話框也好通常是你把代碼片段粘進(jìn)去它給一個(gè)回答。上下文靠你手動(dòng)貼它很少主動(dòng)去翻你的項(xiàng)目目錄。Claude Code 的行為是另一套邏輯你在終端里輸入claude 幫我把這個(gè)模塊的內(nèi)存泄漏修一下它會(huì)自己讀項(xiàng)目結(jié)構(gòu)定位可疑代碼改完跑測(cè)試測(cè)試掛了再翻日志繼續(xù)改整個(gè)過程會(huì)持續(xù)很多輪直到它覺得自己完成了或者確認(rèn)沒法繼續(xù)下去。所以它更像一個(gè)能獨(dú)立接活的人而不是一個(gè)提供答案的工具。它也正因如此才值得專門集成到 VS Code 這種日常編輯器里。1.2 集成到 VS Code 的實(shí)際收益有人說Claude Code 本來就是命令行工具直接在終端跑不就行了為什么非要在 VS Code 里再搞一次我實(shí)際用了兩周體會(huì)比較深的有三點(diǎn)。第一不用在終端和編輯器之間來回切換。VS Code 的集成終端可以直接跑claude左側(cè)是代碼、右側(cè)是 agent 輸出選中一段代碼可以快速加進(jìn)上下文。單獨(dú)開一個(gè)終端窗口再切來切去效率會(huì)明顯低一截。第二插件提供了可視化的改動(dòng)確認(rèn)。Claude Code 修改完文件之后VS Code 插件可以像 review 同事代碼一樣把每個(gè)文件的 diff 列出來你可以逐個(gè)查看、接受或駁回。這點(diǎn)比終端里的字符對(duì)比舒服太多了尤其是一次改動(dòng)十幾個(gè)文件的場(chǎng)景。第三跟現(xiàn)有工作流融為一體。你在 VS Code 里本來就裝了一堆插件有調(diào)試器、Git 面板、任務(wù) runner。Claude Code 進(jìn)來之后相當(dāng)于多了一個(gè)會(huì)寫代碼的同事寫代碼、跑測(cè)試、看 diff、提交 Git 都在一個(gè)窗口完成。1.3 自定義模型需求從哪來說完集成再談自定義模型。為什么那么多人想把 Claude Code 的底模換掉原因很現(xiàn)實(shí)。官方模型確實(shí)強(qiáng)但有配額限制按量計(jì)費(fèi)不便宜有些人還希望跟團(tuán)隊(duì)已有的模型基礎(chǔ)設(shè)施統(tǒng)一管理。而且 Claude Code 在設(shè)計(jì)上留了一個(gè)很有意思的口子它連接模型時(shí)用的是 Anthropic Messages API 協(xié)議但這個(gè) API 的地址和認(rèn)證令牌都支持用環(huán)境變量覆蓋。這意味著只要有一個(gè)接口兼容 Anthropic 格式的模型服務(wù)你就可以把底層模型換成 DeepSeek、通義、Kimi、GLM甚至本地跑的模型。當(dāng)然自定義模型不是填個(gè) Key 就完事中間有一個(gè)協(xié)議轉(zhuǎn)換的關(guān)卡。這個(gè)我放在第 3 章詳細(xì)說先記住一個(gè)結(jié)論Claude Code 不認(rèn)識(shí)DeepSeekQwen這些型號(hào)它只知道我連接的那個(gè)端點(diǎn)是 Anthropic 兼容的。誰(shuí)在端點(diǎn)背后響應(yīng)完全由你的配置決定。2. 環(huán)境準(zhǔn)備、安裝與首次認(rèn)證把基礎(chǔ)跑通2.1 前置條件Node.js、VS Code 版本、賬號(hào)先把最基礎(chǔ)的東西列出來缺一個(gè)都會(huì)在后續(xù)某一步突然卡住。Node.js 18 或更高版本推薦直接用 20 LTS。Claude Code 和它的 VS Code 插件都依賴 Node 運(yùn)行時(shí)版本太老了裝不上裝上了也可能報(bào)語(yǔ)法錯(cuò)誤。VS Code 1.85 以上太舊的話插件市場(chǎng)可能搜不到擴(kuò)展或者裝完不顯示入口。一個(gè)終端環(huán)境。Windows 用 PowerShell 5.1 或 Git Bash 都可以macOS 和 Linux 用系統(tǒng)自帶終端就行。模型賬號(hào)或 API Key。如果你暫時(shí)只接自定義模型官方賬號(hào)可以放在后面再處理如果你要先試官方模型就得準(zhǔn)備好 Claude 賬號(hào)或 Anthropic Console 里的 API Key。檢查 Node 版本很簡(jiǎn)單node -v npm -v如果node -v沒輸出先去 Node 官網(wǎng)裝 LTS 版本。這里我的建議是不要圖新裝 22 或 24很多 npm 全局包在奇數(shù)大版本環(huán)境下容易冒出莫名其妙的兼容問題20 LTS 是目前最穩(wěn)的選擇。2.2 安裝 CLI 與 VS Code 插件Claude Code 的命令行工具通過 npm 全局安裝npm install -g anthropic-ai/claude-code裝完驗(yàn)證一下claude --version claude doctorclaude doctor會(huì)檢查環(huán)境里的常見問題包括 Node 版本、登錄狀態(tài)、權(quán)限配置等。如果這條命令能順利跑完并列出綠色狀態(tài)說明基礎(chǔ)環(huán)境基本沒問題。VS Code 插件在擴(kuò)展市場(chǎng)直接搜 Claude Code認(rèn)準(zhǔn)發(fā)布者是 Anthropic 的那個(gè)。安裝后左側(cè)活動(dòng)欄會(huì)出現(xiàn)對(duì)應(yīng)的圖標(biāo)點(diǎn)開后能直接發(fā)起會(huì)話也能看到當(dāng)前登錄狀態(tài)。這里有兩個(gè)很容易踩的細(xì)節(jié)。一個(gè)是安裝渠道務(wù)必認(rèn)準(zhǔn)官方不要用來路不明的安裝包尤其是網(wǎng)上那種綠色版整合版保不齊里面夾了私貨。另一個(gè)是插件和 CLI 版本不能差太多。插件本質(zhì)上是在包裝調(diào)用命令行工具如果兩邊版本差距大很容易出現(xiàn) CLI version mismatch 或類似報(bào)錯(cuò)。遇到這種問題升級(jí)/重裝 CLI 通常能一并解決。2.3 登錄認(rèn)證與連通性檢查安裝完成后在終端運(yùn)行claude第一次會(huì)進(jìn)入登錄流程。兩種方式用 Claude 賬號(hào)掃碼/跳瀏覽器授權(quán)或者用 Anthropic Console 生成的 API Key。用 API Key 的場(chǎng)景可以在啟動(dòng)前手動(dòng)設(shè)置環(huán)境變量export ANTHROPIC_API_KEYsk-ant-你的key claude這里說一個(gè)比較現(xiàn)實(shí)的注意點(diǎn)如果你在瀏覽器登錄頁(yè)遇到地區(qū)不支持之類的提示先冷靜確認(rèn)是否在官方支持范圍里。對(duì)于一心想接自定義模型的人來說其實(shí)可以跳過官方認(rèn)證這步直接進(jìn)入第 3 章的網(wǎng)關(guān)配置。Claude Code 在自定義模型模式下連接的是你自己的端點(diǎn)認(rèn)證邏輯完全由該端點(diǎn)決定不一定非要持有官方賬號(hào)。登錄狀態(tài)可以用斜杠命令查看。進(jìn)入 Claude Code 會(huì)話后輸入/status它會(huì)列出當(dāng)前模型、賬號(hào)、工作目錄等信息。這一步確認(rèn)通過基礎(chǔ)就沒有問題了。3. 自定義模型的接入原理關(guān)鍵在協(xié)議轉(zhuǎn)換3.1 Claude Code 是怎么找到模型的要講明白自定義模型怎么接得先看看 Claude Code 啟動(dòng)時(shí)讀哪些環(huán)境變量。它們決定了請(qǐng)求發(fā)到哪、認(rèn)證用什么、模型叫什么。環(huán)境變量作用ANTHROPIC_BASE_URL覆蓋 API 根地址指向你的自定義端點(diǎn)ANTHROPIC_AUTH_TOKEN覆蓋認(rèn)證令牌常用于自定義網(wǎng)關(guān)場(chǎng)景ANTHROPIC_API_KEY官方 API Key走官方地址時(shí)使用ANTHROPIC_MODEL設(shè)置主模型名稱ANTHROPIC_SMALL_FAST_MODEL設(shè)置后臺(tái)快速模型用于標(biāo)題生成、上下文壓縮等小任務(wù)ANTHROPIC_DEFAULT_SONNET_MODEL覆蓋默認(rèn) Sonnet 檔位ANTHROPIC_DEFAULT_HAIKU_MODEL覆蓋默認(rèn) Haiku 檔位Claude Code 發(fā)起的每個(gè)請(qǐng)求本質(zhì)上是 POST 到{BASE_URL}/v1/messages請(qǐng)求體里帶 model、messages、system、tools 這些字段。默認(rèn)情況下 BASE_URL 是https://api.anthropic.com你換成自己的端點(diǎn)后它就把那里當(dāng)成官方來對(duì)話。理解這條邏輯特別重要Claude Code 不關(guān)心端點(diǎn)背后是 DeepSeek 還是本地模型它只認(rèn)協(xié)議。所以自定義模型成功與否取決于兩端格式是不是匹配。3.2 方案一直接用 Anthropic 兼容端點(diǎn)最省事的情況是模型服務(wù)商直接提供 Anthropic 兼容接口?，F(xiàn)在不少云平臺(tái)都同時(shí)提供 OpenAI 格式和 Anthropic 格式的 API你只需要在配置里填三樣?xùn)|西ANTHROPIC_BASE_URL填對(duì)方給的消息接口根地址ANTHROPIC_AUTH_TOKEN或ANTHROPIC_API_KEY填對(duì)方的令牌ANTHROPIC_MODEL填對(duì)方支持的模型名然后啟動(dòng)claude就能用。那為什么很多人還是繞了一圈因?yàn)榇罅繜衢T模型只開放 OpenAI 格式也就是/v1/chat/completions不直接兼容 Anthropic 協(xié)議。這時(shí)候就需要第三種方案。3.3 方案二用模型網(wǎng)關(guān)做協(xié)議轉(zhuǎn)換網(wǎng)關(guān)是自定義模型場(chǎng)景里最常用的組件。它的核心工作只有一件把 Anthropic 格式的/v1/messages請(qǐng)求翻譯成 OpenAI 格式的/v1/chat/completions再把返回結(jié)果翻譯回去。Claude Code 說的話是Anthropic 方言模型服務(wù)那邊聽的是OpenAI 方言網(wǎng)關(guān)就是那個(gè)同聲傳譯。常見的網(wǎng)關(guān)有 LiteLLM、one-api、new-api 等。用 LiteLLM 舉個(gè)最小可跑的流程pip install litellm[proxy]準(zhǔn)備一個(gè)config.yamlmodel_list: - model_name: deepseek/deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的deepseek key啟動(dòng)litellm --config config.yaml --port 4000然后驗(yàn)證網(wǎng)關(guān)是否活著curl http://localhost:4000/v1/models有模型列表返回就說明網(wǎng)關(guān)起來了。接下來把 Claude Code 的環(huán)境變量指過去即可。需要提醒的是網(wǎng)關(guān)本身不產(chǎn)生模型能力它只是個(gè)翻譯和路由層。真正的算力還是由后端模型服務(wù)商提供。所以選網(wǎng)關(guān)時(shí)重點(diǎn)看三件事協(xié)議轉(zhuǎn)換是否完整、工具調(diào)用function calling是否保真、有沒有日志方便排錯(cuò)。3.4 方案三只換官方模型檔位不動(dòng)端點(diǎn)如果你不是想換供應(yīng)商只是覺得官方模型太貴、或者想讓小任務(wù)用便宜檔位那不需要碰網(wǎng)關(guān)。直接在會(huì)話里輸入/model可以切換模型也可以在環(huán)境變量里指定默認(rèn)檔位。export ANTHROPIC_MODELclaude-sonnet-4-20250514 export ANTHROPIC_SMALL_FAST_MODELclaude-haiku-4-5-20251001這里后一個(gè)變量容易被人忽視。SMALL_FAST_MODEL是給后臺(tái)高頻小任務(wù)用的模型比如生成會(huì)話標(biāo)題、總結(jié)歷史上下文、壓縮對(duì)話。只要把這些小任務(wù)指到便宜快速檔位整體開銷會(huì)明顯降下來。對(duì)于官方按量計(jì)費(fèi)的用戶這個(gè)變量比主模型更能省成本。4. 實(shí)操把 DeepSeek 接進(jìn) VS Code 里的 Claude Code4.1 第一步本地起一個(gè)模型網(wǎng)關(guān)以 DeepSeek 為例完整跑通一次。先確認(rèn)你有 DeepSeek 的 API Key然后安裝并啟動(dòng) LiteLLM。pip install litellm[proxy]創(chuàng)建~/litellm-config/config.yamlmodel_list: - model_name: deepseek/deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: sk-你的deepseek key啟動(dòng)litellm --config ~/litellm-config/config.yaml --port 4000啟動(dòng)后最好單獨(dú)開一個(gè)終端跑一次 curl 確認(rèn)網(wǎng)關(guān)真的能通curl http://localhost:4000/v1/models這一步如果 404 或者 connection refused先檢查端口有沒有被占、配置文件路徑是否正確。不要急著去動(dòng) Claude Code 那邊網(wǎng)關(guān)沒通后面全是白搭。4.2 第二步配置環(huán)境變量Windows / Linux / macOSLinux 和 macOS 在終端里臨時(shí)生效export ANTHROPIC_BASE_URLhttp://localhost:4000 export ANTHROPIC_AUTH_TOKENsk-你的deepseek key export ANTHROPIC_MODELdeepseek/deepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek/deepseek-chat claudeWindows 的 PowerShell 寫法不同$env:ANTHROPIC_BASE_URLhttp://localhost:4000 $env:ANTHROPIC_AUTH_TOKENsk-你的deepseek key $env:ANTHROPIC_MODELdeepseek/deepseek-chat $env:ANTHROPIC_SMALL_FAST_MODELdeepseek/deepseek-chat claude想要永久生效Linux 寫進(jìn)~/.bashrc或~/.zshrcWindows 用系統(tǒng)設(shè)置里的環(huán)境變量面板。這里有個(gè)很多人搞混的地方既然網(wǎng)關(guān)地址是 localhost那 ANTHROPIC_AUTH_TOKEN 填什么如果網(wǎng)關(guān)本身沒有額外鑒權(quán)Claude Code 在自定義模式下依然需要一個(gè) token 才不會(huì)報(bào) auth 錯(cuò)誤。最簡(jiǎn)單的做法就是填你后端模型的 Key網(wǎng)關(guān)會(huì)讀這個(gè)字段做轉(zhuǎn)發(fā)或者不細(xì)究它、反正真實(shí)請(qǐng)求到達(dá)后端時(shí)用的是網(wǎng)關(guān) config 里的 api_key。兩種都能跑通。4.3 第三步把配置固化到項(xiàng)目 .claude/settings.json環(huán)境變量寫全局有個(gè)壞處你同時(shí)看好幾個(gè)項(xiàng)目每個(gè)項(xiàng)目想接的模型可能不一樣。官方提供了項(xiàng)目級(jí)配置在項(xiàng)目根目錄創(chuàng)建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: http://localhost:4000, ANTHROPIC_AUTH_TOKEN: sk-你的deepseek key, ANTHROPIC_MODEL: deepseek/deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek/deepseek-chat }, permissions: { defaultMode: acceptEdits } }這個(gè)文件放進(jìn) Git 倉(cāng)庫(kù)后團(tuán)隊(duì)里所有人打開項(xiàng)目都自動(dòng)帶上這套配置不用每個(gè)人都去設(shè)一遍系統(tǒng)環(huán)境變量。這也是我最推薦的實(shí)踐方式比全局 export 干凈得多。4.4 第四步驗(yàn)證請(qǐng)求確實(shí)走到了自定義模型配置完如何確認(rèn)我真的在用 DeepSeek而不是官方模型三種辦法可以交叉驗(yàn)證。第一種進(jìn)入 Claude Code 會(huì)話輸入/status看 Model 行。第二種觀察網(wǎng)關(guān)日志LiteLLM 啟動(dòng)后每次請(qǐng)求都會(huì)打日志能看到請(qǐng)求來自哪個(gè)進(jìn)程、模型名是什么。第三種故意在配置里寫一個(gè)不存在的模型名如果立刻報(bào)錯(cuò)說明請(qǐng)求確實(shí)到達(dá)了你的網(wǎng)關(guān)。我在這一步遇到過最典型的翻車情況是終端里 export 了變量但 VS Code 插件里啟動(dòng)的 Claude Code 沒有讀到。原因是插件啟動(dòng)進(jìn)程時(shí)不一定繼承你的 shell 環(huán)境。所以如果你發(fā)現(xiàn)終端能用、插件不能用優(yōu)先去檢查插件的設(shè)置項(xiàng)或者干脆把環(huán)境變量寫進(jìn).claude/settings.json讓插件自己完整地讀那個(gè)文件。4.5 網(wǎng)關(guān)部署的選型本地跑還是團(tuán)隊(duì)共用自己一個(gè)人折騰本地localhost:4000足夠。但如果是團(tuán)隊(duì)協(xié)作每臺(tái)電腦各跑一個(gè)網(wǎng)關(guān)很浪費(fèi)而且 Key 散落在各人配置里不好管理。更合理的做法是把網(wǎng)關(guān)部署到一臺(tái)服務(wù)器或容器里加一層訪問令牌然后 Claude Code 的ANTHROPIC_BASE_URL指向那臺(tái)服務(wù)器的地址。團(tuán)隊(duì)共用網(wǎng)關(guān)還有一個(gè)好處可以在網(wǎng)關(guān)這一層做模型路由、配額統(tǒng)計(jì)、成本審計(jì)。誰(shuí)用了多少 token、調(diào)用的是哪個(gè)模型日志里全都有。對(duì)負(fù)責(zé)基建的人來說這套體系比讓每個(gè)開發(fā)自己填不同模型的 Key 容易管理得多。5. 接入后的日常使用與進(jìn)階玩法5.1 換模型后要注意的性格差接上 DeepSeek 之后你會(huì)發(fā)現(xiàn) Claude Code 的表現(xiàn)跟官方模型不完全一樣就像團(tuán)隊(duì)里來了個(gè)新實(shí)習(xí)生能力不差但做事風(fēng)格不同。具體表現(xiàn)有哪些官方 Claude 對(duì)工具調(diào)用的遵循非常穩(wěn)定規(guī)劃步驟基本不會(huì)漏部分開源或第三方模型在長(zhǎng)任務(wù)里可能突然忘掉系統(tǒng)提示里的約束或者工具調(diào)用格式偶爾出錯(cuò)。另外不同模型對(duì) CLAUDE.md 指令的執(zhí)行嚴(yán)格度差別很大同一句話在官方模型下會(huì)被嚴(yán)格執(zhí)行在自定義模型下可能被當(dāng)成背景信息忽略掉。所以我的建議是換自定義模型后把任務(wù)拆小一點(diǎn)一次不要讓它干太多事。比如重構(gòu)整個(gè)模塊這種任務(wù)很容易半路失憶不如拆成先梳理依賴再改接口最后跑測(cè)試三個(gè)小步驟。同時(shí)保留 diff 確認(rèn)的習(xí)慣不要在自定義模型下輕易開全自動(dòng)權(quán)限。5.2 權(quán)限模式的選擇與自動(dòng)執(zhí)行邊界Claude Code 有幾種權(quán)限模式理解它們的適用場(chǎng)景能避免不少麻煩。默認(rèn)模式每次執(zhí)行敏感命令前先問你要不要繼續(xù)。acceptEdits自動(dòng)接受文件編輯但執(zhí)行命令仍需確認(rèn)。bypassPermissions什么都不問直接干活。plan模式只出計(jì)劃不動(dòng)手改代碼。在自定義模型場(chǎng)景下我從不開bypassPermissions。原因很簡(jiǎn)單非官方模型對(duì)哪些命令是安全的判斷并不一定可靠。它可能覺得rm -rf沒問題也可能在改配置時(shí)把無關(guān)文件一并動(dòng)掉。保留一個(gè)確認(rèn)環(huán)節(jié)是成本最低的安全策略。5.3 手動(dòng)安裝 GitHub 上的 Skills很多人會(huì)搜claude code 怎么手動(dòng)裝 github 上的 skills。其實(shí) Skill 的本質(zhì)就是一個(gè)目錄里面放一個(gè) SKILL.md 文件用 Markdown 描述這個(gè)技能是干什么的、怎么用再配上一些腳本或資源。手動(dòng)安裝很簡(jiǎn)單。把倉(cāng)庫(kù)克隆到用戶級(jí) skills 目錄mkdir -p ~/.claude/skills git clone skill倉(cāng)庫(kù)地址 ~/.claude/skills/你的技能名項(xiàng)目級(jí)安裝則放到項(xiàng)目根目錄的.claude/skills/下。裝完后重啟 Claude Code 會(huì)話輸入/skills看看技能是否被加載。SKILL.md 的開頭有 YAML front matter基本格式是--- name: 技能名 description: 什么時(shí)候使用這個(gè)技能 ---這里有個(gè)很多人不知道的細(xì)節(jié)description 會(huì)被模型用來做技能檢索。如果描述寫得含糊模型可能永遠(yuǎn)都不會(huì)主動(dòng)調(diào)用它。寫得越具體越好比如當(dāng)用戶要求將項(xiàng)目部署到服務(wù)器時(shí)使用此技能而不是泛泛的部署相關(guān)。5.4 MCP 擴(kuò)展讓 agent 讀寫外部工具M(jìn)CP 是 Claude Code 連接外部工具的標(biāo)準(zhǔn)方式。通過 MCP 服務(wù)器它可以查詢數(shù)據(jù)庫(kù)、調(diào)用瀏覽器、讀寫文件、操作第三方服務(wù)。配置一般放在項(xiàng)目根目錄的.mcp.json里{ mcpServers: { fetch: { command: npx, args: [-y, mcp-server-fetch] } } }配置完成后重啟 Claude Code 它會(huì)自動(dòng)加載并告訴你可用的工具。自定義模型環(huán)境下MCP 有一個(gè)需要特別注意的坑工具返回的數(shù)據(jù)會(huì)占用上下文窗口。如果后端模型窗口比官方模型小一次大表查詢可能直接把上下文塞爆后面的對(duì)話就失憶了。所以接 MCP 后盡量讓查詢帶上明確的 LIMIT 和 WHERE少拉全表。5.5 用 CLAUDE.md 調(diào)教自定義模型Claude Code 啟動(dòng)時(shí)會(huì)自動(dòng)讀項(xiàng)目根目錄的 CLAUDE.md把它作為長(zhǎng)期記憶。這個(gè)文件對(duì)自定義模型的影響很大因?yàn)樗喈?dāng)于唯一穩(wěn)定的人設(shè)說明書。我的寫法一般是四段式# 項(xiàng)目概述 這個(gè)服務(wù)是做什么的、技術(shù)棧、關(guān)鍵目錄結(jié)構(gòu)。 # 常用命令 如何跑測(cè)試、如何啟動(dòng)開發(fā)服務(wù)器、如何構(gòu)建。 # 編碼規(guī)范 命名風(fēng)格、目錄組織、錯(cuò)誤處理約定。 # 需要避免的事 不要?jiǎng)幽男┠夸洝⒉灰哪男┪募?、不要?zhí)行哪些命令。自定義模型對(duì)長(zhǎng)文檔的理解不如官方模型強(qiáng)所以 CLAUDE.md 要短、明確、條目化。超過兩頁(yè)紙的規(guī)范文檔模型大概率會(huì)漏讀后半部分。把最重要的約束放在前幾行比放在末尾管用得多。6. 踩坑記錄我配自定義模型時(shí)的五個(gè)翻車現(xiàn)場(chǎng)6.1 坑一模型不在允許列表請(qǐng)求直接被攔這是我第一次切網(wǎng)關(guān)時(shí)遇到的。配置全都填好啟動(dòng)claude立刻報(bào)錯(cuò)說當(dāng)前模型不在允許列表里。原因是 Claude Code 內(nèi)部有一套模型名校驗(yàn)它認(rèn)識(shí)的名字通常是claude-開頭的。你直接填deepseek/deepseek-chat它會(huì)覺得這是非法模型。解決辦法是給模型取一個(gè)它認(rèn)識(shí)的名字在網(wǎng)關(guān)里把入口模型名配成claude-sonnet-4-20250514實(shí)際轉(zhuǎn)發(fā)到 DeepSeek。LiteLLM 里是這樣改的model_list: - model_name: claude-sonnet-4-20250514 litellm_params: model: deepseek/deepseek-chat api_key: sk-你的deepseek key然后ANTHROPIC_MODEL也填claude-sonnet-4-20250514。這樣 Claude Code 校驗(yàn)通過網(wǎng)關(guān)再把請(qǐng)求轉(zhuǎn)發(fā)給 DeepSeek。6.2 坑二一直轉(zhuǎn)圈 / 網(wǎng)關(guān)返回格式錯(cuò)誤另一種常見現(xiàn)象是 Claude Code 一直轉(zhuǎn)圈沒有任何輸出網(wǎng)關(guān)日志里出現(xiàn) BadRequestError 之類的報(bào)錯(cuò)。我遇到的情況基本都出在工具調(diào)用上。Claude Code 會(huì)用 tools 字段要求模型具備函數(shù)調(diào)用能力如果自定義模型本身不支持 function calling或者返回的工具調(diào)用內(nèi)容格式不規(guī)范兩邊就僵住了。這時(shí)先去網(wǎng)關(guān)的測(cè)試頁(yè)或者寫一個(gè)最小請(qǐng)求驗(yàn)證同一個(gè)模型能否正確返回帶工具調(diào)用的響應(yīng)。確認(rèn)模型支持 function calling 之后再回 Claude Code 重試。如果模型確實(shí)不支持可以考慮換一個(gè)模型版本或者限制 Claude Code 不使用工具——但那樣 agent 能力基本就廢了不太推薦。6.3 坑三上下文被截?cái)嗳蝿?wù)做到一半失憶用某個(gè)模型跑長(zhǎng)任務(wù)時(shí)它突然忘了最初的指令或者開始重復(fù)做已經(jīng)完成的事。剛開始我以為是自己提示詞沒寫好后來才發(fā)現(xiàn)是上下文窗口問題。自定義模型的上下文窗口可能比官方模型小而 Claude Code 默認(rèn)會(huì)維護(hù)一個(gè)比較大的對(duì)話上下文包括讀取過的文件、執(zhí)行過的命令、中間結(jié)果。窗口被塞滿后要么截?cái)嘁磯嚎s但壓縮邏輯是基于 Anthropic 模型設(shè)計(jì)的換到別的模型上表現(xiàn)不一定好。應(yīng)對(duì)方式有三個(gè)。一是縮小任務(wù)的顆粒度每次只讓它處理幾個(gè)文件不要整個(gè)項(xiàng)目一把梭。二是在 CLAUDE.md 里明確寫清不要讀哪些目錄避免無關(guān)文件占用窗口。三是用/compact手動(dòng)壓縮上下文在關(guān)鍵節(jié)點(diǎn)主動(dòng)瘦身而不是等它滿到爆。6.4 坑四VS Code 插件與終端表現(xiàn)不一致終端里 Claude Code 一切正常一用 VS Code 插件就報(bào)Auth error或者模型沒生效這類問題我排查了很久。原因基本是插件執(zhí)行 Claude Code 時(shí)用的環(huán)境變量跟你終端里 export 的不一樣。插件有自己?jiǎn)?dòng)進(jìn)程的方式不一定會(huì)繼承你的 shell profile。解決思路也簡(jiǎn)單不要依賴 export把配置寫進(jìn).claude/settings.json。插件每次啟動(dòng)都會(huì)讀這個(gè)文件里的 env 字段等于給每個(gè)項(xiàng)目綁定了固定的模型和端點(diǎn)繞開了 shell 環(huán)境差異。如果還是不行檢查插件設(shè)置里的 CLI path 是否正確確保它調(diào)用的是你全局安裝的那個(gè)claude。6.5 坑五卸載殘留與重裝陷阱卸載 Claude Code 不是只有一條命令。npm 全局卸載npm uninstall -g anthropic-ai/claude-code但配置和緩存目錄~/.claude不會(huì)自動(dòng)刪除。如果想留 skills 和項(xiàng)目配置可以只刪日志和臨時(shí)文件rm -rf ~/.claude/logs ~/.claude/tmp如果徹底不用了直接刪整個(gè)~/.claude也沒問題。VS Code 插件在擴(kuò)展面板卸載即可卸載后如果還彈身份錯(cuò)誤檢查一下工作區(qū)信任管理里殘留的 Claude Code 授權(quán)記錄。重裝時(shí)有個(gè)我踩過的坑舊版 CLI 沒卸載干凈claude命令指向的還是舊文件新裝的版本始終沒生效。所以重裝前先claude --version確認(rèn)版本號(hào)再執(zhí)行安裝命令。最后說一點(diǎn)個(gè)人體會(huì)。Claude Code 真正值錢的地方不是它某一次回答有多聰明而是它愿意把改動(dòng)方案攤開給你看讓你逐個(gè) diff 確認(rèn)后再?zèng)Q定是否落地。自定義模型的接入本質(zhì)上解決的是模型選型權(quán)問題把 agent 的底模換成你熟悉、可控、便宜的模型代價(jià)是你得自己處理協(xié)議差異和模型質(zhì)量波動(dòng)。我的建議是新手先按官方模型把整個(gè)流程跑通再切自定義模型。這樣出現(xiàn)問題時(shí)你至少能判斷官方能通那問題就出在網(wǎng)關(guān)或模型參數(shù)上而不是在一個(gè)全黑的盒子里猜。