企业官网建设流程全解析

Claw3D 生产部署完全指南：Docker 打包、Tailscale 跨机组网与 SSH 隧道实战教程

【免费下载链接】Claw3DClaw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.项目地址: https://gitcode.com/gh_mirrors/cl/Claw3D

Claw3D 生产部署是把这座 3D 智能体办公室从开发环境搬上正式服务器的关键一步。Claw3D 是基于 OpenClaw 构建的开源 3D 引擎与可视化 Studio，用于创建游戏、仿真和高性能 3D 应用。本文手把手带你完成三种主流上线方案：Docker 镜像部署、Tailscale 跨机安全组网、SSH 隧道远程连接，并附上故障排查与安全清单。

部署前必知：Claw3D 的两段式连接模型

理解连接模型，是部署不踩坑的前提。Claw3D 与后端的通信分为两跳：

1. 浏览器 → Studio：走 HTTP 和同源 WebSocket（/api/gateway/ws）
2. Studio → OpenClaw Gateway：由 Studio 自定义服务器发起第二条 WebSocket

这意味着ws://localhost:18789永远指Studio 所在机器能到达的网关，而不是浏览器的。相关实现可参考 server/index.js 中的代理逻辑。

💡 记住这个模型，后面所有方案本质上只是"让 Studio 主机能到达 Gateway"的不同手段。

方案一：Docker 部署 Claw3D 生产镜像

项目自带多阶段构建的 Dockerfile，结构非常清晰：

构建与运行步骤

git clone https://gitcode.com/gh_mirrors/cl/Claw3D cd Claw3D docker build -t claw3d:prod . docker run -d --name claw3d -p 3000:3000 \ -e CLAW3D_GATEWAY_URL=ws://127.0.0.1:18789 \ -e CLAW3D_GATEWAY_TOKEN=你的令牌 \ claw3d:prod

三个环境变量值得重点关注（完整清单见 .env.example）：

• CLAW3D_GATEWAY_URL/CLAW3D_GATEWAY_TOKEN：运行时生效的网关地址与令牌，重启即改，无需重新构建。注意别和构建期的NEXT_PUBLIC_GATEWAY_URL混淆——后者改了要重新npm run build才生效。
• CLAW3D_GATEWAY_ADAPTER_TYPE：标记后端类型，可选openclaw、hermes、demo、custom。

Docker 场景下的一个高频坑：容器内的localhost不是宿主机。若 Gateway 跑在宿主机上，Linux 请用ws://host.docker.internal:18789（配合--add-host）或172.17.0.1。

方案二：Tailscale 跨机方案（推荐生产使用）

这是官方 TUTORIAL.md 中最推荐的生产架构：

机器 A（Gateway 主机） 机器 B（Claw3D 主机） OpenClaw Gateway 127.0.0.1:18789 Claw3D Studio :3000 └──────── Tailscale tailnet 私有网络 ────────┘

一键安装 Tailscale 到两台机器

两台机器分别执行tailscale up加入同一 tailnet，然后用tailscale status确认彼此可见。若 tailnet 开启了设备审批，需在管理后台先把两台设备都批准，否则互不可达。

用 Tailscale Serve 暴露 Gateway

Gateway 保持绑定回环地址（127.0.0.1:18789）不变，只通过 Serve 发布：

tailscale serve --yes --bg --https=443 http://127.0.0.1:18789 tailscale serve status

这样 Gateway 获得一个https://<gateway主机>.<tailnet>.ts.net的私有 HTTPS 地址，无需在公网开放任何端口。另一种写法是openclaw gateway --tailscale serve，让 OpenClaw 自行托管 Tailscale 模式。

在 Claw3D 中填写连接

1. Gateway URL 填wss://<gateway主机>.<tailnet>.ts.net（注意是wss://）
2. 粘贴机器 A 上openclaw config get gateway.auth.token拿到的令牌
3. 点击 Connect

首次连接：设备配对审批（最容易被漏掉）

首次连接后，请到机器 A 批准设备配对：

openclaw devices list openclaw devices approve --latest

⚠️ 审批是按浏览器/设备生效的，换台浏览器再连可能还要批准一次。

方案三：SSH 隧道打通远程 Gateway

没有 Tailscale 或只是临时调试时，一条 SSH 隧道就够了。它的原理是把远程机器的18789端口映射到本地：

ssh -L 18789:127.0.0.1:18789 user@<gateway主机>

隧道建立后，在 Claw3D 中直接填ws://localhost:18789即可——对 Studio 来说，远程网关就"住"在了本地回环地址上。

两种方案的取舍：

注意协议匹配：HTTPS 端点必须用wss://，裸ws://端点不能反着用，否则会报EPROTO / wrong version number。

连接验证与常见故障排查

部署完成后按顺序核对（与 TUTORIAL.md 验证清单一致）：

1. 机器 A 上openclaw gateway status显示健康
2. 两台机器tailscale status显示已连入同一 tailnet
3. 机器 A 上tailscale serve status显示 443 → 18789 的转发
4. Claw3D 连接界面使用wss://...ts.net+ 有效令牌
5. 首次连接后已执行openclaw devices approve --latest

如果还是连不上，推荐运行项目内置的诊断工具 scripts/claw3doctor.mjs，它会自动识别 Tailscale、隧道等端点特征并给出针对性建议。高频问题速查：

生产环境安全清单 🛡️

结合 SECURITY.md 的加固建议，上线前请逐项确认：

• ✅Gateway 始终绑定回环地址，除非有明确理由才对外暴露
• ✅ Studio 一旦绑定公网/局域网地址，必须设置STUDIO_ACCESS_TOKEN访问令牌
• ✅ 生产环境配置UPSTREAM_ALLOWLIST，限制 Studio 可代理的网关主机
• ✅ 令牌不要提交进 git 或可共享的.env文件
• ✅ 优先 Tailscale Serve，避免裸端口直接暴露
• ✅ 把设备配对审批当作安全闸门，而不是麻烦

写在最后

三种方案覆盖了绝大多数场景：单机生产用 Docker，跨机长期运行用 Tailscale，临时接入用 SSH 隧道。部署完成后，打开浏览器就能看到你部署的智能体团队在 3D 办公室里各司其职。更多远程组网细节可阅读 docs/multi-agent-beta.md，本地一键启动开发环境则可以用 scripts/clawd3d-start.sh 脚本。祝部署顺利！🚀

【免费下载链接】Claw3DClaw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.项目地址: https://gitcode.com/gh_mirrors/cl/Claw3D