nansen-wallet-keychain-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

无论使用哪种迁移路径，都必须通过

nansen wallet export default

确认密码已正确迁移——

wallet show

无法证明密码可用（它从不加载密码）：

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-keychain-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`
环境变量中