mcpField
N
nansen-wallet-migration

nansen-wallet-migration

github.com/nansen-ai安全14480 次安装今天更新
代码仓库

关于 nansen-wallet-migration

nansen-wallet-migration 是一项指导 nansen-cli 用户将旧钱包密码存储方式迁移到系统密钥链的技能。它涵盖多种密码存储状态，并要求迁移后验证密码能否解密钱包。

主要功能

  1. 01检查钱包及密码存储状态
  2. 02按密码来源选择迁移步骤
  3. 03验证密钥链密码能否解密钱包
  4. 04提供忘记密码与新建钱包指引

适用场景

  1. 01迁移 ~/.nansen/.env 中的密码
  2. 02处理 .credentials 警告并验证迁移
  3. 03密码遗失时了解后续处理方式

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nansen-ai/nansen-cli --skill nansen-wallet-migration

安装后在 Claude Code 中输入/nansen-wallet-migration确认已加载。

详细介绍

钱包迁移 — 从旧流程迁移到安全密钥链

当用户已经设置了 nansen-cli 钱包，使用的是旧的密码存储方式，并希望迁移到新的安全流程时，请使用此技能。

适用场景

  • 用户提到曾将密码存储在 ~/.nansen/.env、.env 文件或 memory.md 中
  • 用户看到 stderr 警告：⚠ Password loaded from insecure .credentials file
  • 用户要求“保护我的钱包”或“迁移到密钥链”
  • 用户在密钥链更新发布之前创建了钱包

检测当前状态

wallet show 只会显示地址，不会加载或检查密码。 要检测密码的实际情况，请检查已存储的密码来源：

# 1. Check if a wallet exists at all
nansen wallet list 2>&1

# 2. Check for insecure password stores
ls -la ~/.nansen/.env 2>/dev/null && echo "FOUND: ~/.nansen/.env (insecure)"
ls -la ~/.nansen/wallets/.credentials 2>/dev/null && echo "FOUND: .credentials file (insecure)"

# 3. Try an operation that requires the password (without setting env var)
nansen wallet export default 2>&1

解读 export 输出：

  • stderr 中出现 ⚠ Password loaded from ~/.nansen/wallets/.credentials → 需要迁移（路径 B）
  • 导出成功且没有输出 → 密码已存储在密钥链中，无需迁移
  • 出现 PASSWORD_REQUIRED JSON 错误 → 密码未持久化到任何位置（路径 C 或 D）

迁移路径

路径 A：密码位于 ~/.nansen/.env 中（旧版技能模式）

之前的钱包技能要求 Agent 将密码写入 ~/.nansen/.env。

步骤 1 — 向用户询问密码：

“您的钱包密码目前存储在 ~/.nansen/.env 中，这种方式不安全。 我可以将其迁移到您的操作系统密钥链。请确认您创建钱包时使用的密码， 或者，如果您授权，我可以从 ~/.nansen/.env 中读取密码。”

步骤 2 — 迁移：

source 和 nansen wallet secure 必须在同一个 shell 中运行，这样环境 变量才能传递给 node 进程：

source ~/.nansen/.env 2>/dev/null && nansen wallet secure

步骤 3 — 验证密码确实可以解密钱包：

# Unset env var to prove keychain works, then export to verify decryption
unset NANSEN_WALLET_PASSWORD
nansen wallet export default 2>&1

如果导出成功（显示私钥），则迁移成功。如果显示 Incorrect password，说明迁移的密码不正确 — 运行 nansen wallet forget-password，并使用正确的密码重试。

步骤 4 — 清理不安全的文件：

rm -f ~/.nansen/.env
路径 B：密码位于 .credentials 文件中（自动保存的备用方式）

当 wallet create 无法访问操作系统密钥链时（例如容器、CI），就会出现这种情况。

nansen wallet secure

如果密钥链仍不可用（例如没有 D-Bus 的容器化 Linux 环境）， nansen wallet secure 会说明情况并提供替代方案。

迁移后，请验证解密是否正常：

nansen wallet export default 2>&1
路径 C：密码仅存储在 NANSEN_WALLET_PASSWORD 环境变量中
# Persist the env var password to keychain
nansen wallet secure

然后在不设置环境变量的情况下验证：

unset NANSEN_WALLET_PASSWORD
nansen wallet export default 2>&1
路径 D：密码已完全丢失

密码无法恢复。钱包的私钥使用 AES-256-GCM 加密，且密码未存储在任何可恢复的位置。

告知用户：

“您的钱包密码无法恢复。如果此钱包中有资金， 这些资金可能无法访问。您可以创建新钱包，并转移任何仍可访问的资金。”

# Create a fresh wallet (human must provide a new password)
NANSEN_WALLET_PASSWORD="<new_password_from_user>" nansen wallet create --name new-wallet

迁移后验证

任何迁移完成后，都要通过确认密钥链中的密码确实可以解密钱包， 来验证密码是否已正确迁移：

# Unset env var to prove keychain works
unset NANSEN_WALLET_PASSWORD

# This MUST succeed — it proves the keychain password decrypts the wallet
nansen wallet export default 2>&1

如果导出结果显示 Incorrect password，说明保存到密钥链中的密码不正确。请通过以下方式修复：

nansen wallet forget-password
NANSEN_WALLET_PASSWORD="<correct_password>" nansen wallet secure

如果 stderr 中仍显示 .credentials 警告，说明密钥链迁移未成功 — 检查操作系统密钥链服务是否正在运行（Linux 上的 secret-tool， macOS 上的 security）。

忘记密码（所有存储位置）

如果用户希望彻底删除已持久化的密码：

nansen wallet forget-password

这会清除操作系统密钥链和 .credentials 文件中的密码。之后的钱包操作将需要设置 NANSEN_WALLET_PASSWORD 环境变量，或重新运行 nansen wallet secure。

Agent 的关键规则

  • 绝不生成密码——始终询问人类
  • 绝不将密码存储在文件、内存、日志或对话历史中
  • 绝不使用 --human 标志——交互式提示会导致 Agent 中断
  • 如果人类授权读取 ~/.nansen/.env，请在同一条命令中读取 （source ~/.nansen/.env && nansen wallet secure）——不要回显或记录该值
  • 迁移后始终使用 nansen wallet export default 验证——wallet show 不能证明密码有效（它不会加载密码）

评论

支持 Markdown