1. 從“caveman”說(shuō)起一個(gè)極簡(jiǎn)代理層為什么值得聊第一次看到“caveman”這個(gè)詞我腦子里蹦出來(lái)的畫(huà)面是原始人拿著石斧敲鍵盤(pán)。但真正讓我停下來(lái)琢磨的是它背后那組關(guān)鍵詞proxy、coding agents、tokens、cli。這幾個(gè)詞湊在一起指向的東西其實(shí)很明確——一個(gè)夾在命令行工具和模型服務(wù)之間的極簡(jiǎn)代理層專(zhuān)門(mén)給寫(xiě)代碼的智能體coding agents省 token、穩(wěn)鏈路、統(tǒng)一出口。說(shuō)白了現(xiàn)在用 CLI 跑 coding agent 的人越來(lái)越多不管是本地起一個(gè)終端助手還是把編輯器里的智能體接到某個(gè)模型端點(diǎn)繞不開(kāi)三件事請(qǐng)求怎么發(fā)出去、token 怎么算、出錯(cuò)怎么查。caveman 這個(gè)項(xiàng)目名字起得很“糙”但糙得有道理——它想做的事情就是把這三件事壓到最薄薄到像原始人一樣只保留最核心的動(dòng)作收請(qǐng)求、轉(zhuǎn)出去、把結(jié)果拿回來(lái)。沒(méi)有花哨的儀表盤(pán)沒(méi)有復(fù)雜的配置樹(shù)就是一個(gè)能跑在本地的小代理。這篇文章適合誰(shuí)看如果你正在用或者準(zhǔn)備用 CLI 形式的 coding agent被 token 消耗速度嚇到過(guò)被各種 404、401、503 報(bào)錯(cuò)折騰過(guò)或者單純想搞清楚“本地代理”到底在整條鏈路里扮演什么角色那這篇就是寫(xiě)給你的。我會(huì)從設(shè)計(jì)思路講到實(shí)操配置再到踩坑排查盡量把每個(gè)選擇背后的“為什么”說(shuō)清楚。不是官方文檔的復(fù)述是我自己折騰這類(lèi)工具時(shí)攢下來(lái)的經(jīng)驗(yàn)。先給個(gè)定調(diào)caveman 這類(lèi)工具的價(jià)值不在于功能多而在于它把“代理”這件事做成了透明的一層。你幾乎感覺(jué)不到它存在但它確實(shí)在幫你省東西——省 token、省排查時(shí)間、省重復(fù)配置的力氣。下面我拆開(kāi)講。2. 整體設(shè)計(jì)思路為什么要在 CLI 和模型之間塞一層代理2.1 直連的問(wèn)題token 浪費(fèi)和鏈路不可控很多人一開(kāi)始用 coding agent 都是直連模型端點(diǎn)的。CLI 工具里填個(gè)地址、填個(gè)密鑰回車(chē)就跑。簡(jiǎn)單是真簡(jiǎn)單但用不了多久問(wèn)題就冒出來(lái)了。最直接的是 token 浪費(fèi)。coding agent 的工作模式和聊天不一樣它會(huì)反復(fù)讀文件、反復(fù)帶上上下文、反復(fù)重試。一個(gè)稍微復(fù)雜點(diǎn)的任務(wù)同一個(gè)文件內(nèi)容可能被塞進(jìn)請(qǐng)求里五六次。直連的情況下這些重復(fù)內(nèi)容每次都實(shí)打?qū)嵉厮沐X(qián)。我實(shí)測(cè)過(guò)一個(gè)中等規(guī)模的重構(gòu)任務(wù)直連跑下來(lái) token 消耗比預(yù)期高了將近三倍其中很大一部分是重復(fù)的上下文。然后是鏈路不可控。CLI 工具本身對(duì)請(qǐng)求的干預(yù)能力很弱你想加個(gè)緩存、想做個(gè)請(qǐng)求合并、想在某個(gè)端點(diǎn)掛了的時(shí)候自動(dòng)切到備用端點(diǎn)直連基本做不到。報(bào)錯(cuò)信息也往往很粗糙一個(gè) 503 甩過(guò)來(lái)你根本不知道是網(wǎng)絡(luò)問(wèn)題、端點(diǎn)限流還是請(qǐng)求本身格式不對(duì)。還有一個(gè)容易被忽略的點(diǎn)多個(gè) CLI 工具各配各的。今天用這個(gè) agent明天換那個(gè) agent每個(gè)都要單獨(dú)填端點(diǎn)、單獨(dú)管密鑰。時(shí)間一長(zhǎng)配置散得到處都是改一個(gè)地方要翻好幾個(gè)文件。2.2 代理層的核心職責(zé)收、轉(zhuǎn)、記、省caveman 這類(lèi)代理層的設(shè)計(jì)邏輯就是把上面這些問(wèn)題集中到一個(gè)地方解決。它的職責(zé)可以拆成四個(gè)動(dòng)作收所有 CLI 工具的請(qǐng)求先打到本地代理由代理統(tǒng)一接收。這樣出口就收斂成一個(gè)配置只需要維護(hù)一份。轉(zhuǎn)代理根據(jù)規(guī)則把請(qǐng)求轉(zhuǎn)發(fā)到真正的模型端點(diǎn)。轉(zhuǎn)發(fā)過(guò)程中可以做端點(diǎn)切換、可以做請(qǐng)求改寫(xiě)、可以加超時(shí)控制。記每個(gè)請(qǐng)求的 token 用量、耗時(shí)、狀態(tài)碼都記下來(lái)。不是為了做花哨的報(bào)表是為了出問(wèn)題的時(shí)候有據(jù)可查。省這是最有價(jià)值的一環(huán)。通過(guò)緩存、去重、上下文裁剪把重復(fù)的 token 消耗壓下去。為什么選擇“本地代理”而不是“云端網(wǎng)關(guān)”因?yàn)?coding agent 的使用場(chǎng)景大多是本地開(kāi)發(fā)請(qǐng)求里經(jīng)常帶著代碼片段甚至整個(gè)文件。走本地代理數(shù)據(jù)不出機(jī)器心理負(fù)擔(dān)小延遲也低。云端網(wǎng)關(guān)雖然功能多但多一跳網(wǎng)絡(luò)、多一份數(shù)據(jù)暴露面對(duì)個(gè)人開(kāi)發(fā)者來(lái)說(shuō)不劃算。2.3 為什么叫 caveman極簡(jiǎn)主義的取舍名字叫 caveman我理解是一種態(tài)度宣示功能可以少但核心鏈路必須穩(wěn)。這類(lèi)工具最容易犯的毛病是越做越重配置項(xiàng)越堆越多最后變成一個(gè)需要專(zhuān)門(mén)學(xué)習(xí)才能用的東西。caveman 反其道而行配置文件盡量扁平啟動(dòng)命令盡量短默認(rèn)行為盡量符合直覺(jué)。這種取舍帶來(lái)的好處是上手快。你不需要讀一長(zhǎng)串文檔才能跑起來(lái)基本是裝完、填個(gè)端點(diǎn)、啟動(dòng)就能用。代價(jià)是高級(jí)功能少比如復(fù)雜的路由規(guī)則、細(xì)粒度的權(quán)限控制它可能不提供。但對(duì)絕大多數(shù)個(gè)人開(kāi)發(fā)者和小團(tuán)隊(duì)來(lái)說(shuō)這些高級(jí)功能本來(lái)就用不上。用 20% 的復(fù)雜度覆蓋 80% 的場(chǎng)景這個(gè)賬算得過(guò)來(lái)。我在選這類(lèi)工具時(shí)有個(gè)習(xí)慣先看它的默認(rèn)配置能不能直接跑。如果一個(gè)工具裝完還要改十幾個(gè)地方才能用我基本就放棄了。caveman 在這點(diǎn)上做得不錯(cuò)默認(rèn)配置的可用性很高這點(diǎn)后面實(shí)操部分會(huì)細(xì)說(shuō)。3. 核心細(xì)節(jié)解析token 節(jié)省、請(qǐng)求轉(zhuǎn)發(fā)與 CLI 集成3.1 token 是怎么被省下來(lái)的token 節(jié)省不是靠某個(gè)魔法開(kāi)關(guān)而是靠幾個(gè)具體機(jī)制疊加。我把常見(jiàn)的幾種拆開(kāi)講你可以對(duì)照自己的使用場(chǎng)景看哪些能用上。第一種是響應(yīng)緩存。coding agent 有個(gè)特點(diǎn)它會(huì)反復(fù)問(wèn)類(lèi)似的問(wèn)題。比如“這個(gè)文件的第 30 行是什么”第一次問(wèn)完過(guò)一會(huì)兒可能又問(wèn)一遍。如果代理層能識(shí)別出相同或高度相似的請(qǐng)求直接返回緩存結(jié)果這次請(qǐng)求的 token 就完全省了。實(shí)現(xiàn)上一般用請(qǐng)求體的哈希做 key命中就返回。要注意的是緩存要有過(guò)期策略代碼改了之后舊緩存必須失效否則會(huì)返回錯(cuò)誤內(nèi)容。第二種是上下文去重。一個(gè)請(qǐng)求里如果同一段代碼出現(xiàn)了多次代理可以在轉(zhuǎn)發(fā)前把它壓成一次。這個(gè)操作有風(fēng)險(xiǎn)因?yàn)橛行┠Ｐ蛯?duì)上下文順序敏感去重可能改變語(yǔ)義。所以一般只對(duì)明確重復(fù)的大塊內(nèi)容做處理比如完全相同的文件片段。第三種是請(qǐng)求合并。短時(shí)間內(nèi)多個(gè)小請(qǐng)求如果它們的目標(biāo)端點(diǎn)相同、參數(shù)兼容可以合并成一個(gè)大請(qǐng)求發(fā)出去減少往返開(kāi)銷(xiāo)。這個(gè)對(duì) token 的直接節(jié)省不明顯但能降低請(qǐng)求次數(shù)間接省錢(qián)。第四種是端點(diǎn)選擇。不同端點(diǎn)的計(jì)費(fèi)方式不一樣有的按輸入輸出分開(kāi)算有的有免費(fèi)額度。代理層可以根據(jù)請(qǐng)求特征選擇更劃算的端點(diǎn)。這個(gè)需要你對(duì)各個(gè)端點(diǎn)的計(jì)費(fèi)規(guī)則比較清楚配置起來(lái)也麻煩一些屬于進(jìn)階用法。我自己的經(jīng)驗(yàn)是緩存和去重這兩招最實(shí)用配置簡(jiǎn)單效果立竿見(jiàn)影。請(qǐng)求合并和端點(diǎn)選擇屬于錦上添花場(chǎng)景合適再用。3.2 請(qǐng)求轉(zhuǎn)發(fā)的關(guān)鍵參數(shù)代理轉(zhuǎn)發(fā)請(qǐng)求時(shí)有幾個(gè)參數(shù)必須搞清楚不然很容易出問(wèn)題。超時(shí)時(shí)間是最容易踩坑的。設(shè)太短稍微大一點(diǎn)的請(qǐng)求就超時(shí)設(shè)太長(zhǎng)端點(diǎn)掛了你要等很久才知道。我的建議是分兩級(jí)連接超時(shí)設(shè)短一點(diǎn)比如 5 秒因?yàn)檫B不上就是連不上等再久也沒(méi)用讀取超時(shí)設(shè)長(zhǎng)一點(diǎn)比如 120 秒給模型生成留足時(shí)間。這兩個(gè)值在配置文件里通常是分開(kāi)的。重試策略也要想清楚。不是所有錯(cuò)誤都值得重試。網(wǎng)絡(luò)抖動(dòng)、端點(diǎn)臨時(shí) 503這些重試有意義401 未授權(quán)、404 找不到端點(diǎn)重試多少次都一樣。所以重試要按狀態(tài)碼分類(lèi)只對(duì)可恢復(fù)的錯(cuò)誤重試并且要有退避不能一秒鐘重試十次把端點(diǎn)打掛。請(qǐng)求頭處理是個(gè)細(xì)節(jié)活。CLI 工具發(fā)過(guò)來(lái)的請(qǐng)求頭里有些需要保留有些需要改寫(xiě)有些需要?jiǎng)h掉。比如認(rèn)證頭代理可能要替換成自己的密鑰比如 User-Agent可能需要統(tǒng)一成一個(gè)值方便端點(diǎn)識(shí)別。這塊配置錯(cuò)了表現(xiàn)就是各種 401、403排查起來(lái)很煩。下面這張表是我整理的常見(jiàn)參數(shù)和推薦值可以直接參考參數(shù)推薦值說(shuō)明連接超時(shí)5s連不上快速失敗讀取超時(shí)120s給生成留時(shí)間最大重試次數(shù)3避免無(wú)限重試重試退避基數(shù)1s指數(shù)退避起點(diǎn)緩存過(guò)期300s代碼場(chǎng)景不宜過(guò)長(zhǎng)最大請(qǐng)求體10MB防止異常大請(qǐng)求3.3 CLI 工具怎么接進(jìn)來(lái)CLI 工具接代理核心就一件事把工具原本指向模型端點(diǎn)的地址改成指向本地代理的地址。大部分 CLI 工具都支持通過(guò)環(huán)境變量或者配置文件指定端點(diǎn)改起來(lái)不難。以常見(jiàn)的 coding agent CLI 為例一般有這么幾種接入方式環(huán)境變量方式設(shè)置類(lèi)似API_BASE_URL或OPENAI_BASE_URL的變量指向http://127.0.0.1:端口。這種方式最干凈不改工具本身。配置文件方式在工具的配置里找到端點(diǎn)字段改成代理地址。適合不支持環(huán)境變量的工具。命令行參數(shù)方式啟動(dòng)時(shí)加參數(shù)指定端點(diǎn)。適合臨時(shí)切換。我一般優(yōu)先用環(huán)境變量因?yàn)榍袚Q方便而且不會(huì)污染工具的配置文件。多個(gè)工具可以共用同一套環(huán)境變量改一處全生效。要注意的是有些 CLI 工具會(huì)對(duì)端點(diǎn)地址做校驗(yàn)比如要求必須是 https。這時(shí)候本地代理要么配個(gè)自簽證書(shū)走 https要么看工具是否支持關(guān)閉校驗(yàn)。自簽證書(shū)在本地用問(wèn)題不大但要注意別把證書(shū)提交到代碼倉(cāng)庫(kù)里。4. 實(shí)操過(guò)程從零把 caveman 跑起來(lái)4.1 環(huán)境準(zhǔn)備與安裝先把基礎(chǔ)環(huán)境理清楚。這類(lèi)工具通常需要 Node.js 或者 Go 的運(yùn)行環(huán)境具體看項(xiàng)目實(shí)現(xiàn)。我這邊以 Node.js 環(huán)境為例因?yàn)榇蟛糠?CLI 工具生態(tài)都在 Node 上。第一步確認(rèn) Node 版本。太老的版本會(huì)有兼容問(wèn)題建議 18 以上。用node -v看一眼如果低于 18先升級(jí)。升級(jí)方式看你的系統(tǒng)用版本管理工具會(huì)比較省心。第二步安裝 caveman。如果它發(fā)布在包管理平臺(tái)上直接全局安裝即可。安裝慢的話可以配置鏡像源這個(gè)后面問(wèn)題排查部分會(huì)講。# 確認(rèn) Node 版本 node -v # 全局安裝 npm install -g caveman # 驗(yàn)證安裝 caveman --version第三步準(zhǔn)備配置文件。大部分這類(lèi)工具會(huì)在用戶目錄下找配置文件比如~/.caveman/config.json或者類(lèi)似路徑。第一次跑可以先不寫(xiě)配置看它有沒(méi)有默認(rèn)配置或者初始化命令。提示安裝前先看一眼項(xiàng)目的 README確認(rèn)它支持的 Node 版本范圍和依賴避免裝完跑不起來(lái)。4.2 配置文件怎么寫(xiě)配置文件是這類(lèi)工具的核心。我以一個(gè)典型的代理配置為例講清楚每個(gè)字段的作用。{ listen: { host: 127.0.0.1, port: 8787 }, upstreams: [ { name: primary, baseUrl: https://api.example.com/v1, apiKey: your-key-here, timeout: { connect: 5000, read: 120000 } } ], cache: { enabled: true, ttl: 300, maxSize: 100 }, retry: { maxAttempts: 3, backoffBase: 1000 } }逐段解釋一下。listen是代理自己監(jiān)聽(tīng)的地址和端口本地用127.0.0.1就行不要監(jiān)聽(tīng)0.0.0.0避免局域網(wǎng)里其他機(jī)器能訪問(wèn)到。端口選一個(gè)不常用的8787 只是示例你可以換成任何沒(méi)被占用的端口。upstreams是上游端點(diǎn)列表。可以配多個(gè)代理會(huì)按順序或者按規(guī)則選擇。每個(gè)端點(diǎn)有名字、地址、密鑰和超時(shí)設(shè)置。密鑰這塊要注意別把真實(shí)密鑰寫(xiě)進(jìn)會(huì)提交到倉(cāng)庫(kù)的文件里用環(huán)境變量引用更安全。cache是緩存配置。enabled開(kāi)關(guān)ttl是過(guò)期秒數(shù)maxSize是緩存條數(shù)上限。代碼場(chǎng)景我建議 ttl 不要設(shè)太長(zhǎng)300 秒差不多因?yàn)榇a改得快緩存太舊會(huì)返回錯(cuò)誤內(nèi)容。retry是重試配置。maxAttempts是最大嘗試次數(shù)包含第一次所以 3 表示最多重試 2 次。backoffBase是退避基數(shù)單位毫秒實(shí)際等待時(shí)間會(huì)按指數(shù)增長(zhǎng)。4.3 啟動(dòng)與驗(yàn)證配置寫(xiě)好之后啟動(dòng)代理。啟動(dòng)命令一般就是caveman start或者直接caveman看具體實(shí)現(xiàn)。啟動(dòng)后應(yīng)該能看到日志輸出顯示監(jiān)聽(tīng)的地址和加載的端點(diǎn)。# 啟動(dòng)代理 caveman start --config ~/.caveman/config.json # 另開(kāi)一個(gè)終端測(cè)試代理是否響應(yīng) curl http://127.0.0.1:8787/health/health這類(lèi)健康檢查端點(diǎn)不是所有工具都有如果沒(méi)有可以直接發(fā)一個(gè)測(cè)試請(qǐng)求看返回。測(cè)試請(qǐng)求建議用一個(gè)最簡(jiǎn)單的模型調(diào)用確認(rèn)整條鏈路通了。驗(yàn)證的時(shí)候重點(diǎn)看三件事代理有沒(méi)有正常啟動(dòng)、請(qǐng)求能不能轉(zhuǎn)發(fā)到上游、返回結(jié)果是不是符合預(yù)期。如果代理啟動(dòng)了但請(qǐng)求失敗先看代理日志再看上游端點(diǎn)是否可達(dá)。4.4 把 CLI 工具接上代理代理跑起來(lái)之后把 CLI 工具的端點(diǎn)指向它。以環(huán)境變量方式為例# 設(shè)置端點(diǎn)指向本地代理 export OPENAI_BASE_URLhttp://127.0.0.1:8787/v1 # 設(shè)置一個(gè)占位密鑰真實(shí)密鑰在代理配置里 export OPENAI_API_KEYplaceholder # 啟動(dòng)你的 coding agent CLI your-agent-cli這里有個(gè)細(xì)節(jié)CLI 工具通常會(huì)校驗(yàn)密鑰格式所以即使真實(shí)密鑰在代理里這里也要填一個(gè)看起來(lái)像密鑰的占位值不能留空。代理收到請(qǐng)求后會(huì)把認(rèn)證頭替換成真實(shí)密鑰再轉(zhuǎn)發(fā)。接上之后跑一個(gè)實(shí)際任務(wù)驗(yàn)證。建議先用小任務(wù)比如讓 agent 讀一個(gè)文件、改一行代碼確認(rèn)整條鏈路通了再上大任務(wù)。跑的時(shí)候盯著代理日志看請(qǐng)求有沒(méi)有正常轉(zhuǎn)發(fā)、token 用量是多少、有沒(méi)有命中緩存。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 那些讓人頭大的狀態(tài)碼用這類(lèi)代理報(bào)錯(cuò)是家常便飯。我把常見(jiàn)的狀態(tài)碼和排查思路整理成一張表遇到問(wèn)題直接對(duì)照。狀態(tài)碼常見(jiàn)原因排查方向401密鑰無(wú)效或未替換檢查代理配置里的密鑰、檢查認(rèn)證頭替換規(guī)則404端點(diǎn)路徑不對(duì)檢查 baseUrl 是否包含正確的路徑前綴503上游過(guò)載或維護(hù)檢查上游狀態(tài)、啟用重試或切換端點(diǎn)超時(shí)讀取超時(shí)太短調(diào)大 read 超時(shí)、檢查網(wǎng)絡(luò)連接拒絕代理沒(méi)啟動(dòng)或端口錯(cuò)檢查代理進(jìn)程、檢查端口占用401 是最常見(jiàn)的。表現(xiàn)是代理日志里顯示請(qǐng)求發(fā)出去了但上游返回未授權(quán)。原因通常是代理沒(méi)有正確替換認(rèn)證頭或者配置里的密鑰本身就是錯(cuò)的。排查時(shí)先把代理日志的請(qǐng)求頭打出來(lái)看確認(rèn)認(rèn)證頭有沒(méi)有被替換成正確的值。404 也很多。很多時(shí)候是 baseUrl 寫(xiě)錯(cuò)了比如少了個(gè)/v1或者多了個(gè)斜杠。不同端點(diǎn)的路徑規(guī)范不一樣要對(duì)著文檔確認(rèn)。還有一種情況是 CLI 工具自己拼路徑的方式和代理預(yù)期的不一樣這種要看代理有沒(méi)有路徑重寫(xiě)功能。503 一般是上游的問(wèn)題不是你的配置問(wèn)題。這時(shí)候重試和端點(diǎn)切換就派上用場(chǎng)了。如果配了多個(gè)上游代理應(yīng)該能自動(dòng)切到可用的那個(gè)。5.2 安裝慢和依賴問(wèn)題CLI 工具安裝慢是高頻問(wèn)題尤其是從默認(rèn)源拉包的時(shí)候。解決辦法是換鏡像源。Node 生態(tài)換源很簡(jiǎn)單一條命令的事。# 查看當(dāng)前源 npm config get registry # 換成國(guó)內(nèi)鏡像 npm config set registry https://registry.npmmirror.com # 裝完可以換回來(lái) npm config set registry https://registry.npmjs.org換源之后安裝速度通常能快好幾倍。如果還是慢可能是網(wǎng)絡(luò)本身的問(wèn)題或者包體積太大。這時(shí)候可以試試只裝核心包或者用離線安裝包。依賴沖突是另一個(gè)坑。有些 CLI 工具依賴的包版本比較老和你系統(tǒng)里已有的包沖突。表現(xiàn)是安裝報(bào)錯(cuò)或者裝完跑不起來(lái)。解決辦法是用獨(dú)立的 Node 版本管理工具給這個(gè)工具單獨(dú)開(kāi)一個(gè)環(huán)境避免污染全局。5.3 緩存導(dǎo)致的詭異問(wèn)題緩存是個(gè)雙刃劍。用好了省 token用不好會(huì)返回過(guò)期內(nèi)容讓你懷疑人生。我踩過(guò)的最坑的一次是改完代碼讓 agent 重新分析結(jié)果它返回的還是改之前的內(nèi)容。查了半天才發(fā)現(xiàn)是代理緩存沒(méi)失效。避免這類(lèi)問(wèn)題有幾個(gè)辦法。一是把 ttl 設(shè)短代碼場(chǎng)景 300 秒甚至更短。二是給緩存加版本標(biāo)識(shí)代碼變更時(shí)手動(dòng)清緩存。三是只對(duì)明確的只讀請(qǐng)求開(kāi)緩存涉及寫(xiě)操作的請(qǐng)求不走緩存。注意調(diào)試階段建議先把緩存關(guān)掉確認(rèn)鏈路本身沒(méi)問(wèn)題之后再開(kāi)緩存。不然出了問(wèn)題你分不清是鏈路問(wèn)題還是緩存問(wèn)題。5.4 端口占用和進(jìn)程殘留代理啟動(dòng)失敗十有八九是端口被占了。查端口占用的命令看系統(tǒng)Linux 和 macOS 用lsof -i :端口Windows 用netstat -ano | findstr 端口。找到占用進(jìn)程之后要么殺掉它要么換個(gè)端口。進(jìn)程殘留是另一個(gè)煩人的問(wèn)題。代理沒(méi)正常退出后臺(tái)還留著進(jìn)程下次啟動(dòng)就報(bào)端口占用。解決辦法是啟動(dòng)前先檢查有沒(méi)有同名進(jìn)程在跑有就先清理。有些工具提供了stop命令優(yōu)先用它比手動(dòng)殺進(jìn)程干凈。# 查端口占用Linux/macOS lsof -i :8787 # 查進(jìn)程 ps aux | grep caveman # 清理殘留進(jìn)程 pkill -f caveman5.5 日志怎么看才有用日志是排查問(wèn)題的核心但很多人不會(huì)看。我的習(xí)慣是分三層看代理層日志、上游響應(yīng)日志、CLI 工具日志。代理層日志告訴你請(qǐng)求有沒(méi)有進(jìn)來(lái)、有沒(méi)有轉(zhuǎn)發(fā)出去、轉(zhuǎn)發(fā)到了哪個(gè)端點(diǎn)。上游響應(yīng)日志告訴你端點(diǎn)返回了什么狀態(tài)碼、什么錯(cuò)誤信息。CLI 工具日志告訴你工具本身有沒(méi)有問(wèn)題。排查時(shí)從代理層開(kāi)始確認(rèn)請(qǐng)求進(jìn)來(lái)了再看轉(zhuǎn)發(fā)出去沒(méi)有。如果請(qǐng)求進(jìn)來(lái)了但沒(méi)轉(zhuǎn)發(fā)問(wèn)題在代理配置如果轉(zhuǎn)發(fā)出去但返回錯(cuò)誤問(wèn)題在上游或請(qǐng)求內(nèi)容如果代理層一切正常但 CLI 還是報(bào)錯(cuò)問(wèn)題可能在 CLI 工具本身。日志級(jí)別也要會(huì)調(diào)。平時(shí)用 info 級(jí)別就夠排查問(wèn)題時(shí)臨時(shí)調(diào)到 debug能看到請(qǐng)求體和響應(yīng)體的細(xì)節(jié)。但要注意 debug 日志可能包含敏感信息排查完記得調(diào)回去別把帶密鑰的日志留在磁盤(pán)上。6. 一些實(shí)操心得和后續(xù)擴(kuò)展方向折騰這類(lèi)工具久了有幾個(gè)體會(huì)比較深。第一個(gè)是配置要版本化。代理配置里有很多調(diào)優(yōu)參數(shù)改來(lái)改去很容易忘記哪個(gè)版本好用。我習(xí)慣把配置文件也納入版本管理每次調(diào)整都記一筆出問(wèn)題能快速回滾。密鑰這種敏感信息用環(huán)境變量引用不寫(xiě)進(jìn)文件。第二個(gè)是別追求一步到位。一開(kāi)始就把所有高級(jí)功能都配上出了問(wèn)題根本不知道是哪塊導(dǎo)致的。我的做法是先跑通最簡(jiǎn)鏈路確認(rèn)能用再一個(gè)一個(gè)加功能每加一個(gè)驗(yàn)證一次。這樣出問(wèn)題范圍小好定位。第三個(gè)是關(guān)注 token 用量的變化趨勢(shì)。代理層記錄的數(shù)據(jù)別浪費(fèi)定期看一眼。如果某個(gè)任務(wù)的 token 消耗突然漲了可能是緩存失效了也可能是 agent 的行為變了。早發(fā)現(xiàn)早處理別等到賬單出來(lái)才后悔。后續(xù)如果想擴(kuò)展有幾個(gè)方向可以考慮。一是加多端點(diǎn)負(fù)載均衡把請(qǐng)求分散到多個(gè)端點(diǎn)提高可用性。二是加請(qǐng)求內(nèi)容分析自動(dòng)識(shí)別哪些請(qǐng)求可以走更便宜的端點(diǎn)。三是把代理層和本地的代碼索引結(jié)合起來(lái)讓 agent 請(qǐng)求上下文的時(shí)候直接從索引取減少重復(fù)讀取。這些都屬于進(jìn)階玩法等基礎(chǔ)鏈路跑穩(wěn)了再折騰。最后分享一個(gè)小技巧代理啟動(dòng)之后先用一個(gè)固定的測(cè)試請(qǐng)求跑一遍把返回結(jié)果存下來(lái)作為基線。以后每次改配置都跑一遍這個(gè)測(cè)試請(qǐng)求對(duì)比結(jié)果有沒(méi)有變化。這個(gè)習(xí)慣幫我省了很多排查時(shí)間尤其是改緩存和重試配置的時(shí)候一眼就能看出有沒(méi)有改壞。