AI Agent on Kalend's Blog

踩过的坑全给你：Blog Agent 最佳实践

Wed, 20 May 2026 00:00:00 +0800

跟着前三篇搭完 Pipeline，满怀信心跑了一次——然后各种炸。这篇文章是我踩了 50+ 个坑之后，精选出 12 个最致命的。

多Agent协作系列第4篇/共4篇（收尾篇） | 避坑指南 | 约2800字 | 作者：varkm

先说结论

踩了 50 多个坑，80% 集中在五个环节。

我把最致命的 12 个挑出来，按"写→排→配→协→省"五个阶段给你。

每个坑都附具体命令和代码。

不是"建议你检查一下"，是"复制这条命令就能验证"。

一、写作篇：Agent 写的东西能看吗

内容质量不是模型能力问题，是验证流程问题。

Writer 写什么不重要，Reviewer 能拦住什么才重要。

坑1：子代理编造不存在的配置键名

这是最致命的一个坑，没有之一。

子代理会"幻觉"出看似合理的配置键名。

比如 tool_circuit_breaker，听起来很专业对吧？

源码里根本没有这个键。正确的叫 tool_loop_guardrails。

读者拿去配，白配。文章发出去，评论区翻车。

类似的情况还有：busy_input_mode 实际叫 display.busy_input_mode。

prompt_cache_ttl 实际叫 prompt_caching.cache_ttl。

验证方法——每个键名必须过这关：

1

grep -rn "键名" hermes_cli/config.py

不存在就不要写，哪怕 AI 信誓旦旦说"我确认过"。

这条规则我写进了 Reviewer 的检查清单，至今拦住了 20+ 次编造。

坑2：AI 味套话满天飞

“值得注意的是”、“总的来说”、“首先…其次…最后”。

这些话一出现，读者秒懂：AI 写的。

解法： 把 AI 味关键词清单写进 Reviewer 的规则文件。

逐段扫描，强制替换为自然过渡。

不是零容忍——允许 1-2 处漏网，但多了必须打回重写。

我维护了一份清单，大概 15 个高频 AI 味词组。

每次审校先跑一遍关键词扫描，比人工逐段看效率高 10 倍。

坑3：评测文事实核查翻车

“发布不到一个月”——实际仓库已创建 3 个月。

“不支持 Docker”——仓库里 Dockerfile 就在根目录。

“我两个都在用”——说实话，根本没用过第二个。

这条最危险，因为读者会去验证。一旦翻车，信任归零。

核心原则： 每一条事实声明都必须验证。

星数看 GitHub API，技术栈看源码，体验只写真话。

验证命令：

1
2


curl -s https://api.github.com/repos/owner/repo \
 | jq '{stars: .stargazers_count, created: .created_at}'

版本追溯三步法：

1
2
3


git log --oneline --all --grep="功能名" | head -5
git tag --contains <commit_hash> | head -3
git show --no-patch --format="%H %ci %s" <commit_hash>

写作篇一行检查：grep -rn "配置键名" config.py

二、排版篇：微信客户端是最大的敌人

微信渲染引擎会做你意想不到的事。

所有样式必须 inline，微信会剥离 <style> 和 class。

这是排版篇的第一条铁律，后面所有坑都跟它有关。

坑4：列表标签全线崩溃

<ul>、<ol>、<li>，三个标签在微信里有三个独立 bug。

<ol> 编号跨板块连续计数：第一个列表从 1 开始没问题。

第二个列表不从 1 开始，接着上一个的编号往下数。

<ul> 加手动 bullet 产生双圆点，一行出现两个点。

<li> 的 margin 产生空行，每个 item 变成空行 + 内容两行。

我在这三个标签上各踩了一轮，前后折腾了两天。

终极方案： 全部不要用。

所有列表统一用 ◆ 替代：

1
2


<p style="margin:4px 0;line-height:1.8;
padding-left:14px;">◆ 列表内容</p>

简单、稳定、不炸。这是 3 轮踩坑之后的终极结论。

坑5：代码块黑底黑字

微信会剥离 <pre> 标签的 color 样式，只剩 background。

黑色背景 + 黑色文字 = 完全看不了。

读者截图问我"代码块怎么什么都没有"。

我才知道这个坑——在电脑浏览器里是正常的。

解法： 永远不要用深色代码块背景。

浅色方案用 <section> 包裹：

1
2
3
4
5
6


<section style="background:#f6f8fa;
border-radius:6px;padding:14px;
border:1px solid #e1e4e8;">
<pre style="margin:0;color:#24292e;
font-size:14px;">代码内容</pre>
</section>

关键是用 <section> 而不是直接靠 <pre> 的样式。

深色方案也可以，但同样必须用 <section> + <span> 做语法高亮。

坑6：封面图中文变方格

Pillow 默认字体（DejaVu）不支持中文。

所有中文字符渲染成方格/空白。

发出去才知道——封面上的标题全是空白方块。

解法： 必须用系统 CJK 字体，且 .ttc 文件要加 index=0：

1
2
3
4
5
6


from PIL import ImageFont
font = ImageFont.truetype(
 "/usr/share/fonts/opentype/noto/"
 "NotoSansCJK-Bold.ttc",
 36, index=0
)

.ttc 是字体集合文件，不指定 index 可能加载到错误字体。

这个参数踩了我半小时才找到原因。

排版篇一行检查：grep -n '<ul>\|<ol>\|<li>' article.html

三、配置篇：80% 的崩溃来自两个默认值

不是功能不好用，是默认配置没改。

改两个配置，解决 80% 的 Pipeline 崩溃。

坑7：max_tokens 太小导致截断

默认 max_tokens 只有 4096。

一篇 2000 字的文章大概需要 8000-12000 token。

超了直接截断，Agent crash，日志显示：

1
2


Response truncated (finish_reason='length')
refusing to execute incomplete tool arguments

解法： Profile 配置里改成 32768 或更大：

1
2


model:
 max_tokens: 32768

Worker 自己改不了这个值。

必须由 Orchestrator 在 Profile 配置文件里提前设好。

算笔账： 一次跑完 vs 截断重跑。

截断一次 = 浪费已消耗的 token + 重新跑一遍完整流程。

max_tokens 调大，单次不会多花，但省掉了重试的浪费。

坑8：Skill 文件没复制到 Profile 目录

全局 skill 目录和 Profile 独立目录是两套。

Profile 看不到全局目录里的 skill，必须手动复制。

报错信息：

1

Error: Unknown skill(s): article-review

明明装了，为什么找不到？因为装错地方了。

解法： Orchestrator dispatch 前检查并复制：

1
2


cp -r ~/.hermes/skills/devops/article-review \
 ~/.hermes/profiles/blog-writer/skills/devops/

路径规则：全局 ~/.hermes/skills/ ≠ Profile 独立目录。

我第一次遇到这个报错时，反复重装了 3 遍 skill 才反应过来。

装的全是全局目录，Profile 根本看不到。

这两个配置改完，80% 的 Pipeline 崩溃直接消失。

配置篇一行检查：grep "max_tokens" ~/.hermes/profiles/你的profile/config.yaml

四、协作篇：Agent 编排的三个反模式

Pipeline 不是流程负担，是质量保险。

跳过的每一步，都会在下游加倍还回来。

坑9：跳过 Pipeline 裸写

手动 delegate_task 直接让一个 Agent 写文章，没有 Reviewer。

看起来快，实际上：

对比项	Pipeline	裸写
Reviewer 把关	有	无
审计链路	有	无
返工次数	1-2 次	3-5 次
总耗时	16 分钟	30+ 分钟

裸写最大的问题不是质量差。

是你不知道质量差——没有 Reviewer 告诉你哪里有问题。

等读者反馈，已经晚了。

我写过一篇裸写的文章，3 个配置键名编造，2 处 AI 味套话。

没有 Reviewer 拦，全发出去了。后来评论区被指出才改。

强制规则： 走完整 Kanban Pipeline，无例外。

流程：Writer → Reviewer → Creator → Reviewer → 发布。

坑10：task_id 幻觉编造

kanban_complete 时传入编造的 task_id。

kernel 验证不通过，直接报错：

1

phantom id blocks the completion

核心： task_id 只能来自 kanban_create 的返回值。

不要从文字描述里"编"，不要从上一轮的上下文里"猜"。

正确写法——先捕获返回值，再传入：

1
2
3
4
5
6


card = kanban_create(
 title="审校文章", assignee="reviewer"
)
kanban_complete(
 created_cards=[card["task_id"]]
)

错误写法：从摘要中看到 “t_deadbeef” 就传进去。

kernel 会验证每个 id 是否真实存在，幻编的 id 100% 被拦截。

坑11：Reviewer 模型比 Writer 弱

Writer 用最强模型写，Reviewer 用弱模型审。

结果：审校形同虚设，该拦的拦不住。

规则： 审核模型必须 ≥ 写作模型。

角色	推荐模型	定位
Writer	glm-4.7	性价比写稿
Creator	glm-4.7	排版生成
Reviewer	glm-5.1	强模型把关

贵的模型只干贵的事——审核就是最该花 token 的环节。

五、成本篇：怎么让 Agent 省着花

不是不能用贵模型，是别在不需要的地方用。

坑12：Pipeline 被反复"跳过"

完整 Pipeline 6 步全 PASS 只需 16 分钟。

但经常有人觉得"Pipeline 慢"，手动跳过。

跳过的后果：质量不过关 → 返工 → 再跑一遍 → 总耗时翻倍。

不要跳。 16 分钟换一次通过，比跳过之后返工 30 分钟划算。

分层用模型才是真省钱

全文用一个模型 = 全程用最贵的模型 = 浪费。

写作用性价比模型，快且便宜。

排版用同样的性价比模型。

审核用强模型，只审核一次。

贵模型用得少，但每次用在关键位置。

max_tokens 调大 + 模型分层，总成本反而比"省钱方案"更低。

具体算一下：Writer 跑 5 分钟用 glm-4.7，Reviewer 跑 2 分钟用 glm-5.1。

比全程用 glm-5.1 省 60% 以上 token。

该省省，该花花——审核环节绝不省钱。

系列 4 篇收尾

回顾整个多Agent协作系列：

第 1 篇 讲了 Kanban + Profile，让 Agent 有了分工和身份。

Kanban 是任务看板，Profile 是 Agent 的角色配置。

两者结合，Agent 从"什么都干"变成"各司其职"。

第 2 篇 搭建了 Blog Writer Agent，7 步从零到能写能部署。

从安装框架到写第一篇文章，全程可跟着操作。

第 3 篇 组建了完整 Pipeline，多 Agent 协作链路跑通。

Writer 写稿 → Reviewer 审校 → Creator 排版 → 发布。

6 步全 PASS 只需 16 分钟。

第 4 篇（这篇）补上了最后一环：搭完怎么不炸。

12 个坑，5 个阶段，每个都有具体命令和代码。

收藏这篇，每次跑 Pipeline 之前扫一遍检查清单。

四篇读完，你就有了一套完整的 Agent 博客系统。

从搭建到协作到避坑，该踩的坑我都替你踩了。

关注 varkm，一起学习，一起成长

多Agent协作系列完更，回复【agent】获取完整检查清单和 Profile 配置模板

Hermes vs OpenClaw对比：终端派 Hermes Agent 的选择

Mon, 18 May 2026 22:00:00 +0800

结论先说：这不是竞品

这两个项目根本不在一条赛道上。

OpenClaw（小龙虾🦞）想做的是「全平台个人AI助手」——像Siri一样渗透到你生活的每个角落，微信、WhatsApp、Telegram、macOS、iOS、Android，它都能接。你想用什么渠道就跟它说什么，它就回你在哪儿。

Hermes Agent 做的是「终端派 Hermes Agent 框架」——给开发者和技术用户的一把瑞士军刀。Kanban任务板、多Agent编排、技能系统、记忆宫殿，全是围绕「如何把复杂任务拆解、分配、执行」设计的。

如果你想找个好用的个人助手，选 OpenClaw；如果你想搭个能自动跑活的Agent系统，选 Hermes。

表格对比：一眼看懂差异

维度	OpenClaw（小龙虾）	Hermes Agent
定位	个人AI助手	终端Hermes Agent框架
GitHub Stars	372,888	较小众
语言	TypeScript	Python + TypeScript
渠道覆盖	20+（微信、WhatsApp、Telegram、Slack、Discord、QQ、iMessage、macOS、iOS、Android等）	微信、飞书、Telegram、Discord
上手门槛	一条命令 `openclaw onboard` 自动配置	需要理解Kanban、Profile、Skill概念
多Agent能力	Multi-agent routing（按渠道/账户隔离）	Kanban任务板 + Subagent委托（可视化编排）
记忆系统	基于会话	MemPalace（四级回忆链：热记忆→MemPalace→session_search→外部知识库）
定时任务	Cron jobs	内置Cronjob工具（带keep-alive、context注入）
技能生态	ClawHub（5400+ skills）	自建Skill系统（轻量级，易定制）
部署方式	Gateway + 多渠道inbox，支持Node 24/22.19+	100%本地部署，零第三方依赖
安全模型	Sandbox模式（Docker/SSH/OpenShell）	可选Bash/SSH后端
特色功能	Voice Wake、Live Canvas、macOS/iOS/Android原生App	Kanban可视化、Profile隔离、技能热加载
适合人群	想要「好用的助手」的普通用户	开发者、技术用户、需要自动化工作流的人

渠道覆盖：OpenClaw 完胜

OpenClaw 支持的渠道列表长得吓人：WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、IRC、Microsoft Teams、Matrix、Feishu、LINE、Mattermost、Nextcloud Talk、Nostr、Synology Chat、Tlon、Twitch、Zalo、Zalo Personal、WeChat、QQ、WebChat、macOS、iOS/Android。

你想在哪个平台跟它聊天，它就在那儿等你。而且它不是简单的「转发消息」，每个渠道都有深度集成——比如 macOS 有 Live Canvas（可视化工作台）、iOS/Android 有 Voice Wake（语音唤醒）、桌面端有原生 App。

Hermes 只支持四个渠道：微信、飞书、Telegram、Discord。但对我来说够用了——我的主要沟通场景就是微信，偶尔在 Discord 跟技术社区交流。

上手门槛：OpenClaw 友好，Hermes 需要理解成本

OpenClaw 的入门体验堪称教科书级别：

1
2


npm install -g openclaw@latest
openclaw onboard --install-daemon

就这么简单。onboard 命令会引导你一步步配置 Gateway、Workspace、Channels、Skills，像安装软件一样。而且它有 macOS 菜单栏 App、iOS/Android Node，可视化程度很高。

Hermes 的学习曲线要陡峭一些。你需要理解三个核心概念：

Kanban：任务板，用来管理和跟踪任务
Profile：Agent 配置文件，不同的 Profile 有不同的工具集和能力
Skill：技能包，可复用的任务流程

这不是「安装就能用」，而是「学习后才能发挥威力」的工具。但一旦你理解了这套系统，它的灵活性远超 OpenClaw。

多Agent能力：设计哲学差异

两者都支持多 Agent，但思路完全不同。

OpenClaw 采用「路由隔离」模式：你可以为不同的渠道、账户、Peer 配置独立的 Agent。比如你的微信发给 Agent A，WhatsApp 发给 Agent B，Telegram 的某个群发给 Agent C。每个 Agent 有自己的 Workspace、Session、Tool 配置。

Hermes 采用「任务板编排」模式：所有任务在 Kanban 上统一管理，通过 parents 字段表达依赖关系。你可以把一个大任务拆解成多个子任务，每个子任务分配给不同的 Profile（比如 researcher 做调研、writer 写文章、reviewer 审核）。当所有父任务完成，子任务自动从 todo 提升到 ready。

OpenClaw 更像「多租户隔离」，Hermes 更像「项目化管理」。前者适合个人多场景使用，后者适合复杂工作流自动化。

记忆系统：MemPalace 是杀手级特性

Hermes 的 MemPalace 是我最喜欢的功能。它不是简单的「存储对话历史」，而是四级回忆链：

热记忆（~2200字符）：高频使用的用户偏好、行为规则、环境配置
MemPalace：长期知识库，支持分类存储（drawers + memories）
Session Search：搜索过去会话的总结，快速找回上下文
外部知识库：通过 IMA 集成，连接你的笔记、知识库、收藏

OpenClaw 的记忆系统相对传统，主要是基于会话的短期记忆。它也能记住一些上下文，但没有 MemPalace 这种结构化的知识管理。

如果你需要 Agent 真正「记住」你的长期偏好和知识，Hermes 的 MemPalace 完胜。

部署方式：100%本地 vs Gateway模式

Hermes 是 100% 本地部署的，零第三方依赖。你只需要一个 Python 环境，就能跑起来。所有数据都在你的机器上，隐私绝对安全。

OpenClaw 是 Gateway 模式——本地跑一个 Gateway 服务（Node 24/22.19+），然后通过各种渠道接入。它支持 7x24 运行，有专业的 daemon 进程管理。但它需要更多的依赖和配置。

两种部署方式各有优劣：

Hermes：简单、轻量、隐私友好，但需要你自己维护进程
OpenClaw：专业、稳定、开箱即用，但需要更多资源

生态：ClawHub vs 自建技能

OpenClaw 有 ClawHub 技能市场，5400+ skills，涵盖各种场景。你想干什么基本都有现成的技能包。

Hermes 的 Skill 系统更轻量级，主要是自建。官方提供了一些通用技能（比如 kanban-worker、hugo-blog），但你大部分时间是自己写技能。

这跟设计哲学有关：OpenClaw 想做「产品」，给你现成的东西用；Hermes 想做「框架」，给你工具自己做。

选择建议：什么人选什么？

选 OpenClaw，如果你：

想要一个好用的个人AI助手，不想折腾
需要覆盖多个渠道（尤其是非技术平台）
喜欢「可视化操作」和「原生 App」的体验
不介意多装一些依赖，希望开箱即用
主要场景是「聊聊天、查查信息、简单自动化」

选 Hermes，如果你：

是开发者或技术用户，愿意学习新概念
需要复杂工作流自动化（比如博客写作、代码审查、多Agent协作）
看重数据隐私，希望 100% 本地部署
想要灵活定制自己的 Agent 系统
主要场景是「项目化任务管理」和「深度自动化」

我的选择

我两个都用了，但最后选择了 Hermes。

原因很简单：我是一个技术用户，大部分时间在终端和编辑器里工作。Hermes 的 Kanban、Profile、Skill 这套系统，正好匹配我的工作方式。我可以用 Kanban 管理博客写作计划，用不同的 Profile 处理不同类型的任务，用 Skill 封装可复用的流程。

OpenClaw 很强大，但它的优势不在我的使用场景里。我不需要在 20 个渠道上跟 AI 聊天，也不需要 Live Canvas 或 Voice Wake。我需要的是能帮我自动化复杂任务、记住我的长期偏好、可灵活定制的工具——这些正是 Hermes 的强项。

当然，这不代表 OpenClaw 不好。它是一个非常优秀的个人AI助手，GitHub 372,888 stars 说明了一切。只是对我来说，Hermes 更对胃口。

后续：有没有可能融合？

技术上完全可能。Hermes 可以通过 WebSocket 或 CLI 接入 OpenClaw 的 Gateway，享受它的多渠道能力；OpenClaw 也可以借鉴 Hermes 的 Kanban 和 MemPalace，增强任务管理和知识记忆。

但目前它们确实是两个方向的产品。OpenClaw 追求「覆盖广」和「易用」，Hermes 追求「深度定制」和「专业自动化」。

没有谁比谁好，只有谁更适合你。

关注 varkm，一起学习，一起成长