OpenClaw 日常问题排查指南

Fri, 06 Mar 2026 00:00:00 +0800

整理了使用 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 running
Port 18789 is already in use
lock 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/`	知识库

运维 on Svtter's Blog

OpenClaw 日常问题排查指南

常用命令

问题 1: Claw 自己改配置把自己改挂了

现象

原因

解决方法

预防措施

常见配置错误示例

问题 2: Telegram 网络断开

现象

原因

解决方法

问题 3: Gateway 进程冲突

现象

原因

解决方法

问题 4: 配置修改后不生效

现象

原因

解决方法

问题 5: 模型配置错误

现象

原因

解决方法

正确的模型配置示例

问题 6: 切换模型

查看可用模型

修改默认模型

日志与配置文件位置