Yggdrasil Setup
Yggdrasil gives every OpenClaw agent a globally-routable 200::/8 IPv6 address derived from their Ed25519 keypair. Without it, P2P addresses are local-only.
Quick Reference
| Situation | Action |
|---|
| "Is P2P working?" / "Can I connect?" | INLINECODE1 , explain result |
| "What is my address?" (first time) |
yggdrasil_check() to confirm routable |
|
p2p_send_message fails |
yggdrasil_check() to diagnose |
| Yggdrasil not installed | Guide through install (see
references/install.md) |
| User asks what Yggdrasil is | Explain briefly, offer to install |
Interpreting yggdrasil_check Results
| Address type | Meaning | Tell the user |
|---|
| INLINECODE6 | Daemon running, globally routable | Ready. Share the address with peers. |
| INLINECODE7 |
Local/Docker only | Fine for testing on the same machine. Not reachable by internet peers. |
|
derived_only | Yggdrasil not running | Address is NOT reachable. Install Yggdrasil first. |
Troubleshooting derived_only
If yggdrasil_check() returns derived_only after install:
- 1. Binary not on PATH: Run
which yggdrasil. If not found, add to PATH or reinstall. - Gateway not restarted: The plugin detects the binary at startup. Restart the OpenClaw gateway.
- Permission denied: On Linux, Yggdrasil needs
CAP_NET_ADMIN to create a TUN interface. Run as root or use setcap. - Docker: Container needs
--cap-add=NET_ADMIN and --device=/dev/net/tun.
After Install
- 1. Restart the OpenClaw gateway.
- The plugin detects Yggdrasil, generates a config, and starts the daemon automatically.
- Call
yggdrasil_check() to confirm the routable 200: address.
See references/install.md for platform-specific install commands.
Yggdrasil 设置
Yggdrasil 为每个 OpenClaw 代理提供一个基于其 Ed25519 密钥对的全局可路由 200::/8 IPv6 地址。没有它，P2P 地址仅限本地使用。
快速参考
| 情况 | 操作 |
|---|
| P2P 工作正常吗？ / 我能连接吗？ | yggdrasilcheck()，解释结果 |
| 我的地址是什么？（首次） |
yggdrasilcheck() 确认可路由 |
| p2p
sendmessage 失败 | yggdrasil_check() 进行诊断 |
| Yggdrasil 未安装 | 引导安装（参见 references/install.md） |
| 用户询问 Yggdrasil 是什么 | 简要说明，提供安装选项 |
解读 yggdrasil_check 结果
| 地址类型 | 含义 | 告知用户 |
|---|
| yggdrasil | 守护进程运行中，全局可路由 | 已就绪。与对等节点共享该地址。 |
| test_mode |
仅限本地/Docker | 适合在同一台机器上测试。互联网对等节点无法访问。 |
| derived_only | Yggdrasil 未运行 | 地址不可达。请先安装 Yggdrasil。 |
解决 derived_only 问题
如果安装后 yggdrasilcheck() 返回 derivedonly：
- 1. 二进制文件不在 PATH 中：运行 which yggdrasil。如果未找到，请添加到 PATH 或重新安装。
- 网关未重启：插件在启动时检测二进制文件。请重启 OpenClaw 网关。
- 权限被拒绝：在 Linux 上，Yggdrasil 需要 CAPNETADMIN 来创建 TUN 接口。以 root 身份运行或使用 setcap。
- Docker：容器需要 --cap-add=NET_ADMIN 和 --device=/dev/net/tun。
安装后
- 1. 重启 OpenClaw 网关。
- 插件检测到 Yggdrasil，生成配置文件，并自动启动守护进程。
- 调用 yggdrasil_check() 确认可路由的 200: 地址。
平台特定的安装命令请参见 references/install.md。
