OpenClaw 博客流水线 v2.5：从模型降级到路由规则的完整修复

背景：从一次异常模型调用说起

博客流水线在运行中，日志突然弹出异常：design-image-prompt-engineer 子 agent 使用的模型是 step-router-v1，而非我们明确配置的 agnes-2.5-flash。这个模型降级直接导致生成图片质量严重不达标，封面图构图混乱、元素缺失，整个发布流程被迫中断。

问题一：子 Agent 模型降级

表象

design-image-prompt-engineer 是负责将文章摘要转化为高质量图片 prompt 的专用 agent。按理说它应该继承主 agent 的模型配置 agnes-2.5-flash，但实际运行中它却使用了 step-router-v1 这个轻量模型。

直观表现：生成的图片充满伪影，构图偏离文字描述，对中文 prompt 的理解能力明显不足。

根因定位

在 openclaw.json 中定位到问题所在：

{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "step-router-v1"
      }
    }
  }
}

agents.defaults.subagents.model 配置了所有子 agent 的默认模型。当这个配置被设置为 step-router-v1 时，新建的所有子 agent（包括 design-image-prompt-engineer、kb-writer 等）都会继承这个轻量模型，而非我们期望的旗舰模型。

修复方案

将默认模型由 step-router-v1 改为 agnes-2.5-flash：

{
  "agents": {
    "defaults": {
      "subagents": {
        "model": "agnes-2.5-flash"
      }
    }
  }
}

这一行修改确保了所有子 agent 默认使用正确的模型，避免了因模型降级导致的图片质量问题。

问题二：中文 Slug 的 URL 编码陷阱

现象

博客文章《鬼谷子：七种示弱术》在 Hugo 部署时彻底失败，页面返回 404 错误。检查 Cloudflare Pages 日志发现，部署过程中出现了 %8N 这样的非法 URL 编码错误。

根因

Hugo 在生成静态页面时，会将中文 slug 进行 URL 编码。但中文 slug 中的某些字符（如 鬼、谷）的 UTF-8 编码字节在转义时，会产生 %XX 这样的编码序列。当这些序列中的十六进制字符恰好落在某些边界条件时，会生成 %8N 这样的非法编码——%8 后跟 N，而 N 不是合法的十六进制字符（0-9, A-F）。

修复

所有 slug 统一使用英文小写连字符格式，将 鬼谷子七种示弱术》改为 guiguzi-money-wisdom-baihe-feiqian-wuhe`。

这个修复不仅解决了当前的部署失败问题，还带来了额外好处：

• URL 更友好、可读性强
• 避免 SEO 排名因 URL 编码遭受损失
• 第三方引用时链接稳定

问题三：图片路径规范化

在修复过程中，发现图片路径存在不一致问题。封面图有的使用 featured-image.webp，有的使用 cover.webp，有的直接 slug 名。这导致 Hugo 的 resources 配置和 featuredImage 字段难以统一配置。

规范化方案

统一封面图命名为 {slug}.webp，resources 和 featuredImage 字段同步引用：

resources:
  - name: featured-image
    src: "{slug}.webp"
  - name: featured-image-preview
    src: "{slug}.webp"
featuredImage: "/images/Code-Art-Studio-images/{slug}/{slug}.webp"
featuredImagePreview: "/images/Code-Art-Studio-images/{slug}/{slug}.webp"

问题四：图片后处理脚本增强

原先的 post_process_image.py 只负责基本的图片处理（压缩、格式转换），但缺少两个关键能力：

1. 原图没有归档保存：一旦处理完成，原图就被覆盖，无法回溯
2. 临时文件残留：每次运行后在 /tmp/ 下留下大量中间文件

增强方案

from pathlib import Path
import glob
import shutil

# 新增原图归档功能
archive_dir = Path(image_dir, slug, "originals")
archive_dir.mkdir(parents=True, exist_ok=True)
shutil.copy2(original_path, archive_dir / f"{timestamp}.webp")

# 自动清理临时文件
for f in glob.glob("/tmp/blog_*"):
    Path(f).unlink(missing_ok=True)

增强后的脚本：

• 处理前将原图归档到 {slug}/originals/ 目录，带上时间戳
• 处理完成后自动清理 /tmp/ 下的临时文件
• 保留最近 3 份原图备份，自动删除更早的版本

问题五：路由规则升级到 v2.5

旧版问题

blog-pipeline 的路由规则在 v2.0 时将所有技术文章统一放入 code-art-studio/ 目录下，没有进一步细分。大量文章堆积在同一个目录下，当文章数量超过 30 篇后，管理变得极其困难。

v2.5 路由规则

OpenClaw 相关文章 → code-art-studio/openclaw/（扁平目录）
其他技术文章 → code-art-studio/{子分类}/（子目录结构）
非技术文章 → digital-asset/{子分类}/

这套规则的核心逻辑：

• OpenClaw 专属目录：所有 OpenClaw 生态相关的文章（配置、排障、工作流、Agent 等）统一归入 openclaw/ 子目录，采用扁平结构——因为 OpenClaw 内部主题繁多但文章数量有限，再细分反而增加管理成本
• 其他技术文章：按子分类建立目录结构，如 Docker 相关的归入 code-art-studio/docker/
• 非技术文章：归入 digital-asset/ 分类下的对应子目录

实现细节

# 路由判断逻辑
if [[ "$category" == "Code Art Studio" ]]; then
  if [[ "$keywords" =~ (openclaw|AI|agent|DAG) ]]; then
    POST_DIR="$BASE_DIR/code-art-studio/openclaw/"
  else
    POST_DIR="$BASE_DIR/code-art-studio/${subcategory}/"
  fi
fi

总结

这次修复从五个维度完整优化了博客流水线：

这五个修复看着各管各的，其实一环扣一环——模型配置影响图片质量，图片质量影响封面图，封面图命名影响路径规范，路径规范影响路由规则。一条博客流水线，本质上是多个子系统协同工作的结果，任何一个环节的偏差都会传导到最终输出。

关联阅读

• [[OpenClaw 多智能体博客流水线：从 4.5 小时到 15 分钟的优化实战]]
• [[OpenClaw 博客流水线 v2.1 修复全记录：模型降级、动态路由与并发限制规避]]
• [[多智能体博客流水线架构设计：从 Skill 到 DAG 的演进]]

参考来源

• Hugo URL 编码规范
• OpenClaw Multi-Agent 配置文档
• Cloudflare Pages 部署错误排查