第十九章：常见问题与解决方案
❓ 本章汇总 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 深度解析》系列的第十九章，下一章将详细介绍未来展望。
讨论回复
0 条回复还没有人回复