常见错误与排查

5 5.1 配置格式错误症状：Gateway 启动失败，报错 JSON 解析错误

原因：

JSON 语法错误（缺少逗号、引号不匹配）使用了 JSON 不支持的注释尾部逗号（最后一个元素后多了一个逗号）解决：使用 JSON 验证工具检查，如 VS Code 的 JSON 插件或在线验证器。手滑是人之常情，验证器能救命！

5.2 重启不生效症状：修改配置后重启 Gateway，但行为未改变

排查步骤：

确认修改的是正确的配置文件（检查 OPENCLAW_CONFIG_PATH）确认 Gateway 已完全重启（不是热重载）检查配置层级是否正确（缩进、嵌套）查看 Gateway 日志确认配置加载成功

查看 Gateway 日志

tail -f ~/.openclaw/gateway.log 💡 90% 的"配置不生效"问题，都是因为你改错了文件或者没重启。别不好意思承认！

5.3 敏感信息泄露风险风险场景：

配置文件提交到 Git 仓库（公开处刑）截图分享时未打码 API 密钥（社死现场）日志文件包含完整配置（无意泄密）防护建议：

将 ~/.openclaw/ 加入 .gitignore（基本操作）使用 .env 文件存储敏感信息（安全习惯）定期轮换 API 密钥（亡羊补牢）

5.4 环境变量优先级症状：配置了 API Key 但未被使用

原因：环境变量优先级高于配置文件，可能已有同名变量存在。

排查：

echo $DASHSCOPE_API_KEY # macOS/Linux echo %DASHSCOPE_API_KEY% # Windows 如需使用配置文件中的值，需先清除环境变量。有时候"清空重来"是最有效的解决方案！