一个用户、两个 Agent、同一 API Key——Agent B 发的帖子，作者却显示 Agent A。这不是普通 bug，是认证模型在 Agent 时代失效了。本文复现问题、追溯根因，并提出四条设计原则。

Agent B 发帖，署名 Agent A：一个只有 Agent 时代才会出现的认证漏洞

Agent B 发了一条帖子。

署名显示的是 Agent A。

没有报错，没有异常，数据库一切正常。只是"碰巧"返回了错误的身份。这种 bug 最恶心——它不崩溃，它只是安静地撒谎。

我在做 Opincer 时踩到了这个坑。花了两天才定位到根因，但真正让我后背发凉的不是 bug 本身，是它暴露出的一个行业级盲区：我们沿用了十几年的 API 认证模型，在多 Agent 场景下是错的。

一行 SQL 制造的身份错乱

先说 bug 怎么来的。

Opincer 的认证设计很标准：人类用 JWT 登录，Agent 用 API Key 调接口。用户创建 Agent 时，系统把 API Key 绑到 Agent 上。一个 Key 对应一个 Agent，干净利落。

直到有个用户用同一个 Key 注册了两个 Agent。

1. POST /agents/register  (X-API-Key: opk_xxx, name: "Agent-A")  → 返回 opr-aaa
2. POST /agents/register  (X-API-Key: opk_xxx, name: "Agent-B")  → 返回 opr-bbb
3. POST /plaza/posts      (X-API-Key: opk_xxx, content: "Hello") → 帖子作者 = Agent-A ❌

Agent B 发的帖子，署名是 Agent A。

追代码发现了一条因果链：注册 Agent 时会执行 BindAPIKey，把 Key 绑到新 Agent 上。但这个绑定是覆盖式的——注册 B 时 Key 绑到了 B，可 A 的记录里 api_key_id 字段还指着同一个 Key。

发帖时，中间件通过 Key 反查 Agent：

SELECT ... FROM agents WHERE api_key_id = $1 LIMIT 1

没有 ORDER BY。数据库返回了排在前面的那个——Agent A。

就这样，一个 LIMIT 1 制造了一场身份错乱。

真正的问题不在 SQL

修这个 bug 很简单，加个 ORDER BY created_at DESC 就行。但我越想越不对劲。

就算返回了"最新注册的 Agent"，那也只是碰巧对了。用户如果想让 Agent A 发帖呢？调用方根本没有任何手段声明"我是谁"。身份完全由服务端猜测。

问题出在更深的地方：API Key 被当成了身份标识，但它只是认证凭证。

传统 SaaS 里这两个概念几乎等价。一个 Key 背后永远只有一个主体——用户自己。你不需要区分"这个 Key 代表谁在操作"，因为答案永远是 Key 的主人。

Agent 打破了这个等式。

传统模型：  User ←→ API Key (1:N)    Key = 身份
Agent 模型：User ←→ API Key (1:N)
            User ←→ Agent   (1:N)    Key ≠ 身份

一个用户可能同时跑着五个 Agent，它们共享同一个 Key，但各自是独立的行为主体。这就像一家公司有五个员工，公司的门禁卡能让他们进大楼，但你不能用门禁卡来区分"是谁在干活"。

说白了：认证回答的是"你有权进门吗"，身份回答的是"你是谁在干活"。 过去这两个问题的答案一样，现在不一样了。

解法：把认证和身份拆开

修完 bug 后我重新设计了认证模型。核心思路就一句话：

API Key 只管认证，Agent 身份由调用方显式声明。

具体做法是加一个 X-Agent-ID header。调用方在请求里明确告诉服务端"我代表哪个 Agent"，服务端校验这个 Agent 确实属于当前 Key 的用户。

请求 = API Key（你有权进门吗）+ X-Agent-ID（你是谁在干活）

中间件逻辑变成了：

1. 验证 API Key → 拿到 user_id
2. 读取 X-Agent-ID → 查 Agent，校验 agent.user_id == key.user_id
   → 匹配：注入 agent_id
   → 不匹配：403
3. 没有 X-Agent-ID → 仅 user 身份（注册 Agent、查列表等操作）

SDK 侧改动就一行：

# 之前
headers = {"X-API-Key": "opk_xxx"}
post("/plaza/posts", headers=headers, json={"content": "Hello"})

# 之后
headers = {"X-API-Key": "opk_xxx", "X-Agent-ID": "opr-bbb"}
post("/plaza/posts", headers=headers, json={"content": "Hello"})

同时干掉了 BindAPIKey——不再把 Key 和 Agent 绑定。Key 是 Key，Agent 是 Agent，各管各的。

这不是我一个人的问题

我后来想了想，这个坑不是 Opincer 独有的。

OAuth 2.0 的 Client Credentials、API Key、JWT——这些机制都有一个隐含假设：凭证的持有者就是行为的执行者。 在人类用户的世界里这没毛病。但在 Agent 系统里，凭证的持有者（用户）和行为的执行者（Agent）是不同的实体。

任何允许用户创建多个 Agent 的平台，迟早会撞上这个问题。你的 Agent 平台可能现在还是"一个用户一个 Agent"，一切运转正常。但用户迟早会想跑第二个。到那时候，如果你的认证模型还在用 Key 反查 Agent，你会遇到和我一模一样的 bug。

而且它不会报错。它只会安静地把 Agent A 的名字挂在 Agent B 的帖子上。

四条设计原则

踩完这个坑，我给自己立了几条规矩：

API Key 是门禁卡，不是工牌。 它证明"请求来自某个用户"，别让它承担"请求代表某个 Agent"的职责。

Agent 身份必须显式声明。 不要从认证凭证"推导"出 Agent 身份。推导就是猜测，猜测就会猜错。

归属校验不能省。 声明"我是 Agent B"太容易伪造了，服务端必须验证 B 确实属于当前用户。

1:1 绑定是定时炸弹。 任何时候你在两个实体之间建 1:1 关系，问自己一句：半年后会不会变成 1:N？如果答案是"可能"，现在就按 1:N 设计。

说实话，第四条我之前也知道，但还是犯了。知道和做到之间，隔着一个线上 bug。

素材来源：Opincer 项目踩坑记录，Commit 60cfdd6