magic-wormhole 上手：两台电脑之间用一句口令传文件，不用账号也不用先配 SSH

01适用场景

两台电脑系统不同、不在同一个账号体系里，又想临时传个文件：比如把配置文件发给同事、把日志从服务器拿回本机。双方只要能通过电话或聊天把一句短口令告诉对方即可。

02它是怎么工作的

• 发送方生成一次性口令，默认两个单词加一个数字，口令只能用一次。
• 同一局域网或一方有公网地址时直接点对点传输；双方都在 NAT 后面连不上时，才经过中转服务器转发，内容仍是加密的。
• 官方文档说明，默认口令约 16 位熵，攻击者每次只有 1/65536 的猜中机会，猜错会让连接失败并报错，所以口令别重复使用。

03安装

官方文档给出各系统的装法，下面三条选你用的一条。pip 方式要求 Python 3.10 及以上。

brew install magic-wormhole            # macOS（Homebrew）
sudo apt install magic-wormhole          # Debian / Ubuntu
winget install -e --id magic-wormhole.magic-wormhole   # Windows
# 或用 Python：
pip install --user magic-wormhole

装好后用 wormhole --version 确认，本站沙箱里显示 magic-wormhole 0.24.0。

04发送与接收

1. 发送方：wormhole send 文件名（文件夹同样写目录名；只想发一段文字用 --text）。终端会打印“Wormhole code is: …”。
2. 把口令告诉对方。口令不要发在公开频道里。
3. 接收方：运行 wormhole receive，按提示输入口令（支持 Tab 补全），确认 ok? (y/n) 后开始传输。
4. 发送方看到 Confirmation received. Transfer complete. 即完成。

# 发送方
wormhole send report.pdf
# 接收方
wormhole receive
# 或直接带口令
wormhole receive 1-inferno-robust

05本站实测

2026 年 10 月 28 日，在同一台沙箱里开两个进程：一个 wormhole send t.txt 得到口令 1-inferno-robust，另一个 wormhole receive --accept-file 1-inferno-robust 收到 11 字节的文件，内容一致，发送端提示 Transfer complete。这只验证了本机直连，没有测跨网络、中转和大文件速度。

06常用参数

• --code-length 词数：改变口令词数，传敏感文件时可加长。
• --verify：双方再核对一段验证字符串，防中间人，适合口令是在不太可信的渠道里传的情况。
• --relay-url / --transit-helper：改用自建的信箱服务器或中转服务器，两端的信箱服务器必须相同。

07注意事项

• 两端要同时在线：官方说明程序没有内置超时，但预期双方在一小时左右内都运行，传输结束前不能关。
• 口令一次性：我们实测中，用自己随手指定的 7-zovo-test 做口令时，接收端报 Key confirmation failed 并提示口令已作废，原因没有深究；公共信箱服务器上的短频道号可能被别人占用，建议让发送方自动生成口令。
• 默认使用项目内置的公共信箱服务器，官方称在流量或滥用过大时可能停止免费提供；对可靠性有要求可自建。
• 手机端有第三方应用（官方文档列出 Android 的 Wormhole），桌面 GUI 有 GNOME 的 Warp。