我照着 Moltbook 的 Verification Flow 做了套认证：把用户的 OpenClaw Agent 绑到账号上

说实话，这类“人和 Agent 绑定”的流程，我一开始是想做成 OAuth 那种大一统的。结果翻了 Moltbook 的 auth README，看完它的 Verification Flow，我改变主意了。

它不复杂，但很稳：注册 → claim → 公开验证 → 状态变更。我打算按这个思路做一套自己的流程，让用户用他们的 OpenClaw 作为客户端，把 agent 绑定到我的网站账号上。

这篇文章把流程拆开讲，并给一个可落地的实现方案。

---

Moltbook 的 Verification Flow 是什么样的

README 里有一张流程图，核心是四步：

1. Agent 注册
   POST /api/v1/agents/register
   返回 api_key、claim_url、verification_code

2. 人类访问 claim_url
   访问类似 https://www.moltbook.com/claim/moltbook_claim_xxx

3. 人类发布验证声明
   发一条带验证码的公开信息（示例是发 Tweet）

4. Agent 状态变为 claimed
   GET /api/v1/agents/status → claimed ✅

看起来简单，但它解决了两个关键问题：

• API Key 归 Agent：Agent 需要有一个专属 API Key 来调用接口
• claim 归人类：人类要主动做一个可验证的动作，证明“我控制这个 Agent”

这就是“人→Agent”绑定的核心。

---

我们的目标：让用户用 OpenClaw 绑定 Agent

你的需求是：

用户有自己的 OpenClaw 作为客户端，注册到我的网站并把 agent 和用户绑定。

翻译成人话就是：

• 用户在你的网站注册账户
• 他们的 OpenClaw Agent 获得 API Key
• 用户证明“这个 Agent 是我控制的”
• 绑定完成

所以我们要实现一个类似 Moltbook 的 Claim + Verification 流程，但验证方式可以换成更适合你的场景。

---

设计一套“像 Moltbook 但更适合我们”的流程

✅ 注册阶段（Agent 拿到 Key）

POST /api/v1/agents/register
→ 返回：
{
  api_key,
  claim_url,
  verification_code
}

几点注意：

• api_key 前缀加标识，比如 moltbook_ 的做法可以参考
• claim_url 里用 claim_token，只给人类使用
• verification_code 用人类可读的格式，比如 reef-X4B2

这样就能做到“一个 Agent 一个 Key”，而且人类才能走 claim。

---

✅ Claim 阶段（人类开始认领）

人类访问 claim_url，页面展示：

• 这台 Agent 的名字/描述（如果有）
• 当前状态：pending_claim
• 验证步骤说明

这里建议写得很明确，比如：

请使用你的 OpenClaw Agent 发送一条验证请求，内容包含验证码：reef-X4B2

---

✅ 验证阶段（证明“我控制这个 Agent”）

Moltbook 用 Tweet，你可以选更适合你的场景。

可选方案 A：Agent 发一个签名请求到你的网站

• Agent 用 api_key 调用 /api/v1/agents/verify
• Body 里带 verification_code
• 服务端校验后标记 claimed

可选方案 B：人类用 OpenClaw 发一条公开消息

• 例如发到 Discord/Telegram/微博
• 服务端根据公开内容抓取验证

我推荐 A，更直接，也更可控。

验证接口示例：

POST /api/v1/agents/verify
Authorization: Bearer <api_key>

{
  "verification_code": "reef-X4B2"
}

服务端逻辑：

• 校验 api_key 是否存在
• 校验 verification_code 是否匹配
• 通过就标记为 claimed

---

✅ 状态变更（绑定完成）

人类回到 claim 页面，看到状态变成：

claimed ✅

这一步很重要，用户会有“我绑成功了”的确定感。

---

关键的数据模型（我踩过的坑）

建议至少保留这些字段：

Agent {
  api_key
  claim_token
  verification_code
  status: pending_claim | claimed
  user_id (绑定后)
  created_at
}

注意点：

• api_key 永远不展示给人类
  这是 Agent 的凭证，别露出来
• claim_token 只用一次
  绑定成功后可以作废，避免重放
• verification_code 有效期
  建议 10-30 分钟，过期重置

---

安全细节别偷懒

Moltbook README 里强调了几件事，我觉得全都值得抄：

• token 前缀：区分不同类型的 token（例如 agent_ / claim_）
• CSPRNG 生成随机值：crypto.randomBytes()
• Timing-safe 比较：避免 timing attack
• HTTPS 强制：尤其是 api_key

这些看似“小题大做”，但真的能省后续大坑。

---

最小可落地实现（伪代码）

// 注册
const apiKey = genKey('agent_');
const claimToken = genKey('claim_');
const verificationCode = genCode(); // reef-X4B2
save({ apiKey, claimToken, verificationCode, status: 'pending_claim' });

// claim 页面
GET /claim/:claimToken
→ 展示验证步骤

// 验证
POST /agents/verify
Authorization: Bearer apiKey
body: { verification_code }

// 服务端校验
if (code match && status === pending_claim) {
  status = 'claimed'
  bind user_id
}

这套流程的好处是：
人类必须主动认领 + Agent 必须主动验证，双向确认，绑定关系更可信。

---

你要的“OpenClaw 客户端绑定”怎么落地

结合 OpenClaw 的能力，我建议这样做：

1. Agent 注册（拿 api_key）
2. 人类访问 claim_url
3. OpenClaw Agent 自动发验证请求
4. claim 页面显示绑定完成

你甚至可以让 OpenClaw 弹一个“点一下就验证”的按钮，体验会非常顺。

---

踩坑提醒（我提前帮你踩了）

• 把 api_key 和 claim_token 分开
  混用会导致“人类能拿到 api_key”，风险很大
• verification_code 不要太长
  人类要读得懂，8-10 字符最合适
• 绑定完成后别忘了作废 claim_token
  不然重放攻击分分钟
• API Key 不要打印到日志里
  一次泄露，全部重置

---

写在最后

这套流程我准备直接落地了。我的网站用的是 Next.js + Boilerplate SaaS，SSO 用 Clerk，所以接下来会把注册、claim、验证三段接口全部接进现有的鉴权体系里。

说白了就是：先跑通，再打磨。等代码跑起来，我再补一篇“实战版实现细节”。

---

参考链接
https://github.com/moltbook/auth