Debug — 调试

工作原理

/debug 技能是一个诊断工具，用于排查各种故障。它了解 NanoClaw 的架构——宿主进程、容器系统、IPC 层以及消息频道——并引导你逐步定位和修复问题。

当你运行 /debug 时，它会询问出了什么问题，然后检查相关组件。它会读取日志、验证环境变量、测试容器连接以及检查挂载配置。它不会一次性输出所有诊断信息，而是逐步缩小问题范围。

日志位置

NanoClaw 根据不同场景将日志写入多个位置：

• logs/nanoclaw.log — 主应用日志。显示轮询循环、消息处理和容器启动相关信息。
• logs/nanoclaw.error.log — 仅包含错误信息。出现问题时首先查看这里。
• groups/{folder}/logs/container-*.log — 各次容器运行的输出。每次代理会话都有独立的日志文件。
• 容器内的 Claude 会话日志位于 /home/node/.claude/ — 这些日志记录了代理在会话期间实际执行的操作。

在环境中设置 LOG_LEVEL=debug 可以生成详细输出，包括每个 IPC 请求、挂载操作和消息路由决策。

常见问题

该技能了解最常见的故障模式，并针对每种情况提供具体的解决方案：

“Claude Code process exited with code 1” — 这通常意味着身份验证失败。该技能会检查你的 Claude API 密钥或 OAuth 令牌是否有效、是否正确传递到容器中，以及容器是否有网络访问权限来连接 Anthropic 的 API。

环境变量未传递到容器 — 容器从宿主进程获取环境变量。如果你在 .env 中添加了变量但容器看不到它，该技能会检查容器启动配置并提供修复建议。

挂载问题 — 代理只能访问被显式挂载到容器中的目录。如果代理找不到它应该能访问的文件，该技能会验证挂载白名单和实际的挂载路径。

权限错误 — 容器以 node 用户而非 root 运行。如果挂载的文件属于其他用户且权限设置严格，代理将无法读取。该技能会定位具体的文件和权限不匹配问题。

会话无法恢复 — NanoClaw 为每个群组维护持久的 Claude 会话。如果会话在容器运行之间未被保留，很可能是 /home/node/.claude/ 的挂载路径配置有误。

MCP 服务器故障 — 如果 Gmail 等工具或自定义 MCP 服务器在容器内不可用，该技能会检查 MCP 配置、验证服务器是否已安装并测试连接状态。

手动测试

该技能还可以帮助你单独测试各个组件：

• 手动启动容器并使用测试消息运行代理。
• 在容器内打开交互式 shell 以检查文件系统和环境。
• 直接在容器内运行 Claude Code 以检查身份验证是否正常。
• 测试宿主机与运行中容器之间的 IPC 通信。

使用技巧

• 始终先检查 logs/nanoclaw.error.log。大多数问题都会在那里留下清晰的错误信息。
• 快速诊断脚本可以一次性检查 8 个常见故障点：服务状态、容器运行时、身份验证、已注册群组、挂载路径、日志错误、磁盘空间和网络连接。
• 如果你在排查间歇性问题，可以设置 LOG_LEVEL=debug 运行一段时间，然后在下次故障发生后检查详细日志。
• 容器日志是按运行次数生成的，不会无限增长。但主应用日志会——如果 NanoClaw 运行了很长时间，建议考虑日志轮转。