1. 项目概述与核心价值最近在折腾一些需要全球访问的Web服务发现一个挺有意思的开源项目叫mduongvandinh/openclaw-cloudflare。乍一看名字可能有点摸不着头脑但说白了它就是一个帮你把本地服务通过 Cloudflare 的网络安全、稳定地暴露到公网的工具。对于开发者、运维或者任何想低成本、便捷地发布个人项目的人来说这玩意儿简直是“神器”。我自己用过不少内网穿透方案从早期的 Ngrok到后来的 FRP再到各种基于 VPS 自建的反向代理。它们各有优劣但痛点也很明显要么免费版有限制流量、带宽、域名要么自己维护 VPS 成本高且麻烦。openclaw-cloudflare的思路就很巧妙它利用了 Cloudflare Tunnel以前叫 Argo Tunnel的能力。Cloudflare 大家都不陌生全球 CDN 节点多网络质量好而且它家的 Tunnel 服务有一个巨大的优势你的服务源站 IP 对公网是完全隐藏的。这意味着什么意味着你不用担心 DDoS 直接打到你家里脆弱的宽带 IP 上也省去了在路由器上做端口转发、配置 DDNS 等一系列繁琐操作。openclaw-cloudflare项目就是把这个能力封装得更易用提供了一套 Docker 化的部署方案和 Web 管理界面让你点点鼠标就能搞定。这个项目适合谁呢首先肯定是个人开发者你想把本地开发的 Web 应用临时展示给客户或朋友看用它最方便。其次是拥有 NAS 或家庭服务器的玩家想安全地远程访问 Jellyfin、Nextcloud、Home Assistant 这些服务又不想把家庭网络完全暴露。最后一些小团队用于内部测试环境的临时外部访问也是极好的选择。它的核心价值在于零成本利用 Cloudflare 免费额度、高安全源站隐身、易操作Docker 一键部署。接下来我就带你彻底拆解这个项目从原理到实操再到避坑指南让你也能轻松玩转。2. 核心原理与架构拆解要玩转openclaw-cloudflare不能只停留在“会用”的层面得先搞清楚它底层到底是怎么工作的。这有助于你在出问题时快速定位也能让你明白它的能力边界在哪里。2.1 Cloudflare Tunnel 是如何工作的传统的网络暴露方式是“由外向内”打洞。你在公网有一个固定 IP或通过 DDNS 解析的动态 IP然后在路由器上设置端口转发将公网 IP 的某个端口比如 80映射到内网服务器的对应端口。这种方式下你的服务器 IP 和端口是直接暴露在公网上的。Cloudflare Tunnel 则反其道而行之采用“由内向外”建立连接。你需要在你的源服务器也就是你想暴露的机器上运行一个轻量级的守护进程叫做cloudflared。这个进程会主动出站与 Cloudflare 全球边缘网络建立一条加密的、持续的 TCP 连接即 Tunnel。由于是主动向外连接所以你的服务器根本不需要有公网 IP也不需要配置任何入站防火墙规则或端口转发。当用户访问你的服务时比如your-app.example.comDNS 会解析到 Cloudflare 的任播 IP。用户的请求到达 Cloudflare 边缘节点后节点会通过之前建立好的那条加密 Tunnel将请求转发给你本地的cloudflared守护进程再由它转发给本地具体的服务比如运行在localhost:8080的 Web 应用。整个过程中用户的流量从未直接触及你的源站源站 IP 得到了完美隐藏。2.2 OpenClaw 在其中扮演的角色openclaw-cloudflare项目本身并不是 Cloudflare Tunnel 的替代品而是一个“Tunnel 编排与管理平台”。它主要做了以下几件事封装与简化它将cloudflared的配置、认证、运行过程全部 Docker 化。你不需要手动去 Cloudflare 面板创建 Tunnel、下载证书也不需要记忆复杂的命令行参数。OpenClaw 通过一个 Web 界面让你以填表单的方式完成所有配置。多服务管理你可以在一个 OpenClaw 实例中创建和管理多个 Tunnel每个 Tunnel 可以代理一个或多个本地服务。这对于需要暴露多个不同端口应用的情况非常方便。提供 Web 管理界面这是最大的亮点。所有操作包括 Tunnel 的创建、启动、停止、删除以及查看日志都可以在一个简洁的 Web UI 中完成大大降低了使用门槛。持久化与高可用通过 Docker Compose 部署它将配置、认证信息等持久化在宿主机上。即使容器重启你的 Tunnel 配置也不会丢失。理论上你也可以配置多个 OpenClaw 实例来实现管理界面的高可用虽然通常单实例足够。所以整个架构可以这样理解OpenClawDocker 容器 作为控制平面负责管理和配置cloudflared数据平面。cloudflared才是真正与 Cloudflare 建立连接并转发流量的那个“苦力”。2.3 为什么选择这个方案优势与考量选择openclaw-cloudflare方案你需要权衡它的优势和潜在的限制。核心优势极致的安全源站 IP 隐藏攻击面大幅减小。所有流量经过 Cloudflare可以免费享受其基础的 DDoS 防护和 SSL/TLS 加密。无视网络环境无论你的服务器是在公司 NAT 后、家庭宽带下甚至是移动热点后面只要它能访问互联网就能建立 Tunnel。零成本公网 IP/域名你不需要购买公网 IP甚至可以利用 Cloudflare 提供的免费.workers.dev子域名虽然自定义域名体验更好。管理便捷Web UI 操作对不熟悉命令行的用户非常友好。基于 Docker部署简单环境隔离不影响宿主机其他服务。需要注意的考量依赖 Cloudflare你的服务可用性部分依赖于 Cloudflare。虽然 Cloudflare 非常可靠但这毕竟是一个第三方服务。免费额度限制Cloudflare Tunnel 免费套餐有并发连接数和流量限制。对于个人或小规模使用完全足够但大流量场景需要关注。网络延迟流量需要绕道 Cloudflare 边缘节点可能会增加一点延迟。对于绝大多数 Web 应用来说感知不强但对实时性要求极高的场景如游戏串流可能不合适。无法暴露原始 TCP/UDPCloudflare Tunnel 主要设计用于 HTTP/HTTPS 和部分 TCP 应用通过“网络”模式。对于需要原始 TCP/UDP 协议的服务如某些游戏服务器、自定义协议可能需要搭配其他方案。注意使用 Cloudflare Tunnel 代理的流量如果源站是 HTTP 服务Cloudflare 会默认强制升级为 HTTPS 访问。如果你的本地服务是 HTTP且没有做相应处理可能会遇到重定向循环等问题。通常的解决方案是在本地服务前加一个反向代理如 Nginx来处理 SSL 终结或者确保你的应用能正确处理X-Forwarded-Proto这样的头部。3. 环境准备与部署实战理论讲完了我们动手把它跑起来。整个过程就像搭积木一步步来非常清晰。3.1 前置条件检查在开始之前请确保你满足以下条件一台能运行 Docker 的服务器可以是你的本地开发机Windows/macOS/Linux、家里的 NAS如群晖、威联通、树莓派或者一台云服务器。本文以 Linux 服务器如 Ubuntu 22.04为例。安装 Docker 和 Docker Compose这是必须的。如果你的系统还没有可以快速安装# Ubuntu/Debian 示例 sudo apt update sudo apt install docker.io docker-compose -y # 将当前用户加入 docker 组避免每次 sudo sudo usermod -aG docker $USER # 退出终端重新登录生效一个 Cloudflare 账户去 www.cloudflare.com 免费注册一个。一个属于自己的域名推荐你需要将域名的 DNS 解析托管到 Cloudflare。这步不是绝对必须你可以用 Cloudflare 提供的xxx.trycloudflare.com域名但自定义域名更专业、易记。在 Cloudflare 面板添加你的域名并按照指引将其 NS 服务器修改为 Cloudflare 提供的地址。3.2 获取 Cloudflare API 令牌这是 OpenClaw 能与你的 Cloudflare 账户对话、自动创建和管理 Tunnel 的“钥匙”。安全性很高务必妥善保管。登录 Cloudflare 仪表板进入你的域名。在左侧菜单栏找到“我的个人资料”右上角头像下拉菜单里也有然后进入“API 令牌”页面。点击“创建令牌”。我们不需要全权限令牌为了安全使用自定义模板。点击“创建自定义令牌”。给令牌起个名字比如OpenClaw-Tunnel-Manager。权限设置是关键需要精细配置账户权限Cloudflare Tunnel-编辑区域权限DNS-编辑用于自动创建 DNS 记录区域权限区域-编辑可能需要用于更广泛的区域设置资源范围选择“包括”“所有资源”或指定你的账户和域名。继续到“摘要”页面确认无误后点击“创建令牌”。重要令牌只会显示一次请立即复制并保存到安全的地方如密码管理器。关闭页面后就再也看不到了。3.3 部署 OpenClaw 服务现在开始部署主角。我们使用 Docker Compose 方式这是最清晰、易于管理的方式。创建项目目录并编写docker-compose.ymlmkdir openclaw-cloudflare cd openclaw-cloudflare nano docker-compose.yml将以下内容粘贴进去并根据注释修改version: 3.8 services: openclaw: image: ghcr.io/mduongvandinh/openclaw-cloudflare:latest container_name: openclaw restart: unless-stopped ports: - 3000:3000 # Web 管理界面端口可以按需修改宿主机端口 environment: - TZAsia/Shanghai # 设置容器时区 - CF_API_TOKENYOUR_CF_API_TOKEN_HERE # 替换为你的 Cloudflare API 令牌 - CF_ACCOUNT_IDYOUR_CF_ACCOUNT_ID_HERE # 替换为你的 Cloudflare 账户 ID volumes: - ./data:/app/data # 持久化存储配置和隧道数据 networks: - openclaw-network networks: openclaw-network: driver: bridgeCF_API_TOKEN: 替换为上一步你保存的令牌。CF_ACCOUNT_ID: 在你的 Cloudflare 仪表板首页右侧就能找到“账户 ID”。ports:3000:3000表示将容器的 3000 端口映射到宿主机的 3000 端口。如果你宿主机 3000 端口已被占用比如跑了另一个 Node.js 应用可以改成8080:3000这样通过宿主机8080端口访问管理界面。启动服务docker-compose up -d这个命令会拉取镜像并在后台运行容器。第一次运行会下载镜像稍等片刻。检查服务状态docker-compose logs -f openclaw如果看到类似Server is running on port 3000的日志说明服务启动成功。按CtrlC退出日志查看。3.4 初始化配置与访问管理界面打开浏览器访问http://你的服务器IP:3000。如果你在本地部署就是http://localhost:3000。首次访问可能会有一个简单的初始化设置页面或者直接进入登录/注册。根据 OpenClaw 项目的具体版本可能需要创建一个管理员账户。请参考项目 README 的最新说明。通常流程是设置一个用户名和密码。登录成功后你应该能看到 OpenClaw 的 Web 管理仪表板。界面通常比较简洁主要功能包括 Tunnel 列表、创建新 Tunnel、查看日志等。实操心得在docker-compose.yml中我们把./data目录挂载到了容器的/app/data。这是一个非常好的习惯所有关键的配置、Cloudflare 的认证文件 (cert.pem) 都会保存在宿主机的./data目录下。务必定期备份这个目录。以后如果需要迁移服务器只需要把这个data目录拷贝到新服务器重新docker-compose up -d所有的 Tunnel 配置都能恢复无需重新在 Cloudflare 面板操作。4. 创建并配置你的第一个 Tunnel管理界面跑起来了现在我们来创建第一个 Tunnel把本地的一个服务暴露出去。4.1 在 OpenClaw 中创建 Tunnel在 OpenClaw 仪表板找到类似“创建隧道”、“New Tunnel”或“”的按钮并点击。输入一个隧道名称例如my-first-tunnel。这个名字会用于在 Cloudflare 面板中标识这个隧道也会作为生成证书文件名的依据。点击创建。OpenClaw 会在后台调用 Cloudflare API在你的账户下创建一个新的 Tunnel并自动下载连接所需的凭证 (cert.pem)。这个过程在 UI 上通常很快完成后隧道会出现在列表中状态可能是“未连接”或“离线”。4.2 配置隧道指向本地服务创建好隧道实体后需要给它添加“路由”即告诉 Cloudflare当用户访问某个域名时把流量通过这个隧道转发到我本地的哪个服务。在隧道列表中找到你刚创建的隧道点击进入详情或配置页面。寻找添加“公共主机名”或“Public Hostname”的选项。配置路由规则子域名/域名例如你想通过app.yourdomain.com访问。这里就填app。你的域名yourdomain.com需要在 Cloudflare DNS 中已托管。域名选择你托管在 Cloudflare 上的主域名例如yourdomain.com。服务类型选择HTTP或HTTPS。URL这是最关键的一步。填写你本地服务监听的地址。这里有个非常重要的概念这个 URL 是从cloudflared容器内部去访问你的服务的地址。如果你的服务运行在宿主机上比如宿主机跑了一个python -m http.server 8080你不能直接填http://localhost:8080因为localhost在容器内指的是容器自己。你需要使用 Docker 的特殊主机名host.docker.internalmacOS/Windows Docker Desktop 支持或宿主机的实际内网 IP如http://192.168.1.100:8080。对于 Linux 原生 Docker更通用的方式是使用http://172.17.0.1:8080Docker 默认网桥网关或创建共享网络。最佳实践将你的应用也 Docker 化并与 OpenClaw 容器放在同一个自定义 Docker 网络中。这样你就可以直接使用容器名作为主机名。例如如果你有一个名为my-web-app的容器监听 80 端口那么这里就可以填http://my-web-app:80。我们接下来会演示这种方式。点击保存或应用。OpenClaw 会同时做两件事在 Cloudflare 上配置这条路由规则并尝试启动隧道连接器Connector。4.3 验证与测试回到隧道列表查看你隧道状态。如果配置正确几十秒内状态应该会变为“活跃”或“在线”。同时打开你的 Cloudflare 仪表板进入“网络”-“隧道”你应该能看到一个同名的隧道状态也是健康的。在“DNS”记录页面你会发现 OpenClaw 已经自动为你创建了一条 DNS 记录例如app.yourdomain.com指向的是{tunnel-id}.cfargotunnel.com这种 CNAME 记录。这就是 Cloudflare Tunnel 的魔力它不需要 A 记录指向你的 IP。最后打开浏览器访问https://app.yourdomain.com。如果一切顺利你应该就能看到运行在你本地服务器的服务页面了注意事项首次访问可能会看到 Cloudflare 的“检查站点连接”页面稍等几秒即可。这是因为 Tunnel 正在建立连接。另外确保你的本地服务确实在运行并且监听地址和端口与你在 OpenClaw 中配置的URL完全一致。防火墙也需要放行容器之间或容器到宿主机的通信。5. 高级配置与最佳实践掌握了基本用法后我们来看看如何用得更好、更稳。这部分是区分“能用”和“好用”的关键。5.1 使用 Docker 网络实现服务互通如前所述让 OpenClaw 的cloudflared访问宿主机上的服务有时会有点别扭。更优雅的方式是将所有服务OpenClaw 和你需要暴露的应用都放在一个用户自定义的 Docker 网络中。修改 OpenClaw 的docker-compose.yml使其连接到一个自定义网络并暴露网络给其他容器。实际上我们之前的配置已经创建了一个openclaw-network。我们需要确保其他应用容器也接入这个网络。# openclaw-cloudflare/docker-compose.yml version: 3.8 services: openclaw: image: ghcr.io/mduongvandinh/openclaw-cloudflare:latest container_name: openclaw restart: unless-stopped ports: - 3000:3000 environment: - TZAsia/Shanghai - CF_API_TOKENYOUR_CF_TOKEN - CF_ACCOUNT_IDYOUR_ACCOUNT_ID volumes: - ./data:/app/data networks: - openclaw-network # 连接到自定义网络 # 假设我们有一个简单的 Nginx 测试服务 my-web-app: image: nginx:alpine container_name: my-web-app restart: unless-stopped networks: - openclaw-network # 同样连接到这个网络 # 这个服务不需要映射端口到宿主机因为只通过 OpenClaw 访问 networks: openclaw-network: driver: bridge重新部署docker-compose down docker-compose up -d。在 OpenClaw 的隧道配置中URL就可以填写http://my-web-app:80。因为它们在同一个 Docker 网络中可以直接通过容器名进行服务发现。5.2 配置多个服务与路径路由一个 Tunnel 可以配置多个公共主机名指向不同的本地服务。但更酷的是你可以在一个主机名下通过路径来区分不同的后端服务。例如你想让https://services.yourdomain.com/app1指向容器app1让/app2指向容器app2。Cloudflare Tunnel 本身支持这种“路径路由”吗答案是原生的公共主机名配置通常只支持到子域名级别。要实现路径路由你有两个选择在 Cloudflare Tunnel 配置中使用“私有网络”模式并结合 Cloudflare Access这更适合企业内网应用配置更复杂。在本地使用一个反向代理如 Nginx、Traefik作为统一入口这是更通用和推荐的做法。架构如下部署一个 Nginx 容器也接入openclaw-network。在 Nginx 中配置根据路径 (/app1,/app2) 将请求代理到对应的后端服务容器。在 OpenClaw 中Tunnel 的URL只指向这个 Nginx 容器例如http://nginx-proxy:80。这样对外只有一个域名入口内部由 Nginx 负责路由。5.3 安全性增强建议虽然 Cloudflare Tunnel 已经提供了很好的源站隐藏但我们还可以做得更安全。使用 Cloudflare Access 保护服务Cloudflare Access 可以让你在 Tunnel 前再加一道身份验证墙。你可以设置只有登录了特定邮箱如公司邮箱、通过了特定认证方式如 GitHub、Google OAuth的用户才能访问你的服务。这对于暴露内部管理界面如 Portainer, Home Assistant特别有用。配置需要在 Cloudflare Zero Trust 面板中完成与 Tunnel 联动。限制 API 令牌权限我们之前创建的令牌权限是“账户-隧道-编辑”和“区域-DNS-编辑”。这已经是最小化权限了。切勿使用全局 API 密钥。定期更新与备份关注openclaw-cloudflare项目的更新及时获取安全补丁和新功能。定期备份./data目录。保护 OpenClaw 管理界面OpenClaw 的 Web 界面3000端口本身不应该暴露到公网。确保它只在内网访问或者通过 SSH 隧道访问。你也可以在 OpenClaw 前面再加一个简单的 HTTP 基础认证或者也通过一个 Cloudflare Tunnel Access 来保护它自己有点套娃但可行。5.4 性能与监控连接稳定性cloudflared连接一般非常稳定。如果遇到隧道频繁断开可以检查服务器本身的网络稳定性以及 Cloudflare 账户的免费额度是否超限。日志查看OpenClaw 的 Web 界面通常提供隧道日志查看功能。更底层的日志可以通过docker-compose logs -f openclaw查看。cloudflared的详细日志可以在./data目录下寻找或者通过 Docker 命令进入容器查看。资源占用openclaw-cloudflare和cloudflared进程资源占用都很低一般不会成为瓶颈。6. 常见问题排查与解决实录在实际使用中你可能会遇到一些问题。这里我整理了几个最常见的情况和排查思路帮你快速定位。6.1 隧道状态一直为“离线”或“不健康”这是最常遇到的问题。检查 API 令牌和账户 ID确认docker-compose.yml中的CF_API_TOKEN和CF_ACCOUNT_ID填写正确没有多余空格。令牌是否具有必要的权限可以尝试在 Cloudflare 面板手动创建一个 Tunnel看是否成功以排除账户级别问题。检查网络连通性确保运行 OpenClaw 的服务器可以正常访问互联网并且能连接到 Cloudflare 的 APIapi.cloudflare.com和 Tunnel 端点。可以尝试在容器内执行docker exec openclaw curl -v https://api.cloudflare.com测试。查看详细日志运行docker-compose logs --tail100 openclaw查看最近日志。关注是否有明显的错误信息如“认证失败”、“权限不足”、“网络错误”等。检查数据卷权限确保宿主机上的./data目录对于 Docker 容器是可写的。有时权限问题会导致cert.pem证书文件无法生成或读取。可以尝试sudo chmod -R 755 ./data注意安全风险或检查目录所有者。重启隧道在 OpenClaw UI 上尝试停止再启动隧道。有时连接需要重新握手。6.2 能访问域名但显示 Cloudflare 错误页面如 502、503这说明 Tunnel 连接可能是正常的但流量无法到达你的本地服务。检查URL配置这是最大的嫌疑犯。确认你在 OpenClaw 中配置的URL地址从cloudflared容器的角度是可以访问的。如果指向宿主机服务在宿主机上执行curl http://localhost:你的端口测试服务本身是否正常。然后在 OpenClaw 容器内测试docker exec openclaw curl -v http://宿主机的内网IP:端口。如果失败说明网络不通需要检查 Docker 网络模式、宿主机防火墙如ufw,firewalld是否放行了来自 Docker 网桥的流量。如果指向其他容器在 OpenClaw 容器内执行docker exec openclaw curl -v http://容器名:端口测试。确保两个容器在同一个 Docker 网络中并且目标容器确实在运行并监听正确端口。检查本地服务是否运行确认你试图暴露的本地服务进程还在运行没有崩溃。检查端口冲突确保本地服务监听的端口没有被其他进程占用。查看cloudflared日志在 OpenClaw UI 的隧道详情页或通过 Docker 命令查看更详细的转发日志看是否有连接被拒绝 (connection refused) 或超时 (timeout) 的错误。6.3 访问域名时出现重定向循环或 HTTPS 错误这通常发生在你的本地服务是 HTTP但 Cloudflare 强制使用 HTTPS 访问时。理解问题用户通过https://访问Cloudflare 以 HTTPS 连接你的 Tunnel但你的本地服务是 HTTP并且可能配置了将 HTTP 重定向到 HTTPS 的逻辑比如很多 Web 框架的默认配置。这就导致了循环。解决方案方案A推荐在本地服务前部署一个反向代理如 Nginx。在反向代理上终结 SSL即配置 HTTPS 证书然后以 HTTP 协议向后端服务转发。这样从 Cloudflare 到你的反向代理是 HTTPS反向代理到应用是 HTTP应用本身无需处理 SSL。方案B修改你的本地应用配置使其在收到通过代理Cloudflare过来的请求时不强制重定向到 HTTPS。这通常涉及检查X-Forwarded-Proto头部。例如在 Node.js Express 中可以设置trust proxy。方案C在 Cloudflare Tunnel 配置中尝试将“服务类型”从HTTPS改为HTTP。但这可能会在浏览器端产生“不安全连接”警告不推荐。6.4 如何更新 OpenClaw 到新版本项目在持续更新修复 Bug 和增加新功能。拉取最新镜像cd /path/to/openclaw-cloudflare docker-compose pull openclaw重启服务docker-compose up -dDocker Compose 会自动用新镜像重新创建容器。由于你的配置和数据通过卷 (./data) 持久化所以升级过程是无损的。验证升级后访问 Web 管理界面检查隧道状态是否正常。6.5 如何迁移 OpenClaw 到另一台服务器迁移的关键在于持久化数据./data目录。在旧服务器上停止服务docker-compose down。将整个项目目录特别是./data子目录打包拷贝到新服务器。在新服务器上安装好 Docker 和 Docker Compose。确保新服务器的docker-compose.yml文件中的环境变量API Token, Account ID是正确的。在新服务器项目目录下启动服务docker-compose up -d。因为cert.pem等认证信息都在./data里隧道应该能自动重新连接无需在 Cloudflare 面板做任何操作。最后再分享一个我踩过的坑有一次部署后隧道始终连不上日志显示权限错误。排查了半天发现是因为我第一次运行docker-compose up时用了sudo导致./data目录的所有者是root。后来不用sudo直接运行容器进程非root用户就没有写入权限了。解决办法就是统一权限要么始终用sudo要么在第一次运行前就确保当前用户对目录有读写权并在docker-compose.yml中指定运行的用户通过user:指令。这个小细节对于生产环境的稳定运行其实很重要。