Portage

Portage 可让 AI Agent 为你在真实的在线商店中查找并购买商品，每笔付款都由你审批。它提供命令行工具（portage）、用于驱动该工具的 Claude Code 插件（buy），以及 Ruby gems，让任何商店都能向购物 Agent 提供相同的开放协议（MCP 和 UCP）。适用于希望 Agent 代为购物的人、构建购物 Agent 的开发者，以及希望 Agent 在自家商店购物的商家。

状态： pre-1.0。小版本之间的 API 仍可能变更。最新发布版本：0.22.0（更新日志）。

快速入门

有两种方式：使用 buy 插件让 Claude 帮你购物，或自行运行 portage CLI。两种方式使用相同的 CLI，约五分钟即可完成。

安装 buy 插件

该插件会教 Claude Code 通过 portage CLI 购物，因此请先安装 CLI。

1. 安装 CLI（portage-cli 0.9.0 或更高版本）：

   brew install tomtom87/portage/portage
   

   或者，如果使用 Ruby 3.2 或更高版本，运行 gem install portage-cli。Homebrew 会打包所有适配器。使用 RubyGems 时，如果需要 Portage 浏览器配置文件和结账自动填充功能，还要安装 portage-ucp-webmcp 0.2.0 或更高版本。

2. 添加插件。 在 Claude Code 中：

   /plugin marketplace add tomtom87/Portage
   /plugin install buy@portage
   

   或者在 shell 中运行：

   claude plugin marketplace add tomtom87/Portage
   claude plugin install buy@portage
   

3. 在终端中运行一次 portage setup。 它会逐项询问你的收货地址、可选的搜索密钥和消费上限，每项都可以跳过。这是交互式流程，因此请自行运行，不要通过 Claude 运行。

4. 向 Claude 提出请求。 输入 /buy a burton snowboard under $600，或者直接用自然语言提问。该技能会显示为 buy:buy。Claude 会检查你的设置、显示真实优惠和模拟运行总额，并在购买前等待你确认。

要更新或移除此插件：

claude plugin marketplace update portage
claude plugin update buy@portage        # then restart Claude Code

claude plugin uninstall buy@portage
claude plugin marketplace remove portage

Claude 插件目录中的收录即将推出。在此之前，请通过此市场安装。

其他 Agent：Codex、Cursor、OpenCode 等

buy 技能是一个纯 SKILL.md 文件，因此任何能加载技能并在你的机器上运行命令的 Agent 都可以使用它。请先按上述说明安装 CLI 并运行 portage setup。该插件还包含第二个技能 shop-research：只读技能，用于回答价格、库存、商店和订单相关问题，不执行购买；需要购买时，它会转交给 buy。按照相同方式将它安装在 buy 旁边。

• 使用 dotagents（Codex、Cursor、OpenCode）：运行一条命令即可将插件安装到 ~/.agents/，并生成各个 Agent 的插件或技能文件。

  npx @sentry/dotagents add tomtom87/Portage
  

  使用 npx @sentry/dotagents install 更新。使用 npx @sentry/dotagents remove buy 移除。如果你的 agents.toml 只允许受信任的来源，请先运行 npx @sentry/dotagents trust add tomtom87/Portage。

• 作为普通技能使用（VS Code，或任何不支持插件的 Agent）：将 plugins/buy/skills/buy/ 文件夹复制到 Agent 的技能目录，并将 plugins/buy/skills/shop-research/ 放在它旁边。使用 dotagents 时，在 ~/.agents/agents.toml 中声明这些技能，然后运行 npx @sentry/dotagents install，即可将它们安装到 ~/.agents/skills/buy 和 ~/.agents/skills/shop-research：

  [[skills]]
  name = "buy"
  source = "tomtom87/Portage"
  path = "plugins/buy/skills/buy"
  
  [[skills]]
  name = "shop-research"
  source = "tomtom87/Portage"
  path = "plugins/buy/skills/shop-research"
  

• OpenClaw。 先安装 CLI（见上文），然后从 ClawHub 安装技能：openclaw skills install @tomtom87/portage-buy 会将其安装到当前使用的 OpenClaw 工作区，clawhub install @tomtom87/portage-buy 则会将其安装到当前目录下的 ./skills（ClawHub 文档）。然后运行 portage setup。该技能的 frontmatter 包含 OpenClaw 的 metadata.openclaw 区块（需要 portage 二进制文件，将读取的每个环境变量都标记为可选，并包含 brew 安装规范），因此 OpenClaw 会在安装 portage 之前禁用该技能。若要跳过 ClawHub，请使用上文的普通技能安装方式：OpenClaw 会从 ~/.agents/skills 读取个人技能，并从 ~/.openclaw/skills 读取托管技能（OpenClaw 技能文档），因此可将 plugins/buy/skills/buy/ 复制或符号链接到其中任一目录。shop-research 也发布在 ClawHub 上，名称为 @tomtom87/portage-shop-research（以相同方式安装），也可以复制或符号链接 plugins/buy/skills/shop-research/。其 frontmatter 具有相同的 metadata.openclaw 结构，只包含其中列出的搜索和零售商密钥。ClawHub 会以 MIT-0 许可证重新发布技能；此仓库仍采用 MIT 许可证。

• OpenClaw 插件。 如果想使用类型化工具而非 shell 命令，请安装原生插件：在安装 CLI（portage-cli 0.12.0 或更高版本）并运行 portage setup 后，执行 openclaw plugins install clawhub:tomtom87/portage。它会通过 CLI 向 Agent 提供 portage_* 工具，并附带 buy、shop-research 和一个简短的 OpenClaw 技能，用于将购买的每个步骤对应到相应工具。只读工具默认启用；用于定价、审批、购买或交接的工具需在 OpenClaw 的工具设置中选择启用。支出策略和审批仍由 Portage 管理，任何工具都不能对 URL 传递 --yes 或放宽你的限制。请参阅插件 README。

• Omarchy（Arch Linux）。使用 Omarchy 自带的辅助工具安装 CLI：omarchy-mise-install gem:portage-cli portage，它会按照 Omarchy 安装 claude、codex 和 gh 的方式，写入 ~/.local/bin/portage 包装脚本。也可以使用普通的 mise（mise use -g gem:portage-cli）或 Linux 上的 Homebrew（brew install tomtom87/portage/portage）。然后运行 portage setup。标准 Omarchy 需要先运行 sudo pacman -S --needed make：Ruby 3.4 会原生编译 bigdecimal，gcc 已通过 clang 提供，缺少的只有 make。对于技能，请将 plugins/buy/skills/buy/ 和 plugins/buy/skills/shop-research/ 链接到所用 Agent 的技能目录。Omarchy 自带的配置会创建指向 ~/.agents/skills（OpenClaw 和 dotagents 方式）、~/.claude/skills（Claude Code；优先使用上文的插件方式）和 ~/.codex/skills 的链接。

• 浏览器中的聊天应用（ChatGPT、Grok 等）无法在你的机器上运行 portage，因此不能使用该技能。请改用厂商的编码 Agent 或 CLI（如果支持加载技能）。

在任意 MCP 客户端中使用 Portage

portage mcp 通过标准输入/输出，为任何可运行本地服务的客户端提供相同的搜索、报价、审批和购买工具。先安装 CLI（brew install tomtom87/portage/portage 或 gem install portage-cli，版本为 0.14.0 或更高），然后在终端中运行 portage setup。支出政策和审批由 Portage 管理：Agent 可以搜索和查看价格，但购买需要等待你的审批。

• Claude Desktop。 将以下内容添加到 claude_desktop_config.json（Settings、Developer、Edit Config），然后重启。Claude Desktop 不会继承 shell 的 PATH，因此请使用 which portage 返回的绝对路径（通常是 /opt/homebrew/bin/portage 或 /usr/local/bin/portage）：

  {
    "mcpServers": {
      "portage": { "command": "/opt/homebrew/bin/portage", "args": ["mcp"] }
    }
  }
  

• Claude Code。 运行 claude mcp add --scope user portage -- portage mcp（去掉 --scope user，即可仅用于当前项目）。

• Docker。 运行 docker run -i --rm -v "$HOME/.portage:/root/.portage" ghcr.io/tomtom87/portage-mcp:0.14.0，即可通过镜像仓库中的镜像运行相同的服务。容器无法打开浏览器，因此移交操作会打印结账链接。

自行使用 CLI

按照上面的第 1 步安装 CLI，运行 portage setup，然后：

portage find --query "burton snowboards" --json
portage buy "burton snowboards" --max-price 600 --dry-run --json

find 无需密钥即可使用。其默认搜索使用 DuckDuckGo 的免密 API，可以解析品牌和商店名称（“burton snowboards”），但无法处理开放式查询（“waterproof hiking boots”）。如需处理这类查询，请添加 Brave 或 Google 搜索密钥：portage setup 会提示你设置，搜索后端中也有详细说明。不带商店 URL 的 buy 会列出商品；在终端中，你可以选择其中一项。--dry-run 会显示实际总价，且绝不会扣款。

提供商店 URL 后，buy 会直接访问该商店的 /.well-known/ucp 清单：

portage buy https://some-ucp-store.example --query "hoodie" --dry-run --json

如需实际购买，请先登记付款方式（portage payment enroll <store-url>），设置支出上限（portage policy set），然后移除 --dry-run 并添加 --yes。buy 只会通过商店公布的 UCP 端点或你已持有凭据的平台 API（你自己的商店）完成结账。其他情况都会转为移交。它绝不会抓取网页。CLI 教程介绍了所有这些操作，包括搜索结果为空时的处理方法。

portage setup 会将设置保存到 ~/.portage/.env（权限为 chmod 600），.env.example 列出了所有变量。只有 ~/.portage/.env 会自动加载，当前目录中的 .env 不会，因此克隆的仓库无法悄悄重定向你的购买或流量（原因）。有关升级、在同一个 PATH 中安装两个版本以及 Linux 密钥环的信息，请参阅安装。

如何完成购买

大多数商店不允许第三方完成付款，因此 buy 通常会构建购物车并将操作移交给你：

层级	操作	默认状态
A	在你自己的浏览器中打开结账页面。由你付款。	开启
B	Portage 在单独的浏览器配置文件中构建购物车，然后停在付款步骤。由你付款。	关闭（可选择启用）
C	仅移交操作。Portage 打开页面，由你自行购买。不会向网站发送请求，不会抓取网页，也不会进行任何形式的自动化。	所有 Amazon 网站，以及 walmart.com、ebay.com、bestbuy.com 和你添加的任何主机

Amazon 及类似零售商在服务条款中限制自动化购买 Agent，因此 Portage 绝不会对它们进行自动化操作。Amazon 条目默认启用，可由你编辑；walmart.com、ebay.com 和 bestbuy.com 始终仅移交操作。详情请参阅层级和移交目标。

安全

这些规则适用于所有层级，包括 CLI 和插件：

• 不处理原始银行卡数据。 银行卡数据绝不会经过 Portage。支付方式是通过 portage payment enroll 获取的令牌，保存在你的操作系统钥匙串中；插件会拒绝任何看起来像银行卡号的内容。
• 每笔付款都由你批准。 未经你明确同意，不会购买任何商品。仅凭 --yes 绝不会购买搜索结果：你必须指定商店。插件会显示供你选择的商品，以及待批准的确切总金额；每个商品都附有商品页面链接，一次确认只对应一次购买。portage policy set --require-approval person 可确保只有你在自己的终端中输入的确认才算数。通过浏览器交接时，由你点击付款。
• 你的浏览器机密信息不会被读取。 Portage 绝不会读取浏览器的密码、Cookie 或自动填充数据，也绝不会连接到你的默认浏览器配置文件。
• 不绕过 CAPTCHA 或反机器人拦截。 Portage 会报告此类情况并交由你处理。
• 支出上限。 portage policy set 可设置单笔、滚动周期和消费频率上限，以及商店允许列表。

Portage 是按原样提供的开源软件，不提供任何形式的保证（MIT）。你如何在任何网站上使用它，以及是否遵守该网站的条款，均由你自行负责。请按照 SECURITY.md 中的说明报告安全问题。

命令

portage --help 会显示此帮助信息。各命令的标志和环境变量见 portage-cli/README.md，也可查阅发布的 CLI 参考。

usage: portage buy <url> --query "..." [--qty N] [--payment-token TOKEN]
                          [--product-id ID] [--yes] [--dry-run]
                          [--auto-open|--no-auto-open] [--notify-webhook URL]
                          [--handoff-target default|print|profile|agent:NAME]
                          [--decision-backend jev|laya] [--min-confidence N] [--json]
                          [--wait [--wait-timeout DURATION|off]]
       portage buy --offer REF [--qty N] [--yes] [--dry-run] ...
       portage buy --quote QUOTE_ID --yes [--json] ...
       portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
       portage find --query "..." [--max-price N] [--limit N] [--json]
       portage compare <url> --product-id ID [--id VALUE ...] [--results N]
                              [--max-price N] [--json]
       portage check <url> [--json]
       portage pick [--search LAST|SEARCH_ID] [--via auto|tty|agent] [--json]
                    [--choose REF | --compare REF | --view REF]
       portage approve QUOTE_ID [--via auto|tty|agent] [--relayed-yes | --view] [--json]
       portage history [list] [--purchases|--searches] [--limit N] [--json]
       portage history clear [--purchases|--searches]
       portage payment list [--json]
       portage payment enroll <url> [--label NAME] [--json]
                              [--scope-merchant HOST ...] [--scope-max-amount N] [--scope-currency CUR]
       portage payment set-default <id>
       portage payment remove <id>
       portage payment freeze <id>
       portage payment revoke <id>
       portage policy show [--json]
       portage policy set [--per-transaction-cap N --currency CUR]
                           [--rolling-cap N --rolling-window-seconds N --currency CUR]
                           [--velocity-count N --velocity-window-seconds N]
                           [--allow HOST ...] [--clear-allowlist]
                           [--require-approval person|any|off]  (lowering asks at a terminal)
       portage orders reconcile [--checkout ID] [--json]
       portage index build [--sources a,b] [--queries FILE] [--dry-run] [--export DIR] [--json]
       portage index refresh [--sources a,b] [--queries FILE] [--dry-run] [--export DIR] [--json]
       portage index show [--stores|--products [--page N] [--per-page N]] [--json]
       portage index search QUERY [--category ID] [--store HOST] [--limit N] [--json]
       portage index add <url> [--crawl] [--json]
       portage index remove <host> [--json]
       portage index sources [--json]
       portage browser import [--browser chrome|edge|brave|arc|firefox|safari] [--profile-root DIR]
                              [--history-days 90] [--include-product-pages] [--max-probes 200]
                              [--exclude HOST,HOST] [--dry-run] [--yes] [--json]
       portage browser profile init|open|status [--browser chrome|edge|brave|arc] [--port N]
                              [--url URL (open only)] [--json]
       portage doctor [--require FILE] [--adapter CLASS_NAME] [--json]
       portage configure [--require FILE] [--adapter CLASS_NAME] [--json]  (alias for doctor)
       portage setup [--json]  (interactive wizard on a TTY; --json/no TTY: today's doctor report)
       portage generate adapter NAME [--dir DIR]
       portage generate agent-profile [--out FILE] [--key-out FILE] [--rotate]
       portage --version

     proxy flags (buy/find/compare/doctor/payment enroll):
       [--proxy URL] [--proxy-mode forward|gateway] [--proxy-header "Name: value"]
       [--no-proxy HOSTS] [--proxy-route ROUTE=URL|direct] [--proxy-chain URL,URL,...]
       [--proxy-passthrough HEADER] [--proxy-ca FILE] [--no-env-proxy]

软件包和文档

包	版本	适用对象	功能	文档
buy 插件	0.10.5	购物者	通过 portage 购物的 Claude Code 插件，另附只读的购物研究技能	购物技能，购物研究技能
portage-cli	0.15.0	购物者	portage 命令	CLI 参考，教程
shop-via-ucp 技能	–	Agent 构建者	通过商店的 UCP 端点购物，可使用或不使用 portage	技能页面
browse-via-ucp 技能	–	Agent 构建者	只读：查看商店的清单、目录，以及是否支持自动化购物	技能页面
portage-ucp-client	0.7.0	Agent 构建者	Ruby 客户端：连接到商店的清单，或以购物者 Agent 的身份驱动自己的 Adapter	操作指南，Agent 配置，工具门控
portage-ucp-decision	0.1.2	Agent 构建者	商品排名、升级处理策略、置信度门控（Jev/Laya）、PolicyGuard	–
portage-ucp-journal	0.1.1	Agent 构建者	买家侧购买日志及其 Store 抽象	–
portage-ucp-webmcp	0.2.0	两者	WebMCP 传输：在页面中提供工具，或驱动页面的工具（Tier B 配置、自动填充）	–
portage-ucp	0.17.0	商家	协议核心：Adapter 合约、能力注册表、清单构建器、MCP 服务	提供 /.well-known/ucp，安全钩子，库用法
serve-via-ucp 技能	–	商家	设置商店自己的 UCP 端点	技能页面
portage-ucp-shopify	0.6.1	商家	Shopify Admin 和 Storefront GraphQL API	–
portage-ucp-wix	0.2.1	商家	Wix Stores Catalog 和 eCommerce REST API	–
portage-ucp-woocommerce	0.3.0	商家	WooCommerce Admin REST API 和 Store API	–
portage-ucp-bigcommerce	0.2.1	商家	BigCommerce v3 Catalog/Carts/Checkouts 和 v2 Orders API	–
portage-ucp-magento	0.2.1	商家	Magento/Adobe Commerce REST v1	–
portage-ucp-etsy	0.1.5	商家	Etsy Open API v3 目录和订单；结账通过重定向链接完成	–
portage-ucp-instagram	0.2.0	商家	Meta Commerce Catalog；结账通过重定向链接完成；get_order 已弃用，并将在 Meta 于 2026-10-27 移除其 Order Management 端点后停止工作	–

商家： 适配器 gem 或你自己的 portage-ucp Adapter 子类，可通过 MCP 和 UCP 提供你的商品目录、购物车和结账功能。每个适配器 gem 都附带一个 exe/ 服务端和 PORTAGE_UCP_CONFIG 钩子，并提供通用的 examples/portage_ucp.rb 起点（库用法、凭据、能力覆盖范围）。在 Shopify 上，原生 Universal Commerce Agent 应用无需编写代码即可处理结账和订单；Portage 则添加 cart、catalog 和签名清单（提供 /.well-known/ucp）。

贡献者和适配器作者： 架构 · 编写适配器 · 规范符合性 · 开发 · CONTRIBUTING.md。 阅读文档的 AI Agent： 文档网站提供 llms.txt 和 llms-full.txt。

在代理后运行

buy、find、compare、check、doctor 和 payment enroll 接受 --proxy* 标志。同样的设置也可通过 PORTAGE_PROXY* 环境变量或 ~/.portage/config.json 中的 "proxy" 部分配置。未配置的项目会回退到标准的 HTTPS_PROXY/HTTP_PROXY/NO_PROXY 变量，但支付流量除外：除非为其指定代理，否则会直接连接。portage doctor 会显示每条路由实际生效的代理，并隐藏凭据。有关企业出口流量、轮换代理池、API 网关、mitmproxy 和 nginx/Cloudflare 的配置示例，以及环境变量注意事项，请参阅 docs/proxy.md。

要求

Ruby 3.2 或更高版本，以及 mcp gem ~> 1.8（由 portage-ucp 引入）。Homebrew 公式自带 Ruby，因此通过 Homebrew 安装无需另行安装 Ruby。

贡献

欢迎在 tomtom87/Portage 提交错误报告和拉取请求。该项目尚未达到 1.0 版本，仍在跟进规范，因此任何超出错误修复范围的更改都请先提交 issue。CONTRIBUTING.md 介绍了工作流程；请遵守行为准则。

许可证

MIT。版权所有 (c) 2026 Tom Whitbread。