timing-up

使用 OpenClaw 管理 Halo Blog（一）：文章草稿与发布实战

最近我在做一件很具体、也很实用的事：让 OpenClaw 真正参与我的博客维护工作流。

最开始我以为只能像普通用户一样登录 Halo 后台，手动复制标题、粘贴正文、设置摘要、再点发布。后来查 Halo 官方文档时才确认：Halo 本身就提供了 RESTful API 和个人令牌（PAT）机制。这意味着，博客文章并不一定要靠 Web 后台手工操作，完全可以通过程序来管理。

这篇文章不讲空泛概念，重点记录一套已经实测可行的方案：

  • 用 Halo 个人令牌完成认证
  • 通过 Halo Console API 管理文章
  • 使用 OpenClaw 生成并写入文章内容
  • 最后完成文章发布

这篇是系列第一篇，先聚焦“文章草稿与发布”。后续再扩展图库、瞬间、归档、友链等能力。

一、目标与最终效果

本文要实现的目标很明确：

  1. 不登录 Halo Web 后台手动发文
  2. 由 OpenClaw 负责生成博客内容
  3. 通过 Halo 官方 API 完成：
    • 读取文章列表
    • 更新草稿元信息（标题、slug、摘要）
    • 更新正文内容
    • 正式发布文章

最终效果是：

给 OpenClaw 一个主题，它可以帮你生成文章，并直接写入到 Halo，必要时还能继续完成发布。

二、前置条件

开始之前，需要满足这些条件：

  • 你有一个可用的 Halo 2.x 站点
  • 你有一个拥有文章管理权限的账号
  • 你可以访问 Halo 的 个人中心 /uc
  • 你可以创建 个人令牌（PAT）
  • 你有一台可以运行 OpenClaw 的机器
  • 你愿意把 Halo PAT 专门分配给 OpenClaw 使用

我这次实际使用的是：

  • 博客地址：https://blog.timingup.dev
  • 管理方式：Halo 个人令牌（PAT）
  • 执行端：OpenClaw 所在服务器

三、Halo 官方提供了哪些能力

这里先给结论：Halo 官方是支持程序化管理博客的。

根据官方文档：

  • Halo 提供 RESTful 风格 API
  • Halo 的前端（Console、UC）与后端本身就是通过 API 交互
  • 推荐的认证方式是 个人令牌（PAT）
  • PAT 可以直接作为 Bearer Token 用于访问 Halo API

也就是说，这条路不是“曲线救国”，而是 Halo 官方认可的能力边界。

个人令牌入口

Halo 2.11 之后，个人中心提供了：

  • 个人资料
  • 通知配置
  • 个人令牌
  • 我的文章

你可以通过：

  • 后台左下角进入个人中心
  • 或直接访问：/uc

然后在 个人令牌 页面创建一个专门给 OpenClaw 用的 PAT。

官方参考文档

建议至少先看这几篇：

  • Halo 个人中心文档：<https://docs.halo.run/user-guide/user-center>
  • Halo RESTful API 介绍：<https://docs.halo.run/developer-guide/restful-api/introduction>
  • Halo 在线 API 文档：<https://api.halo.run>

四、这次实际用到的关键 API

这部分是整篇文章最核心的内容。实际接入时，我主要用到了 Halo Console API 下面这几组接口。

1）读取文章列表

GET /apis/api.console.halo.run/v1alpha1/posts

用途：

  • 查看已有文章和草稿
  • 获取文章 metadata.name
  • 获取 headSnapshot
  • 获取当前文章状态（草稿 / 已发布）

2）读取某篇文章当前内容

GET /apis/api.console.halo.run/v1alpha1/posts/{name}/content?snapshotName={snapshotName}

用途：

  • 读取指定文章在某个 snapshot 下的正文
  • 获取当前 raw、content、rawType
  • 为后续更新内容做准备

3）更新文章元信息

PUT /apis/api.console.halo.run/v1alpha1/posts/{name}

用途：

  • 更新标题
  • 更新 slug
  • 更新摘要
  • 更新文章配置项

这里要注意：这个接口不是只传一个简单对象，而是要按 PostRequest 结构提交。

4）更新正文内容

PUT /apis/api.console.halo.run/v1alpha1/posts/{name}/content

用途：

  • 更新 Markdown 原文
  • 更新渲染后的 HTML 内容
  • 指定 rawType

我这次实际测试里，PUT /content 是整个流程里最关键的一步。只要这一步通了，正文就能真正写进去。

5）发布文章

PUT /apis/api.console.halo.run/v1alpha1/posts/{name}/publish?headSnapshot={headSnapshot}

用途：

  • 把当前草稿对应的内容版本正式发布出去

这个接口要求带上当前文章的 headSnapshot，否则无法明确发布哪一个内容版本。

五、为什么我最后选择“先更新草稿，再发布”

一开始我以为最直接的方法是：

  • 创建一篇新文章
  • 一次请求把标题、正文、摘要全写进去
  • 然后直接发布

但实际测试后发现，这样并不稳。原因在于 Halo 的文章模型并不是一个简单的“标题 + 正文”表单，而是包含了：

  • Post 对象
  • Snapshot
  • headSnapshot / baseSnapshot
  • Console API 和内容接口的协同

所以更可靠的方案是：

  1. 先选定一个草稿
  2. 更新文章元信息
  3. 再更新正文内容
  4. 最后发布

这条路径的优点是：

  • 接口职责更清晰
  • 出错时更容易定位
  • 更接近 Halo Console 自己的工作方式

六、OpenClaw 侧的实现思路

这次我在 OpenClaw 工作区里写了一个脚本：

scripts/halo_post.py

它负责做这些事：

  1. 读取 Halo 文章列表
  2. 选定一个可复用的草稿
  3. 更新标题、slug、摘要
  4. 把 Markdown 正文和 HTML 内容一起写入
  5. 根据参数决定是否发布

这次用到的关键参数

  • --base-url：Halo 站点地址
  • --title：文章标题
  • --excerpt：文章摘要
  • --content-file：Markdown 正文路径
  • --reuse-post-name：指定使用哪个草稿
  • --publish：是否直接发布

七、实际命令示例

1）更新一个已有草稿，但不发布

HALO_PAT=你的PAT python3 scripts/halo_post.py \
  --base-url https://blog.timingup.dev \
  --reuse-post-name 文章ID \
  --title "你的标题" \
  --excerpt "你的摘要" \
  --content-file ./post.md

2）更新一个已有草稿并直接发布

HALO_PAT=你的PAT python3 scripts/halo_post.py \
  --base-url https://blog.timingup.dev \
  --reuse-post-name 文章ID \
  --title "你的标题" \
  --excerpt "你的摘要" \
  --content-file ./post.md \
  --publish

3）我这次实际验证的结果

这篇文章本身，就是通过这套流程发布出来的。

也就是说，这套链路不是“理论可行”，而是：

  • 已经实测
  • 已经能发
  • 已经能从 OpenClaw 侧完成一次真实发布

八、这次踩到的坑

这部分很重要，因为如果你也准备自己接 Halo，很可能会踩到同样的问题。

坑 1：不是所有接口都能直接乱用

Halo 的内容接口、Console 接口、底层内容模型接口，虽然看起来都和文章有关，但用途并不完全一样。

一开始如果直接对底层内容模型硬 POST / PUT，很容易出现：

  • 500 Internal Server Error
  • 502 Bad Gateway

这不代表 Halo 不支持，而是说明接口使用方式不对。

坑 2：创建草稿接口的行为不算特别直觉

在这次测试里，POST /apis/api.console.halo.run/v1alpha1/posts 这个接口有一个细节：

  • 空 body 比传 {} 更稳定

这类行为在官方 schema 里不一定写得非常直观，所以实测很重要。

坑 3：更新标题和更新正文不是一回事

很多系统里，标题和正文常常一起提交。

但在 Halo 这里：

  • 标题 / slug / 摘要 走 PUT /posts/{name}
  • 正文内容 走 PUT /posts/{name}/content

这意味着你必须按顺序理解它，而不是把它当成一个扁平表单接口。

坑 4：不要随便用简陋的 Markdown 转 HTML

如果你要同时写 raw 和 content，渲染层一定要认真处理。

否则就会出现：

  • 列表格式不对
  • 代码块丢失
  • Markdown 语法没正确转成 HTML
  • 页面可读性差

这也是这次改稿里专门补的一部分。

九、推荐的实际工作流

如果你想长期让 OpenClaw 参与博客维护，我推荐的顺序是：

第一阶段：自动生成内容

让 OpenClaw 帮你完成：

  • 标题
  • 摘要
  • 正文
  • 标签建议
  • Markdown 成稿

第二阶段：自动写入草稿

让 OpenClaw 通过 Halo API：

  • 更新草稿元信息
  • 更新正文
  • 返回 permalink 和状态

第三阶段：确认后发布

如果你想保守一点：

  • 先看草稿
  • 再决定要不要正式发布

如果你已经很信任这条链路，也可以让它一步完成发布。

十、为什么我仍然建议“先草稿、后发布”

虽然这次已经跑通了自动发布，但对大多数博客场景来说，我仍然建议：

优先把 OpenClaw 当成“博客搭子”和“草稿助手”，而不是无脑自动发文机器。

原因很简单：

  • 博客内容通常比聊天消息更值得最后审一眼
  • 你可能会临时补图、改标题、调语气
  • 草稿模式自动化收益已经很高，但风险比直接发布低很多

所以真正适合长期维护的方式，是：

OpenClaw 负责生成与落稿，你负责最后判断和定稿。

十一、后续扩展方向

这篇只解决了 文章草稿与发布。

如果继续往下做，后面还可以扩展：

  • 图库管理
  • 瞬间（动态）发布
  • 分类 / 标签自动化
  • 归档维护
  • 友链管理
  • 发布后自动回传文章 URL
  • 图片上传与正文自动插图

也就是说，这篇只是第一步。

十二、参考链接

  • Halo 个人中心文档：<https://docs.halo.run/user-guide/user-center>
  • Halo RESTful API 介绍：<https://docs.halo.run/developer-guide/restful-api/introduction>
  • Halo 在线 API 文档：<https://api.halo.run>

结语

这次折腾之后，我最大的感受是：

OpenClaw 不只是一个聊天助手，也完全可以变成博客工作流的一部分。

当它能帮你写内容、帮你整理结构、帮你自动落草稿、甚至帮你完成发布时，博客维护这件事真的会顺手很多。

如果你也在用 Halo，又正好在折腾 OpenClaw，希望这篇实战记录能帮你少走一点弯路。

site logo

Hi,Friend

© 2026 timing-up