Portage

Portageを使うと、AIエージェントが実際のオンラインストアから商品を探して購入できます。支払いは毎回ユーザーが承認します。コマンドラインツール（portage）、その操作を担うClaude Codeプラグイン（buy）、そしてあらゆるストアがショッピングエージェントに同じオープンプロトコル（MCPとUCP）を提供できるRuby gemとして提供されています。エージェントに買い物を任せたい人、ショッピングエージェントを開発する人、エージェントに自分のストアで購入してもらいたい販売者を対象としています。

ステータス： 1.0より前のバージョンです。マイナーバージョン間でAPIが変更される場合があります。最新リリース一式：0.22.0（変更履歴）。

クイックスタート

利用方法は2通りあります。buyプラグインを使ってClaudeに買い物を任せる方法と、portage CLIを自分で実行する方法です。どちらも同じCLIを使用し、所要時間は約5分です。

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
   

   または、シェルから次を実行します。

   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 プラグインディレクトリへの掲載は準備中です。それまでは、このマーケットプレイスからインストールしてください。

その他のエージェント：Codex、Cursor、OpenCode など

buy スキルは通常の SKILL.md ファイルなので、スキルを読み込めて、お使いのマシンでコマンドを実行できるエージェントなら使用できます。まず、上記のとおり CLI をインストールし、portage setup を実行してください。プラグインには、読み取り専用の第 2 のスキル shop-research も含まれています。購入を前提としない価格、在庫、店舗、注文に関する質問に対応し、購入する場合は buy に引き継ぎます。同じ方法で buy の隣にインストールしてください。

• dotagents を使う場合（Codex、Cursor、OpenCode）：1 つのコマンドでプラグインを ~/.agents/ にインストールし、各エージェントのプラグインまたはスキルファイルを生成します。

  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、またはプラグインに対応していないエージェント）：plugins/buy/skills/buy/ フォルダーをエージェントのスキルディレクトリにコピーし、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 を実行します。このスキルのフロントマターには 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/ をコピーするか、シンボリックリンクを作成してください。こちらのフロントマターも同じ形式の metadata.openclaw を持ち、指定されているのは検索キーと小売業者キーのみです。ClawHub はスキルを MIT-0 ライセンスで再公開していますが、このリポジトリのライセンスは MIT のままです。

• OpenClaw プラグイン。 シェルコマンドの代わりに型付きツールを使うには、ネイティブプラグインをインストールします。CLI（portage-cli 0.12.0 以降）と portage setup の実行後、openclaw plugins install clawhub:tomtom87/portage を実行してください。CLI を介した portage_* ツールがエージェントに提供され、buy、shop-research、および購入の各手順を対応するツールに割り当てる短い OpenClaw スキルがバンドルされます。読み取り専用ツールはデフォルトで有効です。価格の確認、承認、購入、または引き継ぎを行うツールは、OpenClaw のツール設定でオプトインする必要があります。支出ポリシーと承認は Portage 側で維持され、URL に対して --yes を渡したり、制限を緩和したりできるツールはありません。プラグインの READMEを参照してください。

• Omarchy（Arch Linux）。Omarchy 独自のヘルパー omarchy-mise-install gem:portage-cli portage で CLI をインストールします。このコマンドは、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/ を、使用するエージェントのスキルディレクトリにリンクしてください。Omarchy 独自のプロビジョニングでは、~/.agents/skills（OpenClaw と dotagents 経由）、~/.claude/skills（Claude Code。上記のプラグイン経由を推奨）、~/.codex/skills にリンクが作成されます。

• ブラウザー上のチャットアプリ（ChatGPT、Grok など）は、お使いのマシンで portage を実行できないため、スキルを使用できません。スキルを読み込む場合は、代わりに各ベンダーのコーディングエージェントまたは CLI を使用してください。

任意の MCP クライアントから Portage を使用する

portage mcp は、ローカルサーバーを実行できる任意のクライアント向けに、同じ検索、見積もり、承認、購入ツールを stdio 経由で提供します。CLI をインストールし（brew install tomtom87/portage/portage または gem install portage-cli、バージョンは 0.14.0 以降）、まずターミナルで portage setup を実行してください。支出ポリシーと承認は Portage で管理されます。エージェントは検索と価格確認ができますが、購入には承認が必要です。

• Claude Desktop。 claude_desktop_config.json に以下を追加し（「Settings」、「Developer」、「Edit Config」）、再起動してください。Claude Desktop はシェルの 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 上にある 2 つのインストール、Linux のキーチェーンについては、インストールを参照してください。

購入の完了方法

ほとんどの店舗では第三者による決済の完了を許可していないため、通常 buy はカートを作成し、あなたに引き継ぎます。

ティア	動作	デフォルト
A	あなた自身のブラウザーでチェックアウトを開きます。支払いはあなたが行います。	有効
B	別の Portage ブラウザープロファイルでカートを作成し、支払いの直前で停止します。支払いはあなたが行います。	無効（オプトイン）
C	引き継ぎのみです。Portage がページを開き、あなた自身で購入します。サイトへのリクエスト、スクレイピング、自動化は一切行いません。	すべての Amazon サイトに加え、walmart.com、ebay.com、bestbuy.com、および追加したホスト

Amazon などの小売業者は利用規約で自動購入エージェントを制限しているため、Portage はそれらの購入を自動化しません。Amazon の項目はデフォルトで有効になっており、編集できます。walmart.com、ebay.com、bestbuy.com は常に引き継ぎのみです。詳細については、ティアと引き継ぎ先を参照してください。

安全性

CLI とプラグインのすべてのティアで、次のルールが適用されます。

• カードの生データは扱いません。 カードデータが Portage を通過することはありません。支払い方法は portage payment enroll で登録したトークンで、OS のキーチェーンに保存されます。また、プラグインはカード番号と思われる情報を拒否します。
• すべての支払いはご自身で承認します。 明示的に承認しない限り、購入されることはありません。検索結果は --yes だけで購入されることはなく、ストアを指定する必要があります。プラグインは選択可能な商品と承認が必要な正確な合計金額を表示し、それぞれに商品ページへのリンクを付けます。1回の承認で購入できるのは1件だけです。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 プラグインと、読み取り専用のショップ調査スキル	buy スキル、shop-research スキル
portage-cli	0.15.0	買い物客	portage コマンド	CLI リファレンス、チュートリアル
shop-via-ucp スキル	–	エージェント開発者	portage を使う場合も使わない場合も、店舗の UCP エンドポイント経由で購入します	スキルページ
browse-via-ucp スキル	–	エージェント開発者	読み取り専用：店舗のマニフェスト、カタログ、および自動購入に対応しているかどうかを確認します	スキルページ
portage-ucp-client	0.7.0	エージェント開発者	Ruby クライアント：店舗のマニフェストに接続するか、買い物客のエージェントとして独自の Adapter を操作します	チュートリアル、エージェントプロファイル、ツールの制御
portage-ucp-decision	0.1.2	エージェント開発者	オファーのランキング、エスカレーションポリシー、信頼度ゲート（Jev/Laya）、PolicyGuard	–
portage-ucp-journal	0.1.1	エージェント開発者	購入者側の購入ジャーナルとその 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エージェントの皆さんへ： ドキュメントサイトでは 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 でインストールする場合はどちらも不要です。

貢献

バグ報告やプルリクエストは tomtom87/Portage で歓迎しています。このプロジェクトはまだ 1.0 未満で、仕様への対応も進行中のため、バグ修正を超える変更を行う前に issue を作成してください。ワークフローについては CONTRIBUTING.md をご覧ください。行動規範が適用されます。

ライセンス

MIT。Copyright (c) 2026 Tom Whitbread.