Cloudflare cf CLI 怎样用 JSON 让 AI Agent 先搜索命令、再核对并调用 API？（2026）

阅读前速览

对象	截至 2026-10-13 的公开事实	Agent 怎么用
cf	9 月 28 日公开测试。覆盖整个 API，文档写超过 2900 条命令。npm 全局安装	默认输出 JSON，不必再加 --json
cf cli search	本地搜索，不需要登录。整句必须加引号。最多 5 条，最好的在前	只拿 command 和 summary，不执行
cf schema	描述生成命令会发的 HTTP：方法、路径、参数、请求体字段	缺字段先补。deploy 这类命令看 --help
执行结果	9 月 29 日文档：JSON 一律缩进。非交互删除若没加 --force，可能只在标准错误打印 Aborted.，退出码仍是 0	先看 stdout 的 JSON，再看退出码

发布稿写「对人美化、对 Agent 压缩」。9 月 29 日的文档改成：无论标准输出是不是终端，JSON 都缩进。10 月 8 日对 1.0.0-beta.5 的公开核对也没有看到压缩输出。解析器按文档来。域名 orders.example.test 是虚构的。

Agent 用三步 JSON 操作 Cloudflare，不靠背命令

9 月 28 日 Cloudflare 公开了 cf。发布稿说，3 月 Agent 约占 Wrangler 用量的四分之一，发布前一周到了 48%。Wrangler 大约 280 条手工命令，盖不住整个 API。新 CLI 由 OpenAPI 生成，文档在 9 月 29 日写成超过 2900 条命令。安装是 npm install --global cf。登录 cf auth login 要人在浏览器里批准。没人值守时用环境变量 CLOUDFLARE_API_TOKEN，它优先于已保存的登录。不要把令牌写进仓库，示例只用 sk_demo_not_real 这个占位。

• 搜索：cf cli search "create D1 database"。引号不能省。本地跑，不碰账号。
• 核对：cf schema d1 create 给出将要发送的 HTTP 字段。真正改资源前加 --dry-run，试运行也不需要凭据。
• 执行：标准输出只有 JSON 结果。选中的 zone、错误和 Aborted. 在标准错误。

这不是浏览器里点页面。插件目录里的 mcp.json 怎么放服务器，见 Agent Plugins 1.0.0 的目录约定。MCP 的 tools/call 长什么样，见 Coding Agent 如何调用 MCP。本篇只写 cf 吐给 Agent 的 JSON。

搜索结果是一个最多五条的数组

9 月 29 日文档给出的前两条就是这个形状。字段只有 command 和 summary：

[
  {
    "command": "cf d1 create",
    "summary": "Create D1 Database"
  },
  {
    "command": "cf d1 update",
    "summary": "Update D1 Database"
  }
]

不加引号时，第一个词之后会被当成未知命令。根命令和分组的 --help 会先提醒 Agent 去搜索。某条命令自己的 --help 是纯文本，不是这份数组。命令不存在时，CLI 会列出接近的名字，那也不是搜索结果。

先读将要发出的请求，再读执行后的一页结果

cf schema 只覆盖生成出来的 API 命令。cf deploy 要看 --help。文档列出的键是 operationId、httpMethod、path、pathParams、queryParams、hasRequestBody、requestBodyFields。参数用 API 名，例如 account_id。请求体字段用选项名，并带说明。有的请求体清单不完整，这时用 --body 交完整正文。下面是同一组字段的示意，主机名是虚构的，不要当成某次线上抓包：

{
  "operationId": "dns-records-create",
  "httpMethod": "POST",
  "path": "/zones/{zone_id}/dns_records",
  "pathParams": [
    { "name": "zone_id", "type": "string", "required": true }
  ],
  "queryParams": [],
  "hasRequestBody": true,
  "requestBodyFields": [
    { "name": "type", "type": "string", "required": true, "description": "Record type" },
    { "name": "name", "type": "string", "required": true, "description": "Record name" },
    { "name": "content", "type": "string", "required": true, "description": "Record content" }
  ]
}

必填项过了门再执行。Schema 为什么不能只写在提示里，见 AI 为什么需要 JSON Schema。列表命令的标准输出是一页 JSON 数组。分页参数每条命令不同。没有数据的修改，标准输出是空的。R2 对象或模型图片会原样打到标准输出，不是对象。虚构的一页 DNS 记录：

[
  {
    "id": "rec_demo_1042",
    "type": "TXT",
    "name": "orders.example.test",
    "content": "demo-pass"
  }
]

字段名随命令变。解析器先确认这是数组，再按该命令的 schema 取 id 或 name。不要假设每一页都有 success 外壳。

标准输出、标准错误和退出码不要合成一个成功

Agent 最容易把三样东西读成一件：

已有 Wrangler 配置的项目继续用 Wrangler。其他 Cloudflare 任务走 cf。这句话可以写进 AGENTS.md 或 CLAUDE.md。--local 只覆盖少数本地资源，例如部分 KV、D1 和 R2。cf d1 query 没有本地等价命令，会报错，而不是悄悄打线上 API。

六步再让 Agent 改线上资源

不要从「把令牌贴进提示」开始：

1. 人来完成 cf auth login。没人值守时才设置 CLOUDFLARE_API_TOKEN。令牌不要出现在命令 JSON 里。
2. 用引号搜索。整句一个参数。先读最多五条里的 command。
3. 跑 cf schema。看 required。清单不完整就改用 --body，并对照 API 文档。
4. 先 --dry-run。它打印请求 JSON，不发送，也不需要凭据。确认路径里是 zone_demo_1042 这种演示值。
5. 只解析标准输出。空输出表示这次修改没有返回数据。破坏性命令看标准错误里有没有 Aborted.。
6. Wrangler 项目先迁移。没有 cloudflare.config.ts 时，不跑 deploy。生成文件里的 TODO(@cloudflare) 没处理完，构建会失败。

公开测试结束以后，Wrangler 还会再维护 18 个月。现在两套可以并存，但不要在同一个项目里让 Agent 用 cf deploy 盖掉旧配置。

放行一次写操作前摊开三份 JSON

一次失败，多半是搜索没加引号、schema 和结果对不上，或把退出码 0 当成已经删除。

• 把搜索数组和 schema 格式化，再用 Schema 校验 看 requestBodyFields 里 required: true 的项是否都在。
• 用 JSONPath 提取 抽出 $[0].command、$.httpMethod、$.path。
• 用 JSON Diff 对比 --dry-run 的请求和执行后的一页结果。先补缺字段，再改提示。
• 标准错误里如果有 Aborted.，这次删除没有发生。
• zone、令牌和账号 ID 不要贴进公共格式化站。JSONSort 在浏览器本地跑。

三份 JSON 对得上，才算 Agent 是在调用 API，而不是在猜命令。缩进本身不是错误。

常见误区

• 按发布稿等一份压缩 JSON。当前文档写的是一律缩进。10 月 8 日对 beta.5 的核对也没有看到因检测到 Agent 而变短的输出。
• 搜索不加引号。第二个词会变成未知命令。搜索结果和「接近的命令名」不是同一份 JSON。
• 退出码 0 就当删除成功。非交互、没有 --force 时，可能只是中止。标准错误要一起看。
• 在只有 wrangler.jsonc 的仓库里跑 cf deploy。它可能生成一份新配置，旧配置被晾在一边。先 dry-run 迁移。
• 把 API 令牌写进提示或提交进 JSON。无人值守只用环境变量。示例不要用真实 token。
• 把 cf 写成会自己点浏览器的 Agent。登录那一步要人批准。之后的 API 调用是 CLI 打出的 JSON，不是页面操作。

FAQ

Agent 还要给每条命令加 --json 吗？

不用。cf 的结果默认就是 JSON，打在标准输出。Wrangler 才是有的命令要加 --json、有的命令给表格。按 9 月 29 日文档，这份 JSON 会缩进，不要等一份压缩格式。

cf cli search 会不会用我的账号去搜？

不会。搜索在本地，不需要凭据。它返回最多五个对象，每个有 command 和 summary。真正改资源的是后面那条命令。

没有返回 JSON，是不是失败了？

不一定。不返回数据的修改，标准输出是空的。失败是非零退出码，错误在标准错误。删除被中止时，标准错误是 Aborted.，退出码可以仍是 0。

已有 Wrangler 项目要马上改成 cf 吗？

不必在同一天切 deploy。有 wrangler.jsonc 或 wrangler.toml 时，开发、构建和部署先留在 Wrangler。迁到 cloudflare.config.ts 用 cf migrate，先加 --dry-run。公开测试结束后 Wrangler 还有 18 个月维护。

schema 里的请求体字段不全怎么办？

文档写明，有些命令的 requestBodyFields 不完整或为空。这时用 --body 提交完整正文，并对照 API 文档。不要把空列表理解成这个接口没有请求体。

结论

cf 让 AI Agent 用 JSON 调用 Cloudflare API：搜索给出命令名，schema 给出将要发送的字段，标准输出给出一页结果。解析时认缩进 JSON，并把标准错误和退出码分开看。

先确认 cf d1 create 来自搜索数组，zone_id 来自 schema，orders.example.test 只出现在演示结果里。三处对得上，再让它改线上资源。

延伸阅读

• Agent Plugins 1.0.0 的 plugin.json 另一份固定位置的 MCP 配置，不是这条 CLI
• Coding Agent 如何调用 MCP tools/call 的线上形状
• 为什么 AI 需要 JSON Schema 必填字段为什么不能只写在提示里
• JSONSort 本地工具箱 格式化、校验、Diff、JSONPath
• 全部文章 更多 JSON 与 AI 开发笔记

更新记录： 2026-10-13 首次发布