關(guān)調(diào)試實(shí)戰(zhàn)：--debug 日志模式與 --no-truncate 完整輸出機(jī)制解析)
PicoClaw 網(wǎng)關(guān)調(diào)試實(shí)戰(zhàn)--debug 日志模式與 --no-truncate 完整輸出機(jī)制解析【免費(fèi)下載鏈接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity項(xiàng)目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 對(duì)每條收到的請(qǐng)求都會(huì)在后臺(tái)執(zhí)行多次復(fù)雜交互——從消息路由、復(fù)雜度評(píng)估到工具執(zhí)行與模型故障自適應(yīng)。想要定位問題甚至真正理解 Agent 的工作方式就必須看清內(nèi)部究竟發(fā)生了什么。本文基于 PicoClaw 官方調(diào)試文檔docs/operations/debug.fr.md完整講解gateway命令的--debug-d與--no-truncate-T兩個(gè)調(diào)試?yán)靼ㄋ鼈兊膯?dòng)方式、日志格式化行為、全局截?cái)鄼C(jī)制的底層實(shí)現(xiàn)以及如何結(jié)合配置文件精準(zhǔn)控制日志級(jí)別幫助你在排障時(shí)拿到完整、真實(shí)的運(yùn)行證據(jù)。一、為什么需要調(diào)試模式看清 Agent 的內(nèi)部運(yùn)轉(zhuǎn)PicoClaw 網(wǎng)關(guān)gateway是一個(gè)單進(jìn)程常駐的運(yùn)行時(shí)它承載著消息路由、復(fù)雜度評(píng)估、工具調(diào)用、上下文構(gòu)建、模型降級(jí)容錯(cuò)等一系列邏輯。在默認(rèn)日志級(jí)別配置文件默認(rèn)為fatal即僅在致命錯(cuò)誤時(shí)輸出下Agent 內(nèi)部發(fā)生的絕大多數(shù)事情對(duì)你是不可見的。調(diào)試模式的直接收益包括查看每次 LLM 請(qǐng)求的細(xì)節(jié)系統(tǒng)提示詞System Prompt、發(fā)送給提供商的完整消息結(jié)構(gòu)跟蹤工具調(diào)用exec、web_fetch、read_file等工具被調(diào)用的參數(shù)與結(jié)果觀察消息路由消息如何在通道、Agent 與模型之間流轉(zhuǎn)理解上下文構(gòu)建系統(tǒng)提示詞的長度統(tǒng)計(jì)、緩存命中情況、會(huì)話歷史如何被組裝。這些信息不僅是排障依據(jù)也是學(xué)習(xí) PicoClaw 架構(gòu)的最佳入口。二、以調(diào)試模式啟動(dòng)網(wǎng)關(guān)啟動(dòng)調(diào)試模式只需為gateway子命令添加--debug標(biāo)志它有一個(gè)等價(jià)的短標(biāo)志-dpicoclaw gateway --debug # 或使用短標(biāo)志 picoclaw gateway -d在該模式下系統(tǒng)會(huì)以詳細(xì)格式輸出日志并展示系統(tǒng)提示詞與工具執(zhí)行結(jié)果的預(yù)覽片段。啟動(dòng)時(shí)終端會(huì)直接打印一行提示 Debug mode enabled。從源碼實(shí)現(xiàn)看--debug的作用鏈路非常清晰gateway 命令定義 將debug聲明為布爾標(biāo)志隨后在 gateway.Run 中執(zhí)行if debug { logger.SetLevel(logger.DEBUG) } else { logger.SetLevelFromString(config.ResolveGatewayLogLevel(configPath)) }也就是說--debug會(huì)把日志級(jí)別強(qiáng)制提升為DEBUG并且如 gateway.go 注釋 所說明的調(diào)試模式會(huì)永久覆蓋配置中的日志級(jí)別——即使你隨后熱重載了配置配置熱重載由 handleConfigReload 處理debug標(biāo)志仍然生效除非重啟網(wǎng)關(guān)。日志系統(tǒng)基于 zerolog 實(shí)現(xiàn)DEBUG 級(jí)別定義為最低級(jí)別pkg/logger/logger.go。調(diào)試模式下你能看到的典型輸出結(jié)合源碼中的日志埋點(diǎn)--debug模式下會(huì)輸出諸如系統(tǒng)提示詞構(gòu)建摘要pkg/agent/context.go 記錄靜態(tài)部分字符數(shù)、動(dòng)態(tài)部分字符數(shù)、總字符數(shù)、是否有摘要、覆蓋層數(shù)量以及是否命中緩存系統(tǒng)提示詞預(yù)覽pkg/agent/context.go 輸出截?cái)嗪蟮?prompt 預(yù)覽默認(rèn)截?cái)嗟?500 字符工具調(diào)用記錄pkg/agent/pipeline_execute.go 以Tool call: 工具名(參數(shù)JSON預(yù)覽)的格式輸出每一次工具調(diào)用最終響應(yīng)預(yù)覽pkg/agent/agent.go 輸出截?cái)嗟?120 字符的最終回復(fù)預(yù)覽。這些預(yù)覽恰好說明了為什么需要下一節(jié)的--no-truncate——默認(rèn)情況下所有長內(nèi)容都會(huì)被截?cái)嘁员３纸K端可讀。三、關(guān)閉日志截?cái)?-no-truncate默認(rèn)情況下PicoClaw 會(huì)對(duì)調(diào)試日志中超長的字符串如龐大的系統(tǒng)提示詞或大體積 JSON 結(jié)果進(jìn)行截?cái)嘁员ＷC控制臺(tái)可讀。當(dāng)你需要檢查某個(gè)命令的完整輸出或需要核對(duì)發(fā)送給 LLM 提供商的精確 payload 時(shí)請(qǐng)使用--no-truncatepicoclaw gateway --debug --no-truncate重要約束--no-truncate只能與--debug組合使用單獨(dú)使用時(shí)網(wǎng)關(guān)會(huì)直接報(bào)錯(cuò)并拒絕啟動(dòng)。底層實(shí)現(xiàn)全局截?cái)嚅_關(guān)--no-truncate的實(shí)現(xiàn)是一個(gè)進(jìn)程級(jí)全局開關(guān)。gateway 命令的 PreRunE 鉤子 做了兩件事校驗(yàn)noTruncate必須伴隨debug否則返回錯(cuò)誤the --no-truncate option can only be used in conjunction with --debug (-d)通過utils.SetDisableTruncation(true)打開全局開關(guān)并記錄日志String truncation is globally disabled via no-truncate flag。開關(guān)本身定義在 pkg/utils/string.go使用原子布爾值保證并發(fā)安全var disableTruncation atomic.Bool func SetDisableTruncation(enabled bool) { disableTruncation.Store(enabled) }而所有日志截?cái)嘧罱K都匯聚到同一個(gè) Truncate 函數(shù)func Truncate(s string, maxLen int) string { // If the no-truncate flag is active, it returns the full string if disableTruncation.Load() { return s } ... }當(dāng)開關(guān)開啟后Truncate直接原樣返回完整字符串不再追加省略號(hào)。由于所有日志預(yù)覽系統(tǒng)提示詞預(yù)覽、工具參數(shù)預(yù)覽、響應(yīng)預(yù)覽都經(jīng)由該函數(shù)處理因此--no-truncate會(huì)一次性全局禁用所有位置的截?cái)喽侵蛔饔糜谀骋粭l日志。該標(biāo)志的三個(gè)典型使用場(chǎng)景官方文檔明確列出了--no-truncate最有價(jià)值的三個(gè)場(chǎng)景核對(duì)發(fā)送給提供商的精確消息語法確認(rèn)請(qǐng)求 payload 的 JSON 結(jié)構(gòu)、字段順序與轉(zhuǎn)義是否正確讀取完整工具輸出exec、web_fetch、read_file等工具返回的超長內(nèi)容不再被截?cái)喾奖銠z查命令真實(shí)輸出調(diào)試內(nèi)存中保存的會(huì)話歷史完整查看被組裝進(jìn)上下文的歷史消息驗(yàn)證會(huì)話拼接邏輯是否符合預(yù)期。命令行參數(shù)的補(bǔ)充信息gateway命令還支持其他標(biāo)志可在調(diào)試時(shí)一并使用標(biāo)志短標(biāo)志說明--debug-d開啟調(diào)試日志DEBUG 級(jí)別--no-truncate-T全局禁用調(diào)試日志中的字符串截?cái)鄡H在與--debug組合時(shí)有效--allow-empty-E即使未配置默認(rèn)模型也繼續(xù)啟動(dòng)網(wǎng)關(guān)--host—覆蓋本次運(yùn)行的網(wǎng)關(guān)綁定地址會(huì)寫入gateway.host對(duì)應(yīng)的環(huán)境變量這些標(biāo)志的定義與校驗(yàn)邏輯均可從 cmd/picoclaw/internal/gateway/command.go 與配套測(cè)試 command_test.go 中核實(shí)。四、配置層面的日志級(jí)別控制非調(diào)試模式除了命令行標(biāo)志PicoClaw 還支持通過配置文件控制網(wǎng)關(guān)日志級(jí)別。在 config/config.example.json 中g(shù)ateway節(jié)點(diǎn)包含如下字段gateway: { _comment: Default log level is set to fatal. Other available options are debug, info, warn and error., host: localhost, port: 18790, hot_reload: false, log_level: fatal }log_level支持debug、info、warn、error、fatal五個(gè)取值。需要留意的是默認(rèn)值是fatal這意味著不顯式配置時(shí)普通日志幾乎全部被抑制——這也正是看不到內(nèi)部發(fā)生了什么的根源在非調(diào)試模式下網(wǎng)關(guān)啟動(dòng)時(shí)會(huì)讀取該配置并設(shè)置日志級(jí)別pkg/gateway/gateway.go 與 pkg/gateway/gateway.go配置熱重載時(shí)也會(huì)同步更新日志級(jí)別pkg/gateway/gateway.go且日志級(jí)別更新放在最后避免重載過程中的 info/warn 日志被抑制--debug標(biāo)志的優(yōu)先級(jí)高于配置文件只要啟動(dòng)時(shí)帶了--debug無論log_level配置成什么都會(huì)強(qiáng)制進(jìn)入 DEBUG 級(jí)別。實(shí)際排障中你可以把gateway.log_level臨時(shí)改為debug并熱重載配置hot_reload開啟時(shí)從而在不重啟進(jìn)程的情況下獲取 DEBUG 日志若需要看清全部細(xì)節(jié)不被截?cái)鄤t仍需以--debug --no-truncate方式重啟網(wǎng)關(guān)。五、相關(guān)閱讀與延伸完整配置文件字段說明見 config/config.example.json其中agents.defaults.tool_feedback.max_args_length等字段默認(rèn) 300 字符見 pkg/config/config.go與日志中工具參數(shù)預(yù)覽長度直接相關(guān)網(wǎng)關(guān)熱重載、端口綁定等運(yùn)行時(shí)行為的代碼入口在 pkg/gateway/gateway.go如果你需要排查連接、鑒權(quán)或消息收發(fā)問題可進(jìn)一步閱讀 docs/operations/troubleshooting.zh.md如果涉及 Docker 部署下的日志查看參考 docs/guides/docker.zh.md項(xiàng)目總覽與快速上手可回到 README.md 或 docs/project/README.zh.md。小結(jié)picoclaw gateway --debug讓你看到 Agent 的每一步動(dòng)作--no-truncate則把被截?cái)嗟募?xì)節(jié)完整還原出來。二者配合配合配置文件中的gateway.log_level可以覆蓋從日常觀察、問題定位到 payload 級(jí)核對(duì)的全部調(diào)試需求——這是深入理解 PicoClaw 運(yùn)行時(shí)機(jī)制最直接的一條路徑?！久赓M(fèi)下載鏈接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity項(xiàng)目地址: https://gitcode.com/gh_mirrors/pi/picoclaw創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 PicoClaw 網(wǎng)關(guān)調(diào)試實(shí)戰(zhàn)：--debug 日志模式與 --no-truncate 完整輸出機(jī)制解析
PicoClaw 網(wǎng)關(guān)調(diào)試實(shí)戰(zhàn)--debug 日志模式與 --no-truncate 完整輸出機(jī)制解析【免費(fèi)下載鏈接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity項(xiàng)目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 對(duì)每條收到的請(qǐng)求都會(huì)在后臺(tái)執(zhí)行多次復(fù)雜交互——從消息路由、復(fù)雜度評(píng)估到工具執(zhí)行與模型故障自適應(yīng)。想要定位問題甚至真正理解 Agent 的工作方式就必須看清內(nèi)部究竟發(fā)生了什么。本文基于 PicoClaw 官方調(diào)試文檔docs/operations/debug.fr.md完整講解gateway命令的--debug-d與--no-truncate-T兩個(gè)調(diào)試?yán)靼ㄋ鼈兊膯?dòng)方式、日志格式化行為、全局截?cái)鄼C(jī)制的底層實(shí)現(xiàn)以及如何結(jié)合配置文件精準(zhǔn)控制日志級(jí)別幫助你在排障時(shí)拿到完整、真實(shí)的運(yùn)行證據(jù)。一、為什么需要調(diào)試模式看清 Agent 的內(nèi)部運(yùn)轉(zhuǎn)PicoClaw 網(wǎng)關(guān)gateway是一個(gè)單進(jìn)程常駐的運(yùn)行時(shí)它承載著消息路由、復(fù)雜度評(píng)估、工具調(diào)用、上下文構(gòu)建、模型降級(jí)容錯(cuò)等一系列邏輯。在默認(rèn)日志級(jí)別配置文件默認(rèn)為fatal即僅在致命錯(cuò)誤時(shí)輸出下Agent 內(nèi)部發(fā)生的絕大多數(shù)事情對(duì)你是不可見的。調(diào)試模式的直接收益包括查看每次 LLM 請(qǐng)求的細(xì)節(jié)系統(tǒng)提示詞System Prompt、發(fā)送給提供商的完整消息結(jié)構(gòu)跟蹤工具調(diào)用exec、web_fetch、read_file等工具被調(diào)用的參數(shù)與結(jié)果觀察消息路由消息如何在通道、Agent 與模型之間流轉(zhuǎn)理解上下文構(gòu)建系統(tǒng)提示詞的長度統(tǒng)計(jì)、緩存命中情況、會(huì)話歷史如何被組裝。這些信息不僅是排障依據(jù)也是學(xué)習(xí) PicoClaw 架構(gòu)的最佳入口。二、以調(diào)試模式啟動(dòng)網(wǎng)關(guān)啟動(dòng)調(diào)試模式只需為gateway子命令添加--debug標(biāo)志它有一個(gè)等價(jià)的短標(biāo)志-dpicoclaw gateway --debug # 或使用短標(biāo)志 picoclaw gateway -d在該模式下系統(tǒng)會(huì)以詳細(xì)格式輸出日志并展示系統(tǒng)提示詞與工具執(zhí)行結(jié)果的預(yù)覽片段。啟動(dòng)時(shí)終端會(huì)直接打印一行提示 Debug mode enabled。從源碼實(shí)現(xiàn)看--debug的作用鏈路非常清晰gateway 命令定義 將debug聲明為布爾標(biāo)志隨后在 gateway.Run 中執(zhí)行if debug { logger.SetLevel(logger.DEBUG) } else { logger.SetLevelFromString(config.ResolveGatewayLogLevel(configPath)) }也就是說--debug會(huì)把日志級(jí)別強(qiáng)制提升為DEBUG并且如 gateway.go 注釋 所說明的調(diào)試模式會(huì)永久覆蓋配置中的日志級(jí)別——即使你隨后熱重載了配置配置熱重載由 handleConfigReload 處理debug標(biāo)志仍然生效除非重啟網(wǎng)關(guān)。日志系統(tǒng)基于 zerolog 實(shí)現(xiàn)DEBUG 級(jí)別定義為最低級(jí)別pkg/logger/logger.go。調(diào)試模式下你能看到的典型輸出結(jié)合源碼中的日志埋點(diǎn)--debug模式下會(huì)輸出諸如系統(tǒng)提示詞構(gòu)建摘要pkg/agent/context.go 記錄靜態(tài)部分字符數(shù)、動(dòng)態(tài)部分字符數(shù)、總字符數(shù)、是否有摘要、覆蓋層數(shù)量以及是否命中緩存系統(tǒng)提示詞預(yù)覽pkg/agent/context.go 輸出截?cái)嗪蟮?prompt 預(yù)覽默認(rèn)截?cái)嗟?500 字符工具調(diào)用記錄pkg/agent/pipeline_execute.go 以Tool call: 工具名(參數(shù)JSON預(yù)覽)的格式輸出每一次工具調(diào)用最終響應(yīng)預(yù)覽pkg/agent/agent.go 輸出截?cái)嗟?120 字符的最終回復(fù)預(yù)覽。這些預(yù)覽恰好說明了為什么需要下一節(jié)的--no-truncate——默認(rèn)情況下所有長內(nèi)容都會(huì)被截?cái)嘁员３纸K端可讀。三、關(guān)閉日志截?cái)?-no-truncate默認(rèn)情況下PicoClaw 會(huì)對(duì)調(diào)試日志中超長的字符串如龐大的系統(tǒng)提示詞或大體積 JSON 結(jié)果進(jìn)行截?cái)嘁员ＷC控制臺(tái)可讀。當(dāng)你需要檢查某個(gè)命令的完整輸出或需要核對(duì)發(fā)送給 LLM 提供商的精確 payload 時(shí)請(qǐng)使用--no-truncatepicoclaw gateway --debug --no-truncate重要約束--no-truncate只能與--debug組合使用單獨(dú)使用時(shí)網(wǎng)關(guān)會(huì)直接報(bào)錯(cuò)并拒絕啟動(dòng)。底層實(shí)現(xiàn)全局截?cái)嚅_關(guān)--no-truncate的實(shí)現(xiàn)是一個(gè)進(jìn)程級(jí)全局開關(guān)。gateway 命令的 PreRunE 鉤子 做了兩件事校驗(yàn)noTruncate必須伴隨debug否則返回錯(cuò)誤the --no-truncate option can only be used in conjunction with --debug (-d)通過utils.SetDisableTruncation(true)打開全局開關(guān)并記錄日志String truncation is globally disabled via no-truncate flag。開關(guān)本身定義在 pkg/utils/string.go使用原子布爾值保證并發(fā)安全var disableTruncation atomic.Bool func SetDisableTruncation(enabled bool) { disableTruncation.Store(enabled) }而所有日志截?cái)嘧罱K都匯聚到同一個(gè) Truncate 函數(shù)func Truncate(s string, maxLen int) string { // If the no-truncate flag is active, it returns the full string if disableTruncation.Load() { return s } ... }當(dāng)開關(guān)開啟后Truncate直接原樣返回完整字符串不再追加省略號(hào)。由于所有日志預(yù)覽系統(tǒng)提示詞預(yù)覽、工具參數(shù)預(yù)覽、響應(yīng)預(yù)覽都經(jīng)由該函數(shù)處理因此--no-truncate會(huì)一次性全局禁用所有位置的截?cái)喽侵蛔饔糜谀骋粭l日志。該標(biāo)志的三個(gè)典型使用場(chǎng)景官方文檔明確列出了--no-truncate最有價(jià)值的三個(gè)場(chǎng)景核對(duì)發(fā)送給提供商的精確消息語法確認(rèn)請(qǐng)求 payload 的 JSON 結(jié)構(gòu)、字段順序與轉(zhuǎn)義是否正確讀取完整工具輸出exec、web_fetch、read_file等工具返回的超長內(nèi)容不再被截?cái)喾奖銠z查命令真實(shí)輸出調(diào)試內(nèi)存中保存的會(huì)話歷史完整查看被組裝進(jìn)上下文的歷史消息驗(yàn)證會(huì)話拼接邏輯是否符合預(yù)期。命令行參數(shù)的補(bǔ)充信息gateway命令還支持其他標(biāo)志可在調(diào)試時(shí)一并使用標(biāo)志短標(biāo)志說明--debug-d開啟調(diào)試日志DEBUG 級(jí)別--no-truncate-T全局禁用調(diào)試日志中的字符串截?cái)鄡H在與--debug組合時(shí)有效--allow-empty-E即使未配置默認(rèn)模型也繼續(xù)啟動(dòng)網(wǎng)關(guān)--host—覆蓋本次運(yùn)行的網(wǎng)關(guān)綁定地址會(huì)寫入gateway.host對(duì)應(yīng)的環(huán)境變量這些標(biāo)志的定義與校驗(yàn)邏輯均可從 cmd/picoclaw/internal/gateway/command.go 與配套測(cè)試 command_test.go 中核實(shí)。四、配置層面的日志級(jí)別控制非調(diào)試模式除了命令行標(biāo)志PicoClaw 還支持通過配置文件控制網(wǎng)關(guān)日志級(jí)別。在 config/config.example.json 中g(shù)ateway節(jié)點(diǎn)包含如下字段gateway: { _comment: Default log level is set to fatal. Other available options are debug, info, warn and error., host: localhost, port: 18790, hot_reload: false, log_level: fatal }log_level支持debug、info、warn、error、fatal五個(gè)取值。需要留意的是默認(rèn)值是fatal這意味著不顯式配置時(shí)普通日志幾乎全部被抑制——這也正是看不到內(nèi)部發(fā)生了什么的根源在非調(diào)試模式下網(wǎng)關(guān)啟動(dòng)時(shí)會(huì)讀取該配置并設(shè)置日志級(jí)別pkg/gateway/gateway.go 與 pkg/gateway/gateway.go配置熱重載時(shí)也會(huì)同步更新日志級(jí)別pkg/gateway/gateway.go且日志級(jí)別更新放在最后避免重載過程中的 info/warn 日志被抑制--debug標(biāo)志的優(yōu)先級(jí)高于配置文件只要啟動(dòng)時(shí)帶了--debug無論log_level配置成什么都會(huì)強(qiáng)制進(jìn)入 DEBUG 級(jí)別。實(shí)際排障中你可以把gateway.log_level臨時(shí)改為debug并熱重載配置hot_reload開啟時(shí)從而在不重啟進(jìn)程的情況下獲取 DEBUG 日志若需要看清全部細(xì)節(jié)不被截?cái)鄤t仍需以--debug --no-truncate方式重啟網(wǎng)關(guān)。五、相關(guān)閱讀與延伸完整配置文件字段說明見 config/config.example.json其中agents.defaults.tool_feedback.max_args_length等字段默認(rèn) 300 字符見 pkg/config/config.go與日志中工具參數(shù)預(yù)覽長度直接相關(guān)網(wǎng)關(guān)熱重載、端口綁定等運(yùn)行時(shí)行為的代碼入口在 pkg/gateway/gateway.go如果你需要排查連接、鑒權(quán)或消息收發(fā)問題可進(jìn)一步閱讀 docs/operations/troubleshooting.zh.md如果涉及 Docker 部署下的日志查看參考 docs/guides/docker.zh.md項(xiàng)目總覽與快速上手可回到 README.md 或 docs/project/README.zh.md。小結(jié)picoclaw gateway --debug讓你看到 Agent 的每一步動(dòng)作--no-truncate則把被截?cái)嗟募?xì)節(jié)完整還原出來。二者配合配合配置文件中的gateway.log_level可以覆蓋從日常觀察、問題定位到 payload 級(jí)核對(duì)的全部調(diào)試需求——這是深入理解 PicoClaw 運(yùn)行時(shí)機(jī)制最直接的一條路徑?！久赓M(fèi)下載鏈接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity項(xiàng)目地址: https://gitcode.com/gh_mirrors/pi/picoclaw創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考