Nansen 钱包密钥链迁移指南：从旧存储迁移至安全密钥链

nansen-wallet-keychain-migration by nansen-ai/nansen-cli

108 周安装量

104 GitHub Stars

GitHub

安装命令

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

区块链命令行工具安全

🇨🇳中文介绍

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

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

使用时机

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

检测当前状态

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

# 1. 检查是否存在钱包
nansen wallet list 2>&1

# 2. 检查不安全的密码存储位置
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. 尝试需要密码的操作（不设置环境变量）
nansen wallet export default 2>&1

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

路径 A：密码在 `~/.nansen/.env` 中（旧技能模式）

之前的钱包技能曾指示代理将密码写入 ~/.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 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` 环境变量中

# 将环境变量中的密码持久化到密钥链
nansen wallet secure

然后在不使用环境变量的情况下验证：

unset NANSEN_WALLET_PASSWORD
nansen wallet export default 2>&1

路径 D：密码完全丢失

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

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

# 创建一个新钱包（用户必须提供新密码）
NANSEN_WALLET_PASSWORD="<new_password_from_user>" nansen wallet create --name new-wallet

在任何迁移之后，通过证明密钥链密码确实能解密钱包来确认密码已正确迁移：

# 取消设置环境变量以证明密钥链有效
unset NANSEN_WALLET_PASSWORD

# 此命令必须成功 — 它证明密钥链密码可以解密钱包
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。

代理的关键规则

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

🇺🇸English

Wallet Migration — Old Flow to Secure Keychain

Use this skill when a user already has a nansen-cli wallet set up with the old password storage method and wants to migrate to the new secure flow.

When to use

User mentions they stored their password in ~/.nansen/.env, a .env file, or memory.md
User gets the stderr warning: ⚠ Password loaded from insecure .credentials file
User asks to "secure my wallet" or "migrate to keychain"
User created a wallet before the keychain update was released

Detect current state

wallet show only displays addresses and does NOT load or check the password. To detect the actual password situation, check for stored password sources:

# 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

Interpret the export output:

⚠ Password loaded from ~/.nansen/wallets/.credentials on stderr → needs migration (Path B)
Export succeeds silently → password is in keychain, no migration needed
PASSWORD_REQUIRED JSON error → password not persisted anywhere (Path C or D)

Migration paths

Path A: Password in `~/.nansen/.env` (old skill pattern)

The previous wallet skill told agents to write the password to ~/.nansen/.env.

Step 1 — Ask the human for their password:

"Your wallet password is currently stored in ~/.nansen/.env, which is insecure. I can migrate it to your OS keychain. Please confirm the password you used when creating the wallet, or I can read it from ~/.nansen/.env if you authorize it."

Step 2 — Migrate:

The source and nansen wallet secure MUST run in the same shell so the env var is available to the node process:

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

Step 3 — Verify the password actually decrypts the wallet:

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

If export succeeds (shows private keys), the migration worked. If it shows Incorrect password, the wrong password was migrated — run nansen wallet forget-password and retry with the correct password.

Step 4 — Clean up the insecure file:

rm -f ~/.nansen/.env

Path B: Password in `.credentials` file (auto-saved fallback)

This happens when wallet create couldn't access the OS keychain (containers, CI).

nansen wallet secure

If the keychain is still unavailable (e.g. containerized Linux without D-Bus), nansen wallet secure will explain the situation and suggest alternatives.

After migrating, verify decryption works:

nansen wallet export default 2>&1

Path C: Password only in `NANSEN_WALLET_PASSWORD` env var

# Persist the env var password to keychain
nansen wallet secure

Then verify without the env var:

unset NANSEN_WALLET_PASSWORD
nansen wallet export default 2>&1

Path D: Password lost entirely

The password cannot be recovered. The wallet's private keys are encrypted with AES-256-GCM and the password is not stored anywhere recoverable.

Tell the human:

"Your wallet password cannot be recovered. If you have funds in this wallet, they may be inaccessible. You can create a new wallet and transfer any remaining accessible funds."

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

Post-migration verification

After any migration, confirm the password was migrated correctly by proving the keychain password can actually decrypt the 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

If export shows Incorrect password, the wrong password was saved to the keychain. Fix with:

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

If stderr still shows the .credentials warning, the keychain migration did not succeed — check if the OS keychain service is running (secret-tool on Linux, security on macOS).

Forget password (all stores)

If the user wants to remove their persisted password entirely:

nansen wallet forget-password

This clears the password from both OS keychain and .credentials file. Future wallet operations will require NANSEN_WALLET_PASSWORD env var or re-running nansen wallet secure.

Critical rules for agents

NEVER generate a password — always ask the human
NEVER store the password in files, memory, logs, or conversation history
NEVER use--human flag — interactive prompts break agents
If the human authorizes reading ~/.nansen/.env, read it in the same command (source ~/.nansen/.env && nansen wallet secure) — do not echo or log the value
ALWAYS verify after migration with nansen wallet export default — wallet show does NOT prove the password works (it never loads the password)

Weekly Installs

108

Repository

nansen-ai/nansen-cli

GitHub Stars

104

First Seen

8 days ago

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

codex105

opencode105

cursor104

gemini-cli104

amp104

cline104

tzst命令行工具使用指南：创建、提取、管理.tar.zst压缩归档文件

35,700 周安装

Nansen 钱包密钥链迁移指南：从旧存储迁移至安全密钥链

🇨🇳中文介绍

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

使用时机

检测当前状态

相关 Skills

迁移路径

路径 A：密码在 `~/.nansen/.env` 中（旧技能模式）

路径 B：密码在 `.credentials` 文件中（自动保存的备用方案）

路径 C：密码仅在 `NANSEN_WALLET_PASSWORD` 环境变量中

路径 D：密码完全丢失

迁移后验证

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

代理的关键规则

🇺🇸English

Wallet Migration — Old Flow to Secure Keychain

When to use

Detect current state

Migration paths

Path A: Password in `~/.nansen/.env` (old skill pattern)

Path B: Password in `.credentials` file (auto-saved fallback)

Path C: Password only in `NANSEN_WALLET_PASSWORD` env var

Path D: Password lost entirely

Post-migration verification

Forget password (all stores)

Critical rules for agents

最新 Skills

Nansen 钱包密钥链迁移指南：从旧存储迁移至安全密钥链

🇨🇳中文介绍

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

使用时机

检测当前状态

相关 Skills

迁移路径

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

路径 B：密码在 .credentials 文件中（自动保存的备用方案）

路径 C：密码仅在 NANSEN_WALLET_PASSWORD 环境变量中

路径 D：密码完全丢失

迁移后验证

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

代理的关键规则

🇺🇸English

Wallet Migration — Old Flow to Secure Keychain

When to use

Detect current state

Migration paths

Path A: Password in ~/.nansen/.env (old skill pattern)

Path B: Password in .credentials file (auto-saved fallback)

Path C: Password only in NANSEN_WALLET_PASSWORD env var

Path D: Password lost entirely

Post-migration verification

Forget password (all stores)

Critical rules for agents

最新 Skills

路径 A：密码在 `~/.nansen/.env` 中（旧技能模式）

路径 B：密码在 `.credentials` 文件中（自动保存的备用方案）

路径 C：密码仅在 `NANSEN_WALLET_PASSWORD` 环境变量中

Path A: Password in `~/.nansen/.env` (old skill pattern)

Path B: Password in `.credentials` file (auto-saved fallback)

Path C: Password only in `NANSEN_WALLET_PASSWORD` env var