踩坑记录
遇到问题？先查这里
安装报错、权限问题、配置失效——这里记录了实际遇到的问题和解决方案， 按错误类型分类，方便快速定位。
权限macOS即将发布
macOS 权限问题：Filesystem MCP 无法访问目录
报错 EACCES 或 Operation not permitted，通常是系统隐私权限没有开放给终端。
环境全平台即将发布
Node 版本冲突导致 MCP Server 启动失败
部分 MCP Server 要求 Node 18+，用 nvm 管理多版本时容易出现路径问题。
连接全平台即将发布
MCP Server 连接超时或无响应
配置文件格式正确但 Server 不响应，排查步骤：日志查看、进程检查、端口占用。
权限全平台即将发布
GitHub MCP Token 权限不足
操作仓库时报 403，Token 需要开启哪些 scope，细粒度 Token 和经典 Token 的区别。
记忆全平台即将发布
OpenClaw 记忆莫名丢失
升级版本后记忆被清空，或者记忆文件路径变更导致读取失败的处理方法。
环境Windows即将发布
Windows 路径分隔符导致配置失效
Windows 下配置文件中的路径需要用正斜杠或转义反斜杠，常见的坑。
通用排查清单
遇到任何问题，先过一遍这个清单：
Node.js 版本是否 ≥ 18（运行 node -v 确认）
配置文件 JSON 格式是否正确（用 jsonlint 验证）
MCP Server 对应的 npm 包是否已安装
API Token / 密钥是否有效且权限足够
查看 OpenClaw 日志文件（~/.openclaw/logs/）
尝试单独运行 MCP Server 命令，看是否有报错输出