systemd 服务管理

OpenClaw 使用 systemd 用户服务管理 Gateway 进程。

安装服务

# onboard 时自动安装
openclaw onboard --install-daemon

# 或手动安装
openclaw gateway install

验证服务已安装：

systemctl --user list-unit-files | grep openclaw
# 应该显示 openclaw-gateway.service

日常管理

# 状态
systemctl --user status openclaw-gateway

# 重启
systemctl --user restart openclaw-gateway

# 停止
systemctl --user stop openclaw-gateway

# 启动
systemctl --user start openclaw-gateway

# 查看日志
journalctl --user -u openclaw-gateway -f

# 只看最近 50 行
journalctl --user -u openclaw-gateway -n 50 --no-pager

# 开机自启（必须执行，否则退出 SSH 后服务会停止）
loginctl enable-linger $(whoami)

# 验证 linger 已启用
loginctl show-user $(whoami) | grep Linger
# 应该显示 Linger=yes

用户 Lingering

systemd 用户服务在用户注销后默认会停止。启用 lingering 让服务持续运行：

# 启用
loginctl enable-linger $(whoami)

# 禁用
loginctl disable-linger $(whoami)

# 验证状态
loginctl show-user $(whoami) | grep Linger

openclaw doctor 会自动检测并提示此问题。

故障排查

# 检查服务状态
systemctl --user status openclaw-gateway

# 看完整日志
journalctl --user -u openclaw-gateway --no-pager -n 50

# 检查端口占用
lsof -i :18789

# 运行诊断
openclaw doctor

# 检查 Gateway 日志
cat /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | tail -50

常见问题

Q: 服务无法启动？

# 查看详细错误
systemctl --user status openclaw-gateway

# 查看日志
journalctl --user -u openclaw-gateway -n 100 --no-pager

Q: 退出 SSH 后服务停止？

# 启用 linger
loginctl enable-linger $(whoami)

Q: 如何卸载服务？

# 停止服务
systemctl --user stop openclaw-gateway

# 禁用服务
systemctl --user disable openclaw-gateway

# 卸载
openclaw gateway uninstall

Q: 如何查看服务文件位置？

systemctl --user show openclaw-gateway -p FragmentPath