组件	描述
网关（守护进程）	维护提供商连接，公开 WS API
客户端	macOS 应用、CLI、Web UI 通过 WebSocket 连接
节点	macOS/iOS/Android/无头设备，使用 `role: node`
WebChat	使用网关 WS API 的静态 UI
Canvas 主机	提供代理可编辑的 HTML（默认端口 18793）

连接流程

客户端                    网关
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|
  |<------ res:agent --------|
  |<------ event:agent ------|

网关配置

基本配置

配置文件位置：~/.clawdbot/clawdbot.json

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token"
    },
    "reload": {
      "mode": "hybrid"
    }
  }
}

端口配置

端口优先级：

--port CLI 标志
CLAWDBOT_GATEWAY_PORT 环境变量
配置中的 gateway.port
默认：18789

认证

默认需要网关认证。设置方式：

配置中的 gateway.auth.token
CLAWDBOT_GATEWAY_TOKEN 环境变量
gateway.auth.password 用于密码认证

客户端必须发送 connect.params.auth.token 或 connect.params.auth.password。

热重载

配置热重载监视 ~/.clawdbot/clawdbot.json：

模式	描述
`hybrid`（默认）	热应用安全更改，关键更改时重启
`off`	禁用热重载

网关服务

HTTP 端点

网关在同一端口上提供多个 HTTP 端点：

端点	描述
`/v1/chat/completions`	OpenAI Chat Completions 兼容
`/v1/responses`	OpenResponses API
`/tools/invoke`	工具调用
Control UI	基于 Web 的仪表板

Canvas 主机

默认在端口 18793 启动，提供：

http://<gateway-host>:18793/__clawdbot__/canvas/

来自 ~/.clawdbot/workspace/canvas。禁用方式：

canvasHost.enabled: false
CLAWDBOT_SKIP_CANVAS_HOST=1

仪表板

访问 Control UI：

http://127.0.0.1:18789/

或运行：

clawdbot dashboard

远程访问

SSH 隧道（推荐）

ssh -N -L 18789:127.0.0.1:18789 user@host

客户端然后通过隧道连接到 ws://127.0.0.1:18789。

Tailscale/VPN

生产环境远程访问的首选方式。相同的握手 + 认证令牌适用。

网关管理

服务命令

# 检查状态
clawdbot gateway status

# 健康检查
clawdbot health

# 安全审计
clawdbot security audit --deep

# 停止网关
clawdbot gateway stop

监督

macOS：使用 LaunchAgent（bot.molt.<profile>）

Linux：使用 systemd 用户服务（clawdbot-gateway-<profile>.service）

Windows：使用 Windows 服务（Clawdbot Gateway (<profile>)）

多网关

通常不需要——一个网关可以服务多个频道和代理。仅在以下情况使用多个网关：

冗余
严格隔离（例如，救援机器人）

要求：

隔离状态 + 配置
使用唯一端口

线协议

传输

WebSocket，文本帧包含 JSON 有效负载
第一帧必须是 connect

消息类型

请求：

{"type": "req", "id": "...", "method": "...", "params": {...}}

响应：

{"type": "res", "id": "...", "ok": true, "payload": {...}}

事件：

{"type": "event", "event": "...", "payload": {...}, "seq": 1}

幂等性

对于有副作用的方法（send、agent），需要幂等性键以安全重试。

故障排除

网关无法启动

检查端口是否被占用：lsof -i :18789
查看日志：cat /tmp/clawdbot/gateway.log
使用 --force 终止现有监听器

连接问题

验证认证令牌匹配
检查网络连接
使用 --verbose 查看 WebSocket 握手日志

频道问题

检查频道状态：clawdbot channels status
重新认证频道：clawdbot channels login
查看频道特定日志

最佳实践

使用认证令牌：始终配置 gateway.auth.token 以确保安全
监控健康：定期检查 clawdbot health
使用监督：让 launchd/systemd 管理重启
备份配置：保留 ~/.clawdbot/clawdbot.json 的备份
查看日志：定期检查日志以发现问题

下一步

Clawdbot 设置指南 - 完整安装指南
Clawdbot WhatsApp 集成 - 连接到 WhatsApp
Clawdbot Telegram 集成 - 连接到 Telegram

Clawdbot 网关服务

Clawdbot 网关概述

什么是网关？

快速开始

启动网关

开发模式

网关架构

组件