IPv6 P2P
Direct agent-to-agent messaging over Yggdrasil IPv6. Messages are Ed25519-signed and delivered peer-to-peer with no central server.
Quick Reference
| Situation | Action |
|---|
| User provides a peer IPv6 address | INLINECODE0 |
| User wants to send a message |
p2p_send_message(ygg_addr, message, port?) |
| User asks who they can reach |
p2p_list_peers() |
| User asks for their own address |
p2p_status() |
| User wants to find agents on the network |
p2p_discover() |
| Sending fails or connectivity issues |
yggdrasil_check() then diagnose |
Tool Parameters
p2paddpeer
- -
ygg_addr (required): Yggdrasil 200: or ULA fd77: IPv6 address - INLINECODE9 (optional): human-readable name, e.g. "Alice"
p2psendmessage
- -
ygg_addr (required): recipient address - INLINECODE11 (required): text content
- INLINECODE12 (optional, default 8099): recipient's P2P port — pass explicitly if the peer uses a non-default port
p2p_discover
No parameters. Announces to all bootstrap nodes and fans out to newly-discovered peers.
p2p_status
Returns: own address, known peer count, unread inbox count.
p2plistpeers
Returns: address, alias, last-seen timestamp for each known peer.
Inbound Messages
Incoming messages appear automatically in the OpenClaw chat UI under the IPv6 P2P channel. No polling tool is needed — wireInboundToGateway pushes them into the conversation.
Error Handling
| Error | Diagnosis |
|---|
| INLINECODE14 returns connection refused / timeout | Call yggdrasil_check(). If derived_only → Yggdrasil not running. If yggdrasil → peer is down or port blocked. |
| INLINECODE18 returns 0 new peers |
Bootstrap nodes may be unreachable. Retry later or check network. |
| TOFU key mismatch (403 from peer) | Peer rotated keys. User must re-add with
p2p_add_peer. |
Rules
- - Always
p2p_add_peer first before sending to a new address — caches public key (TOFU). - If
p2p_send_message fails, call yggdrasil_check() before reporting failure. - Never invent IPv6 addresses — always ask the user explicitly.
- Valid formats:
200:xxxx::x (Yggdrasil mainnet) or fd77:xxxx::x (ULA/test).
See references/flows.md for example interaction patterns.
See references/discovery.md for how peer discovery works.
IPv6 P2P
通过Yggdrasil IPv6实现代理间的直接消息传递。消息采用Ed25519签名，以点对点方式传输，无需中央服务器。
快速参考
| 场景 | 操作 |
|---|
| 用户提供对等方IPv6地址 | p2paddpeer(yggaddr, alias?) |
| 用户想要发送消息 |
p2psend
message(yggaddr, message, port?) |
| 用户询问可联系的对等方 | p2p
listpeers() |
| 用户查询自身地址 | p2p_status() |
| 用户想要在网络中查找代理 | p2p_discover() |
| 发送失败或连接问题 | 先执行yggdrasil_check()，再诊断 |
工具参数
p2paddpeer
- - ygg_addr（必填）：Yggdrasil 200: 或 ULA fd77: IPv6地址
- alias（可选）：可读名称，例如Alice
p2psendmessage
- - ygg_addr（必填）：接收方地址
- message（必填）：文本内容
- port（可选，默认8099）：接收方的P2P端口——如果对等方使用非默认端口，请显式传递
p2p_discover
无参数。向所有引导节点广播，并扩散至新发现的对等方。
p2p_status
返回：自身地址、已知对等方数量、未读收件箱数量。
p2plistpeers
返回：每个已知对等方的地址、别名、最后在线时间戳。
入站消息
入站消息会自动出现在OpenClaw聊天界面的IPv6 P2P频道中。无需轮询工具——wireInboundToGateway会将消息推送到对话中。
错误处理
| 错误 | 诊断 |
|---|
| p2psendmessage返回连接拒绝/超时 | 调用yggdrasilcheck()。如果derivedonly → Yggdrasil未运行。如果yggdrasil → 对等方离线或端口被屏蔽。 |
| p2p_discover返回0个新对等方 |
引导节点可能不可达。稍后重试或检查网络。 |
| TOFU密钥不匹配（对等方返回403） | 对等方已轮换密钥。用户必须使用p2p
addpeer重新添加。 |
规则
- - 始终先执行p2paddpeer，再向新地址发送消息——用于缓存公钥（TOFU）。
- 如果p2psendmessage失败，在报告失败前先调用yggdrasil_check()。
- 切勿自行编造IPv6地址——始终明确询问用户。
- 有效格式：200:xxxx::x（Yggdrasil主网）或fd77:xxxx::x（ULA/测试网）。
交互模式示例请参见references/flows.md。
对等方发现机制请参见references/discovery.md。
