夜雨聆风📌 现象：unsupported node.js version 或闪退
🧠 原理： 需要 Node.js v22 LTS+，低版本缺少关键特性。
✅ 填坑：
node -v # 下载 https://nodejs.org v22 LTS 并勾选 PATH nvm install 22 --lts # 可选💡 避坑： 安装前必查版本，这是第一道门槛。
📌 现象： 卡在 fetchMetadata 然后 ETIMEDOUT
🧠 原理： 依赖在海外，直连慢。
✅ 填坑：
npm config set registry https://registry.npmmirror.com npm config get registry # 验证💡 避坑： 国内用户必须换源，成功率接近100%
📌 现象： 启动网关自动退出，无报错
🧠 原理： Node解析中文路径编码错误，静默失败
✅ 填坑： 安装路径和系统用户名必须纯英文，例如 C:\OpenClaw
💡 避坑： 玩技术用英文路径，省掉80%玄学问题
📌 现象：EPERM: operation not permitted
🧠 原理： 全局安装需管理员，sudo导致后续权限混乱
✅ 填坑： 配置用户目录
mkdir ~/.npm-global npm config set prefix '~/.npm-global' # 将下面加入 ~/.bashrc 或 ~/.zshrc export PATH=~/.npm-global/bin:$PATH💡 避坑： 别用sudo，配置用户目录一劳永逸
📌 现象： 显示 0.0.0.0:18789，公网可访问
🧠 原理： 默认绑定所有网卡，无认证，27万实例曾裸奔
✅ 永久修复： 编辑 ~/.openclaw/openclaw.json
{ "gateway": { "port": 28901, "bind": "127.0.0.1" } }然后重启 openclaw gateway restart
💡 避坑： 改端口+绑本地，第一件防弹衣
📌 现象：Invalid API Key 或账单被盗刷
🧠 原理： 需接入大模型API，Key错则无法连接
✅ 填坑： 环境变量或配置文件
export OPENCLAW_AI_PROVIDER="zhipuai" export OPENCLAW_AI_API_KEY="你的key" openclaw ai test # 验证💡 避坑： 打死也不要把Key上传到网络！用环境变量
📌 现象：Rate limit exceeded 或 Skill not found
✅ 填坑： 用npx绕过
npx clawhub@latest install weather并确认Skill名称正确，目录包含 skill.md
💡 避坑： 优先npx安装官方Skill
📌 现象： 无响应，状态可能为inactive
✅ 填坑： 检查状态、重启、看日志
clawhub list clawhub activate weather openclaw skills restart cat ~/.openclaw/logs/skills/weather/error.log💡 避坑： 装完≠能用，学会看状态查日志
📌 现象：Cannot find module 'axios'
✅ 填坑： 查看skill.md，安装依赖
cd ~/.openclaw/skills/weather npm install axios # 或 pip install requests💡 避坑： 装前看“说明书” skill.md
📌 现象：ECONNREFUSED 127.0.0.1:11434
🧠 原理： Ollama服务未启动或硬件带不动
✅ 填坑：
ollama pull llama3.2 ollama serve openclaw config set ai.provider "ollama" openclaw config set ai.model "llama3.2" openclaw config set ai.baseurl "http://localhost:11434" openclaw ai test💡 避坑： 内存<16G，老老实实用云端