网络模型
Gateway 支持多种网络拓扑（Network Topology），从纯本地到跨互联网远程访问。本文档介绍各种连接架构及其配置。
网络拓扑概览
text
┌─────────────────────────────────────────────┐
│ 互联网 │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ 远程客户端 │ │ LLM 提供商 │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ │ ┌──────────────┤ │
│ │ │ NAT / 防火墙 │ │
│ │ └──────┬───────┘ │
│ │ │ │
│ ┌──────┴───────────┴──────────────────┐ │
│ │ 局域网 (LAN) │ │
│ │ │ │
│ │ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Gateway │ ←── │ 本地客户端│ │ │
│ │ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────┘本地连接
Loopback（回环）模式
默认模式，Gateway 仅监听 127.0.0.1，只接受本机连接。
json5
{
"gateway": {
"host": "127.0.0.1", // 仅本机
"port": 18789
}
}- ✅ 最安全 — 外部无法访问
- ✅ 无需额外配置
- ❌ 仅限同一台机器
LAN（局域网）模式
绑定到所有网络接口，允许局域网内的其他设备连接。
json5
{
"gateway": {
"host": "0.0.0.0", // 所有接口
"port": 18789
}
}- ✅ 局域网内多设备共享
- ⚠️ 需要配置认证
- ❌ 无 TLS 加密（局域网内可接受）
安全提醒
绑定到 0.0.0.0 时，务必确保已配置 Token 认证。参阅 认证。
远程连接
NAT 穿越（NAT Traversal）
大多数家庭和办公网络位于 NAT（网络地址转换）后面，需要额外配置才能从外部访问。
方案对比：
| 方案 | 复杂度 | 安全性 | 适用场景 |
|---|---|---|---|
| Tailscale VPN | 低 | 高 | 推荐 — 个人/小团队 |
| 反向代理 + 端口转发 | 中 | 中 | 有公网服务器 |
| 云部署 | 中 | 高 | 企业/团队 |
| 路由器端口转发 | 低 | 低 | 不推荐 |
端口转发
不推荐
直接将 Gateway 端口暴露到公网存在严重安全风险。强烈建议使用 Tailscale 或反向代理方案。
如果确实需要端口转发，必须同时：
- 启用 TLS 加密
- 配置强 Token 认证
- 启用速率限制
- 配置防火墙规则
反向代理
通过 Nginx 或 Caddy 等反向代理（Reverse Proxy）提供 HTTPS 接入：
nginx
server {
listen 443 ssl;
server_name gateway.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://127.0.0.1:18789;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}text
gateway.example.com {
reverse_proxy 127.0.0.1:18789
}Caddy 自动 HTTPS
Caddy 会自动申请和续期 Let's Encrypt 证书，是最简单的反向代理方案。
VPN 隧道
使用 Tailscale 或 WireGuard 等 VPN 创建安全隧道：
text
┌──────────┐ Tailscale 隧道 ┌──────────┐
│ Client │ ◀──────────────────▶ │ Gateway │
│ (远程) │ 端到端加密 │ (家庭) │
└──────────┘ └──────────┘详见 Tailscale 集成。
连接架构选型指南
text
只在本机使用？
└─ 是 → Loopback 模式（默认）
└─ 否 → 在同一局域网？
└─ 是 → LAN 模式 + Token 认证
└─ 否 → 需要远程访问
└─ 个人使用 → Tailscale VPN
└─ 团队/公开 → 反向代理 + HTTPS
└─ 企业 → 云部署 + 完整安全配置网络诊断
bash
# 检查 Gateway 监听状态
openclaw status --network
# 测试从其他设备的连接
curl http://192.168.1.10:18789/health
# 检查端口是否可达
nc -zv 192.168.1.10 18789