SIGPIPE 被说成欠费：错误归因如何把排障带沟里

OpenClaw 用户报了一个让人哭笑不得的 bug（#11722）：在本地执行 curl -I https://example.com 2>&1 | head -n 5 之后，Agent 告诉他——

⚠️ API provider returned a billing error — your API key has run out of credits or has an insufficient balance...

一条管道命令被 head 截断（SIGPIPE，exit code 141），跟计费没有半毛钱关系。但 Agent 言之凿凿地让用户去检查 API 余额。

到底发生了什么

curl | head -n 5 是很常见的用法。head 读完 5 行后退出，curl 继续往管道写数据时收到 SIGPIPE 信号，exit code 141。这是正常行为，不是错误。

但 OpenClaw 的错误归因逻辑不这么看。exec 工具拿到非零 exit code 后，这个结果被 Agent 的错误处理链路"解读"了。链路里有一个叫 sanitizeUserFacingText 的函数，以及与之配套的错误模式匹配逻辑。在某个环节，"进程非正常退出"被映射成了"API 计费错误"。

报告者说得很清楚：底层日志里写的是 SIGPIPE/exit 141，但呈现给用户的却是"计费错误"。两层之间的翻译出了问题。

为什么错误归因这么容易出问题

Agent 系统里的错误来源极度多样化。一条调用链上可能同时存在：

本地进程信号（SIGPIPE、SIGKILL、SIGTERM）
HTTP 状态码（402、404、429、500）
供应商自定义错误（"insufficient_quota"、"model_not_found"）
模型自身的输出（"I cannot complete this task"）
框架内部错误（上下文溢出、Token 超限）

这些错误在不同层级产生，但最终都要"翻译"成用户能理解的一句话。翻译的过程中，粒度信息丢了。

具体到 OpenClaw，错误处理的流程大致是：

exec 工具返回 exit code 141
→ Agent 运行时包装成错误对象
→ 错误对象经过 formatAssistantErrorText() 或 sanitizeUserFacingText() 
→ 被映射到一个预定义的"用户友好"消息模板
→ 显示给用户

问题出在映射规则太粗。SIGPIPE 的 exit code 141 大概率是被兜底规则捕获了——"无法分类的错误 → 检查是否是计费问题"。这种兜底规则在设计时可能是合理的（因为 402 错误确实是常见原因），但它不应该覆盖明确的本地信号。

真实的排障成本

错误归因错误不只是"显示了一条不对的消息"。它改变了排障方向。

收到"计费错误"的用户会做什么？登录 Anthropic Console 检查余额，登录 OpenAI Dashboard 看账单，搜索"OpenClaw billing error"，甚至给供应商提工单。全都是无用功。

正确的排障方向是：看 exec 命令的 exit code，查 SIGPIPE 的含义，理解管道截断是正常行为。但用户被带到了完全相反的方向。

如果这发生在一个跑自动化任务的场景——比如 Cron 任务里的管道命令触发了 SIGPIPE，Agent 把它报成计费错误，监控系统触发了"API 余额不足"告警，oncall 的工程师半夜爬起来查计费问题——浪费的就不只是一个用户的时间了。

怎么做更好的错误归因

几个原则。

优先级：具体的优先于模糊的。如果 exit code 明确是一个 Unix 信号（128 + signal number），就按信号归因。SIGPIPE（141）、SIGKILL（137）、SIGTERM（143）都是有明确含义的。只有在无法识别的情况下，才走兜底规则。

错误源标记。在错误对象里加一个 source 字段：local_exec、http_provider、framework_internal。不同来源的错误走不同的归因逻辑。来自 local_exec 的非零 exit code 不应该被映射到"API 计费问题"。

保留原始信息。不管"翻译"成什么用户友好消息，都要在某个地方保留原始的错误信息。用户看到"命令被 SIGPIPE 终止（通常是管道截断导致，如 | head）"比看到"计费错误"有用一百倍。

分层展示。给用户看一个简洁的概要，同时提供"查看详情"入口展示完整的错误上下文。Web UI 可以用折叠面板，Telegram 可以用追加消息。

更普遍的问题：Agent 的错误消息设计

Agent 系统面临一个矛盾：它要足够"聪明"来把技术性的错误翻译成普通用户能懂的语言，但翻译过程天然会丢信息。

传统软件的错误消息可以直接暴露技术细节——"Segmentation fault (core dumped)"，用户是开发者，看得懂。Agent 产品的用户可能不是技术人员，他们需要"出了点问题，我重试一下"这种消息。

但 OpenClaw 的定位比较特殊——它的用户群体大部分是开发者和技术爱好者。对这类用户，隐藏技术细节反而造成困扰。

一个可能的方案是提供"错误详细程度"配置：

{
  "display": {
    "errorVerbosity": "technical"  // 或 "friendly"
  }
}

technical 模式下，直接展示 exit code、信号名、原始错误消息。friendly 模式下，做翻译但附带"查看原始错误"链接。默认值根据用户画像来——如果用户是通过 CLI 安装的，大概率是技术用户，默认 technical。

OpenClaw 已有的修复方向

2026.2.6 的 CHANGELOG 里有一条相关的修复："Compaction/errors: allow multiple compaction retries on context overflow; show clear billing errors." 以及 #12309 报告的 sanitizeUserFacingText 误杀问题。

看起来错误展示层正在被重新审视。#11722 报告的 SIGPIPE 归因问题如果被修复，大概率会在错误分类链路里加一步"本地信号识别"，在套用 HTTP 错误模板之前先排除本地进程退出的情况。

参考链接

OpenClaw Issue #11722（SIGPIPE 被归因为计费错误）：https://github.com/openclaw/openclaw/issues/11722
Unix 信号与 Exit Code 对照：exit code = 128 + signal number