语速
整理了使用 OpenClaw 过程中遇到的常见问题和解决方法,方便日后快速定位和排查。
常用命令
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| # 查看服务状态
systemctl --user status openclaw
# 重启服务
systemctl --user restart openclaw
# 停止服务
systemctl --user stop openclaw
# 启动服务
systemctl --user start openclaw
# 查看实时日志
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log
# 查看配置
cat ~/.openclaw/openclaw.json
# 验证配置是否有效
openclaw --version
|
问题 1: Claw 自己改配置把自己改挂了
现象
- 让 Claw 修改
openclaw.json 配置后服务无法启动 Invalid config 报错- Gateway 无法启动,Bot 完全无响应
原因
- Claw 修改配置时格式错误(JSON 语法、字段类型等)
- 写入了不支持的配置项
- 配置文件损坏
解决方法
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| # 1. 检查配置是否有效
openclaw --version
# 2. 如果报错,查看具体错误信息
# 常见错误:
# - Invalid input (不支持的字段值)
# - Required field missing (缺少必要字段)
# 3. 从备份恢复
ls ~/.openclaw/openclaw.json.bak*
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
# 4. 如果没有备份,手动修复
vim ~/.openclaw/openclaw.json
# 5. 修复后重启
systemctl --user restart openclaw
|
预防措施
改配置前先备份:
1
| cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d_%H%M%S)
|
让 Claw 改配置后验证:
1
| openclaw --version # 如果没报错说明配置有效
|
小步修改,逐步验证: 不要一次性让 Claw 改太多配置项,改一处验证一次
常见配置错误示例
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| // 错误: input 写了不支持的值
"input": ["text", "image", "video"] // video 不被支持
// 正确:
"input": ["text", "image"]
// 错误: JSON 语法错误(多了逗号)
"models": [
{"id": "a"},
{"id": "b"}, // <- 这里多了逗号
]
// 错误: 字段类型错误
"reasoning": "true" // 应该是 boolean,不是 string
// 正确:
"reasoning": true
|
问题 2: Telegram 网络断开
现象
- Bot 不回复消息
- 日志显示:
Network request for 'getUpdates' failed! - 日志显示:
Telegram network error
原因
Telegram API 长连接超时或网络波动导致连接断开
解决方法
1
2
| # 重启服务
systemctl --user restart openclaw
|
问题 3: Gateway 进程冲突
现象
Gateway already runningPort 18789 is already in uselock timeout after 5000ms
原因
多个 openclaw 实例同时运行,端口被占用
解决方法
1
2
3
4
5
6
7
8
9
| # 方法1: 使用 openclaw 命令停止
openclaw gateway stop
# 方法2: 手动杀掉残留进程
ps aux | grep openclaw
kill <pid>
# 重新启动
systemctl --user start openclaw
|
问题 4: 配置修改后不生效
现象
- 修改了
~/.openclaw/openclaw.json 但还是用旧模型 - 日志显示旧的模型名称
原因
Gateway 需要重启才能加载新配置
解决方法
1
| systemctl --user restart openclaw
|
问题 5: 模型配置错误
现象
Invalid config at /home/svtter/.openclaw/openclaw.json- 服务无法启动
原因
模型配置字段不正确,如:
input 类型写了不支持的值(如 video)- 缺少必要字段
解决方法
检查并修正配置文件:
1
2
3
4
5
| # 验证配置
openclaw --version
# 如果报错,编辑配置
vim ~/.openclaw/openclaw.json
|
正确的模型配置示例
1
2
3
4
5
6
7
8
9
| {
"id": "kimi-k2.5",
"name": "Kimi K2.5",
"reasoning": true,
"input": ["text", "image"],
"cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
"contextWindow": 262144,
"maxTokens": 16384
}
|
问题 6: 切换模型
查看可用模型
1
2
3
| # 查询 API 提供的模型列表
curl -s https://api.moonshot.cn/v1/models \
-H "Authorization: Bearer YOUR_API_KEY" | jq '.data[].id'
|
修改默认模型
编辑 ~/.openclaw/openclaw.json:
1
2
3
4
5
6
7
8
9
| {
"agents": {
"defaults": {
"model": {
"primary": "kimi/kimi-k2.5"
}
}
}
}
|
然后重启: systemctl --user restart openclaw
日志与配置文件位置
| 路径 | 说明 |
|---|
/tmp/openclaw/openclaw-YYYY-MM-DD.log | 日志文件 |
journalctl --user -u openclaw | systemd 日志 |
~/.openclaw/openclaw.json | 主配置文件 |
~/.openclaw/workspace/ | 工作目录 |
~/.openclaw/workspace/knowledge/ | 知识库 |