网关总览
网关是 Moltbot 的核心——一个常驻服务，拥有你的消息连接（WhatsApp、Telegram 等）并处理聊天频道与代理之间的所有编排。
可以把它理解为指挥家：监听入站消息、路由到正确的代理会话、流式回传响应，并在你不活跃聊天时仍保持一切连接。
功能
- 维持与消息平台的持久连接（WhatsApp 用 Baileys、Telegram 用 Bot API 等）
- 为 CLI、应用与远程节点暴露 WebSocket 控制平面
- 提供 HTTP 端点：OpenAI 兼容 API、webhook、控制 UI
- 管理代理会话、消息队列与投递
- 处理配置热重载与进程内重启（多数变更无需停机）
入口：moltbot gateway
本地运行
简单启动：
moltbot gateway就这样。网关默认绑定到 127.0.0.1:18789 并运行直到停止。
带选项：
# 使用不同端口
moltbot gateway --port 19000
# 调试模式（将所有日志事件镜像到控制台）
moltbot gateway --verbose
# 先强制终止占用端口的进程，再启动
moltbot gateway --force
# 开发模式（代码变更时自动重载）
pnpm gateway:watch网关监视配置文件（默认 ~/.clawdbot/moltbot.json）并热重载安全变更。关键变更会通过 SIGUSR1 触发自动进程内重启。
若希望手动控制可设置 gateway.reload.mode="off" 关闭热重载。
认证
默认即使在 localhost 上网关也需要认证。设置 token 或密码：
# 在设置期间生成 token
moltbot setup
# 或手动设置
export CLAWDBOT_GATEWAY_TOKEN="your-secret-token"然后配置客户端（CLI、应用、节点）在 WebSocket 握手中包含 auth.token。
**Tailscale 用户：**若使用 Tailscale Serve 且设置 gateway.auth.allowTailscale: true，来自 tailnet 的请求可通过 Tailscale 身份头认证，无需 token。
远程访问
推荐：Tailscale 或 VPN
保持网关私有。使用 Tailscale 从任何地方访问，无需向互联网暴露端口。
完整指南见 Tailscale 设置。
替代：SSH 隧道
若无法使用 Tailscale，可通过 SSH 建立隧道：
ssh -N -L 18789:127.0.0.1:18789 user@remote-host然后将 CLI 连接到 ws://127.0.0.1:18789，就像网关在本地一样。
多网关（通常不需要）
一个网关可轻松处理多个消息频道与代理。仅在以下情况需要多网关：
- 冗余（当主设置损坏时保持在线的救援机器人）
- 严格隔离（分离生产与开发环境）
若采用此方式，需隔离状态目录、配置文件与端口。
模式与示例见 多网关。
Dev 配置（隔离测试）
想在不影响生产设置的前提下测试变更？使用 --dev：
moltbot --dev setup
moltbot --dev gateway --allow-unconfigured
moltbot --dev statusdev 配置使用隔离的目录与端口：
- 配置：
~/.clawdbot-dev/moltbot.json - 状态：
~/.clawdbot-dev/ - 工作区：
~/clawd-dev/ - 端口：
19001（主配置为18789）
与主网关无冲突。
服务管理
安装为系统服务：
# macOS (launchd)
moltbot gateway install
# Linux（systemd 用户服务）
moltbot gateway install
sudo loginctl enable-linger $USER
# 检查状态
moltbot gateway status控制：
moltbot gateway start
moltbot gateway stop
moltbot gateway restart
moltbot logs --follow网关作为受监管服务运行（macOS 用 launchd，Linux 用 systemd）。崩溃时监管程序会自动重启。
服务名称
服务使用配置感知命名：
- macOS：
bot.molt.gateway（或bot.molt.<profile>） - Linux：
moltbot-gateway.service（或moltbot-gateway-<profile>.service）
systemd（Linux/WSL2）
默认 Moltbot 安装用户服务（单用户机器更简单）。对常驻服务器可改用系统服务。
用户服务（默认）：
moltbot gateway install
sudo loginctl enable-linger $USER
systemctl --user enable --now moltbot-gateway.service系统服务（多用户/常驻）：
创建 /etc/systemd/system/moltbot-gateway.service 并设置适当的 User= 与 WorkingDirectory=，然后：
sudo systemctl daemon-reload
sudo systemctl enable --now moltbot-gateway.service单元文件示例见 后台进程。
端点与端口
网关在单一端口（默认 18789）上多路复用所有内容：
- WebSocket（
/）——CLI、应用与节点的主控制平面 - HTTP API：
/v1/chat/completions——OpenAI 兼容聊天 API/v1/responses——OpenResponses API/tools/invoke——直接工具调用
- 控制 UI（web 仪表板，若启用）
- Canvas 文件服务器（默认
18793，独立端口）——在/__moltbot__/canvas/提供~/clawd/canvas
浏览器控制使用派生端口：
- 控制服务：网关端口 + 2（如
18791） - 扩展中继：网关端口 + 3（如
18792） - 浏览器配置在
18800–18899范围自动分配 CDP 端口
通过 --port、CLAWDBOT_GATEWAY_PORT 或配置中的 gateway.port 修改基础端口。
协议基础
客户端通过 WebSocket 连接，须先发送 connect 请求：
{
"type": "req",
"id": "1",
"method": "connect",
"params": {
"minProtocol": 7,
"maxProtocol": 7,
"client": {
"id": "cli-abc123",
"version": "1.0.0",
"platform": "darwin",
"mode": "operator"
},
"auth": {
"token": "your-gateway-token"
}
}
}网关回复 hello-ok 负载，包含 presence、health 与配置快照——无需额外请求即可渲染状态。
握手后：
- 请求遵循
{type:"req", id, method, params}→{type:"res", id, ok, payload}模式 - 事件推送为
{type:"event", event, payload}
常见事件：agent（流式工具输出）、presence（已连接者）、tick（保活）、shutdown（网关重启）。
完整规范见 网关协议。
关键方法
health——完整系统健康快照status——快速摘要agent——运行一轮代理（流式回传事件）send——经频道发送消息system-presence——列出已连接客户端node.*——发现、配对与控制远程节点cron.*——管理定时任务
配置热重载
网关监视 moltbot.json 的变更。当你保存时：
- 安全变更（白名单、阈值、功能开关）立即生效
- 关键变更（频道凭证、绑定地址）触发自动重启
默认模式为 "hybrid"。设置 gateway.reload.mode="off" 可完全关闭。
进程内重启
发送 SIGUSR1 可在不停机的前提下重启：
kill -USR1 $(pgrep -f "moltbot gateway")或从代理使用 gateway 工具：
{
"tool": "gateway",
"action": "restart",
"delayMs": 2000
}重启会先完成当前代理运行、广播 shutdown 事件、重新加载一切，并在数秒内恢复。
运维健康检查
存活性：
- 能否打开到网关端口的 WebSocket？
connect请求是否收到hello-ok响应？
就绪性：
health是否返回ok: true？- 主消息频道是否已链接？（检查 health 负载中的
linkChannel）
监控：
- 订阅
presence事件——若停止接收更新说明有问题 - 监视
shutdown事件（计划重启 vs. 崩溃） - 检查
status的代理队列深度与错误计数
安全态势
- 默认绑定到 localhost（
127.0.0.1:18789）——仅本地进程可连接 - 即使在回环也需要认证——无未认证访问
- 使用 Tailscale Serve 进行远程访问（基于身份的认证、加密隧道）
- 避免公网暴露——不要在没有强认证与防火墙的情况下绑定到
0.0.0.0
确实需要远程访问时：
- Tailscale Serve/Funnel（推荐）
- SSH 隧道（回退）
- VPN（wireguard 等）
永远不要将网关端口直接暴露到互联网。
威胁模型与加固检查清单见 安全。
故障排查
网关无法启动：
- 检查端口是否已被占用：
lsof -i :18789 - 使用
moltbot gateway --force终止现有监听器 - 检查日志：
moltbot logs或~/.clawdbot/logs/gateway.log
CLI 无法连接：
- 验证网关是否运行：
moltbot gateway status - 检查 auth token 是否匹配：
echo $CLAWDBOT_GATEWAY_TOKEN - 尝试用显式 URL 连接：
moltbot --url ws://127.0.0.1:18789 status
频道未链接：
- WhatsApp：运行
moltbot setup并扫描 QR 码 - Telegram：检查
channels.telegram.accounts并验证 bot token - 运行
moltbot doctor进行健康审计
完整运维手册见 故障排查。