多网关部署
在大规模或分布式场景中，你可能需要运行多个 Gateway 实例。本文档介绍多网关的部署架构和配置方法。
使用场景
| 场景 | 说明 |
|---|---|
| 地理分布 | 不同地区部署 Gateway，降低延迟 |
| 负载均衡 | 分担请求压力 |
| 高可用 | 一个 Gateway 故障，其他继续服务 |
| 环境隔离 | 开发/测试/生产使用不同 Gateway |
| 团队隔离 | 不同团队使用独立 Gateway |
架构模式
模式 1：独立实例
每个 Gateway 完全独立，不互相通信：
text
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Gateway A │ │ Gateway B │ │ Gateway C │
│ (开发环境) │ │ (测试环境) │ │ (生产环境) │
│ :18789 │ │ :18790 │ │ :18791 │
└──────────────┘ └──────────────┘ └──────────────┘
独立数据目录 独立数据目录 独立数据目录模式 2：桥接实例
Gateway 之间通过桥接协议（Bridge Protocol）共享 Channel 和会话：
text
┌──────────────┐ Bridge ┌──────────────┐
│ Gateway A │◀───────────▶│ Gateway B │
│ (北京) │ │ (上海) │
│ OpenAI │ │ Ollama │
└──────────────┘ └──────────────┘模式 3：负载均衡
通过负载均衡器（Load Balancer）分发请求：
text
┌──────────────┐
│ Load │
Client ──────────▶ │ Balancer │
│ (Nginx) │
└──────┬───────┘
│
┌────────────┼────────────┐
│ │ │
┌──────┴───┐ ┌─────┴────┐ ┌─────┴────┐
│ Gateway 1│ │ Gateway 2│ │ Gateway 3│
└──────────┘ └──────────┘ └──────────┘配置独立实例
在同一台机器上运行多个 Gateway，需使用不同的端口和数据目录：
bash
# 实例 1：开发环境
openclaw gateway \
--port 18789 \
--data-dir ~/.openclaw-dev \
--config ~/.openclaw-dev/openclaw.json
# 实例 2：测试环境
openclaw gateway \
--port 18790 \
--data-dir ~/.openclaw-test \
--config ~/.openclaw-test/openclaw.json数据隔离
每个实例使用独立的 --data-dir，确保锁文件、日志和配置完全隔离。
配置桥接
Gateway A（北京）
json5
{
"gateway": {
"port": 18789,
"bridge": {
"enabled": true,
"allowedTokens": ["${BRIDGE_TOKEN}"]
}
},
"channels": [
{
"name": "openai",
"provider": "openai",
"apiKey": "${OPENAI_API_KEY}"
}
]
}Gateway B（上海）
json5
{
"gateway": {
"port": 18789,
"bridges": [
{
"name": "beijing-gateway",
"url": "wss://beijing-gw.example.com/bridge",
"token": "${BRIDGE_TOKEN}",
"shareChannels": true
}
]
},
"channels": [
{
"name": "local-ollama",
"provider": "ollama",
"baseUrl": "http://localhost:11434"
}
]
}桥接建立后，Gateway B 的客户端可以使用 Gateway A 的 OpenAI Channel，反之亦然。
负载均衡配置
Nginx 负载均衡
nginx
upstream openclaw_backends {
# 会话粘滞（WebSocket 需要）
ip_hash;
server 127.0.0.1:18789;
server 127.0.0.1:18790;
server 127.0.0.1:18791;
}
server {
listen 443 ssl;
server_name gateway.example.com;
location / {
proxy_pass http://openclaw_backends;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
}
}会话粘滞
WebSocket 连接需要会话粘滞（Session Stickiness），确保同一客户端始终路由到同一 Gateway 实例。使用 ip_hash 或 cookie-based 粘滞策略。
会话同步
多 Gateway 间的会话同步策略：
| 策略 | 说明 | 复杂度 |
|---|---|---|
| 无同步 | 会话绑定到单个 Gateway | 低 |
| 桥接同步 | 通过桥接协议同步状态 | 中 |
| 外部存储 | 使用 Redis 等共享会话 | 高 |
桥接同步配置
json5
{
"gateway": {
"bridges": [
{
"name": "peer",
"url": "wss://peer-gateway.example.com/bridge",
"token": "${BRIDGE_TOKEN}",
"syncSessions": true // 启用会话同步
}
]
}
}管理多实例
bash
# 查看所有实例状态
openclaw status --all
# 指定实例操作
openclaw status --data-dir ~/.openclaw-dev
openclaw logs --data-dir ~/.openclaw-test --follow
# 停止指定实例
openclaw gateway stop --data-dir ~/.openclaw-dev监控
为每个 Gateway 实例配置独立的健康检查：
bash
# 检查各实例
curl http://localhost:18789/health
curl http://localhost:18790/health
curl http://localhost:18791/health注意事项
- 端口冲突 — 每个实例必须使用不同端口
- 数据目录 — 每个实例必须使用独立数据目录
- 资源分配 — 合理分配 CPU 和内存
- 桥接安全 — 桥接连接使用强 Token
- 一致性 — 多实例间的配置保持一致