zerion-agent-management

Zerion — Agent 令牌与策略管理

Agent 令牌授权 CLI 代表钱包签署交易，无需提示输入密码短语。附加到令牌的策略用于限定令牌可执行的操作（链、允许列表、拒绝规则、到期时间）。这是安全实现自主交易和链下签名的基础。

设置

如果运行 zerion 命令时出现 command not found，请安装一次：

npm install -g zerion-cli

需要 Node.js ≥ 20。有关身份验证，请参阅 zerion 总技能。完成设置后执行交易 → zerion-trading。签署消息/typed-data → zerion-sign。

适用场景

• “创建 Agent 令牌”
• “设置自主交易”
• “将机器人限制在链 X / 地址 Y”
• “阻止转账” / “阻止授权” / “让令牌在 N 天后到期”
• “切换当前使用的 Agent 令牌”
• “撤销令牌”

Agent 操作与手动操作

操作	类型	说明
agent list-tokens、agent list-policies、agent show-policy、agent use-token	Agent	只读或仅配置操作。可安全地自主执行。
agent create-token（默认）	手动	会交互式提示输入密码短语。由人类运行。
agent create-token --passphrase-file <path>	可由 Agent 执行	从权限为 chmod 600 的文件中读取密码短语。适用于 CI / 无头环境 / 脚本化设置，前提是文件已由人类或机密管理器准备好。
agent revoke-token、agent create-policy、agent delete-policy	手动	需要密码短语或确认。必须由人类直接运行。

只读操作 — Agent 可自由调用

zerion agent list-tokens              # Tokens, attached policies, active flag, wallet binding
zerion agent list-policies            # All policies with rules summary
zerion agent show-policy <id>         # Full policy details
zerion agent use-token --wallet <wallet>   # Switch the active token (config edit, no passphrase)

令牌与策略管理

默认流程需要人类交互。agent create-token 还提供非交互式变体（--passphrase-file），可在准备好密码短语文件后用于自动化。本节中的其他所有操作都需要人类执行。

创建 Agent 令牌

# Interactive policy picker (recommended)
zerion agent create-token --name <bot> --wallet <wallet>

# Attach an existing policy by ID
zerion agent create-token --name <bot> --wallet <wallet> --policy <id>

# Multiple policies (AND semantics — all must pass)
zerion agent create-token --name <bot> --wallet <wallet> --policy <id1>,<id2>

令牌会自动保存到 ~/.zerion/config.json 中的 agentTokens 下；如果之前没有活动令牌，它也会成为默认令牌。交易命令（zerion-trading）和签名命令（zerion-sign）会从配置中读取该令牌。

非交互式创建令牌（--passphrase-file）

--passphrase-file <path> 接受一个路径，指向一个纯文本文件，文件的全部内容都必须是钱包密码短语（与人类在 TTY 提示符下输入的字符串相同）。CLI 只读取一次文件，并使用其中的内容解锁密钥库。文件中不能有其他内容——不能包含 JSON、key=value 或标头。

对于 CI、无头服务器或脚本化 Agent 设置，请将密码短语写入此类文件，而不是手动输入：

# Write the passphrase to a file readable only by you
umask 077                                   # ensure new files default to 0600
printf '%s' "$ZERION_PASSPHRASE" > ~/.zerion-pass
chmod 600 ~/.zerion-pass                    # required — refused if looser

# Create the token non-interactively
zerion agent create-token \
  --name bot --wallet my-agent \
  --policy <id> \
  --passphrase-file ~/.zerion-pass

# Clean up immediately
shred -u ~/.zerion-pass 2>/dev/null || rm -f ~/.zerion-pass

对于临时存储（在 Linux 上推荐），请使用 tmpfs 挂载，而不是 $HOME：

# Linux only — /run is tmpfs (RAM-only, gone on reboot)
sudo install -d -m 0700 -o "$USER" /run/zerion
printf '%s' "$ZERION_PASSPHRASE" > /run/zerion/pass && chmod 600 /run/zerion/pass
zerion agent create-token ... --passphrase-file /run/zerion/pass

在 macOS 上，请使用 /private/tmp/<your-user>/... 或 ~/Library/Caches/ 下的应用专用目录。macOS 未提供用户可写入的 /run。

文件格式

纯 UTF-8 文本。整个文件（减去恰好一个可选的尾随 \n 或 \r\n）都将作为口令。

规则	原因
内容 = 仅原始口令字节	不得包含 JSON、key=value、注释或引号。文件中的任何内容都是口令的一部分。
去掉一个尾随 \n 或 \r\n	这样 echo "pass" > file 就能按预期工作。额外的换行符会保留。
保留口令中的前导 / 尾随空格	口令可能确实包含这些空格。CLI 不会执行 .trim()。
使用 UTF-8 编码	通过 readFileSync(path, "utf8") 读取。非 UTF-8 字节会转换为替换字符。
非空	空文件或仅含换行符的文件 → 拒绝。
权限为 0600（POSIX）	否则拒绝 — 参见下文规则。
普通文件，且归当前 uid 所有	会跟随指向文件的符号链接；目标文件仍须通过权限和所有权检查。

示例（文件字节 → CLI 使用的口令）：

命令	文件字节	口令结果
printf '%s' 'hunter2' > f	hunter2	hunter2 ✅
printf '%s\n' 'hunter2' > f	hunter2\n	hunter2 ✅
echo 'hunter2' > f	hunter2\n	hunter2 ✅
echo '"hunter2"' > f	"hunter2"\n	"hunter2"（包含引号！）❌
echo ' spaces ' > f	spaces \n	spaces （保留空格）✅
printf '' > f	（空）	拒绝 ❌
printf '\n' > f	\n	拒绝 ❌

规范格式 — 不带尾随换行，没有意外内容：

umask 077
printf '%s' 'YOUR-PASSPHRASE' > ~/.zerion-pass
chmod 600 ~/.zerion-pass

使用前请验证：

wc -c ~/.zerion-pass     # byte count == passphrase length
xxd ~/.zerion-pass | head # eyeball raw bytes — no BOM, no quotes, no CRLF

规则

• 文件必须为 0600 权限（仅所有者可读写）。如果存在任何组或其他用户权限位 → CLI 将拒绝并返回 passphrase_file_error。
• 文件必须归当前 uid 所有（POSIX）。拒绝读取其他用户的文件（例如通过符号链接读取）。这与 SSH IdentityFile 的行为一致。
• 会去掉尾随换行符（\n 或 \r\n）；保留口令中的前导 / 尾随空格。
• 空文件会被拒绝。
• Windows 上会跳过权限和所有权检查（POSIX 权限位和 uid 在 Windows 上没有意义）——请改用 NTFS ACL 限制访问。

推荐做法：

环境	来源	备注
本地开发	~/.zerion-pass (chmod 600)	使用后删除。
Docker	将文件绑定挂载到 tmpfs	先使用 --tmpfs /run/zerion:mode=0700，再在其中写入口令。
Kubernetes	将 Secret 挂载为文件	默认挂载权限为 0644 — 请在卷规范中设置 defaultMode: 0600。
GitHub Actions	将 ${{ secrets.X }} 写入临时文件，执行 chmod 600，然后运行	作业结束时会自动清理。
HashiCorp Vault	vault agent 模板渲染为权限为 0600 的文件	在中央进行续期和轮换。

威胁模型：与存储在磁盘上的 SSH 私钥相同。任何能够在会话期间读取该文件的人都可以解锁密钥库。请勿将文件路径放在共享文件系统中、提交到 git，或使其出现在进程列表中。不支持通过 argv 传递口令（--passphrase <value>），因为它会泄露到 ps aux、Shell 历史记录和 CI 日志中。

目前，--passphrase-file 仅影响 agent create-token。wallet create、wallet import 和其他需要口令的命令仍要求使用交互式 TTY。

撤销令牌

zerion agent revoke-token --name <bot>
zerion agent revoke-token --id <id>

创建策略

策略是一组令牌在签名前必须通过的规则。至少需要一条规则。

# Chain lock — restrict to specific chains
zerion agent create-policy --name safe-base --chains base,arbitrum
zerion agent create-policy --name monad-only --chains monad

# Expiry — token deactivates after duration (e.g. 24h, 7d)
zerion agent create-policy --name short-lived --expires 7d

# Block raw native transfers (ETH/SOL send command)
zerion agent create-policy --name no-transfers --deny-transfers

# Block ERC-20 approvals (prevents allowance grants)
zerion agent create-policy --name no-approvals --deny-approvals

# Allowlist — only allow interaction with specific contract addresses
zerion agent create-policy --name dex-only --allowlist 0xUniRouter,0xCowSwap

# Combined rules (AND semantics)
zerion agent create-policy --name strict \
  --chains base \
  --expires 7d \
  --deny-transfers \
  --deny-approvals

删除策略

zerion agent delete-policy <id>

引用了已删除策略的令牌将不再通过该规则检查。

策略参考

标志	效果
--chains <list>	限制为列出的链（以逗号分隔）
--expires <duration>	令牌在指定时长后停用。格式：<n>h、<n>d（例如 24h、7d）
--deny-transfers	阻止原生资产的直接转账（对原生资产执行 zerion send）
--deny-approvals	阻止 ERC-20 approve 调用
--allowlist <addrs>	仅允许与列出的合约地址交互（以逗号分隔）

策略通过本地生成的脚本执行（CLI 仓库中的 policies/*.mjs）。每次尝试签名时，都会在构建交易之前运行这些脚本。

推荐的设置模式

# 1. Create wallet (manual — see zerion-wallet skill)
zerion wallet create --name agent-bot

# 2. Create a tight policy
zerion agent create-policy --name swap-only \
  --chains base,arbitrum \
  --expires 30d \
  --deny-transfers \
  --allowlist 0xUniswapRouter,0x1inchRouter

# 3. Create the agent token bound to that policy
zerion agent create-token --name agent-bot \
  --wallet agent-bot \
  --policy <swap-only-id>

# Now zerion-trading and zerion-sign work autonomously

常见错误

代码	原因	修复方法
no_agent_token	钱包没有有效令牌	agent create-token --wallet <wallet>
agent_token_expired	策略的 --expires 已过期	创建新令牌
policy_denied	操作被策略阻止	执行 agent show-policy <id> 查看规则；修改规则或使用其他令牌
policy_not_found	策略 ID 不存在	执行 agent list-policies 查找有效 ID
policy_no_rules	执行 create-policy 时未指定标志	添加至少一条规则（--chains、--expires、--deny-*、--allowlist）
token_name_exists	--name 重复	选择其他名称，或先执行 agent revoke-token --name <bot>
passphrase_file_error	--passphrase-file 路径不存在、权限错误或文件为空	执行 chmod 600 <path>；确保文件存在且非空