1. 先别急着开箱运行用户与目录规划决定后续省不省心1.1 为什么一定要单独建一个系统用户而不是拿 root 直接跑我第一次部署 OpenClaw 的时候就吃了这个亏。当时图省事root 用户下一条命令装完就启动服务确实跑起来了但后面配置文件想调个参数、日志想轮转、目录权限想收紧越改越别扭到了 Nginx 反向代理那一步更是各种权限错位。最后全部清掉重来规规矩矩建了专用用户十分钟搞定。这不是强迫症。OpenClaw 作为对外提供服务的常驻进程它有读取配置、写入日志、缓存临时文件、可能还要调用外部模型接口这些行为。如果直接用 root 跑万一 Web 服务层被传入的恶意请求打穿攻击者拿到的就是一个 root 权限的 shell那后患太大了。单独建一个低权限用户即使服务被攻破能造成的破坏也局限在它自己的目录和端口范围里。另外还有一个很实际的原因后续你要用 systemd 托管它而 systemd 服务单元里指定 User 和 Group 是一种标准做法官方维护者也好、社区教程也好默认都是按专用用户来教的。提前把用户建好后面每一步都能对上。1.2 用户创建与目录结构一次性规划到位我建议在系统里创建一个名为openclaw的普通用户不设置登录密码或者干脆锁定登录只用来运行服务。# 创建用户不建家目录也行我习惯给它一个专门的数据目录 sudo useradd --system --home-dir /opt/openclaw --shell /usr/sbin/nologin openclaw # 创建目录结构 sudo mkdir -p /opt/openclaw/{bin,config,logs,data,run} sudo chown -R openclaw:openclaw /opt/openclaw解释一下这几个目录的用途bin放 OpenClaw 的可执行文件或启动脚本和安装包分离升级时直接换这一目录。config集中放配置文件尽量不散落在家目录里方便备份和版本管理。logs日志输出目录配合 logrotate 做轮转。dataOpenClaw 运行过程中产生的业务数据比如会话记录、技能包缓存单独隔离。run放置 pid 文件和 socket 文件权限要求比较高交给 systemd 的RuntimeDirectory管理也可以但手动建好更直观。这个结构不是死的但用户独立 目录分层这个思路值得保留。后面你配置 Nginx 反代的时候要读取日志、可能要改 socket 权限如果当初目录随意建排查问题的时间会成倍增加。1.3 环境检查装之前先确认这几条创建用户之后不要急着下载安装包。先把基础环境摸一遍我一般在全新服务器上按这个顺序检查# 系统版本与架构 uname -m cat /etc/os-release # 是否已有 Web 服务占用端口 ss -lntp | grep -E :(80|443|3000|8080)\s # 磁盘空间 df -h /opt # 内存OpenClaw 依赖本地模型时特别吃内存 free -hOpenClaw 的部署形态比较多样有的场景需要 Node.js 运行时有的会走 Python 生态还有的是直接调用 Ollama 等本地模型服务。我的建议是先确认你准备跑在哪一种形态上再据此决定要不要装对应运行时。拿不准的话优先保留 Node.js LTS 版本环境这是兼容性最稳妥的选择。注意如果你是在 Windows 上用 WSL 跑 OpenClaw做环境检查时用wsl --status和wsl -l -v确认发行版是 WSL2 而不是 WSL1两者的网络和 systemd 行为差异很大。WSL2 才支持 systemd 托管服务这点决定了后面第 3 章的内容能否顺利落地。2. 依赖、下载包与配置文件安装阶段最容易翻车的三个点2.1 依赖安装版本对齐比想象中更重要部署 OpenClaw 这类服务90% 的安装失败都出在依赖版本不一致上。我遇到过的最典型问题系统自带的 Node.js 是 16.x而 OpenClaw 要求的运行环境至少是 18.x结果启动时直接报语法错误。更要命的是有些报错信息本身还有误导性它提示的是配置文件字段缺失实际根源却是运行时版本太老ESM 模块解析不过去。所以依赖这一块我给你的建议是先看官方发布说明里标注的运行时最低版本不要只看能装就完事。装完运行时后用node -v npm -v或对应语言的--version确认版本。如果服务器上有多个版本共存用update-alternatives或 nvm 显式指定当前生效版本避免 PATH 混乱。如果你的场景还要联动 Ollama 这类本地模型服务那额外要确认的是 Ollama 的 API 地址和端口是否可达。我曾经在配置里写了localhost:11434但 OpenClaw 进程运行在 systemd 私有网络命名空间下两个服务直接互相访问不到。后放开 network 限制才通这个细节很多人第一次部署根本想不到。2.2 下载安装包校验完整性别直接解压就跑OpenClaw 的发布包一般会提供压缩包和对应的校验文件。我每次部署都坚持做一步# 以 tar.gz 举例 wget https://example.com/path/to/openclaw-x.y.z.tar.gz wget https://example.com/path/to/openclaw-x.y.z.tar.gz.sha256 sha256sum -c openclaw-x.y.z.tar.gz.sha256这一步看着多余实际上很值得。一是压缩包在传输过程中是否损坏解压时不一定立刻暴露有时候是运行到某个功能模块才崩溃二是如果发布方提供了签名文件校验一下能确认拿到的确实是对应版本而不是被替换过的文件。解压之后把内容放到/opt/openclaw/bin目录下然后给可执行文件加上权限sudo tar -xzf openclaw-x.y.z.tar.gz -C /tmp sudo cp -a /tmp/openclaw-x.y.z/* /opt/openclaw/bin/ sudo chown -R openclaw:openclaw /opt/openclaw/bin sudo chmod x /opt/openclaw/bin/openclaw版本号这里我用x.y.z代替具体版本请以你部署当天的官方发布为准。我强烈建议不要用latest这种浮动标签来下载后续升级和排查问题时你不知道自己跑的是哪一天的版本日志都无从查起。2.3 配置文件字段理解每一项再去改OpenClaw 启动时会读取配置文件默认位置一般在/etc/openclaw/config.yaml或项目目录下的config目录里。不同版本字段略有差异但以下几项是核心我逐个说# 服务监听地址默认只监听本机 host: 127.0.0.1 # 服务端口Nginx 反代时指向这里 port: 8080 # 对外访问密钥或 Token建议用足够长的随机字符串 auth_token: your-super-long-random-token # 数据存储目录 data_dir: /opt/openclaw/data # 日志相关 log: level: info file: /opt/openclaw/logs/openclaw.log第一个容易踩的坑是host字段。如果你把host写成0.0.0.0并且服务器有公网 IPOpenClaw 就直接暴露在公网上了这非常危险。我部署时的做法是host保持127.0.0.1只让本机访问所有外部流量都走 Nginx 反向代理由 Nginx 统一处理 HTTPS 和访问控制。这样即使 OpenClaw 自身有安全漏洞外网也无法直接触达。第二个重点是auth_token。OpenClaw 对外提供类似 API 服务的接口Token 就是第一道防线。建议用以下命令生成强随机值openssl rand -base64 48别用123456、admin这类弱口令也别直接写在启动脚本里通过命令行参数传入那样容易被进程列表泄露。写进配置文件并收紧文件权限即可。2.4 首次启动与连通性验证配置改好后先手动前台启动一次观察输出sudo -u openclaw /opt/openclaw/bin/openclaw --config /opt/openclaw/config/config.yaml这里有一个必须强调的细节用sudo -u openclaw切换到专用用户来启动而不是 root 启动。如果启动成功不会立刻退出你会看到监听端口和一个提示服务已就绪的输出。如果有报错按错误信息逆着查配置。确认服务正常后再做一步验证curl -s http://127.0.0.1:8080/health用curl打一下健康检查接口看有没有预期响应。这一步过了服务本身就没问题了可以进入 systemd 托管阶段。首次启动时建议开着前台窗口盯着看一轮确认没有任何异常输出后再 CtrlC 停掉进入下一步。不要一看到端口起来了就直接配 systemd有些运行时错误是延后的比如异步加载模型失败。3. 手动启动一时爽systemd 守护才是正解3.1 为什么不用 nohup 或 screen你当然可以用nohup把进程丢在后台甚至用screen挂着但这些方式有几个问题机器重启之后你得手动恢复、进程崩溃了没人帮你拉起来、开机自启更是要自己写脚本。我更推荐直接用 systemd它是现在主流 Linux 发行版的标准服务管理器写一个 service 文件就能解决上述所有问题。3.2 编写 systemd 服务单元文件在/etc/systemd/system/openclaw.service下创建服务单元[Unit] DescriptionOpenClaw Service Afternetwork-online.target Wantsnetwork-online.target [Service] Typesimple Useropenclaw Groupopenclaw WorkingDirectory/opt/openclaw ExecStart/opt/openclaw/bin/openclaw --config /opt/openclaw/config/config.yaml Restarton-failure RestartSec5 # 日志输出到 journald同时保留文件日志 StandardOutputjournal StandardErrorjournal # 安全相关配置 NoNewPrivilegestrue PrivateTmptrue ProtectSystemfull ProtectHometrue [Install] WantedBymulti-user.target这里解释一下关键配置项TypesimpleOpenClaw 启动后持续运行的常驻进程不需要 fork用 simple 最合适。Restarton-failure进程崩溃或异常退出时自动重启这是守护的核心意义。加上RestartSec5防止频繁重启把机器拖垮。ProtectSystemfull和ProtectHometrue把系统目录强制设为只读禁止访问家目录即使进程被攻破也改不了系统文件这是纵深防御。写好之后执行sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclawenable是设置开机自启的意思start是立刻启动。你不需要再写什么 rc.local 脚本systemd 会处理好。3.3 日志查看与状态确认服务跑起来以后看状态和日志是新常态操作# 查看服务状态 systemctl status openclaw # 查看最近 50 行日志 journalctl -u openclaw -n 50 --no-pager # 实时跟踪日志 journalctl -u openclaw -f我个人的习惯是journalctl -u openclaw -f配合curl一起用。改一次配置、重启服务、打一次请求看日志输出是否符合预期这样能快速定位配置问题。3.4 常见启动失败与排查思路我把部署过程中遇到最多的几种启动失败情况列在下面方便你按图索骥现象常见原因排查方法端口被占用之前手动启动的进程还没退出ss -lntp | grep 8080kill 掉旧进程Permission denied配置目录或数据目录权限不对sudo chown -R openclaw:openclaw /opt/openclaw启动后又退出重启循环配置解析错误或依赖端口不通journalctl -u openclaw -n 100看报错日志里出现地址绑定失败host配置为已经不存在的 IP把host改为127.0.0.1再试连接外部模型服务超时systemd 网络限制或防火墙策略检查PrivateNetwork是否被误开检查防火墙这里特别说一个现象如果服务一直处于activating (auto-restart)状态多半是启动即崩溃。这时不要慌着改配置先把Restart临时改成no然后systemctl stop openclaw再到前台手动跑一次看清楚真实报错。3.5 资源限制防止服务吃光内存OpenClaw 如果接了本地模型推理内存占用可能高得离谱。建议在 service 文件里加上内存限制避免它把整台机器拖死[Service] MemoryHigh4G MemoryMax6GMemoryHigh是软限制超过后系统会尝试回收MemoryMax是硬限制超过会被 OOM Kill。具体数值根据你的机器配置来定。加上这个配置之后即使某个模型推理任务失控服务被重启也不会殃及机器上的其他服务。4. Nginx 反向代理与 HTTPS 落地域名访问的最后一公里4.1 为什么需要反向代理而不是直接把服务端口暴露出去走到这一步OpenClaw 在127.0.0.1:8080已经跑得很稳了但只有本机能访问外部根本进不来。要让团队成员或自己在浏览器里通过域名访问常规做法就是加一层 Nginx 反向代理。反向代理解决的不只是端口转发它带来几个直接价值HTTPS 终结SSL 证书配置在 Nginx 这一层OpenClaw 自身不用处理加密证书维护也集中了。域名路由一个 IP 可以挂多个域名通过server_name区分流量这也是多站点共存的基础。统一安全策略IP 白名单、请求频率限制、静态文件缓存等都可以在 Nginx 层完成不用改应用代码。隐藏内部拓扑外部只知道你有个域名不知道后面实际跑的是什么端口、什么服务。4.2 Nginx 安装与启动在你的服务器上安装 Nginx# Debian/Ubuntu 系 sudo apt update sudo apt install nginx -y # CentOS/RHEL 系 sudo yum install nginx -y安装完成后先确认它没被占用端口冲突影响sudo systemctl start nginx sudo systemctl enable nginx ss -lntp | grep :80如果 80 端口已经被 OpenClaw 或其他服务占用Nginx 是起不来的。这个在前面第 1 章的端口预检里就应该排查过了。4.3 站点配置文件详解Nginx 的站点配置放在/etc/nginx/conf.d/或/etc/nginx/sites-available/下我习惯用conf.d/openclaw.conf管理一个域名对应一个文件日后排查问题干净利落。upstream openclaw_backend { server 127.0.0.1:8080; keepalive 32; } server { listen 80; server_name openclaw.example.com; # 强制跳转 HTTPS return 301 https://$host$request_uri; } server { listen 443 ssl http2; server_name openclaw.example.com; # SSL 证书路径先占位下面单独讲 ssl_certificate /etc/nginx/ssl/openclaw.example.com/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/openclaw.example.com/privkey.pem; # 安全和性能相关配置 ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256; ssl_session_cache shared:SSL:10m; ssl_session_timeout 1h; # 交给 OpenClaw 处理 location / { proxy_pass http://openclaw_backend; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket 支持如果 OpenClaw 用到实时推送这四行必须有 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; } # 静态资源直接给 Nginx 处理减轻 OpenClaw 压力 location /static/ { alias /opt/openclaw/data/static/; expires 7d; } }逐段解释upstream块定义了后端服务器地址。把它独立出来以后扩容时可以加多个server条目做负载均衡。第一个server监听 80专门负责跳转 HTTPS。不是必须的但没有它用户输入域名时还得手动加 https体验不好。第二个server才是真正干活的地方。location /把所有请求代理给 OpenClaw。proxy_set_header这四行必须写对尤其是Host和X-Forwarded-Proto。OpenClaw 如果生成回调链接或重定向地址读不到正确的Host头会拼出错误的 URL。如果 OpenClaw 提供交互式终端或流式输出WebSocket 的Upgrade头被漏掉页面就会一直转圈。这个坑我踩过排查了整整一下午。写完配置后测试并重载sudo nginx -t sudo systemctl reload nginxnginx -t会检查配置语法有错误直接报行号不要跳过这一步。reload 是无损重载不会中断现有连接。4.4 SSL 证书手动申请 vs 自动续期证书这块我直接建议用支持自动续期的方案。手动去后台点申请、下载、上传、改配置、reload一套流程下来哪怕熟练也要十分钟而且很容易忘记续期过期那天的报错绝对能让你怀疑人生。推荐的流程是安装 ACME 客户端执行签发命令# 以 certbot 为例 sudo apt install certbot python3-certbot-nginx -y sudo certbot --nginx -d openclaw.example.comcertbot会自动修改 Nginx 配置并重载省去手动改证书路径的麻烦。它还会写入定时任务自动续期你基本不用再管证书的事。如果你的服务器在国内访问 ACME 服务的网络不通畅可以用支持自动部署的替代方案部署时把证书文件放到指定目录并配置自动更新命令即可。无论用哪种方案证书申请成功后记得手动验证一下curl -sI https://openclaw.example.com/health | head -n 5能返回HTTP/2 200就说明证书和反代链路都没问题了。4.5 常见报错与排错思路反代配置完成之后最容易遇到下面这几个报错我把排查路径列出来502 Bad GatewayNginx 连不上 OpenClaw。先确认 OpenClaw 进程还活着systemctl status openclaw再看 Nginx 的proxy_pass是不是指向了错误端口最后看防火墙有没有拦截本机回环请求。504 Gateway TimeoutOpenClaw 的某个请求处理时间太长。在 OpenClaw 侧排查是什么操作卡住了同时调整 Nginx 的proxy_read_timeout将它从默认 60s 放宽到 300s 甚至更长。SSL 证书不生效访问时提示证书错误。最常见原因是证书路径写错或证书文件内容空。用openssl x509 -in fullchain.pem -text -noout查看证书信息确认域名和有效期是否匹配。替换证书后不生效多半是没有 reload Nginx光nginx -t是不够的。ERR_CERT_COMMON_NAME_INVALID浏览器访问时提示域名不匹配。这个是证书域名和server_name不一致导致的重新签发包含正确域名的证书即可。把这些可能出现的问题提前熟悉一遍等真出现时才不会慌。我当初第一次配证书时因为路径少了文件名浏览器直接报 404 拿不到证书折腾了大半个小时后来就是靠一行一行排查nginx -t和证书文件有没有正常加载才定位到的。5. 多站点与多端口场景一台机器跑多个服务的配置思路5.1 多个 OpenClaw 实例怎么共存实际部署中一台服务器可能同时跑开发环境的 OpenClaw、测试环境的另一个实例甚至还要挂一个 1Panel 管理面板。这时候不能所有服务都抢 8080 端口要在配置层面区分开。我的做法是给每个实例分配独立端口和独立 systemd 服务实例配置端口systemd 服务名域名openclaw-prod8080openclaw.serviceopenclaw.example.comopenclaw-dev8081openclaw-dev.servicedev.openclaw.example.com每个实例的配置和数据目录完全隔离在 service 文件的WorkingDirectory和配置文件里指定不同路径即可。Nginx 里按域名路由到对应端口互不干扰。这个方案的可扩展性很好后期要加实例只需要复制 service 文件、改端口和路径不用动其他任何东西。5.2 Nginx 中同时配置多个站点在 Nginx 里加第二个站点配置文件dev.openclaw.conf逻辑和第 4.3 节完全一样唯一的区别是server_name和proxy_pass的目标端口server { listen 443 ssl http2; server_name dev.openclaw.example.com; ssl_certificate /etc/nginx/ssl/dev.openclaw.example.com/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/dev.openclaw.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:8081; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }写好之后nginx -t sudo systemctl reload nginx两个站点就能同时访问了。我在本地开发场景里还常用虚拟机加自定义域名的方式模拟多站点环境做法是改/etc/hosts把dev.openclaw.example.com指向 127.0.0.1Nginx 配置和线上保持一致这样本地调试和线上行为几乎无差异。5.3 与 1Panel 面板结合时的注意事项如果你用 1Panel 这类面板管理服务器反向代理配置可以直接在面板里操作但我还是习惯手动写 Nginx 配置。原因是面板生成的配置更新频率低、可控性差出了问题你还要去辨别它生成的规则。而自己写的配置每行都能看懂排错成本低很多。不过面板也有它的价值证书申请、续期和定时任务可以交给面板统一管。我目前的生产环境是面板管证书 手动管 Nginx 配置的组合证书快到期时面板自动续期Nginx 只要引用证书文件的固定路径即可证书文件覆盖更新并不需要对 Nginx 做任何操作。5.4 最后再分享两个操作经验一个经验是日志别只看 application 日志Nginx 的access.log配合error.log一起看。有一次用户反馈 OpenClaw 页面白屏我去看 OpenClaw 日志一无所获最后翻了 Nginx access log 才发现请求根本没到达后端绕了一圈才找到是防火墙拦了/health路径。另一个经验是改了 OpenClaw 配置文件之后记得用systemctl daemon-reload刷新 systemd 对配置的感知然后再重启服务。尤其是改过 service 文件的路径或环境变量之后不daemon-reload直接 restart新配置是不生效的。这个小动作我大概救了我十几次希望你也能少踩这个坑。