人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载本文档对应仓库中的 docs/operations/debug.pt-br.md以及其英文版 docs/operations/debug.md聚焦 PicoClaw 网关gateway的调试能力。PicoClaw 每收到一条请求都会在后台执行一连串复杂交互——从消息路由、复杂度评估到工具执行与模型故障自适应。能够看清内部到底发生了什么不仅对排查问题至关重要也是真正理解 Agent 工作机制的前提。读完本文你将掌握如何以调试模式启动网关、如何通过--no-truncate获取完整日志如何解读工具调用生命周期中的结构化日志以及如何借助tool_feedback将工具执行状态实时反馈到聊天渠道。以调试模式启动 PicoClaw 网关要获得关于 Agent 内部行为的详细信息LLM 请求、工具调用、消息路由可以用调试标志启动 PicoClaw 网关picoclaw gateway --debug # 等价写法 picoclaw gateway -d在该模式下系统会以更详尽的方式格式化日志并显示 System Prompt 与工具执行结果的预览。这意味着你可以直接观察到每次请求中模型收到了什么、决定调用哪些工具、工具又返回了什么。从源码看gateway命令定义在 cmd/picoclaw/internal/gateway/command.gocmd.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))该命令还支持gateway的别名gAliases: []string{g}。除调试相关标志外--allow-empty/-E允许在未配置默认模型时继续启动--host可在本次运行时临时覆盖配置中的gateway.host覆盖逻辑通过resolveGatewayHostOverride调用 pkg/netbind 的NormalizeHostInput完成并将值写入环境变量EnvGatewayHost后启动gateway.Run。关闭日志截断查看完整输出默认情况下PicoClaw 会在调试日志中截断超长字符串例如System Prompt或大型 JSON 结果以保持控制台可读性。如果你需要检查某条命令的完整输出或发给 LLM 模型的精确 payload可以使用--no-truncate标志picoclaw gateway --debug --no-truncate注意该标志只有与--debug模式组合时才生效。这一约束并非口头约定而是由命令的PreRunE钩子强制校验的见 cmd/picoclaw/internal/gateway/command.goPreRunE: func(_ *cobra.Command, _ []string) error { 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) } return nil },一旦该标志生效全局截断功能即被关闭。这在以下场景中极为有用核对发送给 provider 的消息的确切语法与格式阅读exec、web_fetch、read_file等工具输出的完整内容调试保存在记忆memory中的会话历史session history。截断机制的底层实现全局截断由 pkg/utils/string.go 实现。它使用一个原子布尔变量控制是否禁用截断var disableTruncation atomic.Bool // SetDisableTruncation globally enables or disables string truncation func SetDisableTruncation(enabled bool) { disableTruncation.Store(enabled) } // Truncate returns a truncated version of s with at most maxLen runes. // Handles multi-byte Unicode characters properly. // If the string is truncated, ... is appended to indicate truncation. func Truncate(s string, maxLen int) string { if disableTruncation.Load() { return s } ... }两个值得注意的实现细节截断按runeUnicode 码点计算而非字节因此对中文、日文等多字节字符是安全的不会把字符拦腰截断被截断的字符串尾部会追加...作为标记当maxLen 3时则直接截取前maxLen个字符。当--no-truncate生效时Truncate直接返回原字符串。调试日志中的工具调用可见性启用调试模式后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 请求调用工具”的日志由 pkg/agent/pipeline_llm.go 发出包含tools、count、iteration等字段“Tool call”日志由 pkg/agent/pipeline_execute.go 发出其中参数预览通过utils.Truncate(string(argsJSON), 200)生成这正是下文“200 字符硬限制”的由来“Async tool completed, publishing result”日志同样位于 pkg/agent/pipeline_execute.go仅在异步工具回调完成、结果发布前记录通常伴随一次将结果重新注入系统的PublishInbound调用。此外工具循环tool loop路径 pkg/tools/toolloop.go 也存在同一套LLM requested tool calls/Tool call:日志结构只是component标签为toolloop用于观察工具循环驱动层的行为。解读一条工具调用日志一个典型的同步工具调用会在控制台产生连续两行日志[...] [INFO] agent: LLM requested tool calls {tools[web_search], count1, iteration1} [...] [INFO] agent: Tool call: web_search({query:picoclaw release notes}) {toolweb_search, iteration1}第一行表明模型在本轮iteration1决定调用 1 个工具web_search第二行则给出实际的调用签名——工具名加参数 JSON 的预览。iteration字段对应多轮工具循环中的轮次编号可用于追踪 Agent 连续调用工具时的推进过程。注意工具参数的预览在日志中硬性限制为200 字符这一限制与--no-truncate无关——因为它走的是INFO级别路径且使用固定的utils.Truncate(..., 200)见 pkg/agent/pipeline_execute.go。如果需要查看发给模型的完整工具定义tools_json字段请将--no-truncate与--debug组合使用然后查看Full LLM request这一DEBUG级条目——它会包含发送给模型的每一个工具定义。在聊天中实时反馈工具状态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}配置结构体定义在 pkg/config/config.go字段如下字段类型默认值说明enabledboolfalse是否在每次工具调用时发送聊天通知separate_messagesboolfalse每次工具反馈更新都作为独立聊天消息发送而不是复用单条占位/进度消息max_args_lengthint300通知中包含的序列化参数的最大字符数这三个字段也全部支持通过环境变量设置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模式相互独立。它在生产环境即可正常工作无需以任何特殊标志启动网关。从实现看工具反馈消息的发送位于 pkg/agent/pipeline_execute.go当shouldPublishToolFeedback判定启用且当前渠道不是pico时会构造反馈消息并通过al.bus.PublishOutbound发布消息种类为messageKindToolFeedback并且带有一个 3 秒的超时上下文避免阻塞工具执行主流程。max_args_length参数则通过GetToolFeedbackMaxArgsLength()读取后交给toolFeedbackArgsPreview生成参数预览。实战建议小结日常观察 Agent 行为用picoclaw gateway -d启动重点看LLM requested tool calls与Tool call:两行日志确认模型是否按预期选择工具、参数是否正确核对发给 LLM 的精确 payload用picoclaw gateway --debug --no-truncate在Full LLM request的DEBUG条目中查看完整工具定义与消息语法注意 200 字符硬限制工具调用参数的预览在任何情况下都不会超过 200 字符需要完整参数请依赖--no-truncate下的DEBUG级日志面向用户透明化在共享机器人或需要向用户展示执行过程的场景启用agents.defaults.tool_feedback.enabled并结合max_args_length与separate_messages控制消息粒度配置参照完整的配置示例可查看 config/config.example.json调试与日志相关的更多运维说明可参阅 docs/operations/README.md 与项目主文档 docs/project/README.zh.md。赞分享人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址https://gitcode.com/gh_mirrors/pi/picoclaw点击查看免费下载相关推荐PicoClaw 网关调试实战--debug 标志、全量日志与工具调用追踪PicoClaw 网关调试实战 debug 标志、全量日志与工具调用追踪 本文基于仓库 docs/operations/debug.vi.md https:/人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆PicoClaw 调试实战指南从 Debug 日志到 Tool Feedback 全链路观测PicoClaw 调试实战指南从 Debug 日志到 Tool Feedback 全链路观测 PicoClaw 的每一次请求背后都牵涉多条复杂链路——消息路由人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆PicoClaw 调试完全指南从调试模式启动到完整日志与工具调用追踪PicoClaw 调试完全指南从调试模式启动到完整日志与工具调用追踪 PicoClaw 在处理每一条入站请求时都会在后台串联起消息路由、复杂度评估、工具执行人工智能AI 应用AI Agent交互助手工具调用MCP ClientsAgent 记忆上一篇Seafile数据库备份终极指南全量与增量备份策略详解下一篇程序员必看数据库设计效率提升指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考