Snapback

OpenClaw 的 Snapback 自愈拦截器

mcp-name: io.github.ra1labsworkx-wq/snapback

让 Snapback 自动运行。 不必再记得调用诊断工具，只需为 Agent 的工具调用添加一次封装——每次错误都会自动诊断，并在通过安全门控时应用修复，然后自动重试，无需人工介入。

“强大的工具可有可无，基础设施不可或缺。” 这让 Snapback 从一个你需要时才调用的工具，变成了每次故障时都会运行的基础设施。

连接 MCP 服务

Snapback 是托管的远程 MCP 服务——无需在本地运行任何内容。将其添加到任意 MCP 客户端（Claude Code、 Cursor、Cline、VS Code、Windsurf）。大多数工具免费且无需令牌。

{
  "mcpServers": {
    "snapback": {
      "url": "https://api.snapback.sh/mcp"
    }
  }
}

端点：https://api.snapback.sh/mcp（Streamable HTTP，JSON-RPC 2.0）。然后调用 tools/list（23 个工具），并使用 {"error": "dns nxdomain servfail"} 尝试 diagnose_infra_error → 返回 family: dns-tls 和经过验证的修复方案。

工具

免费（无需令牌）：diagnose_infra_error、detect_loop、budget_guard、search_docs、what_others_did、 recommend_failover、cascade_root、suggest_budget_recovery、convert_trace、preflight、session_start、 session_step、session_end、discovery。

按量计费（免费入门令牌或 x402）：diagnose_trace、diagnose_batch、get_verdict、submit_feedback、 report_outcome、request_pattern、my_usage、my_impact、agent_memory。

• diagnose_infra_error — 输入晦涩难懂的基础设施错误，即可获得错误类别和经过验证的修复方案（优先使用库，约 150ms，命中时不使用大模型）。支持 46 种错误类别。
• detect_loop — 在达到步骤上限前，于运行过程中捕获重复的工具调用循环。
• budget_guard — 在运行过程中捕获令牌数、步骤数、上下文或成本超限。
• what_others_did — 查看其他 Agent 针对某类故障的匿名处理结果。
• diagnose_trace — 对多步骤完整追踪记录进行诊断（按量计费）。

功能说明

出现任何工具调用错误时，拦截器会：

1. 调用 diagnose_infra_error（免费、无需令牌、不使用大模型，耗时 <150ms）。
2. 应用三重条件门控——仅当以下条件全部满足时，才自动应用修复：
   • confidence >= 0.85
   • source == "library"（来自经过整理和验证的修复方案，而非大模型猜测）
   • auto_safe == true（修复操作为 retry / refetch / config——可逆且无副作用）
3. 若通过门控 → 应用修复并重试一次。若未通过 → 转交人工处理（记录判定结果）。绝不会自动应用 mutate 或 destructive 修复（创建或更改状态、资金或授权）。

采取默认拒绝策略：无法确定时，会转交人工处理，而非自行操作。

安装

# no install needed beyond the stdlib; drop the file in, or:
cp snapback_interceptor.py your_agent/
export SNAPBACK_MCP=https://api.snapback.sh/mcp   # default; the free tools need no token

使用

from snapback_interceptor import SnapbackInterceptor

heal = SnapbackInterceptor(
    auto_apply=True,
    on_escalate=lambda v: my_ops_inbox.log(v),   # human sees non-auto-safe verdicts
    on_heal=lambda v: metrics.count("snapback.autoheal", family=v["family"]),
)

# wrap any call that might raise:
result = heal.run(call_solana_rpc, wallet, amount)

# or as a decorator:
@heal.guard
def call_solana_rpc(wallet, amount): ...

# or manually on a caught error:
verdict = heal.diagnose("BlockhashNotFound")
if verdict["gate"]["auto_apply_ok"]:
    ...apply verdict["fix"] and retry...

门控约定（Snapback 返回）

diagnose_infra_error 返回 {matched, family, fix, confidence, source, action_class, auto_safe, gate}。 action_class 的取值如下：

类别	含义	是否自动安全？
retry	使用退避策略重新运行（幂等）	✅
refetch	重新获取／重新定价／重新同步后，再次应用	✅
config	更改客户端参数（提高 max_tokens、提供中间证书）	✅（可建议）
mutate	创建或更改外部状态、资金或授权	❌ 转交人工处理
destructive	删除／回退／执行不可逆操作	❌ 绝不

纵深防御（1.8.3）： 即使修复属于可逆类别，只要其文本中包含破坏性命令（删除 pod、清空密钥、删除表），也会降级为转交人工处理。门控会返回 gate.contains_destructive_step，因此无论其 action_class 如何，修复都绝不会自动执行破坏状态的步骤。

gate.auto_apply_ok 会直接给出是否可自动应用的判定结果；拦截器也会在本地重新判定，避免过度信任过期的客户端。

隐私与安全

• 100% 在客户端运行。仅调用免费的公开 diagnose_infra_error 端点。
• 诊断时绝不会发送你的 Snapback 令牌（诊断免费）。
• Snapback 会在服务端清理追踪记录内容；此处只会发送你传入的错误字符串。
• 可与 bridge.py（事后分析转发）配合使用——这是实时自愈层。

路线图

• 在重试结果中调用 submit_feedback（修复是否奏效？）→ 纳入共享库（网络效应）。
• Hermes + LangChain 适配器（相同的门控，不同的框架钩子）。