网关服务

网关服务 🌐

网关是 OpenClaw 的核心进程，负责管理所有连接和消息处理。

🎯 什么是网关？

网关是一个始终运行的后台服务，它：

📱 维护与消息平台的连接
🧠 管理 AI 代理的生命周期
🌐 提供 Web 控制界面
📊 处理消息路由和转换

┌─────────────────────────────────────────┐
│              OpenClaw 网关               │
│                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │WhatsApp │  │Telegram │  │ Discord │ │
│  │ 连接    │  │ 连接    │  │ 连接    │ │
│  └────┬────┘  └────┬────┘  └────┬────┘ │
│       └─────────────┼─────────────┘    │
│                     ↓                   │
│            ┌─────────────────┐         │
│            │   消息路由器     │         │
│            │   + AI 代理      │         │
│            └────────┬────────┘         │
│                     ↓                   │
│            ┌─────────────────┐         │
│            │   Web 界面      │         │
│            │   :18789        │         │
│            └─────────────────┘         │
└─────────────────────────────────────────┘

🚀 启动网关

基本启动

# 前台运行（查看日志）
openclaw gateway

# 指定端口
openclaw gateway --port 18789

# 显示详细日志
openclaw gateway --verbose

# 开发模式（自动重载）
openclaw gateway --dev

后台运行

# 启动为后台服务
openclaw gateway --daemon

# 或使用系统服务
openclaw service start

Docker 启动

# 使用 Docker
docker run -d \
  --name openclaw-gateway \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw gateway

# 使用 Docker Compose
docker compose up -d gateway

🛑 停止网关

正常停止

# 优雅关闭（处理完当前消息）
openclaw gateway stop

# 或 Ctrl+C（如果是前台运行）

强制停止

# 强制终止
openclaw gateway kill

# 或使用系统命令
kill -9 $(pgrep -f "openclaw gateway")

📊 网关状态

查看状态

# 检查运行状态
openclaw gateway status

# 详细状态
openclaw gateway status --verbose

# 输出示例：
# ✅ Gateway 运行中
# 📍 地址: http://127.0.0.1:18789
# 📱 频道: WhatsApp ✓, Telegram ✓
# 🧠 代理: Pi Agent ✓
# 💾 内存: 256MB
# ⏱️  运行时间: 2小时

监控命令

# 实时日志
openclaw logs --follow

# 指标监控
openclaw gateway metrics

# 连接状态
openclaw gateway connections

⚙️ 配置选项

命令行参数

参数	说明	默认值
`--port`	监听端口	18789
`--host`	绑定地址	127.0.0.1
`--config`	配置文件路径	~/.openclaw/openclaw.json
`--verbose`	详细日志	false
`--dev`	开发模式	false
`--daemon`	后台运行	false

配置文件

{
  gateway: {
    // 网络设置
    port: 18789,
    host: "127.0.0.1",

    // 安全设置
    token: "auto-generated",
    cors: {
      enabled: true,
      origins: ["http://localhost:3000"]
    },

    // 性能设置
    workers: 4,
    maxConnections: 100,

    // 热重载
    reload: {
      mode: "hybrid",  // off / hybrid / full
      watch: ["~/.openclaw/openclaw.json"]
    },

    // 日志
    logging: {
      level: "info",  // debug / info / warn / error
      format: "json",
      file: "~/.openclaw/logs/gateway.log"
    }
  }
}

🔌 连接管理

频道连接

# 查看频道连接状态
openclaw channels status

# 重新连接特定频道
openclaw channels reconnect whatsapp

# 断开频道连接
openclaw channels disconnect telegram

连接诊断

# 诊断连接问题
openclaw doctor

# 网络连通性测试
openclaw gateway ping

# 测试特定频道
openclaw channels test whatsapp

🌐 Web 界面

访问地址

http://127.0.0.1:18789/

界面功能

💬 实时聊天 - 无需配置频道即可测试
📊 状态监控 - 查看网关运行状态
⚙️ 配置管理 - 修改配置并热重载
📜 日志查看 - 实时查看运行日志
🔌 频道管理 - 连接/断开消息频道

API 端点

GET  /health          # 健康检查
GET  /status          # 详细状态
POST /config/apply    # 应用配置
GET  /logs            # 获取日志
WS   /ws              # WebSocket 控制

🔄 热重载

配置热重载

修改配置文件后，网关会自动应用：

{
  gateway: {
    reload: {
      mode: "hybrid",  // 安全更改热应用，关键更改重启
      // mode: "full"  // 任何更改都重启
      // mode: "off"   // 禁用热重载
    }
  }
}

手动重载

# 触发配置重载
openclaw gateway reload

# 完全重启
openclaw gateway restart

🛡️ 安全配置

访问控制

{
  gateway: {
    // 认证令牌
    token: "your-secure-token",

    // IP 白名单
    allowedHosts: [
      "127.0.0.1",
      "192.168.1.0/24"
    ],

    // CORS 设置
    cors: {
      enabled: true,
      origins: ["https://yourdomain.com"],
      credentials: true
    }
  }
}

TLS/SSL

{
  gateway: {
    tls: {
      enabled: true,
      cert: "/path/to/cert.pem",
      key: "/path/to/key.pem"
    }
  }
}

📈 性能调优

资源限制

{
  gateway: {
    // 内存限制
    memory: {
      max: "512MB",
      gcInterval: 30000
    },

    // 连接限制
    maxConnections: 100,
    maxMessageSize: "10MB",

    // 超时设置
    timeouts: {
      connect: 30000,
      read: 60000,
      write: 30000
    }
  }
}

高并发优化

# 增加工作线程
openclaw gateway --workers 8

# 或使用配置
{
  gateway: {
    workers: 8,
    queue: {
      size: 1000,
      concurrency: 50
    }
  }
}

🐛 故障排除

网关无法启动

症状： 命令执行后立即退出

检查步骤：

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

# 2. 检查配置文件
openclaw config validate

# 3. 查看错误日志
openclaw logs --level error

# 4. 使用调试模式
openclaw gateway --verbose

解决方案：

# 更换端口
openclaw gateway --port 18888

# 修复配置
openclaw doctor --fix

# 重置配置
rm ~/.openclaw/openclaw.json
openclaw onboard

频道连接失败

症状： 网关运行但无法接收消息

检查：

# 查看频道状态
openclaw channels status

# 测试连接
openclaw channels test whatsapp

# 重新认证
openclaw channels login whatsapp

内存泄漏

症状： 内存使用持续增长

解决方案：

# 定期重启
0 4 * * * openclaw gateway restart

# 或配置自动重启
{
  gateway: {
    restart: {
      enabled: true,
      maxMemory: "1GB",
      interval: "24h"
    }
  }
}

🔧 高级功能

多网关部署

{
  gateway: {
    cluster: {
      enabled: true,
      id: "gateway-1",
      peers: ["http://gateway-2:18789"]
    }
  }
}

负载均衡

# nginx 配置
upstream openclaw {
    server 127.0.0.1:18789;
    server 127.0.0.1:18790;
}

server {
    location / {
        proxy_pass http://openclaw;
    }
}

健康检查

# 编写健康检查脚本
#!/bin/bash
if ! curl -sf http://127.0.0.1:18789/health; then
    openclaw gateway restart
fi

📊 监控和日志

日志级别

# 错误日志
openclaw logs --level error

# 调试日志
openclaw logs --level debug --follow

# 特定模块
openclaw logs --module gateway --level verbose

指标收集

{
  gateway: {
    metrics: {
      enabled: true,
      endpoint: "/metrics",
      prometheus: true
    }
  }
}

网关服务

网关服务 🌐

🎯 什么是网关？

🚀 启动网关

基本启动

后台运行

Docker 启动

🛑 停止网关

正常停止

强制停止

📊 网关状态

查看状态

监控命令

⚙️ 配置选项

命令行参数

配置文件

🔌 连接管理

频道连接

连接诊断

🌐 Web 界面

访问地址

界面功能

API 端点

🔄 热重载

配置热重载

手动重载

🛡️ 安全配置

访问控制

TLS/SSL

📈 性能调优

资源限制

高并发优化

🐛 故障排除

网关无法启动

频道连接失败

内存泄漏

🔧 高级功能

多网关部署

负载均衡

健康检查

📊 监控和日志

日志级别

指标收集

📚 相关文档