QClaw客户端架构与Queue Guard排队机制探索

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

QClaw Electron (桌面客户端)
├── UI 界面（对话、设置、工作流）
├── 进程管理（启动/停止/守护 OpenClaw Gateway）
├── 认证管理（登录、JWT token、GUID）
├── 资源调度（queue-guard 的排队接口）
└── 配置管控（写入/覆盖 openclaw.json 的部分字段）

OpenClaw Gateway (AI Agent 运行时)
├── Agent 管理（main、写作助手、代可行等）
├── 会话管理（session、对话历史）
├── 插件系统（queue-guard、skill-interceptor 等）
├── 工具调用（exec、browser、web\_search 等）
├── 渠道接入（微信、webchat 等）
└── 配置读取（openclaw.json）

1
2
3
4
5
6
7
8
9

QClaw Electron 启动
 ↓
注入环境变量（QCLAW\_USER\_GUID、QCLAW\_USER\_ID、QCLAW\_LLM\_BASE\_URL 等）
 ↓
写入/同步 openclaw.json（可能会覆盖 AI 修改的字段）
 ↓
拉起 OpenClaw Gateway 子进程
 ↓
Gateway 加载配置、注册插件、开始服务

1
2
3
4
5
6
7
8
9

用户登录 QClaw 账号
 ↓
Electron 获取 JWT token → AES-128-CBC 加密
 ↓
通过 HTTP endpoint 推送给 queue-guard 插件
 ↓
queue-guard 解密后用于排队接口认证
 ↓
排队通过 → LLM 请求带上原始 token

1
2
3
4
5
6
7
8
9

用户发消息 → OpenClaw Gateway
 ↓
queue-guard 拦截 fetch
 ↓
调用 QClaw 后端排队接口（命令字 4158）
 ↓
QClaw 后端根据全局负载决定排队/放行
 ↓
放行 → 真实 LLM 请求发出

1
2
3
4

OpenClaw 日志 → C:\\Users\\you\\.qclaw\\logs\\openclaw\\
 ├── \config-audit.jsonl （记录配置写入审计 每次openclaw.json变更的时间、进程、hash、字节数等）
 ├── \*.log （早期未加密）
 └── \*.enc （当前 AES 加密，AI 无法读取）

1
2
3
4
5
6
7
8
9

AI 通过 config.patch 写入 queue.mode = "queue"
 ↓
Gateway 重启（SIGUSR1）
 ↓
QClaw Electron 检测到 Gateway 重启
 ↓
Electron 重新同步 openclaw.json（覆盖为客户端默认值 followup）
 ↓
结果：修改被还原

1

C:\\Program Files\\QClaw\\resources\\openclaw\\config\\openclaw.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

QClaw Electron 启动
 ↓
读取默认模板：C:\\Program Files\\QClaw\\resources\\openclaw\\config\\openclaw.json
 ↓
替换 ${...} 占位符为实际值（token、guid、userId 等）
 ↓
与用户配置：C:\\Users\\youfo\\.qclaw\\openclaw.json 合并
 ↓
写入用户配置（模板中声明的字段会覆盖 AI 的修改）
 ↓
拉起 OpenClaw Gateway

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

用户发消息
 ↓
OpenClaw 准备调用 LLM（llm\_input 钩子记录 sessionKey）
 ↓
fetch 拦截器检测到 LLM 请求（model 含 "modelroute"）
 ↓
每 2 秒轮询后端排队接口（命令字 4158）
 ↓
┌─ 资源可用 → 放行真实请求 → 正常对话
├─ 超时 120s → fail-open 直接放行 → 不阻塞用户
└─ 用户中止（点停止）→ 返回伪造响应 → "当前为高峰期，已为您暂停任务。"

1
2
3
4
5
6
7
8
9

你发消息 → queue-guard 开始排队（等待模型资源）
 ↓（排队中，还没到）
你又发了消息 / UI 超时重试
 ↓
followup 模式取消上一个排队中的请求
 ↓
queue-guard 返回伪造响应（"当前为高峰期..."）
 ↓
webchat UI 收到 abort 信号，消息闪现后消失