博客生图 Pipeline 排障实战：从卡住几小时到全自动 Fallback

f

本文记录了博客图片生成 pipeline 的完整排障过程。如果你也遇到过"生图命令跑了几小时没动静、session 反复 failed、每次都卡在 agnes-image 调用上"的问题，这篇笔记会帮你把整个链路梳理清楚。

一、症状：生图成了博客发布的最大卡点

博客发布的最后一步是生成封面图和文内插图。整套流程依赖 design-yuntianguang agent 调用 agnes-image skill 完成。

但最近一周，这一步成了整个 pipeline 的最大瓶颈：

• 一次生图请求发出去，几小时后没有任何结果
• sessions_list 显示 design-yuntianguang 的 session 状态是 failed
• 没有任何错误提示，调用方一直干等
• 重新发送请求，同样的问题再次发生

二、排查：三个根因逐个定位

2.1 根因 1：design-yuntianguang Session 反复 Failed

查看 sessions_list 返回的 design-yuntianguang session 记录，最近 5 个 session 中有 3 个状态是 failed，1 个是 done（但耗时 492 秒≈8 分钟），只有 1 个正常完成。

失败 session 的 trajectory 显示：agent 调用 agnes-image API 后，命令进入了后台执行模式，然后 agent 反复用 process tool 轮询进程状态，每次轮询 60-120 秒。轮询了几十次之后，session 超时崩溃。

关键发现：agent 不会在命令完成后自动恢复，它进入了一个"轮询 → 等待 → 再轮询"的死循环。

2.2 根因 2：Agnes AI 限流 + 无重试

Trajectory 中有一个关键错误：

500 rate_limit_check_failed (request id: 20260725024328300757629J1P1CFif)

Ages AI API 返回了 500 限流错误。但 agent 没有做限流判断，继续重试同样的请求，每次都被限流拒绝。

2.3 根因 3：模型漂移

失败的 session 中，model 从初始的 agnes-2.0-flash 漂移到了 LongCat-2.0。这意味着 OpenClaw 在原始模型不可用或超时时自动切换到了备用模型。而备用模型对 agnes-image 脚本的调用方式理解不同，进一步加剧了不稳定。

三、解法：五层防护网

第 1 层：安全包装脚本（超时 + 重试 + 退避）

创建 agnes_image_safe.py 替代直接调用 agnes_image.py：

• 2 次自动重试：命令失败或超时后自动重试
• 指数退避：遇到限流错误时，等待 5s → 10s 再重试，避免被持续限流
• 硬超时 120 秒：每次调用不超过 2 分钟，超时立即失败
• 自动 PIL 后处理：下载 PNG → Resize 到精确尺寸 → WebP quality=95 → 重命名 → 删除临时文件

python3 ~/.openclaw/skills/agnes-image/scripts/agnes_image_safe.py \
  --prompt "A strategic visual representation..." \
  --size "1360x768" \
  --output-dir "/data/oklifeme/static/images/Code-Art-Studio-images/{slug}" \
  --slug "{slug}" \
  --is-cover true \
  --max-retries 2 \
  --timeout 120

第 2 层：前置检查（Dry-Run）

正式生图前先执行 3 个快速检查：

1. AGNES_AI_API_KEY 是否存在且格式正确
2. STEPFUN_API_KEY 是否存在（用于 fallback）
3. 输出目录是否可写

如果 agnes-image key 缺失，直接走 step-image，省掉无效等待。

第 3 层：反轮询规则

在设计 agent 的配置文件中明确禁止轮询行为：

⚠️ 禁止使用 process tool 轮询！所有命令直接用 exec + timeout，失败即报错

之前 agent 反复调用 process(action=poll, timeout=120000) 轮询后台进程，每次轮询本身就要等 2 分钟，轮询几十次就是几小时。改为直接用 exec + timeout 参数，命令失败立即返回错误。

第 4 层：限流快速降级

当 agnes-image 返回限流错误或超时时，立即降级到 step-image，不反复重试：

agnes-image 失败 → 等待 5s → 重试一次 → 仍失败 → 立即调 step-image API

整个降级链路不超过 30 秒。

第 5 层：明确角色分工

修正了 agent 间的职责边界：

• kb-writer：不直接生图，只负责编写 prompt 和委托 design-yuntianguang
• design-yuntianguang：唯一的生图执行者，内部按 agnes-image → step-image 顺序执行
• 设计 agent 优先使用 agnes-image，step-image 仅作为临时 fallback（已知 step-image 服务月底停运）

四、配置变更清单

五、关键教训

5.1 不要让 Agent 无限轮询

Agent 的默认行为是"命令在后台运行 → 轮询等待完成"。如果后台命令本身有超时或卡住，轮询就会无限持续。必须在配置文件中明确禁止轮询，改用同步执行 + 硬超时。

5.2 限流错误要分类处理

rate_limit_check_failed 和 timeout 是两种不同的失败模式：

• 限流：需要等待后重试，用指数退避（5s → 10s → 20s）
• 超时：可能是 API 暂时不可用，应立即降级到备用方案

不要把两种错误混为一谈，都"重试就完了"。

5.3 Fallback 链要短且确定

agnes-image → step-image → 失败报告，这条链路不超过 3 步，每步都有明确的失败条件和下一步动作。不要设计"智能选择"或"自动重试 N 次"——简单确定的规则比聪明的策略更可靠。

5.4 角色边界要硬

“kb-writer 不生图，design-yuntianguang 是唯一生图执行者”——这条规则必须写在配置文件里，不能靠"理解"。之前 kb-writer 自己调 step-image 生图，违反了角色边界，导致流程混乱。

六、后续：step-image 停运后的准备

step-image 服务预计 8 月中旬停运（最晚 8 月 15 日）。届时 agnes-image 将成为唯一的图片生成来源。

已做的准备工作：

• agnes-image 安全包装脚本经过完整测试
• 限流退避策略已验证有效
• 工作流不依赖 step-image

待观察：

• agnes-image 的余额/配额能否支撑日常博客发布
• 如果 agnes-image 也出现大规模故障，是否有备选方案

关联阅读

• [[openclaw-multi-agent-pipeline-g1-g2-gate-skip]] — Multi-Agent Pipeline 排障的另一案例
• [[2026-07-20-1918-openclaw-multi-agent-pipeline-g1-g2-gate-skip]] — sessions spawn 排查与修复

参考来源

• OpenClaw 官方文档：Agent 配置与 Session 管理
• Agnes Image API 文档：限流策略与错误码说明
• StepFun API 文档：step-image-edit-2 接口说明
• 本文基于 2026-07-25 的实际排障过程记录

–全文完–

若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：　　　《内容已折叠，点击展开》

希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。　　　　　　　　　　　　　　　　　　　　　《内容已折叠，点击展开》

“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”

转载请注明来自https://oklife.me。