节点故障排查

本页面汇总了 OpenClaw 节点使用过程中常见的问题及其解决方案。

诊断命令

在排查问题之前，请先运行以下诊断命令收集信息：

# 检查网关和节点整体健康状态
openclaw doctor

# 查看所有节点状态
openclaw nodes

# 查看节点详细日志
openclaw logs --filter node

# 检查特定节点连接状态
openclaw nodes --verbose

日志级别

遇到难以排查的问题时，可以启用 Debug 日志获取更多信息：

openclaw node --type audio --log-level debug

音频问题

麦克风未检测到

症状：启动音频节点时提示 No audio input device found

解决方案：

1. 确认系统识别到了麦克风：

# macOS
system_profiler SPAudioDataType

# Linux
arecord -l

# Windows (WSL2)
# WSL2 不直接支持音频设备，需要 PulseAudio 转发

2. 检查系统权限：

   • macOS：系统设置 → 隐私与安全 → 麦克风 → 允许终端/iTerm
   • Linux：确认用户在 audio 组：groups $USER
   • Windows：设置 → 隐私 → 麦克风 → 允许应用访问

3. 指定设备启动：

openclaw node --type audio --list-devices
openclaw node --type audio --device "设备名称"

录音质量差 / 杂音多

症状：STT 识别准确率低，转录结果混乱

解决方案：

1. 开启噪声抑制：

audio:
  noise_suppression: true
  noise_level: aggressive

2. 检查采样率设置，确保与设备匹配：

audio:
  stt:
    sample_rate: 16000     # 常用值：16000 或 44100
    encoding: opus

3. 排除物理问题：
   • 确认麦克风未被遮挡
   • 远离风扇、空调等噪音源
   • 使用外接麦克风代替笔记本内置麦克风

STT 识别结果为空

症状：说话后 Agent 没有任何响应

排查步骤：

1. 测试 STT 连接：

openclaw node --type audio --test

2. 检查 API Key 是否有效：

openclaw doctor --check stt

3. 确认语言设置正确：

audio:
  stt:
    language: zh-CN        # 确保与实际语言匹配

摄像头问题

Permission denied（权限拒绝）

症状：启动摄像头节点时提示权限错误

解决方案：

• macOS：系统设置 → 隐私与安全 → 摄像头 → 允许终端应用
• Linux：

# 检查设备权限
ls -la /dev/video*

# 添加用户到 video 组
sudo usermod -aG video $USER
# 重新登录后生效

摄像头被占用

症状：提示 Device is busy 或画面全黑

解决方案：

1. 关闭可能占用摄像头的程序（Zoom、Teams、浏览器视频通话）
2. 检查是否有其他进程占用：

# Linux
lsof /dev/video0

# macOS
lsof | grep VDC

图片格式不支持

症状：模型返回格式错误

解决方案：

camera:
  format: jpeg             # 改用最通用的 JPEG 格式
  quality: 85

连接问题

节点无法连接网关

症状：节点启动后一直显示 connecting... 或 connection refused

排查步骤：

1. 确认网关正在运行：

openclaw status

2. 检查网关地址和端口：

# 节点连接时需要指定正确的网关地址
openclaw node --type audio --gateway ws://localhost:7681

3. 检查防火墙：

# Linux
sudo ufw status

# 确保网关端口已放行
sudo ufw allow 7681

4. 检查网络连通性：

# 从节点设备 ping 网关
ping <网关IP>

# 测试 WebSocket 端口
curl -v http://<网关IP>:7681/health

节点频繁断线

症状：节点连接后反复断开重连

解决方案：

1. 检查网络稳定性：

# 持续 ping 测试
ping -c 100 <网关IP>

2. 调整心跳和重连参数：

nodes:
  heartbeat_interval: 15     # 缩短心跳间隔（秒）
  reconnect_attempts: 120    # 增加重连次数
  reconnect_delay: 3         # 重连间隔（秒）

3. 如果使用 Wi-Fi，尝试切换到有线连接

移动节点问题

手机后台进程被杀

症状：App 切到后台后节点断开连接

常见于国产 Android 手机

小米、OPPO、Vivo、华为等品牌手机有激进的后台管理策略。

解决方案：

1. 将 OpenClaw App 加入电池白名单
2. 关闭省电模式对 OpenClaw 的限制
3. 开启前台服务模式

详细步骤请参考 Android 平台。

电池消耗过快

症状：运行节点后手机电量下降明显

优化建议：

1. 降低位置更新频率：

location:
  update_interval: 300       # 每 5 分钟更新一次

2. 关闭不需要的能力：

node:
  capabilities:
    audio: true
    camera: false            # 不需要的能力关掉
    location: false

3. 使用唤醒词模式代替持续监听

iOS 后台限制

症状：iOS App 在后台运行一段时间后被系统暂停

说明：iOS 对后台进程有严格限制，以下功能在后台可能受影响：

• 持续录音（约 3 分钟后暂停）
• 摄像头采集（后台不可用）
• 位置更新（仅低频更新）

建议：在 iOS 上使用推送通知 + 按需激活模式。

通用诊断步骤

遇到无法定位的问题时，请按以下步骤排查：

1. 检查版本：确保网关和节点版本一致

openclaw --version

2. 运行诊断：

openclaw doctor

3. 查看日志：

openclaw logs --filter node --level error --tail 50

4. 重置节点：

openclaw node --reset

5. 重新配对：

openclaw pairing --regenerate

最后手段

如果以上步骤都无法解决问题，可以尝试完全重置节点配置：

openclaw node --factory-reset

这将清除所有节点配置和配对信息，需要重新配对。