OpenClaw 生产故障排查实录：会话卡死与模型超时链路分析

heidsoft

发布于 2026-07-02 10:52:09

日期: 2026-04-30 环境: macOS 25.4.0 | OpenClaw 2026.4.26 | Node.js v22.22.0 作者: 云与AI

📋 摘要

本次故障表现为主会话（main session）长时间卡死、钉钉 Stream 频繁断连重连、模型 fallback 链全部超时。Gateway 重启后恢复正常，但暴露了模型供应商认证失效、hook 注册异常、向量记忆降级等多层问题。本文记录完整诊断与修复过程，供同类问题参考。

🧩 一、故障现象

早上 7:14 左右，收到用户反馈后开始排查，发现以下症状并发：

症状	详情
主会话卡死	state=processing，age 持续增长（970s → 1270s → 2251s），queueDepth=0 但一直不释放
模型超时	M2.7 → M2.5 → M2.5-highspeed → VL-01 → M2 → M2.1，14 级 fallback 全部超时
钉钉断连	心跳丢失触发 reconnection，每约 16 分钟一次，WebSocket code 1006
bailian API 失效	8 个 fallback 模型全部 401 invalid_api_key
Hook 注册失败	pg-memory / self-learning 的 Handler 'default' is not a function
向量记忆降级	sqlite-vec 不可用，chunks_vec 未更新

🔍 二、诊断过程

1. 基础设施状态检查

# Gateway 健康状态
openclaw gateway status

# 通道连接状态
openclaw channels status dingtalk

# Cron 任务状态
openclaw cron list

输出显示：

• Gateway: running (pid 36585, state active) ✅
• 钉钉: enabled, configured, running, connected ✅
• 但 session 卡死，queueDepth=1 持续

2. 日志分析

关键日志路径:

• 应用日志: /tmp/openclaw/openclaw-2026-04-30.log
• 错误日志: ~/.openclaw/logs/gateway.err.log
• 配置审计: ~/.openclaw/logs/config-audit.jsonl

# 提取最近错误事件
tail -100 ~/.openclaw/logs/gateway.err.log

# 实时追踪模型 fallback 决策
tail -f /tmp/openclaw/openclaw-2026-04-30.log | python3 -c "
import sys, json
for line in sys.stdin:
    try:
        d = json.loads(line.strip())
        msg = str(d.get('1',''))
        if 'model-fallback' in msg or 'stuck session' in msg or 'error' in msg.lower():
            print(d.get('time','')[11:19], msg[:200])
    except: pass
"

3. 会话状态诊断

# 通过 sessions_list API 检查当前会话
sessions_list(includeLastMessage=true, limit=5)

# 发现：sessionId=main, status=running, queueDepth=1, age=持续增长
# 这说明会话虽然标记为 running，但实际卡在 LLM 请求阶段

4. 模型供应商可用性验证

# 直接测试 bailian API（通义千问）
curl -s --max-time 15 -X POST "https://coding.dashscope.aliyuncs.com/v1/chat/completions" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5-plus","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

# 返回: {"code":"invalid_api_key","message":"invalid access token or token expired"}

# 测试 minimax-cn API
curl -s --max-time 15 -X POST "https://api.minimaxi.com/anthropic/v1/messages" \
  -H "x-api-key: <key>" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"MiniMax-M2.1","messages":[{"role":"user","content":"hi"}],"max_tokens":5}'

# 返回: {"type":"authentication_error","message":"Please carry the API secret key in the Authorization header"}

5. 配置文件解析

# 查看当前 fallback 链配置
python3 -c "
import json
with open('/Users/cloudmesh/.openclaw/openclaw.json') as f:
    data = json.load(f)
fallbacks = data.get('agents', {}).get('defaults', {}).get('model', {}).get('fallbacks', [])
for i, f in enumerate(fallbacks):
    print(f'{i+1}. {f}')
"

Fallback 链共 17 个，其中 8 个是 bailian（阿里云百炼）模型，全部已失效。

🕵️ 三、根因分析

1. 主因：模型认证失效导致级联超时

Bailian API Key 过期:

• 配置路径: models.providers.bailian.apiKey
• 症状: 所有 bailian/* 模型返回 401，触发 fallback
• 影响: 8 个 fallback 模型全部无效

MiniMax API 认证方式变更:

• 原配置使用 authHeader: true（HTTP header 认证）
• 新版 API 要求 Authorization: Bearer <secret_key> 格式
• 当前配置中 minimax:cn profile 只有 mode: api_key，没有实际 key
• 所有 minimax 模型也开始超时（可能是账号权限或网络问题）

2. 辅助因：会话状态机卡死

正常流程: user message → processing → waiting for LLM → responding → idle
卡死流程: user message → processing → [LLM 超时] → [fallback 超时] → [永远等待]

session 卡死原因：

• 模型全部超时后，会话状态停留在 processing
• 没有超时释放机制
• abortedLastRun: false 说明没有 abort 信号
• queueDepth=1 但没有实际消息在队列里

3. 钉钉断连根因

heartbeatMisses: 112+
heartbeatTriggeredReconnects: 19
socketCloseEvents: 14
runtimeDisconnects: 19

钉钉 Stream 连接因心跳丢失触发 reconnection，这通常是因为：

• 网络不稳定（可能与 Mac 睡眠/唤醒有关）
• 钉钉服务端对长连接有超时限制
• Gateway 重启期间连接中断

4. Hook 注册失败

[ERROR] Handler 'default' from pg-memory is not a function
[ERROR] Handler 'default' from self-learning is not a function

原因：Skill 的 hook 入口文件导出格式与 Gateway 期望不一致。Gateway 期望 default 是函数，但实际导出的是对象或其他类型。

5. 向量记忆降级

[memory] chunks_vec not updated — sqlite-vec unavailable. Vector recall degraded.

sqlite-vec 扩展未安装，向量检索降级为文本匹配，不影响对话但记忆精度下降。

🔧 四、修复措施

立即修复：重启 Gateway

openclaw gateway restart

效果：

• Session 状态重置，卡死会话自动恢复
• 钉钉 Stream 重新连接成功
• 模型 fallback 链重新初始化

重启后日志：

[07:26:26] [INFO] gateway ready
[07:26:26] [INFO] heartbeat: started
[07:26:27] [INFO] [default] DingTalk Stream client connected successfully
[07:26:27] [INFO] [default] DingTalk Stream client connected successfully
[07:27:22] [INFO] ⇄ res ✓ chat.history 26358ms

根本修复

1. 更新 Bailian API Key 登录阿里云百炼控制台，获取新的 API Key，并更新到 models.providers.bailian.apiKey
2. 修复 MiniMax 认证 检查 minimax 账号的 key 是否还有效，考虑切换到新的认证方式
3. 清理过期 fallback 模型 从配置中移除已失效的 bailian 模型，避免无效尝试浪费资源
4. 修复 Hook 注册 检查 pg-memory 和 self-learning 的导出格式，确保 handler.default 是函数

📊 五、监控与预防

关键监控指标

# 定期检查 session 状态
openclaw sessions list | grep -E "stuck|processing"

# 检查模型可用性
curl -s --max-time 10 -X POST "https://api.minimaxi.com/anthropic/v1/messages" \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"MiniMax-M2.7","messages":[{"role":"user","content":"test"}],"max_tokens":5}'

# 检查 bailian API
curl -s --max-time 10 "https://coding.dashscope.aliyuncs.com/v1/models" \
  -H "Authorization: Bearer <key>"

建议的 Cron 健康检查

# 每小时检查 Gateway 和通道状态
cron:
  - name: "health-check"
    schedule: "0 * * * *"
    payload:
      kind: "systemEvent"
      text: "健康检查：检查 gateway status、channels、模型可用性"

配置改进建议

{
  "agents":{
    "defaults":{
      "model":{
        "primary":"minimax/MiniMax-M2.7",
        "fallbacks":[
          "minimax/MiniMax-M2.5",
          "minimax/MiniMax-M2.1"
        ],
        "timeoutMs":30000,
        "maxRetries":2
      }
    },
    "session":{
      "maxProcessingTimeMs":300000,
      "autoAbortStuck":true
    }
}
}

📚 六、关键命令速查

场景	命令
查 Gateway 状态	openclaw gateway status
查通道连接	openclaw channels status dingtalk
查 cron 任务	openclaw cron list
查活跃 session	openclaw sessions list
重启 Gateway	openclaw gateway restart
查详细日志	tail -f /tmp/openclaw/openclaw-YYYY-MM-DD.log
查错误日志	tail -100 ~/.openclaw/logs/gateway.err.log
验 API 可用性	curl -s -X POST <endpoint> -H "Authorization: Bearer <key>" ...
查配置	openclaw config get agents.defaults.model

🎯 七、经验总结

1. Session 卡死要先查日志中的 stuck session age= 值持续增长是核心信号，说明 LLM 请求卡住了
2. 多级 fallback 全部超时 = 提供商级故障 8 个 bailian 模型全挂 → API Key 过期，不是单个模型的问题
3. 钉钉断连通常随 Gateway 重启自动恢复 钉钉 SDK 有内置重连机制，只要 Gateway 自身健康
4. 重启是排查卡死的万能解 在确认 Gateway 进程正常的情况下，重启可以重置所有 session 状态
5. Hook 注册失败不影响核心功能 pg-memory 和 self-learning 的 hook 挂了，但对话本身不受影响

📎 附录：完整日志时间线

04:44  bailian/kimi-k2.5 → 401 invalid_api_key (第一个失败)
05:00  钉钉 Stream 断连 (attempt 1)
05:16  主会话卡死 age=971s，开始 fallback
05:32  钉钉心跳丢失，触发 reconnection
06:01  钉钉再次 reconnection
06:18  钉钉再次 reconnection
06:34  主会话卡死 age=1977s
06:50  钉钉 reconnection
07:11  主会话卡死 age=2251s，M2.1 也超时
07:25  Gateway 重启开始
07:26  Gateway ready，钉钉连接成功
07:27  会话恢复正常
07:33  用户确认问题已修复

本文参与腾讯云自媒体同步曝光计划，分享自微信公众号。

原始发表：2026-04-30，如有侵权请联系 cloudcommunity@tencent.com 删除

日志