为什么要为 OpenClaw 建立“可操作”的错误处理体系

在真实项目里，错误不是“偶发事件”，而是系统运行的常态：网络抖动、第三方接口限流、数据不一致、权限问题、磁盘空间不足、配置变更、版本升级引入的不兼容……如果只是简单地 try/catch 然后打印日志，很快会陷入三个困境：

1. 错误不可度量：你不知道哪些错误占比最高、是否在变多、是否集中在某一类资源或某一时间段。
2. 错误不可恢复：同样的失败不断出现，却没有重试、降级或补偿机制。
3. 错误不可追踪：一次任务涉及多个步骤/多个节点时，难以还原链路与根因。

本篇作为《OpenClaw教程：从入门到实战的分层学习路线》中的实战型章节，聚焦：异常分类 → 降级策略 → 失败重放（重试/补偿/回放），给出可落地的规范、决策表与实现步骤。你可以直接把本文当作团队约定的“错误处理设计文档模板”。

一、异常分类：先把“失败”分清楚

错误处理体系的第一步是“分类”。分类的目的不是学术，而是为了让系统能自动选择：要不要重试、要不要降级、要不要中止、要不要触发告警与回放。

1.1 推荐的异常大类（面向 OpenClaw 任务流）

在 OpenClaw 的任务/工作流语境下，你可以将异常归为 6 大类：

（1）输入与参数类（InputError）

• 典型：缺少必填字段、参数格式不合法、文件路径不存在、数据 schema 不匹配
• 处理倾向：不重试（重试不会改变输入），直接失败并返回明确错误信息
• 需要：错误定位到字段/行号/步骤

（2）依赖与外部服务类（DependencyError）

• 典型：HTTP 5xx、超时、DNS 失败、第三方接口限流 429、数据库连接中断
• 处理倾向：多数可 重试，但要区分“可重试/不可重试”子类

（3）资源与运行环境类（ResourceError）

• 典型：内存不足、磁盘满、线程池耗尽、句柄耗尽、容器 OOMKill
• 处理倾向：通常 短期重试也无效，更适合快速失败 + 触发扩容/释放资源/排队限速

（4）业务规则类（BusinessError）

• 典型：订单状态不允许变更、幂等冲突、库存不足、黑名单命中
• 处理倾向：不重试，要把业务原因可视化（给上游或运营/用户看得懂）

（5）一致性与并发类（ConsistencyError）

• 典型：乐观锁失败、并发写冲突、读到旧数据导致校验不通过
• 处理倾向：通常 可重试，但要有次数/退避，并避免热点放大

（6）未知与缺陷类（UnknownError / Bug）

• 典型：空指针、越界、断言失败、未覆盖分支、序列化异常
• 处理倾向：默认不自动重试（避免无限放大），优先收集上下文并快速告警

1.2 进一步细分：可重试 / 不可重试 / 可降级

为了让 OpenClaw 的执行器在运行时能做自动决策，建议每个异常都落到三个维度的“标签”：

• retryable：是否可重试（true/false）
• degradable：是否允许降级（true/false）
• fatal：是否必须立即中止（true/false）

一个实用的决策表如下（可直接放进项目 wiki）：

在 OpenClaw 教程实践里，你可以把这套分类落到统一的错误对象（例如 ErrorCode + Metadata），这样“工作流引擎/节点”不用硬编码具体异常类型。

二、标准化错误结构：让失败能被统计、检索、回放

仅靠字符串日志无法支撑自动化。建议你为 OpenClaw 的每一次失败生成结构化字段（即便底层语言不同，概念一致）。

2.1 建议的错误字段（最小可用集合）

• error_code：稳定的错误码（例如 DEP_TIMEOUT, BIZ_INVENTORY_SHORT, INPUT_SCHEMA_INVALID）
• error_type：对应上文的大类（DependencyError/BusinessError…）
• message：人类可读信息（包含关键参数，但避免敏感信息）
• step_id / node_id：失败发生在哪个节点/步骤
• run_id：一次工作流执行的唯一 ID
• trace_id：跨服务追踪用
• retryable / degradable / fatal
• context：用于排障与回放的上下文（输入摘要、依赖响应摘要、环境信息）

2.2 错误码设计建议（避免后期失控）

1. 错误码要稳定：不要把具体异常消息当错误码。
2. 按域划分前缀：例如 DEP_、DB_、BIZ_、INPUT_、SYS_。
3. 每个错误码绑定处理策略：至少包含“是否重试/最大次数/退避方式/是否告警”。

三、降级策略：失败不等于不可用

降级不是“把功能关掉”，而是让系统在能力受限时仍保持核心链路可用，且结果可解释、可追溯。

3.1 OpenClaw 场景下常见的降级方式

（1）结果降级：用“可接受的替代结果”

• 例：第三方画像服务不可用时，使用本地缓存画像或默认画像
• 适用：对精度要求不高，但对时效/稳定性要求高

（2）路径降级：走备用链路/备用依赖

• 例：主数据库读超时 → 读只读副本；主模型服务不可用 → 使用轻量模型
• 适用：有多套依赖且切换成本低

（3）能力降级：减少耗时或消耗

• 例：批处理任务从“全量计算”降级为“增量计算”；或减少并发、缩小批次
• 适用：资源紧张、限流时期

（4）延迟降级：把“同步”变成“异步”

• 例：实时写入失败 → 写入消息队列，稍后补偿
• 适用：强依赖不稳定但业务允许最终一致

3.2 降级触发条件：别靠拍脑袋

建议你在 OpenClaw 中引入“触发器”概念（可以是配置或策略组件），常用指标：

• 依赖错误率：例如 1 分钟内 DEP_TIMEOUT > 5%
• P95/P99 延迟：例如 P95 > 2s
• 资源水位：CPU > 80% 持续 3 分钟；队列堆积长度超过阈值
• 熔断状态：某依赖进入 open 状态

一旦触发，工作流节点在执行前就能判断：走主路径还是降级路径。

3.3 为每个关键节点准备“降级输出契约”

降级要可用，关键在于契约：上游/下游必须能识别这是降级结果。

建议输出包含：

• is_degraded: true/false
• degrade_reason：触发原因（如 CIRCUIT_OPEN, TIMEOUT_BURST）
• data_version 或 confidence_level：标明可信度

这样后续分析能区分：“业务真实变化” vs “系统降级导致的质量变化”。

四、失败重放：重试、补偿与回放三件事要分开

很多系统把“重试”当作全部，但在工作流系统里更推荐拆成三层能力：

1. 重试（Retry）：同一步骤、同一请求，过一会再来一次。
2. 补偿（Compensation）：已经产生副作用，需要撤销或对冲。
3. 回放（Replay）：在相同输入/相同版本下重新执行（可能跨天、跨版本，面向排障或补数）。

4.1 重试策略：别把依赖打崩

（1）退避算法建议

• 指数退避 + 抖动（Jitter）：最通用，避免雪崩
• 固定间隔：只适用于很稳定、失败原因明确的场景

一个可落地的配置示例（概念）：

• 最大重试次数：3
• 初始等待：200ms
• 退避倍数：2
• 最大等待：5s
• 抖动：±30%

（2）按错误码决定是否重试

• DEP_TIMEOUT：重试 true
• DEP_429_RATE_LIMIT：重试 true，但要更长退避并尊重 Retry-After
• DEP_401_UNAUTHORIZED：重试 false（更可能是配置/过期密钥）
• INPUT_SCHEMA_INVALID：重试 false

（3）重试要做幂等

如果一次节点执行可能产生副作用（写库、扣款、发送消息），必须做到：

• 幂等键（idempotency key）：run_id + step_id + business_key
• 写入前先检查是否已成功
• 或使用“去重表/幂等记录”

否则重试会制造重复扣款、重复发货等灾难。

4.2 补偿策略：把“回滚”前置设计

工作流中经常遇到：步骤 A 成功、步骤 B 失败，此时系统处于“半完成”。补偿提供两类解法：

（1）反向操作补偿（SAGA 模式常见）

• 例：已创建订单 → 失败后执行取消订单
• 要点：补偿操作也要幂等；补偿也可能失败，需要重试与人工介入

（2）对冲补偿（无法真正回滚时）

• 例：已经发送通知无法撤回 → 再发送“更正/撤销”通知
• 适用：外部系统不支持回滚

建议在 OpenClaw 每个有副作用的节点旁边，定义一个 compensate() 分支，写清楚：

• 触发条件
• 补偿动作
• 最大重试
• 失败后如何升级（人工工单/告警）

4.3 回放（Replay）：用于排障、补数与恢复

回放与重试的核心区别：

• 重试通常发生在同一次运行内，短时间内完成；
• 回放可能发生在运行结束后，用于补数、纠错、或在修复 bug 后重新跑。

（1）回放需要“可重现输入”

建议将每个 run 的关键输入进行持久化：

• 原始请求（或其哈希+存储引用）
• 配置快照（当时的阈值、开关、路由规则）
• 依赖版本信息（模型版本、接口版本）

否则你无法回答：为什么同样的请求今天成功、昨天失败。

（2）回放需要“版本隔离”

如果代码或配置变化了，回放结果可能不同。实操建议：

• 给工作流定义 workflow_version
• 回放时允许指定版本：按原版本跑（用于复现）或按新版本跑（用于补数）

（3）回放的边界：避免重复副作用

回放常用于补数据，但也可能误触发外部动作。建议提供三种回放模式：

• Dry-run：只执行计算，不写外部（用于验证）
• Write-internal：只写内部存储，不触发外部系统
• Full-run：完整执行（必须强幂等与授权审批）

五、把体系落地到 OpenClaw：一套可执行的实现步骤

下面给出一套从 0 到 1 的落地步骤，你可以按顺序在项目里推进。

5.1 第一步：定义错误码与策略映射表

建立一份表（配置文件/数据库均可），每行包含：

• error_code
• error_type
• retryable、max_retries、backoff_policy
• degradable、degrade_plan_id
• alert_level（none/warn/critical）

这样执行器只要拿到 error_code，就知道下一步动作。

5.2 第二步：为每个节点定义“失败出口”

对每个 OpenClaw 节点（步骤）至少定义三条路径：

• success：正常输出
• handled_failure：可预期失败（已分类、有策略）
• unhandled_failure：未知失败（进入兜底告警与终止）

并明确：handled_failure 是否允许继续后续步骤（例如走降级结果继续跑）。

5.3 第三步：实现统一的错误封装与上下文采集

要求所有节点抛出的异常最终转换为统一结构：

• 自动补齐 run_id/step_id/trace_id
• 采集 context：输入摘要、依赖请求 ID、响应码、耗时、机器信息
• 对敏感字段脱敏（token、手机号、身份证）

这一步能显著提升排障效率，也是失败回放的基础。

5.4 第四步：加入熔断与限流，配合降级

对于外部依赖（HTTP/DB/模型服务），建议至少具备：

• 超时控制（连接超时、读超时）
• 并发上限（线程池/连接池）
• 熔断（错误率/超时率触发）
• 限流（令牌桶/漏桶/队列长度）

当熔断打开时，节点不应继续“硬打依赖”，而应快速返回降级结果或进入延迟降级（入队等待补偿）。

5.5 第五步：构建失败队列与回放工具

把“最终失败（超过重试/不可恢复）”写入失败队列或失败表，至少包含：

• run_id、step_id、error_code
• 原始输入引用
• 最后一次失败的上下文
• 建议动作（重放/补偿/人工）

配套一个回放工具（CLI/控制台均可）：

• 按时间、错误码筛选
• 支持选择回放模式（dry-run/write-internal/full-run）
• 支持指定版本与并发
• 生成回放报告（成功数、失败数、失败原因分布）

六、示例：从一次“依赖超时”走完分类→降级→回放

假设工作流中有一步“拉取用户画像”，调用外部画像服务：

1. 发生超时，节点捕获异常并映射为 DEP_TIMEOUT（DependencyError）。
2. 策略表命中：retryable=true, max_retries=3, backoff=exp+jitter。
3. 重试 3 次仍失败，触发降级：读取本地缓存画像（is_degraded=true, degrade_reason=TIMEOUT），流程继续。
4. 同时把该 run 记录到“降级事件”指标里：用于监控画像服务健康度。
5. 若缓存也不可用，则进入最终失败：写入失败表，标记 suggested_action=replay。
6. 画像服务恢复后，通过回放工具对失败表中 DEP_TIMEOUT 的记录进行批量回放：选择 write-internal，只补齐内部画像存储，不触发外部通知。

这一整套流程的关键价值：用户侧尽量不受影响（降级），系统侧数据可补（回放），团队侧可定位（结构化错误与指标）。

七、检查清单：上线前必须过的 10 个问题

1. 每个失败是否都有稳定 error_code？
2. 是否能区分 retryable 与 non-retryable？
3. 重试是否有退避与抖动？是否有总时长上限？
4. 会产生副作用的节点是否幂等？
5. 是否有熔断/限流，防止重试放大故障？
6. 关键节点是否有明确的降级输出契约？
7. 降级是否会被监控统计（否则降级会掩盖问题）？
8. 是否记录可回放的输入与配置快照？
9. 是否提供 dry-run 回放，避免误写外部系统？
10. UnknownError 是否能自动收集足够上下文并触发告警？

结语：把“失败”当成产品能力的一部分

在 OpenClaw 的工程化落地中，错误处理不是附属功能，而是决定系统可用性、可维护性与可扩展性的核心能力。通过“异常分类 + 策略化降级 + 失败重放”，你能把不可控的线上故障，变成可度量、可恢复、可演进的工程流程。