Introducing Vercel Connect

介绍 Vercel Connect - Vercel

为代理提供访问您的工具、数据和服务的权限，是它们变得有用的关键。随着代理在不同系统中执行更深入的工作，对这些访问权限进行身份验证和授权，已成为您应用架构的核心。

目前，代理的访问权限通常是通过长期有效的提供者令牌来授予的，这些令牌存储在您的环境变量中，并为代理可能需要的一切进行了预置。这些令牌被所有用户共享，永远不会过期，并且可以赋予代理对所有任务的完全访问权限，无论任务多么微小。

保险库虽然让令牌更难被窃取，但并不能降低其危险性。真正的问题在于当令牌泄露时会发生什么：它能够访问的一切都会暴露出来。

我们开发了 Vercel Connect 来解决这个问题。现在 Vercel Connect 已进入公开测试阶段，它用运行时凭证交换取代了存储的令牌。您只需注册一次连接器。当代理有工作要做时，您的应用向 Vercel Connect 证明其身份，然后获取一个仅限于该任务的短期凭证。您之前使用令牌完成的一切仍然有效。代理只需每次请求访问权限，而不是一直持有它。

每个代理都通过 Vercel Connect 接入其服务，使用自己的作用域令牌和触发器。

链接到标题 注册一次连接器，然后在多个项目和环境中重复使用

连接器是您 Vercel 团队与像 Slack 或 GitHub 这样的提供者之间的可重复使用连接。您可以从仪表板或 CLI 创建一次连接器，然后将其附加到需要它的项目和环境中，并使用项目级别的访问控制。

vercel connect create slack
--name
mybot

创建一个 Slack 连接器

与提供者之间的关系成为一个单一实体，您可以查看和管理它，而不是分散在十几个环境变量面板中，每次轮换都需要找到所有副本。

您的编码代理也可以运行这种设置。通过 npx skills add vercel/vercel-plugin --skill vercel-connect 安装 vercel-connect 技能，它就可以为您创建和附加连接器。

链接到标题 在运行时请求作用域令牌

有了连接器之后，代理只有在有工作要做时才会请求凭证。@vercel/connect SDK 会返回一个令牌，您可以立即用于提供者 API，而您的应用中不会存储任何提供者的秘密。

app/lib/connect-token.ts

1
import
{
getToken
}
from
'@vercel/connect'
;
2
3
const
token
=
await
getToken
(
'slack/mybot'
,
{
4
subject
:
{
type
:
'app'
}
,
5
}
)
;

在运行时请求令牌

令牌的生命周期是短暂的，具体取决于提供者。SDK 会自动刷新它们，因此您无需手动轮换秘密。这留下了一个问题。如果您的应用不持有任何秘密，那又是什么证明它被允许请求呢？

链接到标题 应用通过 OIDC 证明其身份

证明就是您的应用已经拥有的身份。Vercel 上的每个部署都会获得一个 OIDC 身份，当您的应用或代理请求令牌时，SDK 会将该身份呈现给 Vercel Connect。Vercel Connect 验证它，检查项目和环境是否被允许使用连接器，然后返回提供者的凭证。这个往返过程就是运行时凭证交换。

在本地开发过程中，通过 vercel link 和 vercel env pull 也可以获得相同的标识。在 Vercel 之外，SDK 接受一个 Vercel 访问令牌。不管哪种方式，您的应用中都没有提供者的秘密，因此不会发生泄露、提交或在不同环境中复制的情况。

限定每个令牌的权限范围，仅限任务所需

并非所有任务都需要相同的权限范围，即使是在同一个代理中。一步可能需要读取仓库，而下一步可能需要打开一个问题。每个请求都只请求它所需的访问权限，并且请求本身会设定限制。一个请求可以包含以下内容：

• 提供商的权限范围

• 安装 ID

• 资源限制

• 特定于提供商的授权详细信息

GitHub 是最明显的例子，因为它可以将令牌限制在特定的仓库和权限上。

app/lib/github-token.ts

1
import
{
getToken
}
from
'@vercel/connect'
;
2
3
const
token
=
await
getToken
(
'github/mybot'
,
{
4
subject
:
{
type
:
'app'
}
,
5
authorizationDetails
:
[
6
{
7
type
:
'github_app_installation'
,
8
repositories
:
[
'myorg/repo1'
]
,
// 一个仓库，而不是整个组织
9
permissions
:
[
'contents:read'
]
,
// 只读，而不是写入
10
}
,
11
]
,
12
}
)
;

将令牌限定为一个仓库，仅限只读

部署代理可以读取该仓库，但无法执行其他操作。一个细粒度的 GitHub 应用安装也可以非常狭窄，但安装是一个长期的授权，一旦设置好，就会一直被信任。这个限制仅适用于一个请求、一个任务。最小权限原则决定了请求的形状。

代表特定用户进行操作，使用按用户限定的令牌

一个共享的机器人令牌会为每个用户的请求赋予相同的标识和权限范围。Vercel Connect 允许您设置这个标识。将主体从应用切换为一个命名用户，令牌就会代表该用户进行操作，并限定在该用户授权的范围内。

app/lib/user-token.ts

1
import
{
getToken
}
from
'@vercel/connect'
;
2
3
const
token
=
await
getToken
(
'linear/mybot'
,
{
4
subject
:
{
type
:
'user'
,
id
:
'user_123'
}
,
5
}
)
;

为特定用户请求令牌

当用户首次授权访问时，startAuthorization 会通过回调 URL、webhook 或设备代码运行同意流程。之后，代理会以该用户的身份请求令牌。

按环境限制访问权限，并在需要时撤销权限

连接器连接到您选择的项目和环境，因此您可以为开发、预览和生产环境分别运行一个连接器，而不是将一个连接器指向所有三个环境。当每个环境都有自己的连接器、授权授予和权限范围时，开发环境中凭证泄露不会影响生产环境。

单独的连接器限制了凭证可以工作的范围，但它们无法回收已经发出的访问权限。通常，这是令人痛苦的部分。使用存储的令牌时，这意味着需要轮换。您生成一个新的密钥，更新所有旧密钥所在的位置，并重新部署所有依赖它的内容。使用 Vercel Connect，您可以撤销连接器的令牌，无论是您自己的还是所有令牌。

# 仅撤销连接器的您自己的令牌
vercel connect revoke-tokens slack/mybot --my-tokens
# 或者撤销所有令牌，包括所有用户和安装的令牌
vercel connect revoke-tokens slack/mybot --all-tokens

撤销连接器的令牌

撤销操作的效果取决于提供商。在提供商支持撤销的情况下，Vercel Connect 会在提供商处撤销令牌。在不支持的情况下，Vercel Connect 会停止为该授权颁发新的令牌，而已经颁发的令牌在提供商处仍然有效，直到过期。这在任何没有撤销 API 的提供商上都是一个真正的限制，而提供商保留的令牌越短，这个窗口期就越小。

链接到标题 通过已验证的 Slack 触发器驱动事件驱动的代理

到目前为止，你的代理是主动发起请求的一方。它请求一个令牌，并在有工作要做时调用一个服务。触发器的运行方式则相反。一个连接的服务会向你的应用发送一个事件，然后你的代理进行响应。

Vercel Connect 接收提供者的网络钩子（webhook），验证它，然后将其转发到你的项目。触发器转发功能目前处于测试阶段，支持 Slack、GitHub 和 Linear。一个 Slack 连接器可以将已验证的网络钩子转发到你的最多三个项目，因此 Slack 中的一条消息可以唤醒一个对它做出反应的代理。

整个流程在不使用提供者密钥的情况下端到端运行：

• 用户在 Slack 中发布一条消息。

• Slack 将事件发送到 Vercel Connect。

• Vercel Connect 使用它持有的 Slack 签名密钥验证事件，然后将其转发到你的 Vercel 应用，并重新使用其 OIDC 身份进行认证。

• 你的应用验证该认证，然后请求一个作用域限定的运行时令牌。

• 代理执行操作并作出响应。

Slack 签名密钥并没有消失。它被转移到了 Vercel Connect 的服务器端，Vercel Connect 验证上游的网络钩子，并使用你的应用可以检查的身份重新对转发的请求进行签名。你的应用不需要持有用于操作的机器人令牌，也不需要持有用于验证的签名密钥。

链接到标题 Vercel Connect 在你现有的代码中与你相遇

在所有内容之下，只有一条调用。无论你的代理是基于 AI SDK 构建的，作为后台任务运行，还是你自己编写的一个循环，它都会以相同的方式请求一个令牌，使用 getToken 方法。围绕这个调用的是对你已经运行的堆栈的适配器。Better Auth（@vercel/connect/betterauth）和 Auth.js（@vercel/connect/authjs）会以它们期望的格式获取提供者配置，而 @vercel/connect/ai-sdk 和 @vercel/connect/mcp 也会对 AI SDK 工具和 MCP 客户端做同样的事情。Nuxt 启动模板为你提供了一个可以构建的现成应用，其中已连接 GitHub 和 Linear，没有提供者密钥，数据库中也没有存储任何 OAuth 刷新令牌。

框架可以更进一步，使连接本身声明化。在 Vercel 开源代理框架 eve 中，一个连接只需要一个文件，而 @vercel/connect/eve 适配器会为该连接提供凭证。

agent/connections/linear.ts

1
import
{
defineMcpClientConnection
}
from
"eve/connections"
;
2
import
{
connect
}
from
"@vercel/connect/eve"
;
3
4
export
default
defineMcpClientConnection
(
{
5
url
:
"https://mcp.linear.app/sse"
,
6
auth
:
connect
(
"linear/mybot"
)
,
7
}
)
;

通过 MCP 连接到 Linear 的 eve 连接

代理代码中没有令牌处理，因为 connect 将授权流程、刷新和错误情况映射到 eve。任何支持 OAuth 的 MCP 服务器都可以通过其 URL 成为连接器，这就是为什么 mcp.linear.app 最终能够拥有与 Slack 或 GitHub 相同的作用域令牌模型。

相同的适配器可以连接一个 Slack 频道。一个 connectSlackCredentials 调用可以覆盖两个方向：发送消息所需的机器人凭证和接收消息所需的网络钩子验证。

agent/channels/slack.ts

1
import
{
slackRoute
}
from
"eve/channels/slack"
;
2
import
{
connectSlackCredentials
}
from
"@vercel/connect/eve"
;
3
4
export
default
slackRoute
(
{
5
credentials
:
connectSlackCredentials
(
"slack/mybot"
)
,
6
}
)
;

eve Slack 频道

Slack 集成通常在你的环境中保存的两个密钥，SLACK_BOT_TOKEN 和 SLACK_SIGNING_SECRET，现在在你的应用中已经不存在了。没有剩下任何需要配置、存储或轮换的内容。

链接到标题 访问权限成为你请求的内容，范围限定于任务

代理能够触及的范围越广，它就越有用，这正是为什么访问权限是需要正确设置的部分。代理能够触及的每个系统，都可能通过泄露的令牌被他人访问。通过运行时凭证交换，没有任何东西是为所有情况预先配置的。没有任何东西是所有用户共享的。没有任何东西会永远存在。没有任何东西会超出当前任务的范围。

凭证管理曾经是架构的一部分。过去，它涉及轮换脚本、在不同环境之间复制的秘密，以及足够宽泛的机器人令牌，你只能希望它们不会被泄露。现在你不再存储这些内容。当代理需要访问权限时，你立即请求访问权限，范围限定于任务。

开始使用 Vercel Connect 构建

注册一个连接器，请求第一个运行时令牌，并将代理连接到 Slack 或 GitHub，而无需存储提供者的秘密。

编码代理只需要一个提示：

在此应用中设置 Vercel Connect，使其能够在不存储 Slack 令牌的情况下向 Slack 发布消息。使用
`npx skills add vercel/vercel-plugin --skill vercel-connect`
安装 vercel-connect 技能，并按照提示操作。如果技能未涵盖任何内容，请参阅 vercel.com/docs/connect.md。链接项目 (
`vercel link`
) 并拉取本地 OIDC 令牌 (
`vercel env pull`
)，使用
`vercel connect create slack --name mybot`
创建一个 Slack 连接器，并将其附加到此项目。然后安装 @vercel/connect，并在运行时使用 getToken('slack/mybot', { subject: { type: 'app' } }) 请求令牌。使用该令牌向我选择的频道发送测试消息。通过项目的类型检查进行验证，除非我要求，否则不要提交代码。

你编码代理的初始提示

连接你的第一个代理

你的部署通过 OIDC 证明其身份，并获取一个短期的令牌，该令牌的范围限定于一个任务。适用于 Slack、GitHub、Linear 和任何 OAuth MCP 服务器。

开始使用

链接到标题 常见问题

什么是 Vercel Connect？

Vercel Connect 允许你的代理和服务代表你的用户和团队访问外部系统。你不再需要在长期有效的环境变量中存储提供者的凭证，而是在运行时请求用户授权的令牌，并使用项目级别的访问控制。

Vercel Connect 解决了什么问题？

它从你的运行时环境中移除了长期有效的第三方秘密，同时仍然允许代理访问外部 API。你为提供者注册一个连接器，将其链接到项目和环境，并在运行时请求提供者的令牌。

何时应该使用 Vercel Connect 而不是集成？

使用 Vercel Integrations 来进行市场管理的安装和 Vercel 市场中提供者管理的产品。使用 Vercel Connect 来进行代理工作流的委托运行时凭证和用户授权，例如需要对 Slack 工作空间进行项目范围访问的代理。

有哪些可用的连接器？

Vercel Connect 支持通用的 OAuth 和 API 密钥连接器，以及专为 Slack、GitHub、Linear、Discord、Notion、Salesforce、Figma 和 Snowflake 设计的连接器。Resend、Workday、Microsoft Teams 等即将推出。

定价是如何计算的？

定价基于令牌请求。Hobby 计划每月包含 5,000 次令牌请求，不收取额外费用。在 Pro 和 Enterprise 计划中，令牌请求按每 10,000 次请求 3 美元计费。

当前 Beta 的限制是什么？

触发转发仅限于 Slack、GitHub 和 Linear，设置连接器品牌字段后无法完全清除它们，令牌撤销、令牌有效期和作用域粒度取决于提供商的支持。