catalog/repos/abstract-foundation--agw-cli.md

# AI智能钱包命令行工具

`CLI工具` `Web3` `AI代理` `钱包` `区块链` `MCP`

<p align="center">
  <img src="./agw-cli-banner.png" alt="AGW CLI Banner" width="100%" />
</p>

# AGW CLI

AGW 是专为 [Abstract Global Wallet](https://docs.abs.xyz/abstract-global-wallet/overview) 打造的以代理为核心的命令行工具。它使 [Claude](https://code.claude.com/docs/en/overview) 等 AI 代理能够自主与你的 Abstract Global Wallet 交互——查看钱包余额、发送交易、与部署在 [Abstract](https://abs.xyz/) 上的应用进行交互。

## 快速开始

将以下提示词复制粘贴给你的 AI 代理（Claude Code、Codex 等）：

```text
按照以下说明安装并配置 AGW CLI（请使用 curl 获取该文件，而非 WebFetch）：https://raw.githubusercontent.com/Abstract-Foundation/agw-cli/main/docs/guide/installation.md
```

或者直接阅读[安装指南](https://github.com/Abstract-Foundation/agw-cli/blob/main/docs/guide/installation.md)。

## 功能特性

- **代理优先设计** — 每条命令均采用结构化 JSON 输入/输出，专为 LLM 工具调用而构建
- **内置 MCP 服务器** — 可接入 Claude Code、Gemini 或任何兼容 MCP 的宿主环境
- **预览优先写入** — 所有改变状态的命令均需在 `--dry-run` 之后显式添加 `--execute`
- **会话密钥认证** — 通过配套应用审批实现委托签名，私钥不暴露给代理
- **Schema 自省** — 使用 `agw-cli schema <command>` 获取机器可读的输入/输出规范
- **分页与字段裁剪** — 使用 `fields` 缩小读取范围，使用 `--page-all` 分页
- **代理技能** — 可安装的技能包，教会 AI 代理安全使用 CLI 的模式

---

### 前置条件

- Node.js 18+
- npm 10+

### 安装

```bash
npm install -g @abstract-foundation/agw-cli
```

### 认证

配套应用负责处理认证。运行初始化流程，创建与你钱包关联的会话密钥：

```bash
agw-cli auth init --json '{"chainId":2741}' --execute
```

这将在浏览器中打开页面，让你连接现有 AGW 或创建新的 AGW，然后批准该机器的代理签名者。

### 验证

```bash
agw-cli session status --json '{"fields":["status","readiness","accountAddress"]}'
```

## 工作原理

AGW CLI 使用由 [Privy](https://www.privy.io/) 提供支持的**委托签名者架构**，使你的 AI 代理能够代表你的钱包执行操作，而无需持有钱包私钥。

### 整体架构

你的 [Abstract Global Wallet](https://docs.abs.xyz/abstract-global-wallet/overview) 是一个智能合约钱包。其签名密钥由 Privy 在[可信执行环境（TEE）](https://docs.privy.io/recipes/tee-wallet-migration-guide)中管理——它从不以完整形式存在于飞地之外，也从不暴露给 CLI 或代理。

取而代之的是，AGW CLI 在本地生成一个**设备授权密钥**，并通过[密钥仲裁](https://docs.privy.io/controls/key-quorum/overview)将其注册为钱包上的[已认证签名者](https://docs.privy.io/security/authentication/authenticated-signers)。该签名者受限于你在入门流程中批准的 [Privy 策略](https://docs.privy.io/controls/policies/overview)，该策略精确定义了签名者被允许使用的 RPC 方法和交易参数。

### 认证流程

```
┌──────────┐                                     ┌──────────────┐
│  AGW CLI  │  1. 生成 P-256 密钥对               │  本地磁盘    │
│ (设备)    │────────────────────────────────────▶│  ~/.agw/     │
│           │     私钥 → privy-auth.key            └──────────────┘
│           │
│           │  2. 携带公钥打开浏览器
│           │────────────────────────────────────▶┌──────────────┐
│           │                                     │  配套应用    │
│           │  3. 用户连接 AGW，审批签名者          │  cli.abs.xyz │
│           │     并选择策略预设                   └──────┬───────┘
│           │                                            │
│           │  4. 签名回调令牌（EdDSA）                  │
│           │◀───────────────────────────────────────────┘
│           │
│           │  5. 验证签名、指纹、
│           │     链 ID → 保存 session.json
└──────────┘
```

1. **密钥生成** — CLI 在本地生成 [P-256 ECDSA](https://docs.privy.io/controls/key-quorum/create) 密钥对。私钥以 `0o600` 权限写入 `~/.agw/privy-auth.key`。公钥（Base64 编码的 DER 格式）传递给配套应用。
2. **浏览器审批** — CLI 在浏览器中打开配套应用。你连接 AGW（或创建新的），然后选择限制代理操作范围的策略预设。
3. **签名者注册** — 配套应用在后台以你设备的 P-256 公钥为授权密钥创建 Privy [密钥仲裁](https://docs.privy.io/controls/key-quorum/overview)，并将该密钥仲裁作为签名者[添加](https://docs.privy.io/wallets/using-wallets/signers/add-signers)到你的钱包，并绑定一个[策略](https://docs.privy.io/controls/policies/overview)来定义允许的 RPC 方法、价值限制和目标合约限制。
4. **回调验证** — 配套应用发回一个经过加密签名的令牌（EdDSA）。CLI 验证签名，检查签名者指纹是否与本地密钥匹配，并确认链 ID。
5. **会话实例化** — 经验证的会话数据（账户地址、签名者绑定、策略 ID、能力摘要）保存到 `~/.agw/session.json`。

### 运行时签名原理

当代理发送交易或签署消息时：

1. CLI 读取本地 P-256 私钥，并对 RPC 请求的规范化表示（方法、URL、请求体、Privy 头部）计算[授权签名](https://docs.privy.io/api-reference/authorization-signatures)。
2. 签名后的请求发送至 [Privy 钱包 RPC API](https://docs.privy.io/wallets/using-wallets/signers/use-signers)，签名放在 `privy-authorization-signature` 头部。
3. Privy 根据密钥仲裁中注册的公钥验证授权签名，然后依据签名者的[策略规则](https://docs.privy.io/controls/policies/overview)评估请求。
4. 若两项检查均通过，Privy 在 TEE 内重建钱包密钥，执行操作并返回结果。密钥在使用后立即销毁。

**你的钱包私钥永远不会离开 Privy 的 TEE。** 设备密钥仅证明*本机器*有权在批准策略范围内请求特定操作。

### 策略预设

入门时，你选择一个策略预设，该预设映射到 Privy 策略，用于管理签名者可调用的 RPC 方法和工具：

| 预设 | 典型能力 |
|--------|---------------------|
| `payments` | 代币转账、余额查询 |
| `trading` | 兑换、转账、合约写入 |
| `gaming` | 游戏内交易 |
| `contract_write` | 任意合约交互 |
| `deploy` | 合约部署 |
| `signing` | 消息和交易签名 |
| `full_app_control` | 全部能力 |
| `custom` | 细粒度工具选择 |

Privy 通过[策略规则](https://docs.privy.io/controls/policies/overview)在服务端强制执行这些限制（默认拒绝，`DENY` 优先于 `ALLOW`）。CLI 也在本地强制执行——两者必须同时同意才能执行任何操作。

### 撤销

运行 `agw-cli auth revoke` 可移除签名者。这将打开配套应用，让你确认移除操作。签名者从 Privy 的密钥仲裁中注销，本地会话和密钥文件也会被清理。你可以随时重新运行 `auth init` 来创建新会话。

## 命令列表

| 分组 | 命令 | 描述 |
|-------|----------|-------------|
| **wallet** | `address`、`balances`、`tokens list` | 查询钱包身份、余额和代币列表 |
| **tx** | `preview`、`send`、`calls`、`transfer-token`、`sign-message`、`sign-transaction` | 预览和执行交易 |
| **contract** | `write`、`deploy` | 与智能合约交互或部署合约 |
| **auth** | `init`、`revoke` | 管理会话密钥认证 |
| **session** | `status`、`doctor` | 检查和排查会话状态 |
| **app** | `list`、`show` | 发现部署在 Abstract 上的应用 |
| **portal** | `streams list`、`user-profile get` | 浏览 Portal 内容和用户资料 |
| **schema** | `list`、`get` | 自省命令 Schema |
| **mcp** | `serve` | 启动内置 MCP 服务器 |
| **mcp-config** | — | 打印可直接粘贴的 MCP 配置片段 |

运行 `agw-cli schema <command>` 可获取任意命令的详细输入/输出 Schema。

## 使用示例

**查询钱包余额：**

```bash
agw-cli wallet balances --json '{"fields":["native","tokens"]}'
```

**发送前预览交易：**

```bash
agw-cli tx send --json '{"to":"0x...","data":"0x1234","value":"0"}' --dry-run
```

**审查预览后执行：**

```bash
agw-cli tx send --json '{"to":"0x...","data":"0x1234","value":"0"}' --execute
```

**流式分页获取代币列表：**

```bash
agw-cli wallet tokens list \
  --json '{"pageSize":25,"fields":["items.symbol","items.value","nextCursor"]}' \
  --page-all --output ndjson
```

**发现 Abstract 上的应用：**

```bash
agw-cli app list --json '{"pageSize":10,"fields":["items.id","items.name"]}'
```

## MCP 服务器

AGW 内置了一个 MCP 服务器，由与 CLI 相同的命令注册表生成。使用以下命令启动：

```bash
agw-cli mcp serve --sanitize strict
```

或生成配置片段，粘贴到你的代理宿主中：

```bash
agw-cli mcp-config        # 本地二进制
agw-cli mcp-config --npx  # 基于 npx（无需全局安装）
```

## 代理技能

本仓库附带代理技能包，教会 AI 代理如何安全使用 CLI。使用以下命令安装：

```bash
npx skills add https://github.com/Abstract-Foundation/agw-cli/tree/main/packages/agw-cli/skills -y
```

可用技能：

| 技能 | 覆盖内容 |
|-------|----------------|
| `authenticating-with-agw` | 会话引导、检查与故障排查 |
| `reading-agw-wallet` | 钱包身份、余额和代币列表 |
| `executing-agw-transactions` | 签名和发送的预览优先执行规则 |
| `discovering-abstract-portal` | 应用和 Portal 流发现 |
| `trading-on-aborean` | Aborean Finance 协议工作流 |
| `trading-on-uniswap` | Abstract 上的 Uniswap V2+V3 兑换和流动性 |
| `bridging-to-abstract` | 原生跨链桥和第三方跨链桥选项 |
| `building-on-abstract` | 开发者入门、部署、Paymaster、会话密钥 |
| `managing-agent-identity` | ERC-8004 代理注册与声誉 |
| `upvoting-on-abstract` | Abstract Portal 链上投票 |
| `mining-with-bigcoin` | Bigcoin 虚拟挖矿模拟器 |

## 代理宿主扩展

预构建配置支持：

- **Claude Code** — MCP 配置脚手架位于 `packages/agw-cli/extensions/claude-code/`
- **Gemini** — 扩展指南位于 `packages/agw-cli/extensions/gemini/`

两者均假设 `agw-cli` 已安装且在 `PATH` 中。

## 配置

通过环境变量进行运行时配置：

| 变量 | 描述 |
|----------|-------------|
| `AGW_HOME` | 覆盖 AGW 主目录（默认：`~/.agw/`） |
| `AGW_CHAIN_ID` | 默认链 ID |
| `AGW_RPC_URL` | RPC URL 覆盖 |
| `AGW_APP_URL` | 配套应用 URL 覆盖 |
| `AGW_OUTPUT` | 默认输出模式（`json` 或 `ndjson`） |
| `AGW_SANITIZE_PROFILE` | 净化配置（`off` 或 `strict`） |

也可使用 CLI 标志：`--home`、`--chain-id`、`--rpc-url`、`--app-url`、`--output`、`--sanitize`。

## 安全性

- 会话密钥以严格的文件权限（`0o600`）存储在本地
- 所有写操作默认拒绝——没有匹配策略，任何操作均不会执行
- 改变状态的命令需在预览后显式添加 `--execute`
- 配套应用回调载荷在会话实例化前经过签名和验证
- 日志中不包含任何密钥或会话材料

详见 [SECURITY.md](SECURITY.md) 和 [THREAT_MODEL.md](THREAT_MODEL.md)。

## 常见问题

### 我的 AI 代理能访问钱包私钥吗？

不能。你的钱包私钥由 [Privy](https://www.privy.io/) 在可信执行环境（TEE）中管理。它从不以完整形式存储，仅在签名时临时在飞地内重建。CLI 持有的是单独的设备授权密钥（P-256），该密钥向 Privy 证明身份——它无法提取或推导出你的钱包密钥。

### 如果我的机器被入侵了怎么办？

攻击者获取到你的设备授权密钥（`~/.agw/privy-auth.key`）后，只能执行你在入门时批准的 Privy 策略所允许的操作。他们无法提取钱包私钥、更改策略或添加新签名者。你可以在任何设备上立即运行 `agw-cli auth revoke` 或通过配套应用直接撤销被入侵的签名者。

### 代理会花费超过我授权的金额吗？

不会。绑定到你签名者的 Privy 策略定义了在服务端强制执行的硬性限制——允许哪些 RPC 方法、每笔交易的价值上限、手续费限制，以及可选的合约调用限制。CLI 也在本地强制执行工具限制，两层必须同时同意。如果代理尝试策略之外的操作，Privy 将拒绝该请求。

### 配套应用是什么？

配套应用（[cli.abs.xyz](https://cli.abs.xyz)）是一个托管的 Web 界面，你可以在此审批或撤销代理签名者。它处理 Privy 签名者注册流程，并向 CLI 发回经过加密签名的回调令牌。你只在 `auth init` 和 `auth revoke` 时需要它——正常的 CLI 使用无需打开浏览器。

### 可以不用 AI 代理直接使用 AGW CLI 吗？

可以。CLI 是一个标准命令行工具，接受 JSON 输入并产生 JSON 输出。你可以直接在终端中用它进行钱包查询、交易预览和应用发现。无论是你手动输入命令还是代理在操作，`--dry-run` / `--execute` 标志的工作方式完全相同。

### MCP 服务器有什么用？

[模型上下文协议](https://modelcontextprotocol.io/)服务器将 AGW 命令作为工具暴露给兼容 MCP 的 AI 宿主（Claude Code、Gemini 等）直接调用。它由与 CLI 相同的命令注册表生成，因此工具接口完全一致。使用 `agw-cli mcp serve` 启动，或使用 `agw-cli mcp-config` 为你的宿主生成配置片段。

### 如何更改代理被允许执行的操作？

重新运行 `agw-cli auth init`，在配套应用中选择不同的策略预设。这将创建一个带有更新策略的新签名者。之前的签名者在你显式撤销之前仍保持注册状态。

### 会话数据存储在哪里？

会话数据默认存储在 `~/.agw/`（可通过 `AGW_HOME` 或 `--home` 覆盖）：
- `session.json` — 账户地址、签名者绑定、策略元数据、能力摘要
- `privy-auth.key` — 设备授权私钥

两个文件均以 `0o600` 权限写入（仅所有者可读写）。目录本身权限为 `0o700`。

### AGW CLI 支持测试网吗？

支持。传入 `--chain-id` 或设置 `AGW_CHAIN_ID` 以指向不同网络。使用 `--rpc-url` 或 `AGW_RPC_URL` 指向测试网 RPC 端点。

## 项目状态

> **持续开发中** — v1.0 之前可能有破坏性变更。

## 贡献

欢迎在 [github.com/Abstract-Foundation/agw-cli](https://github.com/Abstract-Foundation/agw-cli/issues) 提交 Issue 和 Pull Request。

## 许可证

[MIT](LICENSE) — Abstract Foundation