nansen-wallet-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

当用户已使用旧的密码存储方式设置了nansen-cli钱包，想要迁移到新的安全流程时，使用本指南。

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

用户提到自己将密码存储在
```
~/.nansen/.env
```
、某个
```
.env
```
文件或者
```
memory.md
```
中

用户收到标准错误警告：

⚠ Password loaded from insecure .credentials file

用户提出需求「保护我的钱包安全」或「迁移到钥匙串」
用户在钥匙串功能更新发布之前就创建了钱包

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:

bash

undefined

wallet show

仅会展示地址，不会加载或校验密码。要检测实际的密码存储情况，请检查已存储的密码来源：

bash

undefined

1. Check if a wallet exists at all

1. 首先检查是否存在钱包

nansen wallet list 2>&1

2. Check for insecure password stores

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. Try an operation that requires the password (without setting env var)

3. 尝试执行需要密码的操作（不设置环境变量）

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)

nansen wallet export default 2>&1


解读`export`命令的输出：
- 标准错误输出`⚠ Password loaded from ~/.nansen/wallets/.credentials` → 需要迁移（路径B）
- 导出静默成功 → 密码已存储在钥匙串中，无需迁移
- 返回`PASSWORD_REQUIRED`JSON错误 → 密码没有被持久化存储在任何位置（路径C或D）

Migration paths

迁移路径

Path A: Password in

~/.nansen/.env

(old skill pattern)

路径A：密码存储在

~/.nansen/.env

中（旧版本功能逻辑）

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:

bash

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

Step 3 — Verify the password actually decrypts the wallet:

bash

undefined

旧版本的钱包功能会引导Agent将密码写入

~/.nansen/.env

文件。

步骤1 — 向用户确认密码：

"你的钱包密码当前存储在~/.nansen/.env中，该存储方式不安全。我可以将其迁移到你的系统钥匙串中。请确认你创建钱包时使用的密码，如果你授权的话，我也可以直接从~/.nansen/.env中读取该密码。"

步骤2 — 执行迁移：

source

命令和

nansen wallet secure

命令必须在同一个shell中执行，这样node进程才能读取到环境变量：

bash

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

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

bash

undefined

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:**

```bash
rm -f ~/.nansen/.env

unset NANSEN_WALLET_PASSWORD nansen wallet export default 2>&1


如果导出成功（展示私钥），说明迁移生效。如果显示`Incorrect password`，说明迁移的密码错误 — 执行`nansen wallet forget-password`，然后使用正确的密码重试。

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

```bash
rm -f ~/.nansen/.env

Path B: Password in

.credentials

file (auto-saved fallback)

路径B：密码存储在

.credentials

文件中（自动保存的降级方案）

This happens when

wallet create

couldn't access the OS keychain (containers, CI).

bash

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:

bash

nansen wallet export default 2>&1

这种情况通常出现在

wallet create

无法访问系统钥匙串时（容器环境、CI场景）。

bash

nansen wallet secure

如果钥匙串仍然不可用（例如没有D-Bus服务的容器化Linux环境），

nansen wallet secure

会说明当前情况并给出替代方案。

迁移完成后，验证解密功能正常：

bash

nansen wallet export default 2>&1

Path C: Password only in

NANSEN_WALLET_PASSWORD

env var

路径C：密码仅存储在

NANSEN_WALLET_PASSWORD

环境变量中

bash

undefined

bash

undefined

Persist the env var password to keychain

将环境变量中的密码持久化存储到钥匙串

nansen wallet secure


Then verify without the env var:

```bash
unset NANSEN_WALLET_PASSWORD
nansen wallet export default 2>&1

nansen wallet secure


然后取消环境变量后验证功能：

```bash
unset NANSEN_WALLET_PASSWORD
nansen wallet export default 2>&1

Path D: Password lost entirely

路径D：密码完全丢失

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."

bash

undefined

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

告知用户：

"你的钱包密码无法找回。如果该钱包中存有资产，你可能无法访问这些资产。你可以创建一个新钱包，转移所有仍可访问的剩余资产。"

bash

undefined

Create a fresh wallet (human must provide a new password)

创建全新钱包（用户需要提供新密码）

NANSEN_WALLET_PASSWORD="<new_password_from_user>" nansen wallet create --name new-wallet

undefined

NANSEN_WALLET_PASSWORD="<new_password_from_user>" nansen wallet create --name new-wallet

undefined

Post-migration verification

迁移后验证

After any migration, confirm the password was migrated correctly by proving the keychain password can actually decrypt the wallet:

bash

undefined

任何迁移完成后，都需要确认密码已正确迁移，验证钥匙串存储的密码确实可以解密钱包：

bash

undefined

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:

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

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).

nansen wallet export default 2>&1


如果导出显示`Incorrect password`，说明存入钥匙串的密码错误。可以通过以下命令修复：

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

如果标准错误仍然显示

.credentials

相关警告，说明钥匙串迁移未成功 — 检查系统钥匙串服务是否正在运行（Linux下为

secret-tool

，macOS下为

security

）。

Forget password (all stores)

清除所有存储的密码

If the user wants to remove their persisted password entirely:

bash

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

如果用户想要完全移除已持久化存储的密码：

bash

nansen wallet forget-password

该命令会同时清除系统钥匙串和

.credentials

文件中存储的密码。后续的钱包操作需要提供

NANSEN_WALLET_PASSWORD

环境变量，或者重新执行

nansen wallet secure

命令。

Critical rules for agents

Agent需遵守的核心规则

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)

绝对不要生成密码 — 始终向用户索要
绝对不要存储密码 到文件、内存、日志或对话历史中
绝对不要使用
--human
参数 — 交互式提示会导致Agent运行失败
如果用户授权读取
```
~/.nansen/.env
```
，在同一个命令中完成读取操作（
```
source ~/.nansen/.env && nansen wallet secure
```
） — 不要输出或记录密码值
迁移后必须执行验证 运行
```
nansen wallet export default
```
—
```
wallet show
```
无法证明密码有效（它不会加载密码）

nansen-wallet-migration

Original

Translation

Wallet Migration — Old Flow to Secure Keychain

钱包迁移 — 从旧流程到安全钥匙串

When to use

适用场景

Detect current state

检测当前状态

1. Check if a wallet exists at all

1. 首先检查是否存在钱包

2. Check for insecure password stores

2. 检查不安全的密码存储位置

3. Try an operation that requires the password (without setting env var)

3. 尝试执行需要密码的操作（不设置环境变量）

Migration paths

迁移路径

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

路径A：密码存储在~/.nansen/.env中（旧版本功能逻辑）

Unset env var to prove keychain works, then export to verify decryption

取消设置环境变量，证明钥匙串可用，然后执行导出验证解密功能

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

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

Path C: Password only in NANSEN_WALLET_PASSWORD env var

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

Persist the env var password to keychain

将环境变量中的密码持久化存储到钥匙串

Path D: Password lost entirely

路径D：密码完全丢失

Create a fresh wallet (human must provide a new password)

创建全新钱包（用户需要提供新密码）

Post-migration verification

迁移后验证

Unset env var to prove keychain works

取消设置环境变量，证明钥匙串可用

This MUST succeed — it proves the keychain password decrypts the wallet

该命令必须执行成功 — 它证明钥匙串中的密码可以解密钱包

Forget password (all stores)

清除所有存储的密码

Critical rules for agents

Agent需遵守的核心规则

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

路径A：密码存储在
`~/.nansen/.env`
中（旧版本功能逻辑）

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

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

Path C: Password only in
`NANSEN_WALLET_PASSWORD`
env var

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