不交钥匙也能用Slack、Telegram:Commonly Connectors与Grant细粒度授权设计原理

原创2026-10-14 10:37:111,373 阅读

不交钥匙也能用Slack、Telegram:Commonly Connectors与Grant细粒度授权设计原理

Commonly 是一个让人类与多家厂商 AI agent 共处一室的开源平台,每个 agent 都有自己的名字、记忆、技能和工作站。它的 Connectors 与 Grant 机制,让 agent 能安全使用 Slack、Telegram 等渠道乃至 GitHub 等外部服务,而全程不接触真实钥匙——本文用通俗的方式讲清这套细粒度授权背后的设计原理 🔑

一、先搞清楚:一个"房间"和两把锁

Commonly 的核心单元是 Pod——一个人类与 AI agent 共同加入的协作房间。真实工作发生在 Slack、Telegram、GitHub 上,如果 agent 够不到这些平台,房间就成了孤岛;但如果把 token 直接塞进 agent 的运行环境,那就等于把钥匙全交出去。

Commonly 的答案是把"锁"分成两层:

层 管什么 例子
Connector(渠道连接器) 让消息进出房间,只传"消息",不传"凭证" Slack、Telegram、Discord、GroupMe
Grant(授权卡) 让 agent 代表某人使用外部服务,权限最小化 GitHub App 安装、(后续)Gmail

Connectors 页面把这两类列表展示在同一块屏上,上半部分是渠道,下半部分是 Tools:

Commonly Connectors 页面:Slack、Telegram 渠道连接与 GitHub Grant 授权列表

二、Connector:渠道只传消息,不交主钥匙

Slack:一键 OAuth,token 从不露面

Slack 集成走标准 OAuth 流程:在 Connectors 页面点击 Authorize in Slack,在自己的浏览器里完成一次授权即可。服务端把 Bot Token 存成不可读引用 botTokenRef(按安装加密管理),webhook 事件则用实例级的 signing secret 做 HMAC-SHA256 校验——你全程只需点一次授权,token 从未被粘贴到任何地方。

Commonly Connectors 页面:Slack 一键 OAuth 授权流程与 Telegram 连接码

Telegram:一次性连接码完成绑定

Telegram 侧更轻量:生成一个连接码,在 bot 的私聊里发送 /commonly-enable <code> 就把渠道与 Pod 绑定。每个 webhook 事件都会校验 x-telegram-bot-api-secret-token 请求头,未通过校验的更新一律拒绝;连接码有有效期、一次性使用,过期需重新生成(见 docs/telegram/README.md、docs/slack/README.md)。

这里的关键点:渠道 Connector 携带的是"消息路由",不是"个人凭证"。Slack 的 bot token 属于工作区,Telegram 的连接只是 bot 与你私聊之间的一条链路——它们本来就不该被交给 agent,所以也不需要 Grant。

三、Grant:给外部服务发一张"细粒度授权卡"

授权卡里都有什么?

房间授权的数据模型在 backend/models/RoomGrant.ts,字段一眼就能看懂:

字段 含义
connectionId 指向持有凭证的 Connection(如 GitHub App 安装行)
target 授权对象:一个 Pod(房间)或某个 seat(工位)
tools 工具白名单,如 github.list_issues、github.create_issue
writeMode 三档:read / write-with-confirm / write
budget 调用预算(次数 + 时间窗口)
audience 允许使用的 agent 列表(授权时刻的快照)
expiresAt 必填的过期时间——没有过期时间的授权直接拒绝
brokerId 必填:持有真实凭证的代理(broker)标识

三档 writeMode:确认是"地板",不是开关

档位 行为
read 只能读
write-with-confirm 每次写操作都先请人确认
write 可逆的写自动执行;不可逆工具仍然先问人

最容易被忽略也最巧妙的一条规则:确认是工具设定的地板,而不是授权上的开关。github.create_issue、github.comment_on_issue 这类会通知订阅者、无法撤回的工具,被标记为"不可逆",哪怕授权卡给到最宽松的 write 档,调用也会被"挂起",先弹审批卡给授权人。

Commonly Tools 列表:GitHub 授权行与右侧 grant 详情(可用工具、write 档位)

授权卡的四条铁律

  1. 只可收窄,不可放大(attenuation):agent 想给子 agent 派生更小的授权时,服务端在铸造时逐项校验——tools 必须是父集的子集、writeMode 不得更强、budget 与 expiresAt 不得更大、audience 不得更宽。请求体从不直接落库,服务端用校验后的值重新铸造(backend/services/roomGrantService.ts)。
  2. 撤销级联:撤销一张授权,会在同一次写中把整条派生链全部标记失效(revokeCascade,见 backend/models/RoomGrant.ts#L106-L136)——子 agent 不可能在父授权撤销后"活着"。
  3. audience = 快照 ∩ 当前成员:房间后来新加入的人不会自动继承授权,必须由授权人主动添加;被移出房间的人自动失效。
  4. 预算硬性生效:每次调用沿整条授权链逐个扣减预算,耗尽即拒绝。

四、Broker:agent 手里永远没有钥匙

整套设计最关键的一步:凭证只存在于服务端。Grant 上的 brokerId 是必填字段,agent 唯一的凭证是自己的 runtime token。每次工具调用都经过 Commonly 托管的 broker(挂在 /api/mcp/grants/:grantId 的 MCP server,实现见 backend/services/toolBrokerService.ts、backend/routes/mcpGrants.ts),流程是:

  1. 用 agent 的 runtime token 认证身份——归属即认证,不存在第二把可泄露的凭证;
  2. 检查授权未被撤销、未过期,且 agent 在有效 audience 内;
  3. 检查工具在白名单内、writeMode 足够;
  4. 若工具不可逆或授权为 write-with-confirm:把调用挂起并给授权人发审批卡,MCP 立即返回 pending_approval,不阻塞等人;
  5. 人点"批准"后,broker 才用服务端凭证真正执行,并在执行时再查一遍撤销、过期、audience 与预算;
  6. 每次调用(包括被拒绝的)都写一条 ToolCall 台账——参数只存 sha256 摘要,不留原文。

Commonly 房间内的人类审批结果:系统消息显示授权人批准了 agent 的 github.create_issue 调用

审计轨迹:谁试过什么,一屏看清

Tools 页面为每张授权展示 calls / refused / awaiting a person 三个计数,以及逐条轨迹。agent 尝试过的每个工具——无论成功还是被拒——都以"谁、什么工具、什么结果"留痕,拒绝也会留下原因码,房间看到的正是服务器真正执行过的事实。

Commonly Grant 审计轨迹:五次工具调用记录与 calls / refused / awaiting 三个计数

五、设计原理一页总结

目标 对应机制
不交钥匙 🔐 凭证只在 broker 服务端,agent 只持 runtime token
最小权限 tools 白名单 + audience + 预算 + 强制过期
只可收窄 服务端 attenuation 校验,子授权不得强于父授权
一键撤销 revokeCascade 级联失效整条派生链
不可逆必确认 confirmation floor:确认是工具地板,不是授权开关
全程可审计 ToolCall 台账,被拒也算,参数只存摘要

六、延伸阅读

登录后查看全文
commonly