第十九章：常见问题与解决方案
❓ 本章汇总 MiniClaw 使用中的常见问题及解决方案。
19.1 安装与配置问题
19.1.1 MCP 客户端无法连接
┌─────────────────────────────────────────────────────────────────────┐
│ MCP 客户端无法连接 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 问题现象： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • MCP 客户端显示 MiniClaw 未连接 │ │
│ │ • 工具列表为空 │ │
│ │ • 无法调用 MiniClaw 功能 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 排查步骤： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 1. 检查 Node.js 是否安装 │ │
│ │ node --version │ │
│ │ # 需要 Node.js 18+ │ │
│ │ │ │
│ │ 2. 检查 npx 是否可用 │ │
│ │ npx --version │ │
│ │ │ │
│ │ 3. 手动测试 MiniClaw │ │
│ │ npx -y github:8421bit/miniclaw │ │
│ │ │ │
│ │ 4. 检查 MCP 配置格式 │ │
│ │ • JSON 格式是否正确 │ │
│ │ • 路径是否正确 │ │
│ │ • 环境变量是否设置 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 常见原因与解决方案： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 原因 解决方案 │ │
│ │ ───────────────────────────────────────────────────────── │ │
│ │ Node.js 未安装 安装 Node.js 18+ │ │
│ │ JSON 格式错误 检查逗号、引号、括号 │ │
│ │ 网络问题 检查网络连接 │ │
│ │ 权限问题 检查文件执行权限 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘19.1.2 首次运行无响应
┌─────────────────────────────────────────────────────────────────────┐
│ 首次运行无响应 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 问题现象： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 首次启动后 Agent 没有反应 │ │
│ │ • 没有触发觉醒访谈 │ │
│ │ • 对话没有上下文 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 排查步骤： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 1. 检查 ~/.miniclaw/ 目录是否创建 │ │
│ │ ls -la ~/.miniclaw │ │
│ │ │ │
│ │ 2. 检查模板文件是否存在 │ │
│ │ ls ~/.miniclaw/*.md │ │
│ │ │ │
│ │ 3. 检查日志文件 │ │
│ │ ls ~/.miniclaw/memory/ │ │
│ │ │ │
│ │ 4. 手动触发初始化 │ │
│ │ # 删除现有目录重新初始化 │ │
│ │ rm -rf ~/.miniclaw │ │
│ │ # 重启 MCP 客户端 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘19.2 功能使用问题
19.2.1 记忆没有被记录
┌─────────────────────────────────────────────────────────────────────┐
│ 记忆没有被记录 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 问题现象： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 告诉 Agent 的信息没有被记住 │ │
│ │ • 下次对话时忘记了之前的偏好 │ │
│ │ • MEMORY.md 没有更新 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 排查步骤： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 1. 检查是否使用了正确的表达方式 │ │
│ │ ✅ "记住我喜欢简洁的回复" │ │
│ │ ✅ "请把这个记录下来" │ │
│ │ ❌ "我喜欢简洁的回复"（可能被忽略） │ │
│ │ │ │
│ │ 2. 检查日志文件是否有记录 │ │
│ │ cat ~/.miniclaw/memory/$(date +%Y-%m-%d).md │ │
│ │ │ │
│ │ 3. 检查 USER.md 是否更新 │ │
│ │ cat ~/.miniclaw/USER.md │ │
│ │ │ │
│ │ 4. 手动触发记忆更新 │ │
│ │ 使用 miniclaw_update 工具 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 解决方案： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 使用明确的记忆指令："记住..." │ │
│ │ • 使用 miniclaw_note 工具直接记录 │ │
│ │ • 使用 miniclaw_update 直接更新文件 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘19.2.2 命令执行被拒绝
┌─────────────────────────────────────────────────────────────────────┐
│ 命令执行被拒绝 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 问题现象： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 执行命令时返回 "Command not allowed" │ │
│ │ • 某些操作无法执行 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 原因分析： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ MiniClaw 使用命令白名单机制，只允许安全的命令： │ │
│ │ │ │
│ │ ✅ 允许的命令： │ │
│ │ • ls, cat, find, grep, head, tail, wc, tree │ │
│ │ • git, npm, node, npx, pnpm, yarn │ │
│ │ • python, pip, python3, pip3 │ │
│ │ • echo, date, uname, which, pwd, ps │ │
│ │ │ │
│ │ ❌ 禁止的命令： │ │
│ │ • rm, rmdir, del │ │
│ │ • sudo, su, doas │ │
│ │ • curl, wget, nc │ │
│ │ • kill, pkill, killall │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 解决方案： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 使用允许列表中的替代命令 │ │
│ │ • 对于文件操作，让 Agent 直接读写文件 │ │
│ │ • 对于危险操作，手动在终端执行 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘19.2.3 技能没有被加载
┌─────────────────────────────────────────────────────────────────────┐
│ 技能没有被加载 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 问题现象： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 新创建的技能没有出现在工具列表中 │ │
│ │ • 技能提示词不可用 │ │
│ │ • miniclaw_status 显示技能数为 0 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 排查步骤： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 1. 检查技能目录结构 │ │
│ │ ls -la ~/.miniclaw/skills/my-skill/ │ │
│ │ # 应该有 SKILL.md 文件 │ │
│ │ │ │
│ │ 2. 检查 SKILL.md 格式 │ │
│ │ cat ~/.miniclaw/skills/my-skill/SKILL.md │ │
│ │ # 确保有正确的 frontmatter │ │
│ │ │ │
│ │ 3. 检查 frontmatter 格式 │ │
│ │ --- │ │
│ │ name: my-skill # 必需 │ │
│ │ description: "..." # 必需 │ │
│ │ --- │ │
│ │ │ │
│ │ 4. 等待缓存过期或重启 │ │
│ │ # 技能缓存 TTL 为 5 秒 │ │
│ │ # 或重启 MCP 客户端 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 常见错误： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • SKILL.md 文件名错误（大小写） │ │
│ │ • frontmatter 格式错误（缺少 ---） │ │
│ │ • 缺少必需字段（name, description） │ │
│ │ • 目录位置错误 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘19.3 性能问题
19.3.1 启动速度慢
┌─────────────────────────────────────────────────────────────────────┐
│ 启动速度慢 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 问题现象： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 首次响应时间过长 │ │
│ │ • 每次对话开始都很慢 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 可能原因与解决方案： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 原因 1：首次 npx 下载 │ │
│ │ 解决：首次使用需要下载，后续会缓存 │ │
│ │ │ │
│ │ 原因 2：日志文件过大 │ │
│ │ 解决：定期清理或归档日志 │ │
│ │ rm ~/.miniclaw/memory/archived/*.md │ │
│ │ │ │
│ │ 原因 3：技能目录过多 │ │
│ │ 解决：删除不需要的技能 │ │
│ │ rm -rf ~/.miniclaw/skills/unused-skill │ │
│ │ │ │
│ │ 原因 4：Token 预算过大 │ │
│ │ 解决：降低 Token 预算 │ │
│ │ MINICLAW_TOKEN_BUDGET=6000 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘19.3.2 内存占用高
┌─────────────────────────────────────────────────────────────────────┐
│ 内存占用高 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 问题现象： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • Node.js 进程内存占用过高 │ │
│ │ • 系统变慢 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 解决方案： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 1. 检查内存使用 │ │
│ │ ps aux | grep miniclaw │ │
│ │ │ │
│ │ 2. 清理大文件 │ │
│ │ # 检查日志文件大小 │ │
│ │ du -sh ~/.miniclaw/memory/ │ │
│ │ # 归档旧日志 │ │
│ │ mv ~/.miniclaw/memory/2025-*.md ~/.miniclaw/memory/archived/│
│ │ │ │
│ │ 3. 重启 MCP 客户端 │ │
│ │ # 这会重新启动 MiniClaw 进程 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘19.4 错误排查
19.4.1 查看错误日志
┌─────────────────────────────────────────────────────────────────────┐
│ 查看错误日志 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ MiniClaw 的错误日志输出到 stderr： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ # MCP 客户端通常会捕获 stderr │ │
│ │ # 查看 MCP 客户端的日志文件 │ │
│ │ │ │
│ │ # Claude Desktop (macOS) │ │
│ │ ~/Library/Logs/Claude/mcp*.log │ │
│ │ │ │
│ │ # Claude Desktop (Windows) │ │
│ │ %APPDATA%\Claude\logs\mcp*.log │ │
│ │ │ │
│ │ # 手动测试并查看错误 │ │
│ │ npx -y github:8421bit/miniclaw 2>&1 | tee miniclaw.log │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 常见错误信息： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 错误信息 可能原因 │ │
│ │ ───────────────────────────────────────────────────────── │ │
│ │ ENOENT 文件或目录不存在 │ │
│ │ EACCES 权限不足 │ │
│ │ Command not allowed 命令不在白名单中 │ │
│ │ Invalid params 参数验证失败 │ │
│ │ Timeout 命令执行超时 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘19.4.2 重置 MiniClaw
┌─────────────────────────────────────────────────────────────────────┐
│ 重置 MiniClaw │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 如果遇到无法解决的问题，可以尝试重置： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ⚠️ 警告：重置会删除所有数据和配置！ │ │
│ │ │ │
│ │ # 备份重要数据（可选） │ │
│ │ cp -r ~/.miniclaw ~/.miniclaw.backup │ │
│ │ │ │
│ │ # 删除 MiniClaw 目录 │ │
│ │ rm -rf ~/.miniclaw │ │
│ │ │ │
│ │ # 重启 MCP 客户端 │ │
│ │ # MiniClaw 会自动重新初始化 │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 部分重置（保留用户数据）： │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ # 只重置状态文件 │ │
│ │ rm ~/.miniclaw/state.json │ │
│ │ rm ~/.miniclaw/heartbeat_state.json │ │
│ │ │ │
│ │ # 只重置日志 │ │
│ │ rm -rf ~/.miniclaw/memory/* │ │
│ │ │ │
│ │ # 只重置实体数据 │ │
│ │ rm ~/.miniclaw/entities.json │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘本章小结
┌─────────────────────────────────────────────────────────────────────┐
│ 第十九章 核心要点 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 🔧 安装配置问题 │
│ • 检查 Node.js 版本（需要 18+） │
│ • 验证 MCP 配置格式 │
│ • 手动测试 npx 命令 │
│ │
│ 📝 功能使用问题 │
│ • 记忆记录：使用明确指令 "记住..." │
│ • 命令拒绝：使用白名单中的命令 │
│ • 技能加载：检查 SKILL.md 格式 │
│ │
│ ⚡ 性能问题 │
│ • 启动慢：清理日志、减少技能 │
│ • 内存高：归档旧文件、重启进程 │
│ │
│ 🔍 错误排查 │
│ • 查看 MCP 客户端日志 │
│ • 手动测试捕获 stderr │
│ • 必要时重置 MiniClaw │
│ │
└─────────────────────────────────────────────────────────────────────┘下一章：未来展望 →