企业官网建设流程全解析

PicoClaw 网关调试实战：--debug 日志模式与 --no-truncate 完整输出机制解析

【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw

PicoClaw 对每条收到的请求都会在后台执行多次复杂交互——从消息路由、复杂度评估，到工具执行与模型故障自适应。想要定位问题，甚至真正理解 Agent 的工作方式，就必须看清内部究竟发生了什么。本文基于 PicoClaw 官方调试文档（docs/operations/debug.fr.md），完整讲解gateway命令的--debug（-d）与--no-truncate（-T）两个调试利器：包括它们的启动方式、日志格式化行为、全局截断机制的底层实现，以及如何结合配置文件精准控制日志级别，帮助你在排障时拿到完整、真实的运行证据。

一、为什么需要调试模式：看清 Agent 的内部运转

PicoClaw 网关（gateway）是一个单进程常驻的运行时，它承载着消息路由、复杂度评估、工具调用、上下文构建、模型降级容错等一系列逻辑。在默认日志级别（配置文件默认为fatal，即仅在致命错误时输出）下，Agent 内部发生的绝大多数事情对你是不可见的。

调试模式的直接收益包括：

• 查看每次 LLM 请求的细节：系统提示词（System Prompt）、发送给提供商的完整消息结构；
• 跟踪工具调用：exec、web_fetch、read_file等工具被调用的参数与结果；
• 观察消息路由：消息如何在通道、Agent 与模型之间流转；
• 理解上下文构建：系统提示词的长度统计、缓存命中情况、会话历史如何被组装。

这些信息不仅是排障依据，也是学习 PicoClaw 架构的最佳入口。

二、以调试模式启动网关

启动调试模式只需为gateway子命令添加--debug标志，它有一个等价的短标志-d：

picoclaw gateway --debug # 或使用短标志 picoclaw gateway -d

在该模式下，系统会以详细格式输出日志，并展示系统提示词与工具执行结果的预览片段。启动时终端会直接打印一行提示：🔍 Debug mode enabled。

从源码实现看，--debug的作用链路非常清晰：gateway 命令定义 将debug声明为布尔标志，随后在 gateway.Run 中执行：

if debug { logger.SetLevel(logger.DEBUG) } else { logger.SetLevelFromString(config.ResolveGatewayLogLevel(configPath)) }

也就是说，--debug会把日志级别强制提升为DEBUG，并且如 gateway.go 注释 所说明的，调试模式会永久覆盖配置中的日志级别——即使你随后热重载了配置（配置热重载由 handleConfigReload 处理），debug标志仍然生效，除非重启网关。日志系统基于 zerolog 实现，DEBUG 级别定义为最低级别（pkg/logger/logger.go）。

调试模式下你能看到的典型输出

结合源码中的日志埋点，--debug模式下会输出诸如：

• 系统提示词构建摘要：pkg/agent/context.go 记录静态部分字符数、动态部分字符数、总字符数、是否有摘要、覆盖层数量以及是否命中缓存；
• 系统提示词预览：pkg/agent/context.go 输出截断后的 prompt 预览（默认截断到 500 字符）；
• 工具调用记录：pkg/agent/pipeline_execute.go 以Tool call: 工具名(参数JSON预览)的格式输出每一次工具调用；
• 最终响应预览：pkg/agent/agent.go 输出截断到 120 字符的最终回复预览。

这些预览恰好说明了为什么需要下一节的--no-truncate——默认情况下，所有长内容都会被截断以保持终端可读。

三、关闭日志截断：--no-truncate

默认情况下，PicoClaw 会对调试日志中超长的字符串（如庞大的系统提示词或大体积 JSON 结果）进行截断，以保证控制台可读。当你需要检查某个命令的完整输出，或需要核对发送给 LLM 提供商的精确 payload 时，请使用--no-truncate：

picoclaw gateway --debug --no-truncate

重要约束：--no-truncate只能与--debug组合使用，单独使用时网关会直接报错并拒绝启动。

底层实现：全局截断开关

--no-truncate的实现是一个进程级全局开关。gateway 命令的 PreRunE 钩子 做了两件事：

1. 校验noTruncate必须伴随debug，否则返回错误"the --no-truncate option can only be used in conjunction with --debug (-d)"；
2. 通过utils.SetDisableTruncation(true)打开全局开关，并记录日志"String truncation is globally disabled via 'no-truncate' flag"。

开关本身定义在 pkg/utils/string.go，使用原子布尔值保证并发安全：

var disableTruncation atomic.Bool func SetDisableTruncation(enabled bool) { disableTruncation.Store(enabled) }

而所有日志截断最终都汇聚到同一个 Truncate 函数：

func Truncate(s string, maxLen int) string { // If the no-truncate flag is active, it returns the full string if disableTruncation.Load() { return s } ... }

当开关开启后，Truncate直接原样返回完整字符串，不再追加省略号。由于所有日志预览（系统提示词预览、工具参数预览、响应预览）都经由该函数处理，因此--no-truncate会一次性全局禁用所有位置的截断，而非只作用于某一条日志。

该标志的三个典型使用场景

官方文档明确列出了--no-truncate最有价值的三个场景：

1. 核对发送给提供商的精确消息语法：确认请求 payload 的 JSON 结构、字段顺序与转义是否正确；
2. 读取完整工具输出：exec、web_fetch、read_file等工具返回的超长内容不再被截断，方便检查命令真实输出；
3. 调试内存中保存的会话历史：完整查看被组装进上下文的历史消息，验证会话拼接逻辑是否符合预期。

命令行参数的补充信息

gateway命令还支持其他标志，可在调试时一并使用：

这些标志的定义与校验逻辑均可从 cmd/picoclaw/internal/gateway/command.go 与配套测试 command_test.go 中核实。

四、配置层面的日志级别控制（非调试模式）

除了命令行标志，PicoClaw 还支持通过配置文件控制网关日志级别。在 config/config.example.json 中，gateway节点包含如下字段：

"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五个取值。需要留意的是：

• 默认值是fatal，这意味着不显式配置时，普通日志几乎全部被抑制——这也正是"看不到内部发生了什么"的根源；
• 在非调试模式下，网关启动时会读取该配置并设置日志级别（pkg/gateway/gateway.go 与 pkg/gateway/gateway.go）；
• 配置热重载时也会同步更新日志级别（pkg/gateway/gateway.go），且日志级别更新放在最后，避免重载过程中的 info/warn 日志被抑制；
• --debug标志的优先级高于配置文件：只要启动时带了--debug，无论log_level配置成什么，都会强制进入 DEBUG 级别。

实际排障中，你可以把gateway.log_level临时改为"debug"并热重载配置（hot_reload开启时），从而在不重启进程的情况下获取 DEBUG 日志；若需要看清全部细节（不被截断），则仍需以--debug --no-truncate方式重启网关。

五、相关阅读与延伸

• 完整配置文件字段说明见 config/config.example.json，其中agents.defaults.tool_feedback.max_args_length等字段（默认 300 字符，见 pkg/config/config.go）与日志中工具参数预览长度直接相关；
• 网关热重载、端口绑定等运行时行为的代码入口在 pkg/gateway/gateway.go；
• 如果你需要排查连接、鉴权或消息收发问题，可进一步阅读 docs/operations/troubleshooting.zh.md；如果涉及 Docker 部署下的日志查看，参考 docs/guides/docker.zh.md；
• 项目总览与快速上手可回到 README.md 或 docs/project/README.zh.md。

小结：picoclaw gateway --debug让你"看到" Agent 的每一步动作，--no-truncate则把被截断的细节完整还原出来。二者配合，配合配置文件中的gateway.log_level，可以覆盖从日常观察、问题定位到 payload 级核对的全部调试需求——这是深入理解 PicoClaw 运行时机制最直接的一条路径。

【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw