启动 OpenClaw Gateway

本文聚焦：Gateway 的作用与生命周期 + 前台/后台启动方式对比

前置知识：初始化配置 下一篇：第一个 Agent

前置条件

• OpenClaw CLI 已安装（npm install -g openclaw）
• 已完成初始化配置（openclaw configure）
• Node.js 18+ 环境

知识点 1：Gateway 是什么

是什么

Gateway 是 OpenClaw 的核心服务进程，它是一个 WebSocket 服务器，负责：

• 接收外部指令：通过 WebSocket 连接接收来自 Telegram、Discord 等渠道的指令
• 管理 Agent 执行：调度并执行用户的任务请求
• 维护会话状态：持久化对话历史和上下文
• 提供 API 接口：为浏览器自动化、文件操作等工具提供统一的调用入口

本质上，Gateway 是 OpenClaw 的"大脑中枢"——没有它，OpenClaw 就无法接收和处理任何外部请求。

为什么需要

在 OpenClaw 的架构中，Gateway 承担着不可替代的角色：

1. 持久化连接：即使你的终端关闭，Gateway 也能保持运行，持续监听来自聊天应用的消息
2. 状态隔离：每个用户会话在 Gateway 中被独立管理，确保多用户场景下的数据隔离
3. 工具编排：Gateway 协调各种工具（浏览器、文件系统、代码执行等）的调用
4. 安全边界：通过 Token 认证机制，确保只有授权客户端可以连接

怎么用（代码示例）

前台启动 Gateway是最简单的启动方式，适合开发和调试：

# 基础启动（前台运行）
openclaw gateway run

# 指定端口启动
openclaw gateway run --port 18789

# 启用 Token 认证（生产环境推荐）
openclaw gateway run --token your-secret-token

# 绑定到局域网（允许其他设备连接）
openclaw gateway run --bind lan --port 18789

# 强制模式（如果端口被占用，自动 kill 占用进程）
openclaw gateway run --force

# 开发模式（创建隔离的 dev workspace，不影响主环境配置）
openclaw --dev gateway run

注意: --bind 支持 loopback（默认，仅本地）、lan（局域网）、tailnet（Tailscale VPN）、auto、custom。

启动成功后，你会看到类似输出：

🦞 OpenClaw 2026.3.8 — I'll do the boring stuff while you dramatically stare at the logs like it's cinema.

Gateway: bind=loopback (127.0.0.1), port=18789
Dashboard: http://127.0.0.1:18789/
Listening: 127.0.0.1:18789

常见陷阱

陷阱	表现	解决方案
端口冲突	EADDRINUSE: address already in use	使用 --force 参数或更换端口
未配置 gateway.mode	gateway.mode is not set to 'local'	运行 openclaw configure 完成初始化
权限不足	Permission denied	检查 ~/.openclaw 目录权限
Token 认证未配置	需要认证但未设置 Token	启动时添加 --token your-secret-token 或设置 OPENCLAW_GATEWAY_TOKEN 环境变量

注意: --token 参数会自动启用 token 认证模式。完整的认证模式包括 none（默认）、token、password、trusted-proxy。

知识点 2：启动方式详解

前台启动

适用场景：开发调试、临时使用、快速验证

命令：

# 标准前台启动
openclaw gateway run

# 带详细日志
openclaw gateway run --verbose

# 紧凑日志模式
openclaw gateway run --compact

# 前台启动 + 日志记录到文件
openclaw gateway run --raw-stream --raw-stream-path /tmp/gateway-stream.jsonl

特点：

• 日志实时输出到终端，便于调试
• 按 Ctrl+C 即可停止
• 终端关闭则服务停止
• 适合开发阶段快速迭代

后台启动（systemd）

适用场景：生产环境、长期运行、服务器部署

OpenClaw 提供了内置的服务安装命令，自动生成并配置 systemd 服务：

# 安装 Gateway 为系统服务
openclaw gateway install

# 指定端口安装
openclaw gateway install --port 18789

# 强制重新安装（覆盖现有配置）
openclaw gateway install --force

# 启动服务（推荐）
openclaw gateway start

# 或使用 systemctl（等效）
systemctl --user start openclaw-gateway.service

# 查看服务状态
openclaw gateway status

# 停止服务
openclaw gateway stop

# 重启服务
openclaw gateway restart

# 设置开机自启
systemctl --user enable openclaw-gateway.service

# 卸载服务
openclaw gateway uninstall

生成的 systemd 服务文件位于 ~/.config/systemd/user/openclaw-gateway.service，内容示例：

[Unit]
Description=OpenClaw Gateway (v2026.3.8)
After=network-online.target
Wants=network-online.target

[Service]
ExecStart="/home/username/.nvm/versions/node/v22.22.0/bin/node" "/home/username/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/dist/index.js" gateway --port 18789
Restart=always
RestartSec=5
KillMode=process
Environment=HOME=/home/username
Environment=OPENCLAW_GATEWAY_PORT=18789
Environment=OPENCLAW_GATEWAY_TOKEN=your-secret-token

[Install]
WantedBy=default.target

特点：

• 终端关闭后服务继续运行
• 自动重启（Restart=always）
• 开机自启支持
• 日志通过 journalctl 查看

如何选择

维度	前台启动	后台启动（systemd）
使用场景	开发、调试、临时使用	生产、长期运行、服务器
启动方式	openclaw gateway run	openclaw gateway install + openclaw gateway start
停止方式	Ctrl+C	openclaw gateway stop
日志查看	终端实时输出	journalctl --user -u openclaw-gateway.service -f
自动重启	否	是（默认配置）
开机自启	否	是（需 enable）
资源占用	当前终端会话	独立进程

决策流程：

1. 如果你是第一次使用或开发调试 → 选择前台启动
2. 如果你需要长期运行或部署到服务器 → 选择 systemd 后台启动
3. 如果你不确定 → 先前台启动验证，再迁移到后台

验证 Gateway 运行状态

启动后，可以通过以下方式验证：

# 1. 查看服务状态
openclaw gateway status

# 2. 检查端口监听
ss -tlnp | grep 18789
# 或
lsof -i :18789

# 3. 测试 Dashboard 访问
curl -s http://127.0.0.1:18789/ | head -n 5

# 4. 查看日志（后台模式）
journalctl --user -u openclaw-gateway.service -f

实践建议

1. 开发环境用前台，生产环境用后台

   • 开发时用 openclaw gateway run 实时查看日志
   • 部署后用 systemd 确保服务稳定运行

2. 配置 Token 认证

   # 临时设置（当前会话有效）
   export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
   
   # 永久设置（添加到 ~/.bashrc 或 ~/.zshrc）
   echo "export OPENCLAW_GATEWAY_TOKEN=$OPENCLAW_GATEWAY_TOKEN" >> ~/.bashrc
   source ~/.bashrc
   
   # 启动时指定
   openclaw gateway run --token $OPENCLAW_GATEWAY_TOKEN
   

3. 查看日志的正确姿势

   • 前台启动：直接看终端输出
   • 后台启动：journalctl --user -u openclaw-gateway.service -f

4. 端口管理

   • 默认端口 18789，如果被占用可以指定其他端口
   • 使用 --force 自动处理端口冲突

5. 快速验证 Gateway 是否运行

   openclaw gateway status
   # 或访问 Dashboard（返回 HTML 页面）
   curl -s http://127.0.0.1:18789/ | head -n 5
   

相关阅读

• 初始化配置
• 第一个 Agent