实测如何给 Agent 分配 Cloudflare Workers 的细粒度权限 API Token

以前给团队或者 AI Agent 配 Cloudflare Workers 权限，基本就是个“要么全开，要么没权”的二元状态。只要给了编辑权限，Agent 顺手把其他 Worker 的日志清空或者改错配置的概率非常高。Cloudflare 最近上线了基于资源级别（Resource-level）的细粒度访问控制，直接把权限拆解成了四个角色，并且能精确绑定到单个 Worker。这意味着你可以专门搞一个 API Token，只让它盯着某一个 Worker 干活，这在多项目并行或者用 Agent 自动化运维时，是个很实用的安全兜底方案。

核心变化：从账号级到资源级的权限隔离

这次更新的核心逻辑是把权限分成了两层：角色（Role）和范围（Scope）。

之前的权限大多是账号级别的，一旦登录，你能看到账户下所有的 Workers、D1、R2 等等。现在新增的四个角色分别是：

• Metadata Read-Only（元数据只读）： 适合调试。能看到设置、指标、日志和追踪链路，但看不到源代码。
• Content Read-Only（内容只读）： 适合代码审查。能读取 Worker 的源码，但不能部署或修改配置。
• Write（写入）： 可以修改和部署代码，但不能删除 Worker。
• Full Control（完全控制）： 拥有该 Worker 的所有权限，包括删除。

范围则分为三级：Developer Platform 级（所有产品）、Product 级（如所有 Workers）和 Resource 级（特定某个 Worker）。这种层级设计的好处在于，你不需要为每个 Worker 创建一个新的用户，只需要调整 Token 的范围即可。

实操步骤：如何给 Agent 绑定单个 Worker 权限

实际使用中，我主要关注的是如何给 AI Agent 或者协作者分配特定的 API Token。以下是我在控制台操作的流程，以及对应的 Token 验证方法。

1. 在控制台创建带范围的 API Token

这一步是基础。你需要明确指定 Token 的作用域。

1. 登录 Cloudflare Dashboard，进入 Workers & Pages。
2. 点击左侧菜单的 API Tokens。
3. 选择 Create Token。
4. 选择 Custom Token。
5. 在配置界面中，添加权限规则。这里的关键是不要选 all_workers，而是通过下拉菜单选择特定的 Worker 名称，或者使用通配符（如果适用，但精细控制建议选具体 ID 或名称）。
6. 设定角色。比如我想让一个调试 Agent 查看日志但不改代码，就选 Metadata Read-Only。
7. 点击创建，复制生成的 Token。

2. 验证 Token 的生效情况

拿到 Token 后，别直接扔给 Agent，先自己测一下边界。

用 curl 请求该 Worker 的元数据接口：

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://api.cloudflare.com/client/v4/accounts/YOUR_ACCOUNT_ID/workers/scripts/TARGET_WORKER_NAME/metadata

如果返回了正确的 Worker 配置信息和最近部署记录，说明 Token 有效。然后尝试用一个不存在的 Worker 名称查询：

curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     https://api.cloudflare.com/client/v4/accounts/YOUR_ACCOUNT_ID/workers/scripts/OTHER_WORKER_NAME/metadata

如果返回 404 或者空结果，说明范围限制生效了。这对防止 Agent “串台”非常重要。

为什么这比之前好用？

以前我们为了区分环境，通常是用不同的命名空间或者前缀，但权限依然是共享的。现在可以直接针对 prod-api-worker 和 staging-api-worker 分配不同的 Token。

举个实际场景：你有一个负责自动修复错误的 Agent。你希望它能：
1. 读取当前报错 Worker 的日志（Metadata Read-Only）。
2. 读取当前代码以分析问题（Content Read-Only）。
3. 推送修复后的代码（Write）。

如果不细化权限，你只能给一个 Write 或 Full Control 的 Token，这就意味着它也能删除你的 Worker。现在你可以组合这些角色，或者为不同的阶段创建不同的 Token。比如，测试环境给 Full Control，生产环境只给 Write 权限，确保它不会误删。

潜在坑点和注意事项

虽然功能很清晰，但在实际落地时有几个细节需要注意：

• 角色继承逻辑： 目前这四个角色是互斥的。如果你同时需要读日志和读代码，你可能需要分配一个更高的角色（比如 Write），或者创建两个 Token。Cloudflare 文档暗示未来可能会更灵活，但目前最好按需申请最小权限。
• 其他产品的同步： 官方提到 D1、R2 和 KV 也会跟进这套权限体系。这意味着你现在建立的 Worker 权限管理习惯，可以直接复用。建议现在就按照 Resource-level 的思路整理你的 Token，以后迁移成本最低。
• Dashboard 视图： 当你用绑定了特定 Worker 权限的用户登录 Dashboard 时，列表只会显示那个 Worker。这对于实习生或者外包开发者来说，视觉干扰大大减少，不容易点错。

总结

这次更新虽然看似只是加了几个按钮，但实际上把 Cloudflare Workers 的多租户管理能力提升了一个档次。特别是对于使用 AI Agent 进行运维的团队，能够精确限定 Agent 的“视野”，避免了因为权限过大导致的意外操作。

建议立刻检查你的生产环境 Token，把那些还在用全局权限的 Key 换成带范围的。尤其是给 Agent 用的 Token，记得加上过期时间。毕竟，能删除生产环境的 Agent，永远比想象中多一个。