polygon-agent-cli

Polygon Agentic CLI

前置条件

• Node.js 22+
• 全局安装：npm install -g @polygonlabs/agent-cli（重新运行即可更新）
• 入口点：agent <command>
• 存储位置：~/.polygon-agent/（使用 AES-256-GCM 加密）

给 Agent 的提示：首次安装时，请告知用户这是全局 npm 安装 — 会在整个系统中安装 agent CLI，使其可从任何终端运行；某些环境可能需要 sudo；重新运行相同命令即可更新；运行 npm uninstall -g @polygonlabs/agent-cli 可将其移除。首次安装时提示一次即可。

如果命令因“Unknown argument”或“command not found”而失败

此技能与 CLI 版本同步 — 不同版本中的命令和标志可能有所变化。检查你的版本，与最新版本进行比较；如果版本较旧，请升级：

agent --version                        # currently installed
npm view @polygonlabs/agent-cli version        # latest published
npm install -g @polygonlabs/agent-cli@latest   # upgrade

架构

CLI 使用 OMS（Open Money Stack）V3 嵌入式钱包模式（@polygonlabs/oms-wallet）。默认情况下，wallet login 会打开 agentconnect 登录页面（POLYGON_AGENT_LOGIN_UI，默认值为 https://agentconnect.polygon.technology），用户可在其中选择 Google 或电子邮件（系统会向用户的收件箱发送 6 位验证码，用户需在页面上输入）。无论浏览器位于本机还是其他设备上，都可以使用此方式，因此无需单独的无头模式。--local 会回退到旧版本地环回流程（原始 Google 登录 URL 加 localhost 回调；浏览器必须位于同一台机器上；仅支持 Google）。--remote 已弃用，目前为空操作，只会打印提示。用户登录后，系统会创建或解锁钱包，并将会话凭据加密后存储在磁盘上。此流程不进行链上权限范围限定。

钱包	创建方式	用途	是否需要注资？
嵌入式钱包（V3）	wallet login	主要支出钱包	是

钱包地址在所有 EVM 链上相同。会话有效期约为 1 周，之后需要重新登录。

环境变量

OMS 凭据（可选）

无需执行设置步骤。CLI 内置默认 OMS publishable key，首次登录时，wallet login 会自动配置专用的 Builder 项目和访问密钥，并将其保存到 ~/.polygon-agent/builder.json。

变量	描述
OMS_PUBLISHABLE_KEY	高级覆盖选项：使用你自己的 OMS Builder 项目，而非默认项目

可通过环境变量设置，也可通过 setup 持久化一次，使每条命令都能从 ~/.polygon-agent/builder.json 读取：

agent setup --oms-publishable-key <key>

也接受 --oms-project-id <proj_...>，但此参数可选 — 仅作为旧版显示元数据保留。普通的 setup（不带密钥）仍可用于手动配置或使用 --force 重新配置。

可选覆盖项

变量	默认值
POLYGON_AGENT_LOGIN_UI	wallet login 打开的浏览器登录页面的基础 URL（默认值为 https://agentconnect.polygon.technology）
POLYGON_AGENT_OIDC_RELAY	wallet login 使用的 OIDC relay 基础 URL（默认值为 https://oidc-relay.polygon.technology）；也可通过每次运行时的 --relay-url 设置
SEQUENCE_PROJECT_ACCESS_KEY	仅用作 DeFi earn-pool 查询的 Trails API 密钥（可选）
TRAILS_TOKEN_MAP_JSON	代币目录查询
POLYGON_AGENT_DEBUG_FETCH	关闭 — 将 HTTP 日志写入 ~/.polygon-agent/fetch-debug.log
POLYGON_AGENT_DEBUG_FEE	关闭 — 将费用选项输出到 stderr

完整设置流程

# Step 1: Log in in the browser
agent wallet login
# → opens the agentconnect login page; choose Google or email (email sends
#   a 6-digit code to the user's inbox, entered on the page)
# → works whether the browser is on this machine or elsewhere, so there is
#   no separate headless mode
# → --local falls back to the legacy loopback flow (Google only, browser
#   must be on this machine)
# → session saved to ~/.polygon-agent/oms/main/; prints the walletAddress
# → no setup step needed: the CLI ships a default OMS publishable key, and
#   login auto-provisions a Builder project + access key to
#   ~/.polygon-agent/builder.json

# Step 1b: Choose transaction mode (asked once)
# → if the login output includes a `modePrompt` field, ask the user whether to
#   enable auto mode (writes broadcast immediately, no preview), then run:
agent mode auto      # or: agent mode dry-run
# → dry-run (default) previews every write; auto broadcasts immediately.
#   Never enable auto mode without the user's explicit answer.

# Step 2: Fund wallet
agent fund
# → reads walletAddress from session, builds Trails widget URL with toAddress=<walletAddress>
# → ALWAYS run this command to get the URL — never construct it manually or hardcode any address
# → send the returned `fundingUrl` to the user; `walletAddress` in the output confirms the recipient

# Step 3: Verify balances
agent balances

# Step 4: Register agent on-chain (ERC-8004, Polygon mainnet only)
agent register --name "MyAgent" --broadcast
# → mints ERC-721 NFT, emits Registered event containing agentId
# → retrieve agentId: open the tx on https://polygonscan.com, go to Logs tab,
#   find the Registered event — agentId is the first indexed parameter
# → use agentId for reputation queries, reviews, and feedback

用例技能

对于特定工作流，请在尝试执行任务之前获取并加载相关子技能：

用例	技能 URL
Polymarket 预测市场交易	https://agentconnect.polygon.technology/polygon-polymarket/SKILL.md
兑换、跨链桥接与存款（也包括收益提取）	https://agentconnect.polygon.technology/polygon-defi/SKILL.md
x402 发现与按次付费 API	https://agentconnect.polygon.technology/polygon-discovery/SKILL.md

重要 — x402 调用： 如果用户要求使用 x402 获取数据或调用服务（网页搜索、抓取、新闻、大模型推理、电子邮件、链上钱包分析、多链 RPC 等），请在发出任何请求之前按顺序执行以下步骤：

1. 获取并阅读 discovery 技能：GET https://agentconnect.polygon.technology/polygon-discovery/SKILL.md
2. 运行 agent wallet list — 如果不存在钱包，请登录：agent wallet login，然后在登录页面上使用 Google 或电子邮件登录，并为钱包充值后再继续。无需先执行任何设置步骤。
3. 运行 agent balances — 确认有可用的 USDC 后再继续；如果钱包为空，x402 调用会因 EOA 资金错误而失败

不要猜测端点，也不要在网上搜索 x402 提供商。discovery 技能文档列出了正确且可用的端点及其精确 URL 格式。

---

命令参考

设置

agent setup [--name <name>] [--force]
  [--oms-publishable-key <key>] [--oms-project-id <proj_...>]  # save OMS credentials (project id optional/legacy)
agent mode [auto|dry-run]   # show or set the persisted transaction mode

钱包

操作可用的 --chain 值：polygon（默认／主网）、amoy（Polygon 测试网）、mainnet（Ethereum）、arbitrum、optimism、base。ERC-8004 Agent 操作仅支持 polygon。嵌入式钱包地址在所有链上均相同。

agent wallet login [--name <n>] [--local] [--no-fund] [--force]
# Opens the agentconnect login page; choose Google or email. Works whether the browser is local or remote, so there is no separate headless mode.
# --local falls back to the legacy loopback flow (raw Google URL + localhost callback; browser must be on this machine; Google only). --remote is deprecated (now a no-op with a notice).
agent wallet logout [--name <n>]   # clears the local session
agent wallet list
agent wallet address [--name <n>]
agent wallet remove [--name <n>]

操作

agent balances [--wallet <n>] [--chain <chain>] [--chains <csv>]
agent send --to <addr> --amount <num> [--symbol <SYM>] [--token <addr>] [--decimals <n>] [--broadcast]
agent send-native --to <addr> --amount <num> [--broadcast] [--direct]
agent send-token --symbol <SYM> --to <addr> --amount <num> [--token <addr>] [--decimals <n>] [--broadcast]
agent swap --from <SYM> --to <SYM> --amount <num> [--to-chain <chain>] [--slippage <num>] [--broadcast]
agent deposit --asset <SYM> --amount <num> [--protocol aave|morpho] [--broadcast]
agent withdraw --position <addr> --amount <num|max> [--chain <chain>] [--broadcast]
agent fund [--wallet <n>]
agent x402-pay --url <url> --wallet <n> [--chain <chain>] [--method GET] [--body <str>] [--header Key:Value] [--broadcast] [--dry-run]

每条写入命令都接受 --broadcast（执行）和 --dry-run（强制预览）；如果两者都未指定，则由已保存的 agent mode 决定。

Agent 身份与声誉（ERC-8004）

agent register --name <n> [--agent-uri <uri>] [--metadata <k=v,k=v>] [--broadcast|--dry-run]
agent identity --agent-id <id> [--key <metadata-key>]   # agent payment wallet + optional metadata
agent reputation --agent-id <id> [--tag1 <tag>] [--tag2 <tag>]
agent reviews --agent-id <id> [--tag1 <t>] [--tag2 <t>] [--include-revoked]
agent feedback --agent-id <id> --value <score> [--tag1 <t>] [--tag2 <t>] [--endpoint <e>] [--feedback-uri <uri>] [--broadcast|--dry-run]

ERC-8004 合约（Polygon 主网）：

• IdentityRegistry：0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
• ReputationRegistry：0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

关键行为

• 交易模式 — 在默认的 dry-run 模式下，写入命令会预览操作，并要求使用 --broadcast 才会执行。agent mode auto 会持久启用始终广播模式；任何命令上的 --dry-run 都会强制预览，无论当前模式如何。首次执行 wallet login 后，如果登录 JSON 包含 modePrompt 字段，请将该问题转达给用户，并根据用户的回答运行 agent mode auto 或 agent mode dry-run，然后再继续。未经用户明确回答，绝不要启用自动模式。
• 智能默认值 — --wallet main、--chain polygon
• balances --chains — 使用逗号分隔链（最多 20 条）；指定两条或更多链时，返回包含 multiChain: true 和 chains 数组的 JSON（每条链使用相同的钱包地址）
• 手续费偏好 — USDC 和原生 POL 都可用时，自动优先选择 USDC；中继器会使用钱包有足够余额支付的手续费代币支付 Gas
• fund — 返回 Agentconnect 仪表板的充值 URL（已预填钱包和链），作为 fundingUrl。始终运行 agent fund 获取 URL 和钱包地址，绝不要硬编码或手动构造。
• deposit — 通过 Trails 的 getEarnPools 选择 TVL 最高的池并直接存入。完整存款参考：https://agentconnect.polygon.technology/polygon-defi/SKILL.md
• Gas 储备 — 使用 deposit 或任何会花费代币的命令时，始终在钱包中至少预留 0.1 USDC 或 0.1 POL 用于支付 Gas。绝不要尝试花完全部余额。deposit 命令会自动预留 0.1，但 Agent 在为 send、swap 或直接合约调用构造金额时，也必须遵守同一规则。
• withdraw — --position = aToken 或 ERC-4626 金库；--amount = max 或底层资产单位（Aave / 金库）。Dry-run JSON 包含 poolAddress / vault。
• x402-pay — 探测端点是否返回 402，并默认预览选定的付款方式。在自动模式下或使用 --broadcast 时，钱包会向构建者 EOA 充值精确的代币金额并完成付款。根据 402 响应自动检测链
• call — 提交任意预编码调用数据：agent call --to <addr> --data 0x... [--value <amt>] [--prefer-native-fee] [--broadcast]。钱包可以调用任何合约（V3 模型没有权限范围限制）
• send-native --direct — 绕过 ValueForwarder 合约，直接进行 EOA 转账
• 无权限范围限制 — V3 嵌入式钱包可以调用任何合约，并花费持有的任意金额；没有按合约设置的白名单或支出限额。应在 Agent 逻辑中控制支出，而不是在钱包层控制。
• 会话过期 — 登录后约 1 周；过期后重新运行 wallet login

向用户展示结果

CLI 命令会输出 JSON（非 TTY）。运行命令后，始终将结果呈现为格式化的 Markdown——切勿在对话中粘贴原始 JSON。

命令	展示方式
balances	Markdown 表格：Token / Balance 列。在表格上方显示钱包地址和链。
send / send-token / send-native	单行摘要：金额、符号、收款人。如果已广播，将交易哈希显示为代码跨度，并将区块浏览器 URL 显示为链接。
swap	摘要：X FROM → Y TO，并注明链。如果已广播，显示存款交易哈希和区块浏览器链接。
deposit	摘要：金额、资产、协议、池地址。如果已广播，显示交易哈希和区块浏览器链接。
withdraw	摘要：kind（aave / erc4626）、头寸、金额、池或金库。如果已广播，显示交易哈希和区块浏览器链接。
fund	将 fundingUrl 显示为可点击链接，并简要提示用户打开它。
wallet login / wallet list	在小型表格或项目列表中显示钱包名称、截断后的地址和链。
register	显示 Agent 名称和作为代码跨度的交易哈希，并提供 Polygonscan 链接。提醒用户从 Logs 标签页的 Registered 事件中获取 agentId。
identity	显示 agentId、钱包地址、是否已设置钱包，以及传入 --key 时解码后的元数据值。
reputation	用小型表格呈现分数和标签明细。

Dry-run 结果——始终明确标示这是一次模拟。在前面加上 ⚡ Dry run，并说明将会执行的操作。提醒用户使用 --broadcast 重新运行以执行操作。

错误——提取 error 字段，并将其作为清晰的句子呈现，而不是 JSON 块。如果适用，请附上 Troubleshooting 表格中的相关修复方法。

---

故障排除

问题	修复方法
Wallet not found	运行 wallet list，然后运行 agent wallet login
会话已过期（OMS_SESSION_EXPIRED）	运行 agent wallet login（有效期约 1 周）
Fee option errors	设置 POLYGON_AGENT_DEBUG_FEE=1，并确保钱包有 POL 或手续费代币。对于仅支持原生代币的钱包，在 call 命令中添加 --prefer-native-fee
Trails 小组件中的收款人有误	运行 agent fund（不要手动构造 URL）
x402-pay：没有 402 响应	端点不需要 x402 付款，或者 URL 有误
x402-pay：付款代币不匹配	402 响应中的链或代币与钱包不一致——检查 --wallet 是否指向正确的链
x402-pay：EOA 资金不足	钱包余额不足以支付款项——运行 balances，并在需要时充值

文件结构

~/.polygon-agent/
├── .encryption-key       # AES-256-GCM key (auto-generated, 0600)
├── config.json           # transaction mode (auto | dry-run)
├── builder.json          # publishableKey, omsProjectId, polymarket/EOA keys (encrypted)
├── wallets/<name>.json   # OMS wallet pointer: walletAddress, loginMethod
└── oms/<name>/           # OMS SDK session storage + encrypted credential key