openclaw dns基于 Tailscale CoreDNS 的广域 DNS-SD 发现配置实战【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw导读openclaw dns是 OpenClaw 内置的一组 DNS 辅助命令用于搭建基于 Tailscale CoreDNS 的广域发现wide-area discovery即 DNS-SD / Wide-Area Bonjour能力让分布在不同物理网络上的 Gateway 客户端macOS 菜单栏应用、iOS/Android 节点能够跨网络发现并直连 Gateway而不再受限于局域网内的组播 Bonjour。读完本文你将掌握openclaw dns setup的规划plan与执行apply两种模式、discovery.wideArea配置的完整语义以及如何通过 Tailscale Split DNS 将自定义发现域名例如openclaw.internal解析到 CoreDNS实现真正可落地的跨网络 Gateway 发现。为什么要用广域 DNS-SD发现问题的全景OpenClaw 的节点发现面对两类核心问题详见 Discovery and transports运维人员远程控制macOS 菜单栏应用控制运行在其他机器上的 Gateway节点配对iOS/Android及未来的节点发现 Gateway 并安全配对。所有网络发现/广播都发生在Gatewayopenclaw gateway侧客户端只是发现结果的消费者。OpenClaw 支持两种互补的发现通道组播 BonjourDNS-SD over mDNS只覆盖local.同一局域网best-effort 且不能跨网段单播 DNS-SDwide-area通过一个自定义发现域名如openclaw.internal把 Gateway 的 beacon 写入 DNS 区域让发现范围扩展到整个 Tailscale tailnet 乃至跨网络。openclaw dns正是为第二种场景而生它用 Tailscale 地址 CoreDNS 把单播 DNS-SD 落地为可运行的本地权威解析服务。其完整流程建立在 Bonjour 发现机制 与 Gateway 运行时配置discovery.wideArea之上。dns setup规划与执行两个阶段openclaw dns setup在任何平台都可以先“打印规划”只有加上--apply才真正落地配置而落地目前仅支持 macOS Homebrew CoreDNS。对应源码实现位于 dns-cli.ts注册为program.command(dns)下的setup子命令。基本用法# 仅打印规划所有平台可用 openclaw dns setup # 显式指定发现域名 openclaw dns setup --domain openclaw.internal # 真正安装/更新 CoreDNS 配置并重启服务macOS sudo openclaw dns setup --apply参数表OptionEffect--domain domain广域发现域名例如openclaw.internal会覆盖配置中的值--apply安装/更新 CoreDNS 配置并重启动服务需要 sudo仅 macOS 可用域名解析优先级命令实际使用的域名按以下顺序确定见 dns-cli.ts 与 widearea-dns.ts命令行--domain显式传入否则读取运行时配置discovery.wideArea.domain否则读取环境变量OPENCLAW_WIDE_AREA_DOMAIN。如果都没有命令会直接报错No wide-area domain configured. Set discovery.wideArea.domain or pass --domain.另外一旦拿到候选域名代码会先调用normalizeWideAreaDomain做严格校验域名必须是合法 DNS 名每段 label 匹配^A-Za-z0-9?$总长度不超过 253非法输入会抛出wide-area discovery domain must be a valid DNS name而不会静默回退到环境变量。无--apply先看规划再动手不加--apply时命令只输出一份“干跑”规划dns-cli.ts解析后的发现域名与zone 文件路径位于~/.openclaw/dns/下文件名形如domain.db见 widearea-dns.ts 的getWideAreaZonePath当前机器的 tailnet IP优先取 Tailscale 的主 IPv4存在时附带 IPv6来源为 tailnet.ts 的pickPrimaryTailnetIPv4/pickPrimaryTailnetIPv6推荐的openclaw.json发现配置JSON 输出{ gateway: { bind: auto }, discovery: { wideArea: { domain: openclaw.internal } }, }Tailscale 管理后台DNS → Nameservers需要设置的值添加 Nameserver本机 tailnet IPv4Restrict to domainSplit DNSopenclaw.internal去掉末尾点。规划模式适合在任意平台Linux、Windows、macOS先确认将要发生什么再决定是否在 macOS 上执行--apply。--apply的执行链路macOS--apply模式对平台和前置条件有硬性要求dns-cli.tsprocess.platform必须为darwin否则报错dns setup is currently supported on macOS only必须检测到至少一个 tailnet IP否则报错no tailnet IP detected; ensure Tailscale is running on this machine。随后命令按以下顺序执行落地步骤探测 Homebrew 前缀运行brew --prefix并对这个快速探测设置了 15 秒 SIGKILL 的超时防止挂死的 brew shim 阻塞整个 setup见 dns-cli.ts安装 CoreDNSbrew list coredns失败忽略→brew install coredns失败也允许继续便于后续重试创建配置目录brew-prefix/etc/coredns/conf.d/必要时通过sudo mkdir -pdns-cli.ts维护 Corefile若brew-prefix/etc/coredns/Corefile不存在则写入import conf.d/*.server否则追加缺失的 import 行ensureImportLine写入 server 配置为发现域名生成domain-without-trailing-dot.server文件内容大致为openclaw.internal:53 { bind 100.64.0.1 # 本机 tailnet IPv4IPv6 存在时一并 bind file /root/.openclaw/dns/openclaw.internal.db { reload 10s } errors log }引导 zone 文件若 zone 文件缺失或缺少SOA/NS记录则生成初始 zone 引导内容dns-cli.ts$ORIGIN、$TTL 60、SOAserial 采用YYYYMMDD01格式、NS、ns1 A/AAAA指向 tailnet IP重启服务sudo brew services restart coredns温馨提示若配置中尚未设置discovery.wideArea.domain命令会提示你在 Gateway 的openclaw.json默认~/.openclaw/openclaw.json中设置该域名并重启 Gateway这样 Gateway 才会实际写入 DNS-SD zone。所有需要写 root 属主文件的步骤Corefile、server 文件、zone 文件都采用“先普通写、遇EACCES/EPERM再回退sudo tee”的策略dns-cli.ts。这一链路有对应测试覆盖例如 dns-cli.test.ts 专门验证“brew-prefix 探测必须受 SIGKILL 超时约束而 install/restart/sudo 写文件等长步骤保持无超时”。配置文件discovery.wideArea与 zone 的生成逻辑广域发现的核心开关是运行时配置里的discovery.wideArea.domain配置参考{ discovery: { wideArea: { domain: openclaw.internal }, }, }设置该域名即启用广域发现Gateway 会把单播 DNS-SD zone 写入~/.openclaw/dns/目录。若再配合 DNS 服务器推荐 CoreDNS Tailscale Split DNS即可实现跨网络发现官方给出的落地命令正是openclaw dns setup --apply。zone 文件的真实生成逻辑位于 widearea-dns.ts 的renderZone/writeWideAreaGatewayZonezone 文件名由域名推导如openclaw.internal→openclaw.internal.db且强制校验路径必须落在 DNS 配置目录内assertZonePathUnderDnsDirzone 内容包含 SOAserial 按 RFC 1982 只允许小于一半序列号空间的增量推进见nextSerial、NS、ns1 A/AAAA、主机 A/AAAA 记录关键的服务发现记录与组播 Bonjour beacon 保持一致_openclaw-gw._tcp IN PTR instance._openclaw-gw._tcp instance._openclaw-gw._tcp IN SRV 0 0 18789 host instance._openclaw-gw._tcp IN TXT displayName... rolegateway transportgateway gatewayPort18789 ...TXT 记录随配置动态增减TLS 启用时加入gatewayTls1与gatewayTlsSha256...discovery.mdns.modefull时加入sshPort、cliPath存在 MagicDNS 时加入tailnetDns提示与 discovery.mdns 配置 的语义一一对应。TXT 记录属于非敏感提示role、transport、displayName 等客户端应只把它们当作 UX 提示真正的路由应优先采用解析出的 SRV A/AAAA 端点。写入采用原子替换replaceWideAreaZoneFile目录权限 0700、文件 0644、同步临时文件与父目录并通过内容 hashopenclaw-content-hash:注释 serial 的配合实现“内容未变不写盘、内容变化才推进 serial”的幂等更新避免 zone 无谓抖动与 Secondary 无谓重传。与其他发现通道的关系组播 Bonjour由内置bonjour插件承担openclaw plugins enable bonjour可手动开启macOS 上默认自启Linux/Windows/容器环境需显式启用。discovery.mdns.mode控制广播内容minimal/full/offOPENCLAW_DISABLE_BONJOUR1可强制关闭。广域 DNS-SD本文主题把同一套_openclaw-gw._tcpbeacon 通过单播 DNS 广播出去覆盖跨网络场景。Tailscale MagicDNS / tailnet IP跨网络直连的推荐目标Gateway 检测到 Tailscale 时会在 beacon 中发布tailnetDns提示macOS 应用优先使用 MagicDNS 名称而非裸 tailnet IP以应对 tailnet IP 变动。SSH 兜底没有任何直连路由时的通用回退方案见 远程访问文档。常见问题与注意事项非 macOS 平台openclaw dns setup的规划模式可在任何平台运行但--apply目前仅支持 macOS其他平台可手工等价落地安装 CoreDNS、写 server 文件、引导 zone。必须先有 Tailscale--apply依赖本机 tailnet IP未检测到会直接报错请先确认 Tailscale 处于运行状态。域名合法性openclaw.internal这类自定义域名需通过 DNS 名校验非法输入会明确报错而不是静默回退。Gateway 必须写 zonedns setup --apply只是把 CoreDNS 服务与初始 zone 引导好真正的 beacon 记录由启用了discovery.wideArea.domain的 Gateway 写入~/.openclaw/dns/因此配置后需要重启 Gateway 生效。Split DNS 匹配Tailscale 管理后台设置 Split DNS 时Nameserver 填本机 tailnet IPv4Restrict to domain 填去掉末尾点的发现域名二者必须与--domain保持一致。相关文档CLI 参考Discovery and transportsBonjour discovery运行时配置discovery.wideArea源码dns-cli.ts、widearea-dns.ts、tailnet.ts测试dns-cli.test.ts、widearea-dns.test.ts【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考