扫码配对
ACP v2.1 没有共享 token。每台设备有长期 X25519 身份，Agent 用 authorized_peers.json 白名单放行。二维码只是把「连谁、一次性登记码、指纹」一次交给 App。
Pairing
ACP v2.1 has no shared token. Each device has a long-term X25519 identity; the agent allowlists it in authorized_peers.json. The QR hands the app the endpoint, a one-time enrollment code, and a fingerprint.
两种入口，不要扫错
Two entry points — don’t mix them
| 场景When | URI | App 入口In the app | 命令Command |
|---|---|---|---|
| 一台 Hub，多个实例One hub, many instances | shepaw://peer |
Device Pairing / Scan to Connect | shepaw-hub peer-pair |
| 单个网关进程Single gateway process | shepaw://pair |
添加 Agent → 扫码Add Agent → Scan | shepaw-acp-proxy pair |
Hub 的 Web 仪表盘在「扫码配对」里出的是 Peer 码，一次授权本机全部实例。单网关的 pair 码只绑定那一个 Agent。
The hub dashboard “pair” button emits a Peer QR and authorizes every instance on that host. A gateway pair QR binds only that one agent.
二维码里有什么
What’s in the QR
- WebSocket 地址（局域网
ws://，外网可带 Channel） - 一次性 enrollment code（握手成功即作废）
- Fragment：
#fp=Agent 静态公钥指纹，可选pk=
- WebSocket URL (LAN
ws://, or Channel when off-site) - One-time enrollment code (consumed on handshake)
- Fragment:
#fp=agent static-key fingerprint, optionalpk=
手动配对
Manual pairing
扫不了码时：把 App「添加 Agent」页显示的设备公钥交给网关：
If you cannot scan, paste the device public key from Add Agent into the gateway:
shepaw-acp-proxy peers add <device-pubkey-base64> --label "My iPhone" # Hub： shepaw-hub pair <instance-id> --label "My iPhone"
URL 里的 #fp= 必须和 Agent 真实公钥指纹一致，否则握手以 4403 关闭——这是为了防止中继替换身份。
The #fp= in the URL must match the agent’s real key fingerprint or the handshake closes with 4403 — that blocks a relay from swapping identity.
吊销一台丢失的手机
Revoke a lost phone
v2.1 里每台设备是白名单里的一行。删掉那一行即可，不必让其他设备重新配对。
In v2.1 each device is one allowlist row. Remove that row; other devices stay paired.
shepaw-acp-proxy peers remove <fingerprint-or-label>