【MiniClaw 深度解析】第十九章：常见问题与解决方案

# 第十九章：常见问题与解决方案 > ❓ 本章汇总 MiniClaw 使用中的常见问题及解决方案。 --- ## 19.1 安装问题 ### 19.1.1 npx 运行失败 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 问题：npx 运行失败 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 症状： │ │ $ npx -y github:8421bit/miniclaw │ │ npm ERR! code ENOENT │ │ npm ERR! syscall spawn git │ │ │ │ 原因： │ │ • Git 未安装或未添加到 PATH │ │ • Node.js 版本过低（需要 >= 18） │ │ • 网络连接问题 │ │ │ │ 解决方案： │ │ 1. 安装 Git：https://git-scm.com/downloads │ │ 2. 检查 Node.js 版本：node --version │ │ 3. 使用 npm 全局安装作为替代 │ │ │ │ 替代方案： │ │ npm install -g miniclaw │ │ miniclaw │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 19.1.2 MCP 客户端无法连接 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 问题：MCP 客户端无法连接 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 症状： │ │ • Claude Code 显示 "miniclaw 未连接" │ │ • 工具列表为空 │ │ │ │ 排查步骤： │ │ 1. 检查配置文件路径 │ │ • Claude Code: ~/.claude-code/settings.json │ │ • Cursor: ~/.cursor/mcp.json │ │ │ │ 2. 手动测试运行 │ │ npx -y github:8421bit/miniclaw │ │ # 应该看到 MCP 握手信息 │ │ │ │ 3. 检查 Node.js 版本 │ │ node --version # 需要 >= 18 │ │ │ │ 4. 重启 MCP 客户端 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 19.2 运行问题 ### 19.2.1 上下文加载失败 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 问题：上下文加载失败 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 症状： │ │ • 回复中缺少 MiniClaw 的标志性语气 │ │ • 没有显示当前时间模式 │ │ • 工具调用失败 │ │ │ │ 排查步骤： │ │ 1. 检查 ~/.miniclaw/ 目录 │ │ ls -la ~/.miniclaw/ │ │ │ │ 2. 检查 DNA 文件是否存在 │ │ ls -la ~/.miniclaw/templates/ │ │ │ │ 3. 检查文件权限 │ │ # 确保有读写权限 │ │ │ │ 4. 重新初始化 │ │ rm -rf ~/.miniclaw/ │ │ # 重启 MCP 客户端，会自动重新初始化 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### 19.2.2 技能未加载 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 问题：技能未加载 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 症状： │ │ • 新创建的技能未出现在工具列表中 │ │ • miniclaw_status 不显示新技能 │ │ │ │ 排查步骤： │ │ 1. 检查技能目录结构 │ │ ~/.miniclaw/skills/ │ │ └── my-skill/ │ │ └── SKILL.md │ │ │ │ 2. 检查 SKILL.md 格式 │ │ • 必须有 Frontmatter（--- 包裹的 YAML） │ │ • name 字段必须存在 │ │ • 文件编码为 UTF-8 │ │ │ │ 3. 等待缓存过期（5 秒）或重启客户端 │ │ │ │ 4. 检查日志 │ │ # 查看是否有解析错误 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 19.3 性能问题 ### 19.3.1 响应缓慢 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 问题：响应缓慢 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 可能原因： │ │ 1. 日志文件过大 │ │ • 检查 ~/.miniclaw/memory/daily_log.md 大小 │ │ • 如果 > 100KB，考虑手动触发蒸馏 │ │ │ │ 2. 技能过多 │ │ • 检查 ~/.miniclaw/skills/ 目录 │ │ • 技能过多会增加上下文大小 │ │ │ │ 3. 实体过多 │ │ • 检查 ~/.miniclaw/entities/ 目录 │ │ • 清理不常用的实体 │ │ │ │ 优化建议： │ │ • 定期归档旧日志 │ │ • 限制技能数量 │ │ • 清理过时实体 │ │ • 调整 Token 预算 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- ## 本章小结 ``` ┌─────────────────────────────────────────────────────────────────────┐ │ 第十九章 核心要点 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 🔧 安装问题 │ │ • npx 运行失败 → 检查 Git/Node.js │ │ • MCP 连接失败 → 检查配置/版本 │ │ │ │ ⚙️ 运行问题 │ │ • 上下文失败 → 检查目录/权限 │ │ • 技能未加载 → 检查格式/缓存 │ │ │ │ ⚡ 性能问题 │ │ • 响应缓慢 → 清理日志/技能/实体 │ │ • 内存占用 → 调整预算/缓存 │ │ │ │ 📚 排查工具 │ │ • miniclaw_status - 查看状态 │ │ • 手动测试运行 │ │ • 检查日志文件 │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` --- *本文档是《MiniClaw 深度解析》系列的第十九章，下一章将详细介绍未来展望。*