前言¶

用过 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