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 首次發布