Clawline Gateway

Clawline 的 WebSocket 消息中继网关 + 管理端，负责 Agent ↔ Client 通信、Channel/User 管理、认证和消息持久化。

概述

Clawline Gateway 是 Clawline 产品族的后端中枢，提供 WebSocket 消息中继、管理端 UI、认证集成和数据持久化。最初由 gatewaybot（已淡出）开发，现由 clawline-client-web Bot 统一维护。

项目信息

属性	值
仓库	`clawline/gateway`
技术栈	Node.js + React 19 + Vite 6 + Tailwind v4 + shadcn/ui
生产环境	https://gateway.clawlines.net
开发环境	https://gw.dev.dora.restry.cn
开发端口	前端 3020 + 后端 3021
现维护 Bot	clawline-client-web Bot（原 gatewaybot 已淡出）

架构

消息中继

Gateway 作为 WebSocket 中继层，连接 OpenClaw Agent 和各客户端（Web、微信小程序等）：

Client (Web/WeChat) ←→ Gateway (WS Relay) ←→ OpenClaw Agent

心跳机制：客户端 30s 间隔 ping，Gateway 回复 pong（commit fc02056 修复）
容错：允许 2 次未回复再判定超时
断点续传：客户端断连后通过 stream.resume 恢复流式内容

管理端 UI (admin-new)

科幻风格三层架构：

层级	内容	说明
TIER_1	Gateway 状态概览	channels、backend links、live clients
TIER_2	Channel 管理	水果命名 + emoji 图标（🥭 mango、🍒 cherry）
TIER_3	User 配置	动物命名（falcon、octopus）

功能：Channel/User CRUD、自动刷新(5s)、连接 URL 生成（openclaw://connect?serverUrl=...）

shadcn/ui 重构

引入 Button/Dialog/Input/Table 组件，App.tsx 从 2000+ 行拆分到 <200 行。

认证系统

完成了三代认证方案演进：

版本	方案	说明
V1	Admin Token 手动输入	`X-Relay-Admin-Token` header
V2	Logto SSO + Admin Token	二次认证
V3 (最终)	Logto SSO → JWT	`Authorization: Bearer` + 后端 JWKS 验证

Logto 配置：

属性	值
SPA App ID	`anbr9zjc6bgd8099ecnx3`
API Resource	`https://gateway.clawlines.net/api`
JWKS Endpoint	`https://logto.dr.restry.cn/oidc/jwks`

详见 logto-sso。

数据持久化 (Supabase)

从本地 data/relay-config.json 迁移到 Supabase PostgreSQL：

表	用途
`cl_channels`	Channel 配置
`cl_channel_users`	Channel 用户

API 演进：/pg/query → /pg/rest/v1（因 PostgREST schema cache 未刷新，REST API 曾返回 404）。

消息持久化已验证（Supabase 有真实消息记录）。

CI/CD

GitHub Actions：移除 tarball 打包（tar “file changed” 竞态问题），只保留 Docker 镜像构建
关键提交：7b27b65(UI 集成)、3696159(JWT 认证)、87da32b(Supabase 存储)、2e5fb54(UI 审计修复)

UI 审计历史

经历完整三轮 UI 审计修复：

轮次	技能	修复内容
Round 1	/harden	Focus indicators、WCAG AA 对比度、Modal Escape、触摸目标 44px+
Round 2	/typeset + /distill	字体大小 10px→12px、Header 简化、移除装饰性动画
Round 3	/normalize	CSS 变量设计令牌、sans/mono 字体统一（47→13 处）

全流程测试记录

researcher agent 通过 Claude Code CLI 进行本地测试：

功能	结果
Admin UI	✅
AI Settings GET/PUT	✅
Suggestions API	✅ 返回 7 条建议
Voice Refine API	✅ 语音转写清理
消息持久化	✅ Supabase 有真实消息

Bug：max_tokens → max_completion_tokens 兼容性问题（GPT-5.4-mini），commit 12bb93d 修复。

部署迁移（2026-04-06）

gw.dev.dora.restry.cn 管理端经历了一次重大迁移：

原状：pm2 dev-gw 从旧的 workspace-clawline-gateway/repo/admin/dist serve 静态文件
根因：research agent build 到了错误目录
迁移：切换到 workspace-clawline-client-web/gateway-repo/public，从独立 gateway 仓库转移到 clawline-client-web Bot 管辖
遗留：旧版 Logto token 残留导致白屏，需手动清除浏览器 logto 缓存

时间线

日期	事件
2026-03-17	GatewayBot 上线，完成 admin-new UI 集成
2026-03-18	Logto SSO + JWT 全流程、Supabase 迁移
2026-03-20	三轮 UI 审计修复、响应式布局
2026-03-21	shadcn/ui 重构，App.tsx 拆分
2026-04-06	管理端部署迁移到 clawline-client-web Bot 管辖
2026-04-08	Gateway 代码整理提交（DESIGN.md、server.js、schema.sql）

2026-04-11 更新：POST /api/chat 端点与虚拟连接

POST /api/chat 端点设计

新增 HTTP API 端点 POST /api/chat，支持外部通过 REST API 方式向已注册 Agent 发送消息并接收回复，类似之前 Mattermost 的 API 机器人交互方式。

核心设计：通过「虚拟连接」模拟 WebSocket 客户端，使后端 Channel 插件完全感知不到这是 API 调用还是真实 WS 客户端。

请求参数

{
  "channelId": "string",     // 必填
  "chatId": "string",        // 可选
  "senderId": "string",      // 可选
  "agentId": "string",       // 可选
  "message": "string",       // 必填
  "timeout": 30000           // 可选，默认 30s
}

虚拟连接机制

创建临时 connectionId（randomUUID()）
注册到 clientConnections，ws: null（无真实 WebSocket）
用 EventEmitter 作为 _apiCallback 收集回复
向 backend 发 relay.client.open + relay.client.event (message.receive)
等待 message.send 回复或超时
清理虚拟连接，发 relay.client.close

server.js 改动清单（3 处，~80 行）

改动点	位置	行数	说明
`POST /api/chat` handler	HTTP 路由区（~1590行后）	~70行	新增端点
`relay.server.event` 分发	~989行	~8行	加 `_apiCallback` 分支
`closeSocket` 空值守卫	~636行	1行	防 null ws

API Source 标识（meta.source）

API 调用的消息通过 meta.source = "api" 字段贯穿全链路：

POST /api/chat → relay.client.event 携带 source:"api"
→ channel 插件透传给 agent
→ agent 回复时 meta.source 透传
→ persistMessageAsync 存入 cl_messages.meta
→ 前端渲染时读取 meta.source 展示标识

全链路改动汇总

文件	改动	行数
`gateway-repo/server.js`	closeSocket守卫 + apiCallback分支 + POST /api/chat handler，inbound meta.source	~80行
`channel-repo/src/generic/bot.ts` 或 `send.ts`	透传 meta.source 到回复	~8行
`repo/src/components/chat/types.ts`	Message 加 meta 字段	2行
`repo/src/screens/ChatRoom.tsx`	解析 meta 字段	5行
`repo/src/components/chat/MessageItem.tsx`	渲染 API 标识 badge	10行

关键决策：Channel 插件、Client-Web、SDK 都不需要改核心逻辑 — 虚拟连接走标准 relay 协议。

🔮 Dora's Wiki

探索

Clawline Gateway

Clawline Gateway

概述

项目信息

架构

消息中继

管理端 UI (admin-new)

shadcn/ui 重构

认证系统

数据持久化 (Supabase)

CI/CD

UI 审计历史

全流程测试记录

部署迁移（2026-04-06）

时间线

相关主题

2026-04-11 更新：POST /api/chat 端点与虚拟连接

POST /api/chat 端点设计

请求参数

虚拟连接机制

server.js 改动清单（3 处，~80 行）

API Source 标识（meta.source）

全链路改动汇总

关系图谱

目录

反向链接