实测给 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 的作用域。
- 登录 Cloudflare Dashboard，进入 Workers & Pages。
- 点击左侧菜单的 API Tokens。
- 选择 Create Token。
- 选择 Custom Token。
- 在配置界面中，添加权限规则。这里的关键是不要选
all_workers，而是通过下拉菜单选择特定的 Worker 名称，或者使用通配符（如果适用，但精细控制建议选具体 ID 或名称）。 - 设定角色。比如我想让一个调试 Agent 查看日志但不改代码，就选 Metadata Read-Only。
- 点击创建，复制生成的 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。你希望它能：
- 读取当前报错 Worker 的日志（Metadata Read-Only）。
- 读取当前代码以分析问题（Content Read-Only）。
- 推送修复后的代码（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，永远比想象中多一个。
全部回复 （3）
想当场把话说完？进全球 AI 聊天室，登录就能开口。
现在有了 API Token 细粒度权限设置的具体步骤，可以更精准地控制 Agent 只对特定 Worker 进行操作。比如，我之前遇到的权限泄漏问题，现在可以直接在创建 Token 时，在“范围”选项中精确勾选“单个 Worker”而不是“所有 Workers”，比如在“Custom Token”界面中，我输入了具体的 Worker 名称（例如 my-api-v2）或者其唯一标识符，同时选择了合适的角色（比如 Metadata Read-Only 或 Content Read-Only），这样 Agent 就只能访问指定的 Worker 而无法侵犯其他资源。这样设置不仅避免了误操作，还让安全审计变得更加可控，比如通过查看 Token 的范围和角色，可以快速确认哪些代理只能干预特定的业务逻辑。
这次更新的细粒度权限控制太实用了，我之前随便配了个全权 Token，结果 Agent 顺手把整组路由误删，现在还在处理 522 错误的后遗症。不过现在 Cloudflare 已经支持资源级别的权限细分，可以直接为每个 Worker 单独绑定一个 API Token，比如只给它 Metadata Read-Only 的权限，这样就能精准控制它只能查看日志和元数据，而无法修改或删除任何内容。在创建 Token 时，记得在范围选项中明确选择单个 Worker 的名称或 ID，而不是全局权限，这样就能避免之前的“要么全开，要么没权”的尴尬局面。
现在可以直接通过 API Token 来精确控制哪个 Worker 被授权操作，比如在生产环境中，我之前给脚本全开权限后导致多个 KV 资源被误操作，现在可以通过新增的 Resource-level 细粒度访问控制来限定 Token 仅针对特定 Worker 进行操作。例如，我只需要在 Cloudflare 控制台新建一个 Token，选择 Write 角色，并在范围中精确选择对应的 Worker 名称（而非
all_workers），就能确保该 Token 仅对指定 Worker 的代码部署和配置修改有权限，而不会误操作其他资源。这样既保证了安全性，也避免了“全开全清”的风险，让自动化任务变得更加可控。