在 Linux 上用 systemd 运行 OpenClaw 守护进程

默认情况下，openclaw gateway 跑在前台，关掉终端 Gateway 就停了。在 Linux 服务器上正式使用，需要把它配成 systemd 服务，做到开机自启、后台运行、崩溃自动重启。

本文所有命令均来自 OpenClaw 官方文档。

方式一：onboard 时直接安装（推荐）

如果你还没有初始化过 OpenClaw，在跑 onboard 时加上 --install-daemon 参数，引导完成后会自动把 Gateway 注册为 systemd 服务：

openclaw onboard --install-daemon

这是最简单的方式，引导会处理好服务注册、token 认证、开机自启的所有细节。

方式二：已有安装，事后补装 systemd 服务

如果之前已经跑过 onboard 但没有加 --install-daemon，可以单独安装后台服务：

openclaw gateway install

安装完启动服务：

openclaw gateway start

确认运行状态：

openclaw gateway status

服务管理常用命令

OpenClaw 对 systemd 操作做了封装，不需要直接用 systemctl：

# 启动
openclaw gateway start

# 停止
openclaw gateway stop

# 重启
openclaw gateway restart

# 查看状态
openclaw gateway status

# 查看状态（深度探测，包含健康检查）
openclaw gateway status --deep

# 卸载 systemd 服务（停止并移除，不删配置）
openclaw gateway uninstall

如果需要直接用 systemctl 操作，服务名会包含你的用户名，格式类似 openclaw-<username>，具体名称可以通过 openclaw gateway status 输出里看到。

查看日志

用 OpenClaw 自带的命令查看实时日志：

openclaw gateway logs
openclaw gateway logs --follow

或者用 journalctl 直接查：

journalctl -u openclaw-$(whoami) -f

日志里遇到问题，先重点看第一条 ERROR 或 FATAL 级别的行，后面的报错往往是连锁反应。

开机自启确认

openclaw gateway install 默认会启用开机自启。确认是否生效：

systemctl is-enabled openclaw-$(whoami)

输出 enabled 说明开机自启已开启。如果没有，手动启用：

systemctl enable openclaw-$(whoami)

环境变量配置

如果你需要自定义配置文件路径或状态目录，可以通过环境变量控制：

把环境变量加入 systemd 服务有两种方式：

方式一：写入 ~/.openclaw/.env 文件，Gateway 启动时会自动读取：

echo 'OPENCLAW_STATE_DIR=/data/openclaw' >> ~/.openclaw/.env

方式二：在 ~/.openclaw/openclaw.json 的 env 段直接配置内联环境变量，Gateway 会在启动时注入。

配置文件热加载

Gateway 服务在运行期间会自动监听 ~/.openclaw/openclaw.json 的文件变化，大多数设置改完之后不需要重启服务就会生效。

以下情况才需要手动重启：

• 修改了 gateway.mode（本地 / 远程模式切换）
• 修改了 gateway.remote 相关配置
• 修改了需要重新建立连接的渠道配置

openclaw gateway restart

常见问题排查

服务起不来

先跑诊断工具：

openclaw doctor
openclaw doctor --fix

openclaw doctor 能检测配置格式错误、遗留文件、端口冲突等常见问题，并在加 --fix 时尝试自动修复。

端口 18789 被占用

Gateway 默认监听 18789 端口。查看是哪个进程占用：

lsof -i :18789

如果是上一个 Gateway 实例没有正常退出：

openclaw gateway stop
openclaw gateway start

如果需要换端口，在配置文件里修改或启动时指定：

openclaw gateway --port 18790

服务启动后 openclaw doctor 报 token 问题

安装后台服务时，Gateway 会自动生成认证 token，本地客户端也需要用这个 token 连接。如果 token 配置出错，openclaw doctor 会给出具体提示，按提示操作即可。官方文档建议：如果 token 通过 SecretRef 管理，daemon 安装时会验证但不会把解析后的 token 明文写入服务环境变量，这是正常行为。

服务运行正常但控制面板打不开

服务器环境没有浏览器，用 SSH 端口转发访问控制面板：

ssh -L 18789:127.0.0.1:18789 user@your-server-ip

然后在本机浏览器访问 http://127.0.0.1:18789。

把旧的 pm2 托管迁移到 systemd

如果你之前用 pm2 运行 Gateway，迁移步骤：

# 停止并删除 pm2 里的 openclaw 进程
pm2 delete openclaw

# 安装 systemd 服务
openclaw gateway install
openclaw gateway start

一张表总结