cloudflare-tools

cloudflare-tools

面向编码 Agent 的 Cloudflare 工具：区域、DNS、分析、Workers、Pages、存储和隧道。

Harness	交付方式	固定版本方式
OpenCode V2	原生插件（npm 包，含技能）	包中的版本
OpenCode V1	原生插件（npm 包，不含技能）	包中的版本
Claude Code	插件：MCP 服务和技能	发行版标签，作为引用
Codex	插件：MCP 服务和技能	发行版标签，作为引用
Grok Build	插件：MCP 服务和技能	发行版标签，作为 @ref
Antigravity	插件：MCP 服务和技能	发行版标签的树 URL
Hermes Agent	原生插件（Python，调用命令行）	发行版提交，作为 SHA
其他 MCP 主机	来自 npm 的 MCP 服务	包中的版本

这些工具需要 Node.js 24 或更高版本。 docs/conventions.md 说明了工具的命名方式 及其行为。

安装

请从发行版安装，切勿从默认分支安装：发行版是一个标签，其提交包含构建好的 dist/，而默认分支不包含。以下命令中，<version> 是发行版的版本号（1.2.3），<sha> 是其标签指向的提交：

gh api repos/craft-agent/cloudflare-tools/commits/v<version> --jq .sha

OpenCode

OpenCode V2 在 opencode.json 中接收包及其选项：

{
  "plugins": [{ "package": "@craftsamo/cloudflare-tools@<version>", "options": { "read_only": false } }],
  "permissions": [{ "action": "cloudflare_*", "resource": "*", "effect": "ask" }]
}

OpenCode V1 接收作为字符串的包，或与其选项组成的一对：

{
  "plugin": [["@craftsamo/cloudflare-tools@<version>", { "read_only": false }]],
  "permission": { "cloudflare_*": "ask" }
}

OpenCode 允许不受规则名称限制地执行任何操作，因此除非规则指定 ask，否则插件的请求会被静默批准。读取工具不会触发询问，因此 cloudflare_* glob 是安全的。

选项即设置。默认关闭的工具集可通过在 toolsets 中列出要保留的工具集来启用，例如 "options": { "toolsets": ["account", "zones", "dns", "workers", "pages", "email"] }。

V1 不会注册技能。解压包并将其 skills/* 文件夹复制到 ~/.config/opencode/skills/：

npm pack @craftsamo/cloudflare-tools@<version>
tar -xzf craftsamo-cloudflare-tools-<version>.tgz
mkdir -p ~/.config/opencode/skills
cp -r package/skills/* ~/.config/opencode/skills/
rm -rf package craftsamo-cloudflare-tools-<version>.tgz

Claude Code

claude plugin marketplace add craft-agent/cloudflare-tools#v<version>
claude plugin install cloudflare-tools@craft-agent

Codex

codex plugin marketplace add craft-agent/cloudflare-tools --ref v<version>
codex plugin add cloudflare-tools@craft-agent

Codex 会将服务器名称中的 - 转换为 _，因此工具显示为 mcp__cloudflare_tools__cloudflare_*。它会在插件的安装目录中启动 MCP 服务，且不会传递 roots，因此服务会根据 Codex 随调用发送的内容，为每次调用确定目录：优先使用服务所请求的沙箱状态，否则使用 Codex 指定的唯一工作区。

插件声明了 default_tools_approval_mode = "writes"：对于每个未标记为只读的工具，Codex 都会先询问。用户的 [plugins."<plugin>".mcp_servers.<server>] 设置只能进一步收紧限制。在该处设置 auto 会得到 prompt（读取操作也会询问），因为 Codex 将 auto 和 writes 视为不可比较。

Grok Build

grok plugin install craft-agent/cloudflare-tools@v<version> --trust

Grok 会在会话的工作目录中启动 MCP 服务。

Antigravity

请从发行版标签的树安装，切勿从默认分支安装，因为默认分支没有构建好的 dist/；Antigravity 会将该标签克隆到 ~/.gemini/config/plugins/cloudflare-tools。

agy plugin install https://github.com/craft-agent/cloudflare-tools/tree/v<version>

Hermes Agent

Hermes 安装的是一个提交，而不是标签，并且插件安装后处于禁用状态：

hermes plugins install craft-agent/cloudflare-tools --ref <sha>
hermes plugins enable cloudflare-tools

Hermes 会在安装插件时扫描插件。从 v0.7.0 开始，判定结果为 caution：隧道工具将令牌权限命名为 Account → Cloudflare One Connector: cloudflared，而 Hermes 会将这个词判定为隧道服务。 随后，hermes plugins install 会在安装前询问；如果无法询问（没有 终端），请添加 --force，它只会覆盖 caution 判定，不会覆盖其他判定。

如果 Hermes 网关已经在运行，请重启它（hermes gateway restart），以 加载插件。

插件会运行 Hermes 启动时找到的 Node。如果版本管理器在 Hermes 运行期间 移除了该版本，调用时会再次查找 Node；如果找不到，请从 node 可运行的 shell 中重启 Hermes。

如果此软件包的写入操作依赖另一个 Hermes 插件，例如一个会阻止写入、且 无人可批准的防护插件，请在 require_plugins 中指定它。即使该插件导入 或注册失败，Hermes 仍会继续加载此插件，并将清单中的 requires_plugins 视为建议。启用此设置后，只要指定的插件尚未加载，每个写入操作都会在 获批前被拒绝，即使处于 --yolo、approvals.mode: off 或已记住答案的 情况下也一样，并会指出缺少的插件。读取操作仍会执行。

plugins:
  entries:
    cloudflare-tools:
      settings:
        require_plugins: [write-guard]

其他任何 MCP 宿主

将服务添加到宿主的 MCP 配置中。标志放在 args 中：

{
  "mcpServers": {
    "cloudflare-tools": {
      "command": "npx",
      "args": ["-y", "@craftsamo/cloudflare-tools@<version>", "--read-only"]
    }
  }
}

工具和技能

下文所述的确认适用于有人值守的运行。启用 unattended 后，只有在授权 范围涵盖某项写入操作时，才会在不询问的情况下执行；否则会拒绝该操作。 请参阅无人可批准的写入操作。

每个工具集都附带一项技能，用于指导 Agent 如何使用其中的工具。技能会在 其 frontmatter 的 metadata 中声明所属工具集 （metadata: { toolset: dns }，以代码块形式书写）。OpenCode V2 和 Hermes 只有在设置至少注册了该工具集中的一个工具时才会注册这项技能，因此， 禁用了该工具集或移除了其中所有工具的配置文件都不会显示这项技能；不属于 任何工具集的技能始终会注册。Claude Code、Codex、Grok Build 和 Antigravity 会安装整个技能文件夹，并且只将设置传递给 MCP 服务，因此无论设置选择了 什么，都会列出所有技能。OpenCode V1 不注册任何技能，其复制的技能也都会 列出。

账户（account）

账户凭据、令牌验证和审计日志。

工具	功能	类别
cloudflare_account_read	view 账户详情和令牌状态、list 已配置的账户，或查询 audit 日志	读取

该技能为 cloudflare-account，在 Claude Code 中显示为 cloudflare-tools:cloudflare-account，在 Hermes 中 显示为 cloudflare-tools:account。

区域（zones）

区域查询、设置（读取和更改）、Universal SSL、证书和 DNSSEC。

工具	功能说明	类别
cloudflare_zone_read	list 区域、view 详情、读取 settings、Universal ssl 状态或 dnssec	读取
cloudflare_zone_setting_edit	按顺序更改 1–20 项区域设置；拒绝降低保护级别的更改	覆盖
cloudflare_zone_setting_weaken	以降低访客保护级别的方式更改区域设置；每次都会先询问	管理
cloudflare_zone_cache_purge	清除区域中最多 100 个 URL、主机、前缀或标签的缓存副本	幂等
cloudflare_zone_cache_purge_all	清除区域的全部缓存；每次都会先询问	管理
cloudflare_zone_dnssec_enable	为区域启用 DNSSEC；在注册商发布 DS 记录之前不会造成影响	幂等
cloudflare_zone_dnssec_disable	为区域关闭 DNSSEC；需先在注册商处移除 DS	管理

该技能为 cloudflare-zones，在 Claude Code 中显示为 cloudflare-tools:cloudflare-zones，在 Hermes 中显示为 cloudflare-tools:zones。

DNS（dns）

DNS 记录：列出、完整读取单条记录、导出区域文件、添加记录、更改记录和删除记录。

工具	功能说明	类别
cloudflare_dns_read	list 记录、完整 view 单条记录，或以 BIND 格式 export 区域文件	读取
cloudflare_dns_record_add	在一个全有或全无的批次中添加 1–20 条共八种类型的记录	添加
cloudflare_dns_record_edit	在一个全有或全无的批次中按 ID 更改 1–20 条记录；绝不更改记录类型	覆盖
cloudflare_dns_record_delete	按 ID 删除 1–20 条记录，并在同一批次中添加替代记录；每次都会先询问	管理

该技能为 cloudflare-dns，在 Claude Code 中显示为 cloudflare-tools:cloudflare-dns，在 Hermes 中显示为 cloudflare-tools:dns。

规则（rules）

规则：读取区域中包含规则的规则阶段，以及某个阶段内按顺序排列的规则，并获取其 ID、位置和版本；添加、更改、移动或删除单个重定向规则、缓存规则、配置规则、URL 重写规则、请求或响应标头转换规则、源站规则或压缩规则。WAF 自定义规则、速率限制规则和自定义错误规则可以读取，但不能更改。表达式、描述和参数均为用户数据，只作为数据返回，绝不会作为指令处理。此工具集默认关闭；通过 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_rules_read	查看区域中哪些 phases 包含规则；按顺序查看某个阶段的 rules	读取
cloudflare_rules_add	在某个阶段添加规则，可放在末尾、某个位置之前、之后或指定位置；若该阶段已有重复规则，则拒绝添加	添加
cloudflare_rules_edit	指定读取时的版本，更改规则的表达式、操作、参数、描述、启用状态或位置；若规则自读取后已更改，则拒绝修改	覆盖
cloudflare_rules_delete	删除某个阶段的规则；始终会先征求确认	管理

令牌需要具有所读阶段对应的 Zone → Dynamic URL Redirects、Cache Settings、Config Settings、Zone Transform Rules、Origin 或 Response Compression → Read 权限，以及在其中添加、更改或删除规则所需的 Edit 权限。Zone → Zone WAF and Custom Errors → Read 权限适用于只读阶段。

该技能为 cloudflare-rules，在 Claude Code 中显示为 cloudflare-tools:cloudflare-rules，在 Hermes 中显示为 cloudflare-tools:rules。

分析（analytics）

分析：读取某个区域近期按天统计的流量（请求数、带宽、缓存命中、威胁、页面浏览量和独立访客数）、请求量最多的路径、客户端所在国家/地区和响应状态、各项安全功能的运行情况（Free 计划不提供），以及最新的安全事件；还可读取账户在近期时间范围内的 Workers 调用次数、错误数和 CPU 时间。此工具集默认关闭；通过 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_analytics_read	按 UTC 天统计的 traffic；排名靠前的 paths、countries 和 statuses；security、security_events 和 workers	读取

令牌需要具有 Zone → Analytics → Read 权限，以及用于查找区域的 Zone Read 权限；读取 workers 则需要 Account → Account Analytics → Read 权限。

该技能为 cloudflare-analytics，在 Claude Code 中显示为 cloudflare-tools:cloudflare-analytics，在 Hermes 中显示为 cloudflare-tools:analytics。

Workers（workers）

Workers：列出 Worker，读取其设置和绑定、部署和版本、某个区域的 Worker 路由、自定义域名、Cron 触发器以及密钥名称和类型，并将 Worker 回滚到此前提供服务的版本。新代码的构建、上传和部署仍由 Wrangler 负责；路由、自定义域名和 Cron 触发器在此处读取，并在 wrangler.toml 中更改。

工具	功能	类别
cloudflare_workers_read	list、view、deployments、versions、routes、domains、schedules、secrets（仅名称）	读取
cloudflare_workers_rollback	将 Worker 回滚到此前提供服务的版本；始终先询问确认	管理

令牌需要 Workers Scripts Read 权限；routes 还需要 Workers Routes Read 权限；routes 以及带有 zone 的 domains 需要 Zone Read 权限才能查询该区域。回滚需要 Workers Scripts Write 权限。

该技能为 cloudflare-workers，在 Claude Code 中显示为 cloudflare-tools:cloudflare-workers，在 Hermes 中显示为 cloudflare-tools:workers。

Pages（pages）

Pages：列出项目，读取其构建设置、环境变量名称和绑定、生产和预览部署（包括当前生效的部署）、构建日志以及自定义域名；将项目的生产环境切换回或前进到已成功构建的部署；并添加或移除其自定义域名。新代码的构建和部署仍由 Git 和 Wrangler 负责；自定义域名的 DNS 记录仍由 DNS 工具负责。

工具	功能	类别
cloudflare_pages_read	list 项目、view 单个项目、其 deployments、构建的 logs、自定义 domains	读取
cloudflare_pages_rollback	将生产环境切换到已成功构建的部署；始终先询问确认	管理
cloudflare_pages_domain_add	为项目添加自定义域名，不创建 DNS 记录；始终先询问确认	管理
cloudflare_pages_domain_remove	移除项目的自定义域名，不删除 DNS 记录；始终先询问确认	管理

令牌需要 Pages Read 权限。写入操作需要 Pages Write 权限，域名工具的 DNS 查询需要 Zone Read 和 DNS Read 权限。

该技能为 cloudflare-pages，在 Claude Code 中显示为 cloudflare-tools:cloudflare-pages，在 Hermes 中显示为 cloudflare-tools:pages。

存储（storage）

存储：按名称、大小和日期列出账户的 R2 存储桶，以及存储桶中的对象和文件夹；读取存储桶是否公开（其 r2.dev 域名和自定义域名）、CORS 规则以及会删除其对象的生命周期规则；列出 Workers KV 命名空间及其键名；列出 D1 数据库并读取其大小和架构；创建空存储桶、命名空间或数据库，并删除已确认为空的对象存储。此工具不会读取对象正文、KV 值或表中的行；D1 架构来自一条固定语句，并且只会列出默认管辖区。Cloudflare 会连同内容一起删除 KV 命名空间或 D1 数据库，因此删除工具会先确认存储为空；清空存储仍由用户负责。此工具集默认关闭；使用 toolsets 设置启用（请参阅 设置）。

工具	功能	类别
cloudflare_storage_read	R2 buckets、bucket 的详情及其 objects；KV namespaces 及其 keys；D1 databases 及 database 的架构	读取
cloudflare_storage_create	根据名称创建空 R2 存储桶、KV 命名空间或 D1 数据库	添加
cloudflare_storage_delete	仅在确认存储桶、命名空间或数据库为空时将其删除；始终会先征求确认	管理

读取存储数据时，令牌需要对应存储的 Account → Workers R2 Storage → Read、Workers KV Storage → Read 或 D1 → Read 权限；创建和删除则需要相同权限的 Edit 权限。

该技能为 cloudflare-storage，在 Claude Code 中显示为 cloudflare-tools:cloudflare-storage，在 Hermes 中显示为 cloudflare-tools:storage。

隧道（tunnels）

隧道：按名称、状态和连接时间列出账户的 Cloudflare 隧道，并读取某个隧道的活动连接器、边缘连接、数据中心和公共主机名入口路由规则。隧道的运行令牌绝不会暴露，不会读取连接器的内部 ID 和源站 IP 地址，也会排除已删除的隧道。对于本地管理的隧道，入口规则保存在主机上，因此无法在此读取。可通过由仪表板管理的隧道，将主机名发布到本地服务：该工具会添加所需的规则和代理 CNAME；如果主机名已有其他 DNS 记录，则会拒绝操作，并且始终会先征求确认。另一个工具可更改已发布主机名指向的服务，还有一个工具可撤下主机名；如果没有其他规则在使用该主机名，它会删除指向隧道的 CNAME，且绝不会触碰其他记录；两者都会先征求确认。此工具集默认关闭；使用 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_tunnel_read	读取账户的 tunnels；读取一个 tunnel 的状态和入口	只读
cloudflare_tunnel_route_add	通过隧道将主机名（及可选路径）发布到本地服务；始终先征求确认	管理
cloudflare_tunnel_route_edit	更改已发布主机名指向的服务，并指定当前服务；始终先征求确认	管理
cloudflare_tunnel_route_remove	从隧道撤下主机名并删除指向隧道的 CNAME；始终先征求确认	管理

令牌需要 Account → Cloudflare One Connector: cloudflared → Read。发布或撤下主机名需要 Account → Cloudflare One Connector: cloudflared → Edit 和 Zone → DNS → Edit；更改主机名的指向需要 Account → Cloudflare One Connector: cloudflared → Edit，以及 Zone → DNS → Read，以读取工具报告的记录。每个公共主机名还会说明是否有 Zero Trust Access 应用与其匹配；这需要 Account → Access: Apps and Policies → Read；若没有此权限，覆盖情况会显示为 unknown。匹配并不意味着每位访客都必须登录：Bypass 策略仍可能允许访客通过。

该技能为 cloudflare-tunnels，在 Claude Code 中显示为 cloudflare-tools:cloudflare-tunnels，在 Hermes 中显示为 cloudflare-tools:tunnels。

电子邮件路由（email）

电子邮件路由：读取某个区域的电子邮件路由是否已启用、路由规则和全权规则（每条规则匹配一个地址，并将邮件转发到一个已验证的地址、丢弃邮件或交给 Worker），以及账户的目标地址和每个地址的验证状态；为一个地址添加、更改或删除路由规则，更改全权规则，以及添加或删除目标地址。由 Worker 的 Wrangler 配置管理的规则会标记为此类规则；未启用电子邮件路由的区域不会路由任何邮件。地址、名称和 Worker 名称均为用户数据，只会作为数据返回，绝不会作为指令处理。此工具集默认关闭；使用 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_email_read	某个区域的 routing 设置和全权规则；其 rules；账户的 addresses	读取
cloudflare_email_rule_add	添加一条规则，将一个地址转发到已验证的目标地址、丢弃邮件或交给 Worker（Cloudflare 会拒绝不存在的 Worker）；如果该地址已有规则，则拒绝添加	添加
cloudflare_email_rule_edit	更改规则的地址、操作、名称或启用状态，并说明当前操作；拒绝更改全权规则和由 Wrangler 管理的规则	覆盖
cloudflare_email_rule_delete	删除规则，并说明邮件接下来会发送到哪里；拒绝删除全权规则和由 Wrangler 管理的规则；始终先征求确认	管理
cloudflare_email_catchall_edit	更改全权规则（未匹配任何规则的邮件）的操作，或将其启用或关闭，并说明当前状态；拒绝更改由 Wrangler 管理的全权规则；始终先征求确认	管理
cloudflare_email_address_add	添加目标地址；Cloudflare 会向其所有者发送确认链接，在所有者点击链接前，任何规则都无法将邮件转发到该地址；始终先征求确认	管理
cloudflare_email_address_delete	删除目标地址；如果账户任一区域中的规则或全权规则仍会将邮件转发到该地址，则拒绝删除；始终先征求确认	管理

令牌需要 Zone → Email Routing Rules → Read 权限，以及 Account → Email Routing Addresses → Read 权限才能读取地址。添加、更改或删除规则，以及更改全权规则，需要 Zone → Email Routing Rules → Edit 权限；添加或更改转发目标还需要 Account → Email Routing Addresses → Read 权限以进行检查。添加或删除目标地址需要 Account → Email Routing Addresses → Edit 权限；删除地址还需要账户所有区域中的 Zone → Email Routing Rules → Read 权限。

此技能为 cloudflare-email，在 Claude Code 中显示为 cloudflare-tools:cloudflare-email，在 Hermes 中显示为 cloudflare-tools:email。

队列（queues）

列出账户的 Cloudflare 队列，并读取一个队列的投递设置、消费者及其批处理和重试设置，以及生产者。绝不会读取消息。队列和 Worker 名称属于用户数据，只会作为数据返回，绝不会作为指令。此工具集默认关闭；通过 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_queues_read	list 账户的队列；view 一个队列的设置、消费者和生产者	读取

令牌需要账户 → Queues → Read 权限。

技能为 cloudflare-queues，在 Claude Code 中显示为 cloudflare-tools:cloudflare-queues，在 Hermes 中显示为 cloudflare-tools:queues。

Hyperdrive（hyperdrive）

列出账户的 Hyperdrive 配置，并读取一个配置的源数据库、缓存、mTLS 和连接数限制。绝不会返回密码和 Access 客户端密钥。名称、主机、数据库名称和其他源信息属于用户数据，只会作为数据返回，绝不会作为指令。此工具集默认关闭；通过 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_hyperdrive_read	list 账户的配置；view 一个配置的源、缓存、mTLS 和连接数限制	读取

令牌需要账户 → Hyperdrive → Read 权限。

技能为 cloudflare-hyperdrive，在 Claude Code 中显示为 cloudflare-tools:cloudflare-hyperdrive，在 Hermes 中显示为 cloudflare-tools:hyperdrive。

Vectorize（vectorize）

列出账户的 Vectorize 索引，并读取一个索引的维度、距离度量、向量数量、处理进度和元数据索引。绝不会读取向量及其元数据值。索引名称和描述属于用户数据，只会作为数据返回，绝不会作为指令。此工具集默认关闭；通过 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_vectorize_read	list 账户的索引；view 一个索引的配置、处理进度和元数据索引	读取

令牌需要账户 → Vectorize → Read 权限。

技能为 cloudflare-vectorize，在 Claude Code 中显示为 cloudflare-tools:cloudflare-vectorize，在 Hermes 中显示为 cloudflare-tools:vectorize。

Turnstile（turnstile）

列出账户的 Turnstile 小组件，并读取某个小组件的主机名、模式、预清除 Cookie 级别、区域和设置。绝不会返回小组件的密钥。小组件名称和主机名是用户数据，仅作为数据返回，绝不作为指令。此工具集默认关闭；使用 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_turnstile_read	list 列出账户的小组件；view 查看某个小组件的主机名、模式、清除级别、区域和设置	读取

令牌需要 Account → Turnstile Sites → Read 权限。

对应技能为 cloudflare-turnstile，在 Claude Code 中显示为 cloudflare-tools:cloudflare-turnstile，在 Hermes 中显示为 cloudflare-tools:turnstile。

Access（access）

列出账户（或某个区域）的 Zero Trust Access 应用，读取某个应用及其策略，并列出账户可重复使用的策略。策略会按配置返回其 include、exclude 和 require 规则，其中包括电子邮件地址；绝不会返回密钥。应用和策略名称、域名及规则是用户数据，仅作为数据返回，绝不作为指令。此工具集默认关闭；使用 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_access_read	apps 列出账户（或某个区域）的应用；app 读取某个应用及其策略；policies 列出可重复使用的策略	读取

令牌需要 Account → Access: Apps and Policies → Read 权限；若要读取某个区域的应用，还需要 Zone → Access: Apps and Policies → Read 权限。

对应技能为 cloudflare-access，在 Claude Code 中显示为 cloudflare-tools:cloudflare-access，在 Hermes 中显示为 cloudflare-tools:access。

Registrar（registrar）

列出账户已注册的域名，并读取某个域名的状态、到期时间、自动续订、转移锁定和 WHOIS 隐私模式。绝不会返回注册人联系信息。域名是用户数据，仅作为数据返回，绝不作为指令。此工具集默认关闭；使用 toolsets 设置启用（参见设置）。

工具	功能	类别
cloudflare_registrar_read	list 使用游标分页和排序列出已注册域名；view 查看某个域名的注册元数据	读取

令牌需要 Account → Registrar Domains → Read 权限。

对应技能为 cloudflare-registrar，在 Claude Code 中显示为 cloudflare-tools:cloudflare-registrar，在 Hermes 中显示为 cloudflare-tools:registrar。

授权（grants）

默认关闭。对于无人可回答的任务，委派受限写入权限。

工具	功能说明	类别
cloudflare_grant_create	请求某人委派一个工具在限额内执行写入操作	管理
cloudflare_grant_read	列出授权及其使用情况，或读取使用日志	读取
cloudflare_grant_revoke	撤销授权，使其不再执行任何调用	覆盖

每个写入工具都可以针对其目标设置授权、每小时调用次数和有效期。 工具可以通过在其规格中声明 bounds 并提供 measure(args, context)，来增加授权也可限制的项目；请参阅 约定。此程序包尚无工具 声明 bounds。

添加工具

1. 使用 defineTool 在 src/core/<domain>/<verb>.ts 中编写规格：包含 ID <prefix>_<domain>_<verb>、标题和描述、Zod 参数和输出架构、所属工具集和写入类别，以及 execute(args, context)。写入工具还需提供 targets(args, context)：说明调用会写入 哪些目标，以便权限规则能够明确指定。若某工具的设置会导致某些调用无论用户如何回答都无法执行，则提供 gate(args, context)，对此类调用抛出异常；此类调用会在询问任何人之前、执行 execute 之前被拒绝。
2. 在规格旁边为其编写测试（<verb>.test.ts），通过入口使用的 invoke 调用工具。运行程序的工具应使用 PATH 上该程序的模拟版本进行测试；测试不会访问真实服务。
3. 在 src/tools.ts 中列出该工具。新增工具集应加入 src/project.ts 中的 toolsets（如果默认启用，也加入 defaultToolsets）；程序包自身的设置应加入 options（并在 project.py 中加入 OPTIONS，在 plugin.yaml 中加入 config_schema）；除设置外，工具读取的变量应加入 toolVariables。
4. 添加或更新工具集的技能文件 skills/<prefix>-<toolset>/SKILL.md， 其 frontmatter 应在 metadata 下列出该工具集。
5. 运行 pnpm run build && pnpm run manifests，将工具列入 plugin.yaml，并将其变量列入 Codex 清单，然后在 “工具和技能”下介绍它。

docs/conventions.md 列出了每个步骤所遵循的规则。

程序包将每个选项声明为 text、boolean、number、list、path 或 paths，也可以声明为带有 type 和可选边界的对象。例如，在 src/project.ts 中：

options: {
  notes_dir: "path",
  note_limit: { type: "number", integer: true, min: 1, max: 50 },
}

integer: true 要求值为整数；min 和 max 用于限定数字，或统计 list 或 paths 值中的项目数。仅包含 type 的对象与单独使用该类型的含义相同。Hermes 的 OPTIONS 会在一行中对应这些声明，对于 integer 使用双引号和 Python 的 True：

OPTIONS: dict[str, str | dict[str, object]] = {"notes_dir": "path", "note_limit": {"type": "number", "integer": True, "min": 1, "max": 50}}

读取与写入

每个读取工具的名称都为 <prefix>_<domain>_read。读取可以在未询问的情况下运行；在有人值守的运行中，写入会由执行框架确认。启用 unattended 后，写入则需要下文所述的适用授权。

执行框架	无需询问即可读取
OpenCode	始终如此；插件只会在写入前询问
Claude Code	~/.claude/settings.json 中 permissions.allow 里的规则 mcp__plugin_cloudflare-tools_cloudflare-tools__*_read
Codex	始终如此；Codex 会在未询问的情况下运行声明了 readOnlyHint 的工具，读取工具就是如此
Grok Build	grok --allow 'MCPTool(cloudflare-tools__*_read)' --allow 'MCPTool(cloudflare_*_read)'（两条规则；见下文）
Antigravity	permissions.allow 中的规则 mcp(cloudflare-tools_cloudflare-tools/<tool id>)，每个读取工具各一条
Hermes	始终如此；插件只会在写入前询问

以下说明写入在哪些情况下会被询问，哪些情况下不会：

• OpenCode 授予任何操作都不需要规则名称，因此除非规则要求询问，否则写入会在未询问的情况下运行：添加 OpenCode 下所示的 cloudflare_* 规则。
• Codex 会因插件的审批模式而在每次写入前询问。 在 codex exec 下，它会报错拒绝：“MCP tool call requires approval, but approval policy is never”。对于有界任务，请参见 无人审批时的写入。
• Grok Build 在 grok -p 下会拒绝无法询问用户的写入，除非已事先授权。
• Grok Build 通过其 use_tool 工具调用插件的工具，而且 Agent 往往会先不带服务名称来指定工具。Grok 会根据给出的名称检查规则，因此仅有带服务名称的规则无法匹配首次调用。第二条规则会匹配短名称；写入仍然两条规则都不匹配。
• Antigravity 会在任何 MCP 工具未被规则授权时先询问，读取也包括在内，并将插件的服务命名为 cloudflare-tools_cloudflare-tools（先是插件，再是服务）。agy -p 会拒绝无法询问用户的工具。
• Hermes 在 hermes chat -q 下会拒绝无法询问用户的写入；hermes -z 和 --yolo 会跳过审批，因此写入会在未询问的情况下运行。对于有界任务，请参见 无人审批时的写入。

如果工具的 gate 拒绝某次调用，无论回答如何，该调用都不会运行。OpenCode 和 Hermes 会在询问前拒绝，因此不会显示相关提示；Hermes 会显示该工具的错误信息来拦截调用。Claude Code、Codex、Grok Build 和 Antigravity 会在 MCP 服务收到调用前显示各自的提示，因此它们仍可能询问是否允许调用；随后服务会拒绝该调用。

无人批准时写入

授权会将某个任务的写入限制为一个工具，最长 90 天。其余条件由人员决定：目标（指定目标，或用 * 表示任意目标）、工具声明的限制（未填写的项不设限制），以及每小时调用次数（未填写则不限制）。每次在授权下进行的调用都会记录。授权绝不会覆盖主机的权限。 约定说明了具体规范。

1. 在有人应答的会话中，提供设置中所述的密钥，同时启用 grants 工具集和任务的工具集，并让 Agent 进行委托。它会调用 cloudflare_grant_create；提示会显示工具、目标、频率、天数、工具声明的每项限制（未填写的项显示 no limit）以及原因。 批准一次。
2. 仅为该任务设置相同的密钥和 unattended，例如 CLOUDFLARE_TOOLS_UNATTENDED=true。否则不会检查授权。
3. 允许主机在本次运行中使用写入工具，如下所示。授权仍会限制每次调用。
4. 使用 cloudflare_grant_revoke 撤销授权，或使用 cloudflare_grant_read 列出授权及其使用情况。

无人应答时，如何允许写入操作到达软件包，例如 cloudflare_dns_record_add：

• OpenCode opencode run 会拒绝所有问题，除非有规则明确允许该工具（"permission": { "cloudflare_dns_record_add": "allow" }），或使用 --auto 启动运行。
• Claude Code claude -p 需要将该工具列入 --allowedTools，例如 mcp__plugin_cloudflare-tools_cloudflare-tools__cloudflare_dns_record_add。
• Codex codex exec 需要在 config.toml 中插件的 MCP 服务下，为该工具设置 approval_mode = "approve"（[mcp_servers.<server>.tools.<tool>]），因为插件默认会在每次写入前询问。
• Grok Build grok -p 需要同时设置以下两条允许规则： --allow 'MCPTool(cloudflare-tools__cloudflare_dns_record_add)' 和 --allow 'MCPTool(cloudflare_dns_record_add)'，分别对应读取和写入中所述的限定名称和短名称。
• Antigravity agy -p 需要在 permissions.allow 中设置 mcp(cloudflare-tools_cloudflare-tools/cloudflare_dns_record_add)。
• Hermes hermes chat -q 在 approvals.single_query_mode 设置为拒绝时会拒绝操作，除非已允许。-z 和 --yolo 会跳过审批并执行写入；此时授权是唯一的限制。

限制

• 如果跳过所有审批（Hermes -z 或 --yolo、始终批准模式、明确允许 cloudflare_grant_create，或 OpenCode V1 全局 allow），则不会显示提示。在这种情况下创建的授权并非由人员应答，其范围可以涵盖任意目标，且 90 天内没有限制或频率上限：仅在运行环境会询问的情况下创建授权。
• 整个恢复较早版本的授权目录不会被检测到。最多 90 天的有效期限制了它可以恢复的内容。
• 任何能读取密钥的人都可以签发授权。请将其存放在 Agent 的工具无法读取的位置。
• OpenCode V2 插件通过钩子强制要求为 cloudflare_grant_create 进行询问；只有提供该钩子的主机才会运行它。

OpenCode V2 服务和 Hermes 网关会保留启动时的环境；更改任务变量前，请参阅设置。

设置

所有入口点都使用相同的设置。标志优先于其环境变量；选项或设置也优先于变量。

设置	标志	变量	含义
toolsets	--toolsets	CLOUDFLARE_TOOLS_TOOLSETS	启用的工具集，或 all；默认使用 src/project.ts 中的名称
read_only	--read-only	CLOUDFLARE_TOOLS_READ_ONLY	不注册任何会写入的工具；优先级高于其他所有设置
unattended	--unattended	CLOUDFLARE_TOOLS_UNATTENDED	无人可以响应：写入操作仅在授权范围涵盖该操作时才会运行；默认关闭
grants_dir	--grants-dir	CLOUDFLARE_TOOLS_GRANTS_DIR	保存授权及其使用记录的位置；默认为 $XDG_STATE_HOME/cloudflare-tools/grants，否则为 ~/.local/state/cloudflare-tools/grants
tools	--tools	CLOUDFLARE_TOOLS_TOOLS	按 ID 添加单个工具，无论它们属于哪个工具集
exclude_tools	--exclude-tools	CLOUDFLARE_TOOLS_EXCLUDE_TOOLS	按 ID 移除单个工具；优先级高于 tools 和 toolsets
confirm	--confirm	CLOUDFLARE_TOOLS_CONFIRM	仅限 MCP 服务：按约定使用 harness（默认）或 elicitation
language	--language	CLOUDFLARE_TOOLS_LANGUAGE	仅限原生插件：审批提示词的语言，例如 ja
emoji	—	—	仅限 Hermes：按工具集名称显示在每个工具集旁边的表情符号（无表情符号时为 ""）
require_plugins	—	—	仅限 Hermes：必须加载的插件；只要有插件尚未加载，所有写入操作都会在审批前被拒绝

CLOUDFLARE_TOOLS_GRANT_KEY 只能是变量，不能是标志或插件选项。请使用至少 32 个字符的值，例如通过 openssl rand -hex 32 生成，并存储在主机保存机密信息的位置。没有该值时，无人值守模式下不会运行任何写入操作，也无法创建授权。Codex 会将其与设置变量一并转发，如下所述。

标志或变量中的列表以逗号分隔。此处为软件包自身设置各列一行，这些设置在 src/project.ts 的 options 中列出，并以相同方式读取。path 会去除首尾空白；~ 和 ~/…（以及使用平台分隔符的形式）表示主目录（如果 HOME 是绝对路径，则使用它，否则使用账户的主目录）。路径之后必须是绝对路径，并会以规范化形式传给工具，不进行文件系统检查。paths 是此类路径组成的列表，在标志或变量中以逗号分隔，在插件选项中则为字符串数组。空路径，以及去除空白并删除空项后不含任何项目的列表，均视为未设置。边界检查只针对给定的值，不针对未设置的选项。被拒绝的值会返回 invalid_argument，并指出标志、变量或选项名称及其要求。Hermes 会将路径和列表传给命令行，由命令行检查路径和边界。各个运行环境读取这些设置的方式如下：

• OpenCode 使用上文所示的插件 options，列表为数组，read_only 为布尔值；未提供时则使用变量。

• Hermes 使用 config.yaml 中的 plugins.entries.cloudflare-tools.settings：

  plugins:
    entries:
      cloudflare-tools:
        settings:
          read_only: false
          exclude_tools: []
  

  如果未设置 language，审批卡片会遵循 Hermes 自身的 display.language（或 HERMES_LANGUAGE），其审批按钮也会使用该语言；否则则使用英语。

• Claude Code、Grok Build 和 Antigravity 不带标志启动插件的服务， 并将客户端的环境传递给它，因此请在运行该宿主的环境中设置这些变量。

• Codex 只向插件的 MCP 服务传递少数几个基本变量（例如 PATH 和 HOME），以及插件清单中列出的变量，也就是上述变量：请在运行 Codex 的环境中设置它们。工具读取的、设置项以外的变量应添加到 src/project.ts 的 toolVariables 中；pnpm run manifests 会将它添加到清单中，排在设置项的变量之后。若要传递标志，或向服务提供包未列出的变量，请改为在 Codex 的 config.toml 中的 [mcp_servers] 下添加该服务，而不要使用插件；在 args 中填写标志，并在 env_vars 中填写要转发的变量，如凭据所示。

各宿主从哪里获取这些变量，以及要在何时重启才能应用更改，请参阅凭据。

凭据

工具通过从环境中读取的 API 令牌调用 Cloudflare，不会从设置项或参数中读取令牌。每个令牌都对应其所操作的一个账户：

变量	选择条件
CLOUDFLARE_API_TOKEN、CLOUDFLARE_ACCOUNT_ID	未填写 account，或 account: "default"
CLOUDFLARE_API_TOKEN_<LABEL>、CLOUDFLARE_ACCOUNT_ID_<LABEL>	account: "<label>"，标签为小写

• 未加标签的一对变量使用 Wrangler 读取的名称。标签由 1 至 24 个小写字母、数字和 _ 组成，在变量名中需使用大写字母 （my_site → CLOUDFLARE_API_TOKEN_MY_SITE）。
• 未填写 account 时，调用会使用未加标签的一对变量；若不存在未加标签的一对变量，则使用唯一的标签。如果存在多个标签且没有未加标签的一对变量，调用会失败并列出这些标签。
• 如果设置了 CLOUDFLARE_API_TOKEN，却没有设置 CLOUDFLARE_ACCOUNT_ID（例如为 Wrangler 导出变量时可能出现这种情况），它仍会被视为未加标签的一对变量：即使设置了完整的带标签变量对，未填写 account 的调用也会失败。请传入 account，或取消设置这个多余的令牌。
• 请使用权限范围与工具应执行的操作相符的 API 令牌；工具会拒绝 Global API Key。

请在各宿主启动工具的环境中设置这些变量：

• OpenCode V2 在后台服务中运行插件，该服务会保留启动时的环境：请在启动该服务的位置设置变量，并在设置或更改变量后重启服务（opencode service restart）。OpenCode V1 在独立进程中运行插件，因此只需在运行该进程的环境中设置变量。

• Claude Code、Antigravity 和 Grok Build 会将运行宿主的环境传递给插件的服务。

• Hermes 会传递其运行时的环境，但已在运行的 gateway 会保留启动时的环境：请在设置或更改变量后重启 gateway（hermes gateway restart）。

• Codex 只向插件的服务传递少数几个基本变量（例如 PATH 和 HOME），以及清单中列出的设置项变量，不会传递凭据。请在 ~/.codex/config.toml 中添加同名服务，以替代插件服务（插件的技能仍会保留），并在 env_vars 中列出要转发的变量。startup_timeout_sec 为 npx 首次启动时获取包留出时间：

  [mcp_servers.cloudflare-tools]
  command = "npx"
  args = ["-y", "@craftsamo/cloudflare-tools@<version>"]
  env_vars = ["CLOUDFLARE_API_TOKEN_<LABEL>", "CLOUDFLARE_ACCOUNT_ID_<LABEL>"]
  startup_timeout_sec = 120
  

• 任何其他 MCP 主机都从其服务条目的 env 中获取这些变量。

目录结构

• src/project.ts — 包的名称、工具 ID 前缀、设置前缀、工具集、工具选项，以及工具读取的其他变量。
• src/core/ — 工具契约和工具，不依赖任何执行环境，也不包含项目名称。
• src/tools.ts — 每个入口点都会注册的所有工具列表。
• src/words.ts — 按语言划分的工具用词译文，原生插件会在审批提示词中使用这些译文。
• src/mcp/ — MCP 服务，构建为 dist/mcp.js，并由 cloudflare-tools 运行。
• src/opencode/ — OpenCode 插件，构建为 dist/opencode.js。
• src/cli/ — Hermes 插件调用的命令行，构建为 dist/cli.js，并由 cloudflare-tools-cli 运行。
• src/hermes/、plugin.yaml 和 __init__.py — Hermes 插件。
• skills/ — 每个工具集对应一个技能，路径为 skills/<name>/SKILL.md。支持技能的每种执行环境都会从包或插件根目录加载技能；原生插件只加载已启用工具集的技能。
• .claude-plugin/、.codex-plugin/、.agents/plugins/、.mcp.json、.antigravity-plugin/ 和 mcp_config.json — 其他执行环境的插件清单。Codex 会读取 .codex-plugin/plugin.json；如果根目录中存在 plugin.json，它会将插件作为 Agent Plugin 加载，而 Agent Plugin 的工具预算会隐藏超过固定数量的工具。根目录的 .mcp.json 是 Grok Build 读取的配置（使用 ${CLAUDE_PLUGIN_ROOT}，这是 Grok Build 和 Claude Code 都会展开的变量）；在 Claude Code 中处理此仓库时，请拒绝它通过该文件提供的项目 MCP 服务。

发布流程见 RELEASING.md。

许可证

AGPL-3.0 with Commons Clause