Featured image of post OpenClaw 日常问题排查指南

OpenClaw 日常问题排查指南

OpenClaw 服务常见问题的排查与解决方法,包括 Telegram 断线、进程冲突、配置错误等场景

语速

整理了使用 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. 改配置前先备份:

    1
    
    cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d_%H%M%S)
    
  2. 让 Claw 改配置后验证:

    1
    
    openclaw --version  # 如果没报错说明配置有效
    
  3. 小步修改,逐步验证: 不要一次性让 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 openclawsystemd 日志
~/.openclaw/openclaw.json主配置文件
~/.openclaw/workspace/工作目录
~/.openclaw/workspace/knowledge/知识库