为什么错误处理如此重要？
凌晨3点17分，你的Agent正在帮用户处理重要任务。突然，OpenAI API返回503错误。然后呢？
- 没有错误处理：Agent崩溃，用户看到"Internal Server Error"，可能永远不再使用你的产品
- 有错误处理：自动重试，如果还是失败，切换到Claude，用户甚至不知道发生过问题
错误处理不是可选项，而是生产环境的生命线。
🚨 统计数据：根据AWS的数据，99.95%的API服务每年至少经历4.4小时的停机时间。没有容错机制，你的Agent必然会在某个时刻挂掉。
错误类型全景图
按来源分类
| 错误类型 | 典型原因 | 处理策略 |
|---|---|---|
| 网络错误 | 连接超时、DNS失败 | 重试+指数退避 |
| API限流 | 429 Too Many Requests | 等待Retry-After |
| 服务端错误 | 500/502/503 | 降级到备用模型 |
| 内容过滤 | 触发安全策略 | 改写prompt/换模型 |
| 上下文溢出 | Token超限 | 压缩/分段处理 |
| 工具执行失败 | 工具bug/权限问题 | 返回错误给LLM重试 |
重试策略详解
指数退避重试
import { Agent, RetryPolicy } from 'openclaw';
const agent = new Agent({
retryPolicy: RetryPolicy.exponential({
maxRetries: 3,
baseDelay: 1000, // 初始延迟1秒
maxDelay: 30000, // 最大延迟30秒
multiplier: 2, // 每次延迟翻倍
jitter: true // 添加随机抖动防止惊群效应
})
});
// 等效的延迟序列: 1s → 2s → 4s (带随机抖动)可重试的错误
agent.setRetryableErrors([
'ECONNRESET',
'ETIMEDOUT',
'ENOTFOUND',
'rate_limit_exceeded',
'server_error',
'model_overloaded'
]);
// 对于内容过滤等错误，不应该重试
agent.setNonRetryableErrors([
'content_policy_violation',
'invalid_api_key',
'context_length_exceeded'
]);降级策略
模型级联降级
agent.setFallbackChain([
{ model: 'gpt-4-turbo', priority: 1 },
{ model: 'claude-3-5-sonnet', priority: 2 },
{ model: 'gpt-3.5-turbo', priority: 3 },
{ model: 'local-llama3', priority: 4 }
]);
// 当GPT-4失败时，自动切换到Claude
agent.on('fallback', (from, to, error) => {
console.warn(`${from} → ${to}: ${error.message}`);
// 可选：通知监控系统
metrics.increment('agent.fallback', { from, to });
});功能降级
当核心功能不可用时，降级到基础功能：
agent.on('tool_error', async (toolName, error) => {
if (toolName === 'web_search') {
// 搜索服务不可用，降级到使用缓存
return await agent.useTool('cache_search');
}
if (toolName === 'code_execution') {
// 代码执行不可用，只返回伪代码
return { type: 'pseudocode', content: '代码执行服务暂时不可用' };
}
// 其他工具失败，返回错误让LLM处理
return { error: error.message };
});优雅降级用户体验
给用户明确的信息
agent.onError((error) => {
const userMessage = {
'rate_limit': '服务繁忙，请稍后再试',
'content_filter': '您的内容触发了安全策略，请修改后重试',
'context_length': '内容过长，请精简后重试',
'default': '服务暂时不可用，请稍后再试'
};
return {
userMessage: userMessage[error.code] || userMessage.default,
retryable: error.retryable,
suggestedAction: error.suggestedAction
};
});自动保存状态
⚠️ 重要：当Agent崩溃时，确保用户的工作状态可以恢复。OpenClaw的Session机制会自动保存对话历史。
agent.enableSessionRecovery({
autoSave: true,
saveInterval: 30000, // 每30秒保存一次
onSave: (session) => {
console.log(`Session ${session.id} saved, ${session.messages.length} messages`);
},
onRecover: (session) => {
console.log(`Session ${session.id} recovered`);
return session.lastActiveState;
}
});监控与告警
错误率监控
agent.setMetrics({
errorRateThreshold: 0.05, // 错误率超过5%告警
latencyThreshold: 10000, // 延迟超过10秒告警
alertChannel: 'slack',
onAlert: (alert) => {
console.error(`ALERT: ${alert.type} - ${alert.message}`);
}
});健康检查端点
// 暴露健康检查端点给负载均衡器
app.get('/health', async (req, res) => {
const health = await agent.healthCheck();
res.status(health.status === 'healthy' ? 200 : 503)
.json({
status: health.status,
models: health.models,
latency: health.latency,
errorRate: health.errorRate
});
});最佳实践清单
- ✅ 为所有外部调用设置超时
- ✅ 使用指数退避重试
- ✅ 配置至少一个备用模型
- ✅ 区分可重试和不可重试的错误
- ✅ 给用户明确的错误信息
- ✅ 记录所有错误到监控系统
- ✅ 设置合理的告警阈值
- ✅ 定期演练故障恢复
✅ 生产级配置模板：OpenClaw提供
agent.config.production预设，自动包含推荐的错误处理配置。
常见问题
Q: 重试次数设多少合适？
建议3次。太少可能错过临时性问题，太多会增加延迟和成本。
Q: 如何处理用户主动取消？
使用AbortController，让用户可以中断长时间运行的任务。
Q: 错误处理会增加多少开销？
几乎可忽略。重试逻辑是毫秒级的，主要开销是额外的API调用。