Debug — 调试

工作原理

/debug 技能是一个诊断工具，用于排查各种故障。它了解 NanoClaw 的架构——宿主进程、容器系统、作为宿主与容器之间唯一 IO 接口的按会话划分的 SQLite 队列（inbound.db/outbound.db），以及消息频道——并引导你逐步定位和修复问题。

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

日志位置

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

• logs/nanoclaw.log — 主应用日志。显示轮询循环、消息处理和容器启动相关信息。
• logs/nanoclaw.error.log — 仅包含错误信息。出现问题时首先查看这里。
• data/v2-sessions/{group}/{session}/ — 按会话划分的 inbound.db（消息是否到达容器？）和 outbound.db（代理是否生成了回复？）。容器以 --rm 运行，因此没有按次运行的容器日志文件——容器的 stderr 会在 debug 级别流式写入 logs/nanoclaw.log。
• 按群组划分的 Claude 状态（设置、会话历史）位于宿主机的 {group}/.claude-shared，挂载到容器内的 /home/node/.claude。

在环境中设置 LOG_LEVEL=debug 可以生成详细输出，包括完整的挂载配置、容器启动命令以及流式的容器 stderr。

常见问题

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

身份验证失败 — 密钥由 OneCLI 网关按请求注入；它们绝不会作为环境变量或聊天上下文传入容器。如果某个 API 对保管库中已有的凭据返回 401，该技能会检查代理的密钥模式（onecli agents list，若该密钥从未被分配则使用 onecli agents set-secret-mode）。如果网关本身不可达，运行器会拒绝启动任何容器——该技能会确认网关在 http://127.0.0.1:10254 上正常运行。

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

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

会话无法恢复 — 会话连续性保存在容器所拥有的、位于该会话 outbound.db 中的 session_state 表内，按会话划分。要重置某个会话，删除其位于 data/v2-sessions/{group}/{session}/ 下的文件夹，下一条消息到来时会重新创建一个全新的会话。/home/node/.claude/ 挂载（来自 {group}/.claude-shared）保存的是按群组划分的 Claude 设置和历史。

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

手动测试

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

• 手动启动容器并使用测试消息运行代理。
• 在容器内打开交互式 shell 以检查文件系统和环境。
• 直接在容器内运行 Claude Code 以检查身份验证是否正常。
• 检查会话数据库（ncl sessions list，或使用 scripts/q.ts 查询 inbound.db/outbound.db），以查看消息是否到达容器以及代理是否已回复。

使用技巧

• 始终先检查 logs/nanoclaw.error.log。大多数问题都会在那里留下清晰的错误信息。
• 快速诊断脚本可以一次性检查 7 个常见故障点：容器运行时、代理镜像、OneCLI 网关、中央数据库、挂载目标、重复的宿主实例，以及近期错误。
• 如果你在排查间歇性问题，可以设置 LOG_LEVEL=debug 运行一段时间，然后在下次故障发生后检查详细日志。
• 容器以 --rm 运行，退出后不会留下任何内容。但主应用日志会不断增长——如果 NanoClaw 运行了很长时间，建议考虑日志轮转。