agent-wallet

Agent Wallet 技能

重要：切勿直接处理私钥或助记词。 所有加密操作都必须通过 CLI 完成。切勿读取密钥库文件、解析私钥，或在对话中泄露助记词——所有操作都使用 CLI 命令。

此技能仅用于签名——不包括构建和广播交易。

安装

运行 agent-wallet --help，检查 CLI 是否已安装。如果找不到该命令，请询问用户：稳定版还是测试版？

# Node.js — stable
npm install -g @bankofai/agent-wallet

# Node.js — beta
npm install -g @bankofai/agent-wallet@beta

交互工作流

每次用户请求都遵循以下 4 步模式：

第 1 步 — 检查当前状态，然后了解用户意图

始终先运行 agent-wallet list，查看现有钱包和当前活动钱包。切勿假设这是首次设置。

• 不存在钱包 → 先介绍钱包类型选项及其说明（不得跳过），然后请用户选择。介绍如下：
  • local_secure — 使用主密码在本地加密私钥。推荐用于生产环境。
  • privy — 通过 API 凭据（App ID + App Secret + Privy Wallet ID）使用 Privy 托管钱包。本地不存储私钥。
  • （raw_secret 已禁用——用户必须手动配置，Agent 无法为其设置）
• 已存在钱包 → 使用 add，不要重新运行 start（除非传入 --override，否则会报错）

第 2 步 — 查阅命令（必须执行，无一例外）

执行命令前，先运行 agent-wallet <command> --help。即使你认为自己了解这些标志，也不得跳过此步骤。

agent-wallet start --help        # always run first
agent-wallet start local_secure --help   # then subcommand help if applicable

第 3 步 — 一次问清所有信息

在一条消息中收集所有必需信息。始终说明以下涉及隐私的选项及其含义：

• --save-runtime-secrets：将未加密的密码保存到 ~/.agent-wallet/runtime_secrets.json。在个人设备上使用较方便；请避免在共享环境中使用。
• --dir：自定义密钥目录。仅当用户可能使用非默认配置时才询问。

第 4 步 — 执行

根据用户的回答，构造一条包含所有标志的完整命令。切勿运行不完整的命令并等待交互提示。

受限操作

remove、reset 和 change-password 均为 Agent 受限操作——Agent 不得执行这些命令。误用可能导致钱包访问权限永久且无法恢复地丢失（私钥无法恢复）。

当用户请求执行其中一项操作时：

1. 说明操作的作用及其不可逆性
2. 告知用户在自己的终端中运行该命令
3. 提供可复制粘贴的准确命令，但不要执行

# Examples to show the user — do NOT run via agent
agent-wallet remove <id> --yes
agent-wallet reset --yes
agent-wallet change-password -p 'OldPass' --new-password 'NewPass'

危险信号——改用 CLI

想法	正确做法
“我来读取 wallets_config.json”	agent-wallet list
“我可以根据密钥推导地址”	agent-wallet resolve-address <id>
“因为需要密码，用户应该自己运行命令”	在对话中询问用户密码，然后在 Bash 命令中使用 --password '<pw>'——Agent 执行 Bash 不会写入 shell 历史记录
“我先构建交易”	超出范围——请用户提供请求负载
“用户想导入密钥/助记词”	告知用户在终端中自行运行 add --private-key / add --mnemonic——切勿通过此对话传递密钥材料
“我已经知道这些标志，跳过 --help 就行”	始终先运行 --help。 缺少子命令或必需标志时，会导致非交互式错误。运行 --help 只需 1 秒，可避免执行失败。

密码解析（匹配第一个即生效）

1. 运行时密钥（~/.agent-wallet/runtime_secrets.json）← 首次设置后优先使用
2. AGENT_WALLET_PASSWORD 环境变量
3. --password '<pw>' 标志 ← 尚未设置运行时密钥时，在 Agent 上下文中使用此项
4. 交互式提示（在非交互式上下文中不可用）

只有用户在终端中手动输入密码时，--password 才会将密码暴露在用户的 shell 历史记录中。Agent 通过 Bash 工具运行命令时，不存在交互式 shell 历史记录。Agent 可以在对话中向用户询问密码，并通过 --password 传入，这是安全且正确的做法。

Agent 上下文规则

在 Agent 上下文中，stdin 不是 TTY — 所有交互式提示均已禁用。务必显式传入所有必需标志，否则命令会挂起或失败。

情况	必需标志
start、add（local_secure）	--wallet-id <id> + --generate
start、add（privy）	--wallet-id <id> + --app-id + --app-secret + --privy-wallet-id
use、inspect、resolve-address	位置参数 <wallet-id>
sign *	--network <net>
未配置运行时密钥	--password <pw>

始终将用户提供的字符串括起来，以防止 shell 展开 !、$、&、* 等字符。单引号 '...' 适用于 bash、zsh、PowerShell 7 和 fish。PowerShell 5 和 cmd.exe 处理 JSON 载荷时需要采用不同方式 — 请参阅 shell-quoting.md。

agent-wallet sign tx '{"to":"0x...","chainId":1}' --network eip155:1

命令

运行 agent-wallet <command> --help 查看完整选项。所有标志请参阅 commands-reference.md。

命令	用途
start local_secure --wallet-id <id> --generate	首次设置：初始化并创建加密钱包
list	列出所有钱包和活动标记
resolve-address [id]	显示钱包的 EVM + TRON 地址
inspect <id> [--show-address]	显示钱包元数据（+ 地址）
use <id>	切换活动钱包
add local_secure --wallet-id <id> --generate	添加新的加密钱包
sign tx '<json>' --network <net>	签署交易
sign msg '<text>' --network <net>	签署消息（EIP-191）
sign typed-data '<json>' --network <net>	签署 EIP-712 类型化数据（仅限 EVM）
remove <id> --yes	❌ 限制 Agent 使用 — 告知用户手动运行
change-password	❌ 限制 Agent 使用 — 告知用户手动运行
reset --yes	❌ 限制 Agent 使用 — 告知用户手动运行

网络标识符

格式：EVM 使用 eip155:<chainId>，TRON 使用规范 CAIP-2 ID：tron:0x2b6653dc（主网）、tron:0xcd8690dc（Nile）或 tron:0x94a9059e（Shasta）。

常用标识符：eip155:1（Ethereum）、eip155:137（Polygon）、eip155:56（BSC）、eip155:42161（Arbitrum）、eip155:8453（Base）。

一个钱包会从同一密钥派生出独立的 EVM 和 TRON 地址 — 使用 resolve-address 查看两者。

错误处理

错误	解决方法
No wallets configured	agent-wallet start --save-runtime-secrets
Password required	使用 --save-runtime-secrets 重新运行设置
DecryptionError / 密码错误	检查 AGENT_WALLET_PASSWORD 或运行时密钥
Already initialized	目录已完成设置 — 跳过 init，继续执行 add
Wallet not found: <id>	运行 agent-wallet list 查看有效 ID
Network not supported	使用 eip155:<chainId> 或规范的 TRON CAIP-2 ID，例如 tron:0x2b6653dc/tron:0xcd8690dc
Private key must be 32 bytes	密钥格式无效 — 用户端问题，请手动运行导入