修复 OpenClaw Gateway systemd 服务配置完整教程

问题背景

OpenClaw Gateway 是 OpenClaw 的核心服务，负责管理所有聊天会话和插件运行。如果通过 systemd 管理服务，配置文件的错误会导致服务无法正常启动。本文详细介绍如何修复 OpenClaw Gateway 的 systemd 服务配置文件。

---

问题分析

原始 /etc/systemd/system/openclaw-gateway.service 文件存在以下问题：

1. 变量未定义

ExecStart=$OPENCLAW_BIN gateway --port 18789

问题：$OPENCLAW_BIN 变量在 systemd 环境中未定义，systemd 不会自动展开未定义的变量。

2. 缺少工作目录

没有指定 WorkingDirectory，OpenClaw 运行时可能找不到配置文件。

3. 缺少启动超时

没有设置 TimeoutStartSec，如果启动卡住会无限等待。

---

修复步骤

第一步：创建环境变量文件

mkdir -p /etc/openclaw
cat > /etc/openclaw/environment << 'EOF'
OPENCLAW_BIN=/root/.nvm/versions/node/v22.22.1/bin/openclaw
EOF

第二步：修改 systemd 服务文件

将 /etc/systemd/system/openclaw-gateway.service 修改为：

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
EnvironmentFile=/etc/openclaw/environment
WorkingDirectory=/root/.openclaw
ExecStart=/root/.nvm/versions/node/v22.22.1/bin/openclaw gateway --port 18789
Restart=on-failure
RestartSec=10
TimeoutStartSec=30

[Install]
WantedBy=multi-user.target

第三步：重新加载 systemd 配置

systemctl daemon-reload

第四步：停止已有的 Gateway 进程

如果 Gateway 之前是手动启动的（不是通过 systemd），需要先停止：

# 查找运行中的 Gateway 进程
ps aux | grep openclaw

# 停止 Gateway（如果是通过 openclaw gateway start 启动的）
openclaw gateway stop

# 或者直接 kill 进程
kill <PID>

第五步：启动服务

# 启动服务
systemctl start openclaw-gateway

# 查看服务状态
systemctl status openclaw-gateway

第六步：设置开机自启

systemctl enable openclaw-gateway

---

常用命令汇总

命令	说明
systemctl start openclaw-gateway	启动服务
systemctl stop openclaw-gateway	停止服务
systemctl restart openclaw-gateway	重启服务
systemctl status openclaw-gateway	查看状态
systemctl enable openclaw-gateway	开机自启
systemctl disable openclaw-gateway	取消开机自启
journalctl -u openclaw-gateway -f	查看日志

---

故障排查

1. 服务启动失败 (EXEC 错误)

如果 journalctl 显示 code=exited, status=203/EXEC：

1. 检查 ExecStart 路径是否正确
2. 确认 openclaw 二进制文件存在且可执行：

ls -la /root/.nvm/versions/node/v22.22.1/bin/openclaw

2. 端口已被占用

如果提示 Port 18789 is already in use：

# 查找占用端口的进程
lsof -i :18789
# 或
netstat -tlnp | grep 18789

# 停止已有的 Gateway
openclaw gateway stop

3. 配置文件找不到

如果 Gateway 启动后报配置文件错误：

1. 确认 WorkingDirectory=/root/.openclaw 设置正确
2. 检查配置文件是否存在：

ls -la /root/.openclaw/openclaw.json

---

验证服务运行

服务正常启动后，可以通过以下方式验证：

# 查看服务状态
systemctl status openclaw-gateway

# 查看 Gateway 日志
journalctl -u openclaw-gateway --no-pager -f

正常状态应显示：

● openclaw-gateway.service - OpenClaw Gateway
     Loaded: loaded (/etc/systemd/system/openclaw-gateway.service; enabled)
     Active: active (running)

---

总结

修复 OpenClaw Gateway systemd 服务配置的关键点：

1. 定义环境变量文件，解决 $OPENCLAW_BIN 变量未定义问题
2. 添加 WorkingDirectory，确保 OpenClaw 能找到配置文件
3. 设置 TimeoutStartSec，避免启动卡死
4. 使用绝对路径，ExecStart 直接写死完整路径更可靠
5. 先停止已有进程，再通过 systemd 启动服务

按照以上步骤操作，即可确保 OpenClaw Gateway 服务稳定运行。’