PicoClaw 调试完全指南从调试模式启动到完整日志与工具调用追踪【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 在处理每一条入站请求时都会在后台串联起消息路由、复杂度评估、工具执行、模型故障适配等一系列复杂交互。本篇指南聚焦于 PicoClaw 的调试体系讲解如何通过gateway --debug开启详细日志、如何用--no-truncate查看完整载荷以及如何借助结构化日志和tool_feedback特性在聊天会话中实时观测工具执行过程。读完本文你将掌握一套从命令行启动调试、读懂工具调用日志、再到生产环境透明化监控的完整实战方案。为什么需要调试模式PicoClaw 是一个多通道的 Agent 网关一条消息从渠道进入后会经历路由分发、上下文组装、LLM 调用、工具调度、结果回传等多个阶段。任何一步出错问题的根源都可能被层层封装掩盖。调试模式的价值在于把黑盒打开——让开发者看到 LLM 请求的完整内容、模型决定调用的工具、工具执行的结果以及消息在系统中的流转过程。这不仅用于排障更是理解 Agent 行为机制的最直接途径。以调试模式启动 PicoClaw获取代理运行的详细信息LLM 请求、工具调用、消息路由需要为网关命令附加调试标志picoclaw gateway --debug # 或使用短标志 picoclaw gateway -d开启后系统会对日志进行详细格式化并在日志中展示系统提示词System Prompt与工具执行结果的预览。CLI 子命令同样支持调试标志例如单条消息模式与交互模式均可通过-d开启 DEBUG 日志级别。从源码看调试标志的实现调试标志在 cmd/picoclaw/internal/gateway/command.go 中定义。gateway命令基于 cobra 构建别名g可简写命令本身cmd.Flags().BoolVarP(debug, debug, d, false, Enable debug logging) cmd.Flags().BoolVarP(noTruncate, no-truncate, T, false, Disable string truncation in debug logs) cmd.Flags().BoolVarP(allowEmpty, allow-empty, E, false, Continue starting even when no default model is configured) cmd.Flags().StringVar(host, host, , Host address for gateway binding (overrides gateway.host for this run))除--debug外gateway还提供--allow-empty即使未配置默认模型也继续启动和--host临时覆盖网关监听地址两个实用标志。调试模式下日志级别通过logger.SetLevel(logger.DEBUG)提升为 DEBUG对应实现见 pkg/logger/logger.go。将日志输出到文件调试日志默认输出到控制台。若需要留存完整日志供事后分析可以通过环境变量PICOCLAW_LOG_FILE将日志写入文件见 pkg/logger/logger.go 的ConfigureFromEnvPICOCLAW_LOG_FILE/var/log/picoclaw/debug.log picoclaw gateway --debug设置后控制台输出会被禁用日志统一写入指定文件路径支持~/开头的主目录展开。禁用日志截断查看完整载荷默认情况下PicoClaw 会在调试日志中截断过长的字符串例如系统提示词或大型 JSON 输出结果以保证控制台可读性。当你需要检查某个命令的完整输出或核对发送给 LLM 模型的精确载荷时可以使用--no-truncate标志picoclaw gateway --debug --no-truncate注意--no-truncate仅在与--debug组合使用时生效。单独使用会直接报错退出。这一点由 cmd/picoclaw/internal/gateway/command.go 中的PreRunE钩子强制保证if noTruncate !debug { return fmt.Errorf(the --no-truncate option can only be used in conjunction with --debug (-d)) } if noTruncate { utils.SetDisableTruncation(true) logger.Info(String truncation is globally disabled via no-truncate flag) }截断机制的底层实现截断开关是一个进程级全局状态utils.SetDisableTruncation(true)通过原子布尔量atomic.Bool存储见 pkg/utils/string.go。所有日志格式化路径统一走utils.Truncate(s, maxLen)该函数在开关激活时直接返回原始字符串否则按 rune 数截断并追加...后缀func Truncate(s string, maxLen int) string { // If the no-truncate flag is active, it returns the full string if disableTruncation.Load() { return s } ... }开启该标志后以下场景会明显受益验证发送给提供商的消息的确切语法——Full LLM request这类 DEBUG 日志会携带完整的messages_json与tools_json字段读取exec、web_fetch、read_file等工具的完整输出排查工具结果被截断导致的误判调试保存在内存中的会话历史确认上下文管理器写入的内容是否完整。工具调用日志可见性开启调试模式后Agent 会在工具执行生命周期的每个阶段输出结构化日志条目。这些条目带有componentagent标签并根据信息量多少使用INFO或DEBUG级别日志消息级别关键字段说明LLM requested tool callsINFOtools、count、iteration模型决定调用的工具名称列表Tool call: name(args)INFOtool、iteration工具名称与参数预览截断至 200 字符Sent tool result to userDEBUGtool、content_len工具结果转发到聊天渠道时触发TTL tick after tool executionDEBUGagent_id、iteration每轮工具执行后 MCP 工具发现 TTL 递减Async tool completed, publishing resultINFOtool、content_len、channel仅针对后台异步执行的工具这些日志的产出位置均可追溯LLM requested tool calls在 pkg/agent/pipeline_llm.go 中通过logger.InfoCF(agent, ...)输出携带tools、count、iteration字段Tool call:在 pkg/agent/pipeline_execute.go 输出Full LLM request则在 pkg/agent/pipeline_llm.go 中以 DEBUG 级别记录完整的messages_json与tools_json。读懂一条工具调用日志一次典型的同步工具调用会在控制台连续产生两行日志[...] [INFO] agent: LLM requested tool calls {tools[web_search], count1, iteration1} [...] [INFO] agent: Tool call: web_search({query:picoclaw release notes}) {toolweb_search, iteration1}第一行告诉你模型决定调用web_search第二行展示实际执行的参数。这里有一个容易踩坑的细节参数预览在日志中被硬性限制为 200 字符源码中为utils.Truncate(string(argsJSON), 200)见 pkg/agent/pipeline_execute.go这一限制属于 INFO 级别路径即使开启--no-truncate也不会放宽。若要查看发给模型的每个工具定义全文请使用--debug --no-truncate组合读取Full LLM request这条 DEBUG 日志中的tools_json字段——它不受 200 字符限制包含完整内容。聊天中的实时工具反馈tool_feedback调试日志属于服务端视角只对运维开发者可见。如果你希望 Agent 在每次执行工具时直接把一条可见通知发送到聊天渠道中——例如把机器人开放给其他用户使用时增加透明度——可以启用config.json中的tool_feedback功能{ agents: { defaults: { tool_feedback: { enabled: true, max_args_length: 300, separate_messages: true } } } }当enabled为true时每次工具调用都会在工具结果返回给模型之前向聊天会话发送一条简短消息形如 web_search {query: picoclaw release notes}配置项说明ToolFeedbackConfig结构体定义在 pkg/config/config.go三个字段含义如下字段类型默认值说明enabledboolfalse每次工具调用是否发送聊天通知separate_messagesboolfalse每次工具反馈更新独立成一条消息而不是复用同一条占位/进度消息max_args_lengthint300通知中序列化参数的最大字符数默认值由 pkg/config/config.go 的GetToolFeedbackMaxArgsLength()保证未配置时返回 300。反馈消息的渲染逻辑在 pkg/utils/tool_feedback.go 的FormatToolFeedbackMessage中实现——工具名置于首行便于渠道端做动画效果参数以 JSON 代码块展示发送条件由shouldPublishToolFeedback控制见 pkg/agent/agent_utils.go仅在配置启用且未被SuppressToolFeedback抑制时触发。环境变量方式三个字段均可通过环境变量设置对应ToolFeedbackConfig上的env标签PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_ENABLEDtrue PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_MAX_ARGS_LENGTH300 PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_SEPARATE_MESSAGEStrue注意tool_feedback与--debug模式相互独立。它在生产环境同样生效不需要网关以任何特殊标志启动——config.json是唯一开关。同时从 pkg/agent/pipeline_execute.go 的实现看pico通道本地通道不会发送工具反馈消息该特性主要服务于外部聊天渠道。调试实践小结日常排障picoclaw gateway -d即可获得 LLM 请求、工具调用、消息路由的完整事件流需要留存时配合PICOCLAW_LOG_FILE写入文件。核对精确载荷picoclaw gateway -d -T-T为--no-truncate的短标志可查看未经截断的系统提示词、消息 JSON 与工具定义全文注意工具调用的 200 字符参数预览不受此影响。面向用户透明化在 config.example.json 对应的agents.defaults.tool_feedback下开启功能让聊天会话中的每位用户都能看到工具正在执行什么无需依赖服务端日志。将调试模式、完整日志与工具反馈三者结合你既能从服务端还原每一次 Agent 决策的完整链路也能在用户侧建立对工具执行的直观感知从而真正看见PicoClaw 的运行全貌。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考