Agent Idempotency（Agent幂等性）是指AI Agent的某个操作执行一次和执行多次的效果完全相同。换句话说，重复调用不会产生额外的副作用。这是构建可靠Agent系统的核心原则——当网络超时、消息重发、用户重复提交时，幂等性确保系统不会"多发一条消息"、"多创建一个任务"或"多扣一次费"。
AI Agent系统中，重复操作的场景比你想象的多得多：
| 操作类型 | 非幂等（危险） | 幂等（安全） |
|---|---|---|
| 发送消息 | 重复发送导致刷屏 | 相同ID只发一次 |
| 创建任务 | 重复创建多个任务 | 相同key只创建一个 |
| 写入文件 | 重复追加内容 | 覆盖写入（结果一致） |
| API调用 | 重复扣费 | 相同请求ID返回相同结果 |
| Git提交 | 重复提交相同内容 | 检查是否已存在 |
# OpenClaw 消息发送的幂等设计
# 通过 uuid 参数实现去重
# 飞书消息发送 - uuid确保同一条消息只发一次
curl -X POST /api/message/send \
-d '{
"channel": "feishu",
"content": "今日AI新闻日报",
"uuid": "news-2026-06-19-001" # 幂等key
}'
# 相同uuid在1小时内只会发送一次
# 重复调用直接返回已有消息ID# 飞书任务创建 - 幂等key防止重复创建
curl -X POST /api/task/create \
-d '{
"summary": "SEO巡检任务",
"idempotent_key": "seo-check-2026-06-19",
"description": "检查网站死链和meta标签"
}'
# 相同idempotent_key不会创建重复任务
# 返回已存在的任务GUID# OpenClaw 文件写入 - 原子写入保证幂等
# write工具使用 temp + rename 模式
# 无论调用多少次，结果都是最后一次写入的内容
write /var/www/miaoquai/news/2026-06-19.html "..."
# 幂等：写1次和写10次，文件内容相同// 在SKILL.md中实现自定义幂等逻辑
// 检查操作是否已经执行过
class IdempotentExecutor {
constructor() {
this.executed = new Map(); // key -> result
}
async execute(key, fn) {
// 检查是否已执行
if (this.executed.has(key)) {
console.log(`⏭️ 跳过重复执行: ${key}`);
return this.executed.get(key);
}
// 执行并缓存结果
const result = await fn();
this.executed.set(key, result);
// 设置过期时间（1小时）
setTimeout(() => this.executed.delete(key), 3600000);
return result;
}
}
// 使用示例
const executor = new IdempotentExecutor();
await executor.execute('send-daily-news-2026-06-19', async () => {
return await sendDailyNews();
});| 策略 | 原理 | 适用场景 |
|---|---|---|
| UUID去重 | 每条消息附带唯一ID，接收方去重 | 消息发送、事件推送 |
| 版本号 | 资源附带版本号，只接受更新版本 | 配置更新、状态变更 |
| 条件写入 | 检查前置条件后再写入 | 文件创建、数据库插入 |
| 幂等Key | 操作附带唯一key，相同key返回缓存结果 | API调用、任务创建 |
| 状态机 | 只允许合法状态转换 | 订单状态、审批流程 |
陷阱1：读操作不需要幂等 — 读操作天然幂等（读10次和读1次结果相同），但要注意缓存一致性。
陷阱2：幂等Key过期太快 — 如果幂等Key在1分钟内过期，但重试在2分钟后到来，就会重复执行。Key的过期时间应该大于最大重试间隔。
陷阱3：副作用不可逆 — 发送邮件、扣费等操作一旦执行就无法撤回。这类操作必须在执行前做幂等检查。
1. 所有写操作都要考虑幂等 — 在设计Agent工具时，问自己："如果这个操作执行两次会怎样？"
2. 使用UUID作为消息标识 — OpenClaw的message工具支持uuid参数，善用它。
3. 幂等Key要包含业务语义 — 比如 daily-news-2026-06-19 比 msg-12345 更有意义。
4. 记录执行日志 — 即使做了幂等检查，也要记录每次调用，方便排查问题。