OpenClaw 排坑指南:12个常见问题与解决方案

踩过坑的人才能写出真正的指南

写在前面

用了这么久 OpenClaw，我踩过的坑比你吃过的盐还多。

这篇不写功能介绍，只写问题和解决方案。每一个坑都是血泪教训，每一个方案都经过实战验证。

如果你遇到了问题，直接按图索骥。如果没遇到问题，收藏备用，迟早用得上。

第一章：安装与配置问题

问题1：安装技能时提示 "command not found: clawhub"

现象：

$ clawhub install xxx zsh: command not found: clawhub

原因： - OpenClaw 未正确安装 - 环境变量未配置 - 使用了错误的命令

解决方案：

检查 OpenClaw 是否安装

which openclaw openclaw --version

重新安装

npm install -g openclaw

检查环境变量

echo PATH | grep openclaw

使用正确命令

openclaw skill install xxx npx openclaw skill install xxx

问题2：配置文件找不到或读取失败

现象：Error: Config file not found

原因：配置文件路径错误、格式错误或权限问题

解决方案：

确认配置文件位置

ls ~/.config/openclaw/ ls ./openclaw.yaml

创建正确的配置文件

app:     name: "my-assistant" skills:     - name: weather     - name: web-search

检查文件权限

chmod 644 ~/.config/openclaw/config.yaml

问题3：环境变量配置不生效

现象：配置了 WECHAT_APPID 和 WECHAT_SECRET，但程序提示未配置

解决方案：

正确设置环境变量

export WECHAT_APPID="your-appid" export WECHAT_SECRET="your-secret"

永久设置（添加到 ~/.bashrc）

echo 'export WECHAT_APPID="your-appid"' >> ~/.bashrc source ~/.bashrc

Windows 用户

[Environment]::SetEnvironmentVariable("WECHAT_APPID", "your-appid", "User")

第二章：技能安装与使用问题

问题4：技能安装失败或卡住

现象：安装时卡住不动，或提示 Failed to install skill

原因：网络问题、技能名称错误或依赖冲突

解决方案：

检查网络连接

ping github.com

使用正确的技能名称

clawhub search weather clawhub install openclaw/weather

手动安装

git clone https://github.com/xxx/xxx-skill.git ~/.openclaw/skills/xxx cd ~/.openclaw/skills/xxx npm install

问题5：技能安装后无法使用

现象：Error: Skill not found: weather

解决方案：

重新加载技能

openclaw skill reload openclaw restart

检查技能配置

openclaw skill list cat ~/.openclaw/skills/weather/config.yaml

安装缺失依赖

cd ~/.openclaw/skills/weather npm install

第三章：微信发布相关问题

问题6：发布到公众号时提示 "invalid media_id"

现象：{"errcode": 40007, "errmsg": "invalid media_id"}

原因：封面图未正确上传、使用了临时素材或素材已过期

解决方案：使用永久素材接口上传封面图

问题7：发布时提示 "title size out of limit"

现象：{"errcode": 45003, "errmsg": "title size out of limit"}

原因：标题超过 64 字节（约 21 个汉字）

解决方案：缩短标题长度

问题8：发布的内容显示为乱码

现象：中文显示为 Unicode 转义序列或乱码

原因：JSON 编码时中文字符被转义

解决方案：json.dumps(data, ensure_ascii=False)

第四章：网络与连接问题

问题9：无法连接 GitHub 下载技能或更新

现象：Error: Failed to connect to github.com

解决方案：

检查网络连接
使用代理：export HTTP_PROXY=http://127.0.0.1:7890
用镜像源:npm config set registry https://registry.npmmirror.com

问题10：微信 API 调用失败或超时

现象：Error: Request timeout 或 system busy

解决方案：

添加重试机制
检查 IP 白名单

第五章：性能与优化问题

问题11：OpenClaw 运行缓慢或卡顿

现象：命令响应慢，内存占用高，CPU 使用率 100%

解决方案：

禁用不用的技能：openclaw skill disable xxx
清理日志文件：truncate -s 0 ~/.openclaw/logs/*.log
重启服务：openclaw restart

问题12：定时任务不执行或执行失败

现象：配置了 cron 任务，但没有按预期执行

解决方案：

检查 cron 表达式（每天 8:00 应该是 0 8 * * *）
检查时区设置：export TZ=Asia/Shanghai
查看任务日志：tail -f ~/.openclaw/logs/cron.log

写在最后

排坑是一门艺术，也是一门科学。

这篇文章总结了 12 个典型问题。每个问题都包含： - 现象：如何识别这个问题 - 原因：为什么会发生 - 解决方案：一步步如何解决

如果你遇到了其他问题，欢迎在评论区留言，我会持续更新这篇指南。

记住：遇到问题不要慌，先查日志，再搜文档，最后求助。

本文是 OpenClaw 系列第六篇，前五篇： - OpenClaw 新手入门必看 - ClawHub 技能完全指南 - OpenClaw 实战技巧 - OpenClaw 进阶秘籍 - OpenClaw 生态全景

可在公众号历史消息中查看。