zerion-agent-management

Zerion — エージェントトークンとポリシーの管理

エージェントトークンを使うと、パスフレーズの入力を求められることなく、ウォレットに代わって CLI がトランザクションに署名できます。トークンに設定したポリシーによって、トークンで実行できる操作（チェーン、許可リスト、拒否ルール、有効期限）が制限されます。これは、安全な自律取引とオフチェーン署名の基盤となります。

セットアップ

zerion コマンドを実行して command not found と表示された場合は、一度だけインストールしてください。

npm install -g zerion-cli

Node.js ≥ 20 が必要です。認証については、zerion の包括スキルを参照してください。セットアップ後に取引を実行する場合は → zerion-trading。メッセージ／typed-data に署名する場合は → zerion-sign。

使用する場面

• 「エージェントトークンを作成する」
• 「自律取引を設定する」
• 「ボットをチェーン X ／アドレス Y に制限する」
• 「送金をブロックする」／「承認をブロックする」／「N 日後にトークンを失効させる」
• 「有効なエージェントトークンを切り替える」
• 「トークンを失効させる」

エージェント操作と手動操作

操作	種別	備考
agent list-tokens、agent list-policies、agent show-policy、agent use-token	エージェント	読み取り専用または設定のみです。自律的に安全に実行できます。
agent create-token（デフォルト）	手動	対話形式でパスフレーズの入力を求められます。人間が実行してください。
agent create-token --passphrase-file <path>	エージェント対応	chmod 600 のファイルからパスフレーズを読み込みます。人間またはシークレットマネージャーがファイルを用意すれば、CI／ヘッドレス環境／スクリプトによる初回セットアップに使用できます。
agent revoke-token、agent create-policy、agent delete-policy	手動	パスフレーズまたは確認が必要です。人間が直接実行してください。

読み取り専用 — エージェントは自由に実行できます

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）もあり、パスフレーズファイルを用意すれば使用できます。このセクションのその他の操作は、すべて人間が実行する必要があります。

エージェントトークンを作成する

# 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、ヘッドレスサーバー、スクリプトによるエージェントのセットアップでは、パスフレーズを入力する代わりに、このようなファイルに書き込んでください。

# 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 では推奨）、$HOME ではなく tmpfs マウントを使用してください。

# 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 をちょうど 1 つ（任意）取り除いたものが、パスフレーズとして扱われます。

ルール	理由
内容はパスフレーズの生バイトのみ	JSON、key=value、コメント、引用符は使用しません。ファイル内のすべてがパスフレーズの一部です。
末尾の \n または \r\n を 1 つ削除	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 に意味がないため）。代わりに 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 に置かず、プロセス一覧にも表示されないようにしてください。引数で渡すパスフレーズ（--passphrase <value>）は、ps aux、シェル履歴、CI ログに漏れるためサポートされていません。

現時点で --passphrase-file が適用されるのは agent create-token のみです。wallet create、wallet import およびその他のパスフレーズが必要なコマンドでは、引き続き対話型 TTY が必要です。

トークンを失効させる

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

ポリシーを作成する

ポリシーとは、トークンが署名する前に満たす必要があるルールの集合です。少なくとも 1 つのルールが必要です。

# 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 にフラグが指定されていません	ルールを少なくとも 1 つ追加します（--chains、--expires、--deny-*、--allowlist）
token_name_exists	--name が重複しています	別の名前を選ぶか、先に agent revoke-token --name <bot> を実行します
passphrase_file_error	--passphrase-file のパスが存在しない、権限が不適切、またはファイルが空です	chmod 600 <path> を実行し、ファイルが存在し、空でないことを確認します