前言¶

用過 Cursor、Claude Code、Codex 這類 AI 編程助手的人，大概都碰到過同一種中斷：任務做到一半，模型突然說「我沒法生成圖片 / 沒法抓即時行情 / 沒法發郵件」，接着讓你去某個網站註冊賬號、申請 API Key，再把密鑰貼回來。有的任務就此停住，有的則被改成一段「請自行完成」的說明。

問題不在模型不會寫代碼，而在能力邊界之外的那一層：圖片、音視頻、網頁抓取、即時數據、短信郵件，往往要接外部付費服務。每個服務一套註冊、一套 Key，Agent 既沒有統一的發現入口，也沒有統一的付費方式，只能把活甩回給用戶。

Zero 想做的就是把這一層補上。它給 Agent 提供一個可搜索的外部能力目錄，以及一次登錄、按次付費的調用通道。對應的 Agent Skill 名字就叫 zero，官方倉庫在 officialzeroxyz/zero-plugins，Skill 原文在 plugins/zero/skills/zero/SKILL.md。VoltAgent 維護的 awesome-agent-skills 也把它列在 Zero 出品的技能裏。

截至 2026 年 8 月中旬，npm 上的命令行工具 @zeroxyz/cli 版本爲 1.30.0。下文安裝命令、配置路徑和調用流程，均以官方倉庫 README、Skill 原文、zero.xyz 以及 npm 文檔交叉覈對後的內容爲準。

這是什麼¶

Zero 官方把自己定位成 面向 AI Agent 的搜索引擎和支付層：Agent 發現自己做不到的事情時，先在 Zero 上搜索外部能力（文檔裏稱爲 capability），看清接口和價格，再直接調用；遇到 HTTP 402 付費響應，由 CLI 自動完成支付，而不是讓用戶去每個服務商那裏單獨註冊。

出品與維護方是 Zero（站點 zero.xyz，GitHub 組織 officialzeroxyz）。插件倉庫 zero-plugins 裏同時放了 Skill、鉤子和各宿主的安裝清單。一次安裝會帶上三樣東西：

1、zero Skill：教 Agent 何時該用 Zero、怎麼搜、怎麼調、怎麼寫評價。觸發條件寫得很明確——正要告訴用戶「我做不到」，或正要讓用戶自己去註冊、登錄、申請某個外部 API 的時候，先跑一次 zero search。
2、Hooks：在會話開始時準備好 Zero CLI runner，並提醒模型 Zero 可用。
3、MCP 連接器（https://mcp.zero.xyz）：給沒有本地 shell 的客戶端用，例如 Claude 網頁版和移動端，主要負責鑑權和充值，而不是完整的搜索-調用循環。

登錄態和運行時是機器級共享的：會話寫在 ~/.zero/config.json，runner 默認在 ~/.zero/runtime。同一臺電腦上的 Claude Code、Codex、Cursor 等，登錄一次即可。

支付協議方面，Skill 原文寫明會自動處理 x402 和 MPP 的 402 響應，並支持從 Base 跨鏈橋接到 Tempo。x402 是把 HTTP 402 Payment Required 用到按次付費 API 上的一套協議；MPP（Machine Payments Protocol）是另一套機器支付協議。對使用者來說，不需要自己拼支付頭，CLI 會代勞。官網 FAQ 寫明：價格在調用前可見，Zero 不加價，資金在用戶自己的錢包裏，ZeroClick 不託管資金。這些是官網陳述，實際結算以調用時返回的支付信息爲準。

核心功能¶

Skill 把一次完整調用寫成四步：search → inspect → call → review。已經有明確 URL 時，可以跳過搜索，直接 zero fetch。

搜索。 zero search "weather forecast" 按自然語言找能力。Skill 要求每次都重新搜，不要複用對話裏記住的 URL、schema 或價格。每條結果帶一個歸因 token，格式是 z_xxx.N（N 是這次搜索裏的 1-based 序號），後續 get / fetch 要用這個 token，而不是隻寫一個數字。npm 文檔還提到默認會過濾掉單次價格高於 30 美元 的結果，可以用 --max-cost、--free 收緊或放寬。

查看詳情。 zero get z_Ab12cd.1 --formatted 打出人類可讀摘要和一條可複製的 Try it: 命令；不加 --formatted 則返回完整 JSON，包括 URL、方法、bodySchema、示例和定價。如果 bodySchema 爲 null，Skill 要求跳過這條結果，不要自己編字段名。

調用。 zero fetch 真正發請求。402 會自動付；--max-pay 限制單次花費；二進制結果（圖片、音頻、PDF）寫到 stdout，需要重定向到文件。進度、支付信息和 Run ID 走 stderr。

評價。 付費調用之後要用 zero review 打分。--success 或 --no-success 必填，另外還有 --accuracy、--value、--reliability（1–5 分）。評價會落到該能力在 zero.xyz 上的公開頁面，給後面的 Agent 當信號。

Skill 也寫了什麼時候不要用 Zero：寫代碼、用模型自己的知識回答、讀本地文件、跑 shell、做數學——這些本機就能做。能力調用會花用戶的真金白銀，用付費服務去幹模型本來就會的事，就是浪費。

另外還有一條旁路：身份斷言。如果某個站點支持 agent auth / ID-JAG，並且把 Zero 列爲可信簽發方，可以用 zero auth identity <host> 換短期 bearer token，不必再走一遍對方的註冊流程。這不是所有服務都支持，命令會立刻告訴你這條路通不通。

安裝與啓用¶

官方推薦的方式，是把下面這段交給你正在用的 Agent，讓它自己裝。這段提示詞和 zero.xyz/setup.md、倉庫 README 是同一套：

Help me set up Zero — a tool that lets you find and use extra services you
don't have built in (image/video generation, search live social media, or
hosting a free webpage). It's free to set up.

Set it up by running the Zero CLI's setup (needs Node.js — install it first if
`npm` isn't available):

    npm i -g @zeroxyz/cli
    zero init
    zero auth login

通用安裝要求 Node.js 20+。zero init 會檢測當前環境裏的宿主 CLI（文檔寫明可調用 claude、codex、gemini、openclaw 時走插件安裝），裝不上再退回獨立的 Skill / Hooks。卸載用 zero uninstall，倉庫說明它會撤掉獨立安裝；各宿主自己的插件，仍由對應工具管理。

沒有 npm 時，官方通用指南還提供獨立安裝腳本，地址是 https://www.zero.xyz/install.sh，具體用法見倉庫的 guides/generic.md。

各工具的入口並不完全一樣，官方 guides 裏分別寫了：

1、Claude Code（CLI）

會話裏：

/plugin marketplace add officialzeroxyz/zero-plugins
/plugin install zero@zero-plugins
/reload-plugins

終端裏：

claude plugin marketplace add officialzeroxyz/zero-plugins
claude plugin install zero@zero-plugins

Claude 網頁版 / 移動端沒有終端，走插件界面，說明在 zero.xyz/install/claude.md。

2、Codex（CLI）

會話裏同樣是 marketplace + 安裝；終端命令略有不同，注意是 plugin add 而不是 plugin install：

codex plugin marketplace add officialzeroxyz/zero-plugins
codex plugin add zero@zero-plugins

3、Gemini CLI

gemini extensions install https://github.com/officialzeroxyz/zero-plugins

裝完需要重啓 Gemini CLI。擴展本身用 gemini extensions update zero 更新。

4、Cursor 以及其他帶 shell 的 Agent

倉庫把 Cursor 歸在通用指南里。plugins/zero/agents.json 裏 Cursor 的獨立安裝路徑是 ~/.cursor/skills（以及 ~/.agents/skills），hooks 寫到 ~/.cursor/hooks.json。本機執行：

npm i -g @zeroxyz/cli && zero init

如果 Cursor 沒有自動讀到 Skill，可以把安裝目錄指過去：

zero init --skills-dir ~/.cursor/skills

倉庫目前單獨打成插件發行的宿主是 Claude Code、Codex、Droid、Gemini CLI，其餘（包括 Cursor）走同一套 Skill + Hooks。裝好後對 Agent 說一句 “help me set up and test Zero”，它會帶你完成登錄。

登錄在用戶自己的電腦上走設備碼流程，不在跑 Agent 的那臺機器上彈瀏覽器：

zero auth login --start --json
# 把返回的 url / userCode 發給用戶，讓用戶在瀏覽器裏授權
zero auth login --finish <deviceCode> --json

也可以直接 zero auth login。查當前身份用 zero auth whoami。沒有人類在場、完全無人值守時，Skill 才允許 zero auth agent register（匿名賬戶 + 託管錢包）；有人在場時不要用這條，以免做出一個暫時無人認領的賬戶。

官網寫明安裝免費，新用戶目前有 5 美元 試用額度（頁面同時標了 limited time，是否長期有效以官網爲準）。餘額不足時，人類賬戶去 https://www.zero.xyz/profile 充值；匿名 Agent 賬戶則用 zero wallet fund --no-open，把一次性充值鏈接轉給用戶。

典型用法¶

下面這條端到端流程來自官方 Skill 原文，URL 是示意性質，真實調用要以當時 zero search / zero get 返回的地址和 schema 爲準。

zero search "sentiment analysis"
# 結果裏會有 token（z_xxx.N），後面都用它引用這條能力
zero get z_Ab12cd.1 --formatted
zero fetch https://nlp-api.example.com/sentiment \
  --capability z_Ab12cd.1 \
  -d '{"text":"Zero is great"}' \
  -H "Content-Type:application/json"
# Run ID 在 stderr，--json 時在信封的 runId 字段
zero review abc123 --success --accuracy 5 --value 4 --reliability 5 \
  --content "Classified a 200-char product-review snippet positive in ~180ms; matched manual read. Clean schema, no auth."

請求形態要按 bodySchema 翻譯成真正的 HTTP，不要把 envelope 整包當 body 發出去：

GET，把 queryParams 編進查詢字符串：

zero fetch "https://api.example.com/locate?ip=8.8.8.8"

POST，把 input.body 當成 JSON：

zero fetch https://api.example.com/translate \
  -d '{"text":"hello","to":"es"}' \
  -H "Content-Type:application/json"

zero fetch 幾個常用參數：

• -X 強制 HTTP 方法；帶了 -d 時默認 POST，否則 GET。
• -d 內聯 JSON、@./file 或從 stdin 讀；超過約 1 MB 不要內聯，改用文件。
• -H 'k:v' 可重複，用來傳調用方自己的鑑權頭。
• --max-pay 單次花費上限，不熟悉或按次計價的能力建議先設。
• --timeout 默認 60 秒，作用在每一跳 HTTP 上；圖片 / 視頻 / 音頻官方建議先加到 --timeout 300，避免付完款卻在 60 秒處被掐掉。
• --json 在 stdout 打出 {runId, ok, status, latencyMs, payment, body, bodyRaw}，判斷成功看 ok，不要只看 status。
• --capability 傳入搜索得到的 token、slug 或 uid，用來記賬和歸因。

已經有明確 URL（用戶點名，或你自己瀏覽時找到的）時，不必強行先搜索：

zero fetch https://some-api.example.com/v1/do-the-thing

輸出處理：stdout 只放響應體，圖片等二進制要重定向：

zero fetch "<url>" | jq .
zero fetch --json "<url>" | jq 'select(.ok)'
zero fetch "<image-url>" > out.png

npm 文檔裏的搜索過濾也可以直接用：

zero search "image classification" --max-cost 5
zero search "image classification" --free

適用場景與注意事項¶

比較對口的場景，是 Agent 已經能寫代碼、改倉庫，但差一截「外部世界」的能力，例如：

1、生成圖片、音頻、音樂、短視頻，而模型本身沒有對應工具。
2、網頁抓取、翻譯、轉寫。
3、天氣、價格、地點、企業信息這類即時或外部數據。
4、發郵件 / 短信，或把一份 HTML/Markdown 發佈成可訪問的頁面（官網示例裏有免費的 Website Hosting）。
5、用戶明確說了「用 Zero」「搜一下 x402 / MPP 能力」。

使用時有幾條官方寫明的坑，值得單獨記：

• 每次都重新 search，每次 fetch 前先 get。 索引、價格、排序會變。
• 不要爲模型本來就會的事付費。 Skill 把這一點寫進了「何時不要用」。
• --max-pay 和 --timeout 要提前設。 尤其是生成類任務，先付款再超時等於白花。
• 沙箱 / CI 出網策略。 zero fetch 會打到各能力自己的域名，只放行 *.zero.xyz 會在搜索階段看起來正常、一調用就失敗。需要比較寬鬆的出站訪問。
• 插件安裝和 zero init 獨立安裝疊在一起 時，同一輪提示可能被注入兩次 Zero 提醒。官方說無害，不要靠刪文件「修復」；用戶想去掉獨立那份，再用 zero uninstall（這是機器級操作，會影響所有讀 ~/.claude / ~/.agents 的應用）。
• 不要自己生成私鑰錢包。 身份來自登錄後的託管錢包；用戶明確提供密鑰時才設置 ZERO_PRIVATE_KEY。
• 評價不要用空話。 「Worked great」這類內容官方建議寧可不寫 --content，只打分。平臺自身的故障用 zero bug-report，不要拿它代替 zero review。

倉庫狀態也需要心裏有數：zero-plugins 說明自己是按 PR 逐步加上各宿主的，今天已發行 Claude Code、Codex、Droid、Gemini CLI 插件，其它 Agent 靠 agents.json 做獨立集成。具體某個小衆工具是否檢測成功，以 zero init 的實際輸出爲準。

小結¶

Zero 並沒有讓模型「突然會畫畫、會打電話」，它做的是更窄、也更實際的一層：當 Agent 走到能力邊界、正準備把註冊 API 的活推回給你時，先去一個統一目錄裏找可調用、可按次付費的服務，用同一套登錄和錢包走完 search、fetch、review。Skill 負責教會模型這件事什麼時候該做、什麼時候不該做；CLI 負責把 402 支付和花費上限收住。

官方資料：

• Skill 原文：https://github.com/officialzeroxyz/zero-plugins/blob/main/plugins/zero/skills/zero/SKILL.md
• 插件倉庫：https://github.com/officialzeroxyz/zero-plugins
• 產品站點：https://www.zero.xyz/
• CLI（npm）：https://www.npmjs.com/package/@zeroxyz/cli
• 安裝提示詞：https://www.zero.xyz/setup.md