1. 项目概述RunClawd一个开箱即用的OpenClaw部署方案如果你正在寻找一个能快速、稳定地将OpenClaw——那个功能强大的AI智能体平台——部署到生产环境的方法并且对Docker Compose和Linux运维有一定了解那么RunClawd这个项目很可能就是你需要的“一站式”解决方案。简单来说RunClawd不是一个全新的软件而是一个经过精心编排和加固的Docker Compose预设仓库。它把OpenClaw及其所有依赖的服务如反向代理、Web终端、文件管理器、无头浏览器服务打包在一起提供了一个“固执己见”但面向生产的部署模板。这意味着你不用再手动去拼接各个组件、配置网络、处理权限和安全问题RunClawd已经为你预设好了一套经过验证的最佳实践。这个方案的核心价值在于“开箱即用”和“生产就绪”。你不需要从零开始研究OpenClaw的每一个配置项RunClawd已经帮你做好了选择比如使用Caddy作为统一的反向代理和基础认证网关通过Cloudflare Tunnel安全地暴露服务以及使用Docker Socket Proxy来限制容器对宿主机Docker API的访问权限这些都是提升安全性和可维护性的关键设计。对于个人开发者、小团队或是想快速搭建一个私有AI助手环境的用户来说它能极大降低部署门槛和后续的运维成本。接下来我会带你深入拆解这个项目的设计思路、每一个核心组件的职责并分享从安装、配置到日常运维的全流程实操经验以及我踩过的一些坑和对应的解决方案。2. 核心架构与设计思路拆解2.1 为什么选择Docker Compose作为部署基石RunClawd选择Docker Compose作为核心部署工具这背后有非常务实的考量。OpenClaw本身是一个Node.js应用但它运行时可能依赖Python环境、系统工具、浏览器实例等直接进行宿主机安装会面临依赖冲突、环境隔离和版本管理难题。Docker Compose通过容器化技术将OpenClaw、Caddy、Cloudflared、ttyd、CloudCmd、Browserless等服务分别封装在独立的容器中并通过定义好的网络和卷进行连接。这样做最大的好处是环境隔离与一致性无论在Ubuntu、CentOS还是Alpine上只要Docker能跑RunClawd就能以完全相同的方式运行彻底杜绝了“在我机器上是好的”这类问题。其次服务编排与依赖管理变得极其清晰。docker-compose.yaml文件就是整个架构的蓝图它明确定义了哪个服务先启动depends_on服务之间如何通信自定义网络配置文件如何挂载volumes以及资源限制mem_limit。例如RunClawd容器需要等待Caddy就绪后才能完全启动这种依赖关系在Compose文件中可以轻松表达。最后简化了运维操作。启动、停止、重启、查看日志、升级整个应用栈都只需要简单的docker compose命令无需记忆复杂的系统服务命令或手动管理进程。2.2 安全第一的设计哲学从网络到权限的层层设防RunClawd在易用性上没有牺牲安全性其架构体现了“最小权限原则”和“纵深防御”的思想。我们逐层来看网络隔离层所有服务运行在一个自定义的Docker网络默认名为runclawd_default内部。这意味着除了明确映射到宿主机的端口如Caddy的80/443服务无法直接从外部网络访问。像CloudCmd文件管理器、Browserless Chrome服务这些辅助组件根本没有绑定宿主端口只能通过内部网络被Caddy访问。API代理层关键安全加固这是RunClawd一个非常巧妙的设计。通常容器内应用如果需要管理Docker例如启动新的任务容器需要挂载宿主机的Docker Socket/var/run/docker.sock。直接挂载等同于赋予容器内应用与root几乎等同的权限风险极高。RunClawd引入了docker-proxy即docker-socket-proxy容器。这个容器唯一的作用就是以只读或受限模式暴露Docker API。在docker-compose.yaml中runclawd服务通过环境变量DOCKER_HOSTtcp://docker-proxy:2375连接到这个代理而不是直接的socket。代理容器通过配置如DOCKERSOCKETPROXY_GET_ONLYtrue可以严格限制允许的API操作例如只允许GET请求、只允许操作特定标签的容器从而将潜在的攻击面降到最低。访问控制层网关令牌OpenClaw Gateway自身需要令牌Token才能访问这个令牌在首次启动时由scripts/bootstrap.sh生成并持久化。HTTP基础认证Caddy作为入口为所有路由/,/term/*,/openclaw/*,/explorer/*,/browserless/*加上了HTTP Basic Auth。用户名固定为runclawd密码在安装时随机生成并显示。这构成了第二道防线即使隧道URL意外泄露没有密码也无法进入。设备审批OpenClaw本身还有一层设备级安全机制新设备首次连接需要管理员在命令行或Web终端中手动批准openclaw devices approve。这防止了未授权的客户端直接接入。配置加固层关键配置文件以只读ro模式挂载到容器中例如./Caddyfile:/etc/caddy/Caddyfile:ro。这防止了运行时应用被篡改后反过来修改配置文件的攻击路径。2.3 服务网格解析每个容器扮演什么角色理解了安全设计我们再看看这个“服务网格”里每个节点具体做什么runclawd(核心)这是OpenClaw主服务的容器。它开放了两个主要端口18789用于Gateway API和UI7681内嵌了ttyd提供Web终端。所有AI智能体的逻辑、会话、技能插件都在这里运行。caddy(入口网关)现代、自动化的HTTP/2 Web服务器。它的角色至关重要反向代理根据Caddyfile将外部请求路由到内部正确的服务。TLS终结如果配置了自定义域名并提供了证书Caddy可以自动处理HTTPS。基础认证为所有路由提供统一的用户名/密码保护。静态文件服务服务于一些前端资源。cloudflared(隧道客户端)可选服务。默认以“快速隧道”模式运行创建一个临时的*.trycloudflare.com域名并将流量安全地隧道回你本地的Caddy服务。这完美解决了家庭宽带没有公网IP、80/443端口被封的问题是内网穿透最省心的方案之一。你也可以配置为使用Named Tunnel命名隧道连接到自己Cloudflare账户下的域名。explorer(文件管理)即CloudCmd容器。它被挂载了runclawd-data和browserless-data两个数据卷让你能通过Web界面/explorer/直观地管理OpenClaw的配置文件、工作空间以及Browserless产生的用户数据非常方便进行调试和文件操作。browserless(无头浏览器)一个作为服务运行的Headless Chrome。许多AI智能体技能如网页抓取、自动化测试、截图需要浏览器环境。通过集成Browserlessrunclawd中的技能可以远程调用这个服务而不需要在每个容器内都安装一个庞大的Chrome节省资源且便于管理。docker-proxy(安全代理)如前所述安全地暴露有限的Docker API给runclawd容器使用。这种架构清晰地将业务逻辑runclawd、网络接入caddy/cloudflared、辅助服务explorer/browserless和安全组件docker-proxy解耦使得每个部分都可以独立升级、扩展或替换。3. 从零到一的完整部署与配置实操3.1 环境准备与一键安装的幕后RunClawd宣称支持多种Linux发行版通过apt/dnf/yum/apk/pacman/zypper这得益于其安装脚本get-runclawd.sh的智能判断。我们来看看执行那一条“魔法命令”时背后到底发生了什么curl -fsSL https://get.runclawd.sh -o get-runclawd.sh sudo bash get-runclawd.sh步骤拆解与原理依赖检测与安装脚本首先会检测系统类型然后使用对应的包管理器安装curl,git,ssh等基础工具。这些是运行后续命令和克隆仓库所必需的。Docker引擎安装如果系统未安装Docker脚本会调用官方的https://get.docker.com安装脚本。这是最可靠的方式能确保安装正确版本并启动Docker服务。代码拉取将RunClawd的Git仓库克隆或更新到/opt/runclawd目录。/opt是存放第三方应用程序的标准位置选择这里便于集中管理。环境准备与启动进入目录直接执行docker compose up -d。这里隐含了一个关键点Docker Compose会自动加载同目录下的.env文件来设置环境变量。首次运行时如果缺少必要的环境变量如API密钥服务可能无法完全正常工作但基础架构Caddy、隧道会先跑起来。信息输出脚本会等待一段时间然后从容器日志中抓取并打印出访问令牌Access Token、基础认证密码Basic Auth Password以及Cloudflare临时隧道URL。这是你首次访问系统的唯一凭证务必妥善保存。实操心得网络与权限网络问题如果服务器在国内从Docker Hub拉取镜像可能会非常慢甚至失败。建议先配置Docker镜像加速器。可以在运行安装脚本前在/etc/docker/daemon.json中配置阿里云、腾讯云等镜像加速地址。Root权限脚本要求sudo因为它需要安装系统包、操作/opt目录、管理Docker服务。如果你在严格限制root的环境可能需要先由管理员安装好Docker然后以有Docker用户组权限的普通用户来运行脚本的--local模式前提是你能读写当前目录。--build标志如果你修改了项目内的Dockerfile或相关构建上下文需要使用--build参数来强制重建自定义镜像否则Docker会使用旧的缓存镜像。3.2 关键配置详解API密钥、隧道与自定义域名安装成功只是第一步让OpenClaw真正“智能”起来需要配置AI模型的API密钥。此外你可能不想用临时的Cloudflare隧道域名而是用自己的域名。1. 配置API密钥.env文件所有密钥都通过环境变量注入。最规范的做法是编辑/opt/runclawd/.env文件。Docker Compose会自动读取这个文件。# 切换到项目目录 cd /opt/runclawd # 复制示例环境文件如果不存在 cp .env.example .env # 编辑.env文件填入你的密钥 nano .env你的.env文件内容可能如下# OpenAI OPENAI_API_KEYsk-your-openai-key-here # Anthropic Claude ANTHROPIC_API_KEYyour-claude-key-here # Google Gemini GEMINI_API_KEYyour-gemini-key-here # 其他可选如DeepSeek, Moonshot等 DEEPSEEK_API_KEYyour-deepseek-key-here MOONSHOT_API_KEYyour-moonshot-key-here # 注意变量名必须与docker-compose.yaml中‘runclawd’服务下的‘environment’部分定义的名字完全一致。编辑保存后需要重启服务使配置生效docker compose down docker compose up -d2. 配置自定义域名与永久Cloudflare隧道默认的trycloudflare.com域名是临时的不适合长期使用。以下是配置自己域名的步骤前提你有一个域名并且其DNS托管在Cloudflare上。步骤在Cloudflare Zero Trust面板中创建一条隧道Access - Tunnels - Create a tunnel。记录下生成的隧道令牌Tunnel Token它是一长串字符串。在你的服务器上设置两个环境变量export CF_TUNNEL_TOKEN你的隧道令牌 export SERVICE_FQDN_OPENCLAWopenclaw.yourdomain.com # 你想使用的子域名使用--preserve-env参数运行安装脚本以确保环境变量传递给sudo环境sudo --preserve-envCF_TUNNEL_TOKEN,SERVICE_FQDN_OPENCLAW bash get-runclawd.sh或者更持久的方法是直接将这两个变量写入/opt/runclawd/.env文件末尾这样每次重启都会生效。安装脚本检测到CF_TUNNEL_TOKEN存在时会自动应用docker-compose.tunnel.yaml这个覆盖配置该配置会使用你提供的令牌运行cloudflared并尝试为SERVICE_FQDN_OPENCLAW配置DNS记录。注意事项域名与DNS确保SERVICE_FQDN_OPENCLAW的DNS记录在Cloudflare上已经被代理橙色云状态。通常隧道客户端会自动创建CNAME记录但最好检查一下。使用自定义域名后Caddy可能仍然使用HTTP。如果你希望Caddy也启用HTTPS在隧道之后再做一次加密即“隧道-TLS”你需要在Caddyfile中为你的域名配置TLS或者依赖Cloudflare的“SSL/TLS加密模式”设置为“Full”或“Full (strict)”由Cloudflare边缘节点提供HTTPS。3.3 首次访问与设备审批流程安装并配置完成后通过安装脚本输出的URL和密码进行访问。流程如下打开Onboarding链接访问你的隧道URL/openclaw/?argonboard。你会先遇到Caddy的HTTP Basic Auth弹窗输入用户名runclawd和脚本给出的密码。完成初始设置按照OpenClaw的网页引导完成初始配置比如选择主要语言模型、连接通信工具如飞书、Telegram机器人等。这部分是OpenClaw应用自身的流程。访问主面板并批准设备完成Onboarding后访问你的隧道URL/?token你的访问令牌进入Gateway主界面。但此时你很可能看不到任何内容或无法操作。这是因为新设备你当前使用的浏览器需要被批准。执行设备批准方法一通过Web终端访问你的隧道URL/term/再次输入基础认证密码后会进入一个在runclawd容器内的Web Shell。直接执行openclaw devices list找到状态为Pending的请求复制其Request列的UUID然后执行openclaw devices approve 复制的UUID方法二通过宿主机SSH如果你能SSH到服务器可以进入项目目录执行docker compose exec runclawd openclaw devices list docker compose exec runclawd openclaw devices approve UUID刷新页面批准设备后刷新Gateway页面你应该就能正常看到界面并开始使用了。这个设备审批机制是OpenClaw安全模型的一部分确保只有受信任的设备可以连接网关在生产环境中非常有必要。4. 日常运维、监控与故障排查指南4.1 常规运维操作命令汇总一旦系统运行起来以下命令会成为你的日常操作命令说明查看日志docker compose logs -f runclawd实时跟踪OpenClaw主服务日志-f代表follow。查看所有日志docker compose logs -f查看所有服务的复合日志。启动服务docker compose up -d在后台启动所有服务。停止服务docker compose stop停止所有服务不删除容器。停止并清理docker compose down停止并移除所有容器、网络保留卷。重启单个服务docker compose restart runclawd仅重启OpenClaw容器。进入容器Shelldocker compose exec runclawd sh进入runclawd容器的命令行用于调试。更新代码git pull origin main在/opt/runclawd目录下拉取最新代码。更新后重启docker compose up -d --build拉取代码后重建镜像并重启如果Dockerfile有变。检查服务状态docker compose ps查看所有服务的运行状态和端口映射。4.2 数据备份与恢复策略RunClawd的核心数据OpenClaw配置、状态、工作空间、历史记录都保存在名为runclawd-data的Docker卷中。定期备份至关重要。手动备份项目提供了便捷的备份脚本cd /opt/runclawd bash scripts/backup-volume.sh这个脚本默认会备份runclawd-data卷到/opt/backups/runclawd/目录下生成一个带时间戳的.tgz压缩包。自动备份使用Cron生产环境必须配置自动备份。你可以手动添加cron任务也可以使用项目提供的安装脚本cd /opt/runclawd # 使用默认设置每天凌晨3:30备份保留14天 bash scripts/backup-cron-install.sh # 或自定义每6小时备份一次保留30天 bash scripts/backup-cron-install.sh --schedule 0 */6 * * * --retention-days 30这个脚本会以idempotent幂等的方式在root用户的crontab中添加或更新一条备份任务非常方便。从备份恢复恢复数据前务必先停止相关服务以免数据损坏。cd /opt/runclawd docker compose stop runclawd bash scripts/restore-volume.sh --backup-file /opt/backups/runclawd/runclawd-data-2023-10-27_030001.tgz docker compose up -d恢复脚本会解压备份包将数据还原到指定的卷中。实操心得备份的细节备份内容runclawd-data卷包含了~/.openclaw目录配置、记忆、会话和/workspace目录项目文件。Browserless的数据在另一个卷browserless-data如果你需要保留浏览器配置文件也应定期备份。恢复测试定期演练恢复流程在一个测试环境中尝试从备份恢复确保备份是有效的。最糟糕的备份就是从未测试过恢复的备份。异地备份/opt/backups/目录仍在同一台服务器上。应考虑使用rclone、scp或云存储CLI工具将备份包同步到另一台机器或对象存储如S3、OSS中。4.3 常见问题与排查技巧实录即使部署顺利运行过程中也可能遇到问题。这里记录了几个我亲自踩过的坑和解决方法。问题1安装脚本卡在“Pulling images...”或拉取镜像超时。现象运行安装脚本后长时间停留在拉取Docker镜像的阶段最后可能报网络错误。排查这是国内访问Docker Hub的典型问题。解决中断脚本CtrlC。配置Docker镜像加速器。编辑/etc/docker/daemon.json若不存在则创建{ registry-mirrors: [ https://registry.docker-cn.com, https://mirror.ccs.tencentyun.com, https://docker.mirrors.ustc.edu.cn ] }重启Docker服务sudo systemctl restart docker。重新运行安装脚本。问题2访问Gateway页面提示“Invalid token”或一直加载。现象使用正确的令牌和密码访问但无法进入界面或提示令牌无效。排查检查令牌确认使用的令牌是安装脚本最新输出的。令牌存储在runclawd-data卷的/data/.openclaw/openclaw.json中。可以通过docker compose exec runclawd cat /data/.openclaw/openclaw.json | grep token查看。检查设备审批这是最常见的原因。通过Web终端或exec命令运行openclaw devices list查看是否有待批准的设备。检查服务状态运行docker compose logs runclawd查看OpenClaw服务是否正常启动有无报错如API密钥无效。解决如果是设备未批准按前述方法批准即可。如果是API密钥错误修正.env文件后重启服务。问题3Cloudflare隧道连接失败无法通过公网访问。现象安装脚本输出的trycloudflare.com网址无法打开或者自定义域名隧道显示“未连接”。排查docker compose logs cloudflared查看隧道客户端日志。常见错误是网络连通性问题或令牌无效。对于自定义域名检查Cloudflare Zero Trust面板中隧道状态是否为“Active”。检查服务器防火墙/安全组是否放行了出站流量特别是到Cloudflare的端口。解决确保CF_TUNNEL_TOKEN正确无误。在Cloudflare面板重新生成令牌并更新.env文件然后重启cloudflared服务docker compose restart cloudflared。如果服务器网络受限可能需要配置HTTP_PROXY环境变量给cloudflared容器。问题4OpenClaw技能调用失败报错与浏览器或网络相关。现象当使用需要网页访问的技能时智能体报错提示无法连接或超时。排查检查browserless服务是否正常运行docker compose ps | grep browserless。查看browserless日志docker compose logs browserless。看是否有Chrome启动失败或内存不足的错误。在runclawd容器内测试是否能连接到browserless:3000docker compose exec runclawd curl -v http://browserless:3000/health。解决如果browserless容器崩溃可能是内存不足。可以尝试在docker-compose.yaml中增加其内存限制mem_limit或者检查宿主机的可用内存。确保OpenClaw的技能配置中浏览器技能的端点endpoint指向了正确的内部地址http://browserless:3000。问题5磁盘空间不足。现象服务运行一段时间后日志报错“No space left on device”。排查Docker的镜像、容器日志、数据卷都会占用空间。解决清理无用的Docker镜像docker image prune -a。清理停止的容器和未使用的卷docker system prune -f。限制容器日志大小在/etc/docker/daemon.json中配置日志驱动和大小限制。定期清理runclawd容器内可能产生的缓存文件或调整备份保留策略。5. 进阶从Docker迁移至原生安装的深度解析项目文档提供了从Docker迁移到原生安装的指南这适用于希望获得更直接控制、更高性能或更少抽象层的用户。但迁移过程有几个关键点需要深入理解。迁移的本质是将运行在Docker容器内的OpenClaw应用及其数据转移到宿主机的原生Node.js环境中。这涉及到应用运行环境和数据路径的两重迁移。步骤精讲与避坑数据备份与路径映射这是最容易出错的一步。Docker容器内的路径如/data/.openclaw在宿主机上对应的是Docker卷的挂载点通常位于/var/lib/docker/volumes/下某个复杂路径。迁移脚本使用docker cp命令直接从容器的文件系统复制数据到宿主机当前目录这是最可靠的方式。你必须清楚两个关键映射容器内/data/.openclaw-宿主机原生~/.openclaw(用户主目录下的隐藏文件夹)。容器内/data/openclaw-workspace-宿主机~/.openclaw/workspace。 迁移后务必使用sed命令修改openclaw.json配置文件中的所有路径引用否则OpenClaw启动时会因为找不到旧路径而失败。权限问题这是原生安装最常见的“拦路虎”。Docker容器内通常以root或特定用户运行文件权限可能比较“宽松”。当这些文件被复制到宿主机你的用户目录下时可能会导致Node.js进程以你的用户身份运行没有读写权限。文档中提到的EACCES: permission denied, mkdir /data/.openclaw错误就是因为配置文件中残留了Docker的路径程序试图在根目录创建文件夹而权限不足。除了按文档清理会话更根本的解决方法是# 确保你对迁移后的目录有完全控制权 chmod -R 755 ~/.openclaw # 同时检查文件所有者是否正确 chown -R $USER:$USER ~/.openclaw网络与安全配置的差异Docker方案中网络隔离、端口映射、反向代理Caddy、基础认证都是由Docker Compose栈管理的。迁移到原生后你需要自己处理服务暴露原生openclaw start默认可能监听所有接口0.0.0.0。在生产环境中这是极其危险的你必须按照指南修改~/.openclaw/openclaw.json将gateway.bind设置为loopback或127.0.0.1仅允许本地访问。访问方式失去了Caddy和Cloudflared你需要通过SSH隧道ssh -L来安全访问或者在宿主机前部署独立的Nginx/Caddy反向代理并配置好TLS和认证。防火墙务必使用ufw或firewalld严格限制入站端口只开放SSH22并明确拒绝OpenClaw服务端口如18789的外部访问。决策什么时候该迁移选择Docker (RunClawd)追求快速部署、环境隔离、易于维护和升级、内置生产级安全与网络配置。适合大多数用户尤其是运维经验不那么丰富的开发者。选择原生安装需要深度定制Node.js版本或依赖、对性能有极致要求、希望减少Docker带来的开销、或者宿主机环境本身已经高度可控且安全策略严格。这需要更强的系统管理能力。我个人建议除非有明确且强烈的理由否则继续使用RunClawd的Docker方案是更省心、更安全的选择。它的价值就在于把那些复杂且容易出错的运维细节封装了起来让你能更专注于OpenClaw智能体本身的开发和使用。