Bagman

为处理私钥和机密信息的AI代理提供安全密钥管理模式。旨在防止：

• - 密钥丢失：代理在会话之间忘记密钥
• 意外泄露：密钥泄露到GitHub、日志或输出中
• 提示注入：恶意提示提取机密信息

核心原则

1. 1. 切勿将原始私钥存储在配置、环境变量或内存文件中
2. 使用会话密钥/委托访问而非完全控制
3. 所有机密访问均通过1Password CLI (op)进行
4. 发送前验证所有输出以防止密钥泄露

参考文档

• - references/secure-storage.md - 代理机密的1Password模式
• references/session-keys.md - ERC-4337委托访问模式
• references/leak-prevention.md - 预提交钩子和输出清理
• references/prompt-injection-defense.md - 输入验证和输出过滤

---

快速参考

正确做法 ✅

bash

通过1Password在运行时检索密钥

PRIVATE_KEY=$(op read op://Agents/my-agent-wallet/private-key)

使用环境注入（密钥从不接触磁盘）

op run --env-file=.env.tpl -- node agent.js

使用具有有限权限的会话密钥

（委托特定能力，而非完整钱包访问权限）

错误做法 ❌

bash

切勿将密钥存储在文件中

echo PRIVATE_KEY=0x123... > .env

切勿记录或打印密钥

console.log(Key:, privateKey)

切勿将密钥存储在内存/日志文件中

即使在私有代理内存中 - 这些都可能被窃取

切勿在密钥操作附近信任未验证的输入

---

架构：代理钱包栈

┌─────────────────────────────────────────────────────┐
│ AI代理 │
├─────────────────────────────────────────────────────┤
│ 会话密钥（时间/价值受限） │
│ - N小时后过期 │
│ - 每次操作有支出上限 │
│ - 允许的合约白名单 │
├─────────────────────────────────────────────────────┤
│ 1Password / 密钥管理器 │
│ - 代理在运行时检索会话密钥 │
│ - 从不存储完整私钥 │
│ - 所有访问的审计日志 │
├─────────────────────────────────────────────────────┤
│ ERC-4337 智能账户 │
│ - 可编程权限 │
│ - 无需暴露私钥即可恢复 │
│ - 高价值操作的多重签名 │
├─────────────────────────────────────────────────────┤
│ 操作员（人类） │
│ - 在硬件钱包中持有主密钥 │
│ - 签发/撤销会话密钥 │
│ - 监控代理活动 │
└─────────────────────────────────────────────────────┘

---

工作流程：设置代理钱包访问

1. 为代理机密创建1Password保险库

bash

创建专用保险库（通过1Password应用或CLI）

op vault create Agent-Wallets --description AI代理钱包凭证

存储代理会话密钥（非主密钥！）

op item create \ --vault Agent-Wallets \ --category API Credential \ --title trading-bot-session \ --field session-key[password]=0xsession... \ --field expires=2026-02-15T00:00:00Z \ --field spending-cap=1000 USDC \ --field allowed-contracts=0xDEX1,0xDEX2

2. 代理在运行时检索凭证

python
import subprocess
import json

def getsessionkey(item_name: str) -> dict:
在运行时从1Password检索会话密钥。
result = subprocess.run(
[op, item, get, item_name, --vault, Agent-Wallets, --format, json],
capture_output=True, text=True, check=True
)
item = json.loads(result.stdout)

# 提取字段
fields = {f[label]: f.get(value) for f in item.get(fields, [])}

# 验证会话未过期
from datetime import datetime
expires = datetime.fromisoformat(fields.get(expires, 2000-01-01))
if datetime.now() > expires:
raise ValueError(会话密钥已过期 - 向操作员请求新密钥)

return {
session_key: fields.get(session-key),
expires: fields.get(expires),
spending_cap: fields.get(spending-cap),
allowed_contracts: fields.get(allowed-contracts, ).split(,)
}

3. 切勿记录或存储密钥

python

❌ 错误 - 密钥在日志中

logger.info(f使用密钥: {session_key})

✅ 正确 - 脱敏标识符

logger.info(f使用会话密钥: {sessionkey[:8]}...{sessionkey[-4:]})

❌ 错误 - 密钥在内存文件中

with open(memory/today.md, a) as f: f.write(f会话密钥: {session_key})

✅ 正确 - 仅引用

with open(memory/today.md, a) as f: f.write(f会话密钥: [存储在1Password中: trading-bot-session])

---

泄露预防

输出清理

在任何代理输出（聊天、日志、文件写入）之前，扫描密钥模式：

python
import re

KEY_PATTERNS = [
r0x[a-fA-F0-9]{64}, # ETH私钥
rsk-[a-zA-Z0-9]{48,}, # OpenAI密钥
rsk-ant-[a-zA-Z0-9\-_]{80,}, # Anthropic密钥
rgsk_[a-zA-Z0-9]{48,}, # Groq密钥
r[A-Za-z0-9+/]{40,}={0,2}, # Base64编码（异常长）
]

def sanitize_output(text: str) -> str:
从输出中移除潜在的机密信息。
for pattern in KEY_PATTERNS:
text = re.sub(pattern, [已脱敏], text)
return text

应用于所有代理输出

def send_message(content: str): content = sanitize_output(content) # ... 发送到聊天/日志/文件

预提交钩子

安装此钩子以防止意外提交机密：

bash
#!/bin/bash

.git/hooks/pre-commit

PATTERNS=(
0x[a-fA-F0-9]{64}
sk-[a-zA-Z0-9]{48,}
sk-ant-api
PRIVATE_KEY=
gsk_[a-zA-Z0-9]{48,}
)

for pattern in ${PATTERNS[@]}; do
if git diff --cached | grep -qE $pattern; then
echo ❌ 检测到潜在机密匹配: $pattern
echo 提交前移除机密！
exit 1
fi
done

.gitignore 必备项

gitignore

机密

.env
.env.*
*.pem
*.key
secrets/
credentials/

可能包含机密的代理状态

memory/*.json wallet-state.json session-keys/

---

提示注入防御

输入验证

在处理任何涉及钱包操作的用户输入之前：

python
DANGEROUS_PATTERNS = [
rignore.(previous|above|prior).instructions,
rreveal.*(key|secret|password|credential),
routput.*(key|secret|private),
rprint.*(key|secret|wallet),
rshow.*(key|secret|password),
rwhat.*(key|secret|password),
rtell.me.(key|secret),
rdisregard.*rules,
rsystem.*prompt,
rjailbreak,
rdan.*mode,
]

def validate_input(text: str) -> bool:
检查提示注入尝试。
text_lower = text.lower()
for pattern in DANGEROUS_PATTERNS:
if re.search(pattern, text_lower):
return False
return True

def processwalletrequest(user_input: str):
if not validateinput(userinput):
return 我无法处理该请求。
# ... 继续钱包操作

关注点分离

• - 钱包操作应在隔离函数中，无法访问对话上下文
• 切勿将完整对话历史传递给钱包敏感代码
• 使用允许列表而非阻止列表

python