Files

duanshuwen dfef9c90a5 feat: add gateway management features and settings

- Implemented new API routes for handling logs and settings related to the gateway.
- Added a new Gateway section in the General Settings panel to manage gateway status and auto-start options.
- Introduced a state management hook for gateway settings, including status, logs, and auto-start functionality.
- Updated configuration service to include gateway auto-start setting.
- Enhanced internationalization support for new gateway-related messages.
- Refactored existing settings store to accommodate new gateway settings.
- Cleaned up code and improved logging functionality.

2026-04-20 22:22:11 +08:00

13 KiB

Raw Blame History

Gateway 配置迁移计划

1. 目标与结论

目标是在 zn-ai/src/pages/Setting/components/GeneralSettingsPanel.tsx 中新增“网关配置”能力，并尽量复用 ClawX 已验证过的交互与主进程职责拆分。

先给结论：

ClawX 的网关设置不是单纯一段 UI，而是“设置持久化 + Gateway 生命周期管理 + Host API/IPC + 日志能力 + 调试能力”的完整链路。
zn-ai 当前已经具备一部分基础能力：/api/gateway/status|health|start|stop|restart、gateway:rpc、gateway:event、config-service、theme-service、updater。
zn-ai 当前缺少的是“网关设置模型”和“日志/文件夹打开/开发者辅助能力”，因此不能直接把 ClawX 的设置页 JSX 拷过来，必须先补设置域和主进程桥接。
推荐采用“两阶段迁移”：
- Phase 1：先落地面向普通用户的网关设置能力。
- Phase 2：再补开发者向的代理、令牌、诊断能力。

2. ClawX 功能盘点

2.1 已落地的网关设置功能

ClawX/src/pages/Settings/index.tsx 中的网关设置实际包含以下能力：

公共网关区块
- 状态徽标
- 端口展示
- 重启按钮
- 日志按钮
- 自动启动网关开关
开发者扩展区块
- 代理总开关
- 代理字段草稿编辑与一次性保存
- Control UI token 拉取与复制
- WS 诊断开关
- 额外的 CLI / Doctor / Telemetry Viewer

2.2 交互特征

状态展示依赖 useGatewayStore，不是页面自己轮询。
gatewayAutoStart 这类简单开关是“切换即持久化”。
代理配置是“本地 draft -> dirty 检测 -> save 一次性提交”。
日志是“按需读取最近 N 行”，不是预加载。
Control UI token 是“点击加载后显示”，不是默认常驻拉取。
开发者能力全部在 devModeUnlocked 后显示，普通用户默认不暴露。

2.3 主进程职责

ClawX 主进程里与网关设置直接相关的职责有：

settings store：持久化 gatewayAutoStart、代理、token、devModeUnlocked、telemetryEnabled`
gatewayManager：网关状态、启停、重启、健康检查、事件广播
settings routes / IPC：通用设置读写
gateway routes / IPC：生命周期与 Control UI 信息
logs routes / IPC：日志读取、日志目录打开
launch-at-startup：OS 级开机启动
proxy：Electron 代理应用与 Gateway 重启联动

3. zn-ai 当前现状

3.1 已有能力

zn-ai 目前已经有这些可复用基础：

设置页容器：src/pages/Setting/index.tsx
通用设置面板：src/pages/Setting/components/GeneralSettingsPanel.tsx
全局设置 store：src/stores/settings.ts
配置持久化：electron/service/config-service/index.ts
主题服务：electron/service/theme-service/index.ts
更新服务：src/pages/Setting/useSettingUpdateState.ts
Gateway Host API：
- GET /api/gateway/status
- GET /api/gateway/health
- POST /api/gateway/start
- POST /api/gateway/stop
- POST /api/gateway/restart
Gateway IPC：
- gateway:rpc
- gateway:event

3.2 关键差异

和 ClawX 相比，zn-ai 目前存在这些差异：

zn-ai 的 GeneralSettingsPanel 还是纯展示组件，没有 gateway props。
src/stores/settings.ts 只管理主题/语言/托盘/主色等字段，没有网关设置字段。
src/types/runtime.ts 和 ConfigValueMap 没有网关相关 key。
config-service 默认配置里没有网关设置默认值。
electron/api/router.ts 没有 /api/settings 与 /api/logs 这类本地设置/日志路由。
electron/service/logger/index.ts 负责写日志，但没有对 renderer 暴露“读取最近日志 / 获取日志目录”的能力。
electron/preload/index.ts 目前也没有 showItemInFolder 之类 shell 能力。
zn-ai/electron/gateway/manager.ts 当前更像 in-process bridge，状态维度只有 connected|disconnected|reconnecting，没有 ClawX 那种 running|starting|stopped|error + port + pid 的完整生命周期视图。

3.3 迁移判断

因此这次迁移不能按“页面复制”推进，而应该按下面的结构推进：

先补 zn-ai 的网关设置模型
再补主进程读写与日志能力
最后在 GeneralSettingsPanel 挂 UI

4. 推荐迁移范围

4.1 Phase 1：建议优先迁移

这些功能优先级最高，且对 GeneralSettingsPanel 最有价值：

网关状态展示
重启按钮
查看日志
自动启动网关开关
基础日志目录打开能力

原因：

这几项直接对应用户最常见的“网关是否可用、出问题怎么恢复、去哪看日志”。
它们对主进程改造要求相对集中。
能在不引入大量开发者专属复杂度的前提下快速产出。

4.2 Phase 2：建议作为增强能力

这些功能建议第二阶段进入：

代理配置
Control UI token 拉取与复制
WS 诊断开关
开发者模式开关
匿名使用数据开关

原因：

代理配置需要联动 Electron session、Gateway 重启，风险高于普通开关。
token / WS 诊断更偏开发与排障。
zn-ai 还没有 ClawX 同等级别的 Host API / preload / shell 白名单体系，直接硬迁会增加耦合。

4.3 Phase 3：建议暂不迁移

以下内容不建议一开始放入 GeneralSettingsPanel：

OpenClaw CLI 命令展示
OpenClaw Doctor
Telemetry Viewer

原因：

它们和 zn-ai 当前产品主线关联较弱。
实现成本明显高于用户价值。
会把通用设置页拉成调试控制台，不利于信息密度控制。

5. 功能映射方案

5.1 UI 映射

建议在 GeneralSettingsPanel 的“语言”与“版本更新”之间新增一个 Gateway section。

建议结构：

网关状态卡片
- 状态文案
- 当前模式/状态
- 可选端口展示
- 重启 按钮
- 日志 按钮
网关自动启动开关
- 标题
- 描述
- Toggle
可选高级区
- 仅在后续需要时加入
- 代理配置、token、诊断开关

5.2 状态层映射

推荐新增一个独立 hook，而不是把所有逻辑塞进 GeneralSettingsPanel：

src/pages/Setting/useGatewaySettingState.ts

职责：

读取 gatewayAutoStart
拉取 /api/gateway/status
执行 restartGateway()
读取日志文本
打开日志目录
管理本地 loading / error / lastFetchedAt

理由：

与现有 useSettingUpdateState.ts 保持模式一致
避免 GeneralSettingsPanel 过度膨胀
后续接入代理草稿状态更自然

5.3 配置模型映射

建议在 src/types/runtime.ts 和 runtime-shared/lib/constants.ts 统一补齐这些 key：

gatewayAutoStart
gatewayProxyEnabled
gatewayProxyServer
gatewayProxyHttpServer
gatewayProxyHttpsServer
gatewayProxyAllServer
gatewayProxyBypassRules
devModeUnlocked
telemetryEnabled

注意：

先只实现 gatewayAutoStart 也可以，但类型层最好一次补齐未来要用的 key，避免下一轮再改类型。
若担心一次性改动过大，也可以只先补 gatewayAutoStart，其余在 Phase 2 再补。

6. 主进程改造方案

6.1 配置持久化

需要修改：

electron/service/config-service/index.ts
src/types/runtime.ts
runtime-shared/lib/constants.ts

目标：

给网关配置提供默认值
让 renderer 和 main 对同一组 key 有一致类型

6.2 本地设置路由

建议新增：

electron/api/routes/settings.ts

并在 electron/api/router.ts 注册。

职责：

GET /api/settings
PUT /api/settings
GET /api/settings/:key
PUT /api/settings/:key

理由：

这样 zn-ai 可以和 ClawX 对齐成 “Host API 管理设置 + renderer store 初始化” 的模式。
后续代理设置和开发者开关也可以挂在这条线，不必每个设置都手写 IPC。

6.3 日志路由与 shell 能力

建议新增：

electron/api/routes/logs.ts
showItemInFolder 或等价 shell handler

至少需要：

GET /api/logs?tailLines=100
GET /api/logs/dir

主进程需要给 logger 增补：

读取当前/最近日志文件内容
返回日志目录

6.4 Gateway 生命周期适配

当前 zn-ai/electron/gateway/manager.ts 状态粒度不足，不一定要完全复制 ClawX，但至少要满足设置页展示。

建议最低改造目标：

checkHealth() 返回稳定状态快照
/api/gateway/status 的返回值包含可用于 UI 的状态字段
若暂时没有真实 port/pid，UI 层应允许缺省，不要强依赖

建议策略：

Phase 1 不强求对齐 ClawX 的 running|starting|stopped|error 全状态模型
先做 connected/disconnected/reconnecting 的 UI 映射
如果后面需要“运行中 / 已停止 / 错误”更细粒度状态，再扩 gatewayManager

7. 实施步骤

Milestone 0：建模

扩展 runtime config key 与类型
扩展 config-service 默认值
统一 renderer/main 的读写入口

Milestone 1：主进程桥接

新增 /api/settings
新增 /api/logs
新增打开日志目录能力
核对 gateway status/restart 路由输出是否满足 UI 需要

Milestone 2：设置状态层

新增 useGatewaySettingState.ts
将 gatewayAutoStart 纳入 settings store 或独立 hook
定义日志读取、重启、状态刷新行为

Milestone 3：渲染层

给 GeneralSettingsPanel 增加 gateway section
在 Setting/index.tsx 注入 gateway state
补齐中英日文案

Milestone 4：增强能力

代理 draft/save 模式
token 读取与复制
WS 诊断
dev mode / telemetry

8. 风险与注意点

zn-ai 当前 gateway manager 是 in-process 模式，和 ClawX 的独立进程 Gateway 生命周期不完全同构。
ClawX 的 gatewayPort 在设置模型里存在，但主流程未必实际使用；迁移时不要把“端口可编辑”误当成必须功能。
zn-ai 现在的 useSettingUpdateState 已经直接使用 get-config/update-config，说明 config key 在多个层定义并不完全一致；这次最好顺手补齐类型债。
若代理功能进入 Phase 1，会额外牵动 Electron session.setProxy、Gateway 重启、网络回归验证，建议放到 Phase 2。
如果没有 showItemInFolder，日志按钮只能先做“查看最近日志”，不能做“打开文件夹”。

9. Sub-agent 数量估算与分工

9.1 调研阶段

本次调研适合 3 个 explorer 并行：

ClawX 渲染层网关设置
ClawX 主进程 / IPC / 存储 / 日志
zn-ai 设置页与现有 Gateway 能力

9.2 开发阶段推荐数量

推荐 4 个 sub-agents 并行开发，不含主协调 agent。

如果要把联调/回归单独拆开，建议扩为 5 个。

9.3 推荐分工

Worker 1：渲染层 Gateway Panel

负责范围：

src/pages/Setting/components/GeneralSettingsPanel.tsx
src/pages/Setting/index.tsx
可选：src/pages/Setting/components/SectionHeader.tsx
src/i18n/messages.ts

职责：

新增 Gateway section
接好状态、按钮、空态、错误态、加载态
控制视觉层级，不让设置页变成调试面板

Worker 2：设置模型与状态层

负责范围：

src/types/runtime.ts
runtime-shared/lib/constants.ts
src/stores/settings.ts
新增 src/pages/Setting/useGatewaySettingState.ts

职责：

补齐 config key 与类型
统一 gatewayAutoStart 等字段的读取/写入
为渲染层提供稳定 state API

Worker 3：主进程设置/日志桥接

负责范围：

electron/api/router.ts
新增 electron/api/routes/settings.ts
新增 electron/api/routes/logs.ts
electron/service/config-service/index.ts
electron/service/logger/index.ts
electron/preload/index.ts

职责：

暴露本地 settings route
暴露 logs route
补 shell 打开目录能力
打通 renderer <-> main 的配置和日志桥

Worker 4：Gateway 生命周期适配

负责范围：

electron/gateway/manager.ts
electron/api/routes/gateway.ts
electron/main.ts
可选：新增更细的 gateway status typing

职责：

校准状态返回结构
保证 restart/status/health 对设置页可用
如果需要，补自动启动策略与更清晰的状态快照

9.4 可选第 5 个 sub-agent

若要提高并行度，可增加一个 QA / Integration worker：

回归设置页、更新页、主题、语言、日志
检查 config key 兼容性
覆盖“无网关 / 重启中 / 读日志失败 / 配置缺省值”场景

10. 建议的开工顺序

建议按以下顺序派发任务：

Worker 2 先补类型与设置模型
Worker 3 并行补 settings/logs 路由与 logger 能力
Worker 4 校准 gateway 状态输出
Worker 1 在前 3 者接口稳定后接 UI

这样可以减少渲染层返工。

11. 本轮建议

如果下一步直接进入开发，我建议按以下范围作为第一批提交：

gatewayAutoStart
gateway 状态展示
restart 按钮
日志查看
日志目录打开

把代理、token、WS 诊断放到第二批。

13 KiB Raw Blame History Unescape Escape

Gateway 配置迁移计划

1. 目标与结论

2. ClawX 功能盘点

2.1 已落地的网关设置功能

2.2 交互特征

2.3 主进程职责

3. zn-ai 当前现状

3.1 已有能力

3.2 关键差异

3.3 迁移判断

4. 推荐迁移范围

4.1 Phase 1：建议优先迁移

4.2 Phase 2：建议作为增强能力

4.3 Phase 3：建议暂不迁移

5. 功能映射方案

5.1 UI 映射

5.2 状态层映射

5.3 配置模型映射

6. 主进程改造方案

6.1 配置持久化

6.2 本地设置路由

6.3 日志路由与 shell 能力

6.4 Gateway 生命周期适配

7. 实施步骤

Milestone 0：建模

Milestone 1：主进程桥接

Milestone 2：设置状态层

Milestone 3：渲染层

Milestone 4：增强能力

8. 风险与注意点

9. Sub-agent 数量估算与分工

9.1 调研阶段

9.2 开发阶段推荐数量

9.3 推荐分工

Worker 1：渲染层 Gateway Panel

Worker 2：设置模型与状态层

Worker 3：主进程设置/日志桥接

Worker 4：Gateway 生命周期适配

9.4 可选第 5 个 sub-agent

10. 建议的开工顺序

11. 本轮建议

13 KiB

Raw Blame History