refactor/channel & ipc (#349)

Co-authored-by: paisley <8197966+su8su@users.noreply.github.com>
Co-authored-by: zuolingxuan <zuolingxuan@bytedance.com>

README.zh-CN.md

@@ -188,7 +188,7 @@ ClawX 内置了代理设置，适用于需要通过本地代理客户端访问
 
 ## 系统架构
 
-ClawX 采用 **双进程架构**，将 UI 层与 AI 运行时操作分离：
+ClawX 采用 **双进程 + Host API 统一接入架构**。渲染进程只调用统一客户端抽象，协议选择与进程生命周期由 Electron 主进程统一管理：
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
@@ -202,18 +202,29 @@ ClawX 采用 **双进程架构**，将 UI 层与 AI 运行时操作分离：
 │  │  • 自动更新编排                                               │  │
 │  └────────────────────────────────────────────────────────────┘  │
 │                              │                                    │
-│                              │ IPC                                │
+│                              │ IPC（权威控制面）                    │
 │                              ▼                                    │
 │  ┌────────────────────────────────────────────────────────────┐  │
 │  │              React 渲染进程                                   │  │
 │  │  • 现代组件化 UI（React 19）                                   │  │
 │  │  • Zustand 状态管理                                           │  │
-│  │  • WebSocket 实时通信                                         │  │
+│  │  • 统一 host-api/api-client 调用                               │  │
 │  │  • Markdown 富文本渲染                                        │  │
 │  └────────────────────────────────────────────────────────────┘  │
 └──────────────────────────────┬──────────────────────────────────┘
                                │
-                               │ WebSocket (JSON-RPC)
+                               │ 主进程统一传输策略
+                               │（WS 优先，HTTP 次之，IPC 回退）
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                  Host API 与主进程代理层                          │
+│                                                                  │
+│  • hostapi:fetch（主进程代理，规避开发/生产 CORS）                │
+│  • gateway:httpProxy（渲染进程不直连 Gateway HTTP）               │
+│  • 统一错误映射与重试/退避策略                                     │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+                               │ WS / HTTP / IPC 回退
                                ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │                     OpenClaw 网关                                 │
@@ -228,9 +239,11 @@ ClawX 采用 **双进程架构**，将 UI 层与 AI 运行时操作分离：
 ### 设计原则
 
 - **进程隔离**：AI 运行时在独立进程中运行，确保即使在高负载计算期间 UI 也能保持响应
-- **优雅恢复**：内置带指数退避的重连逻辑，自动处理瞬时故障
+- **前端调用单一入口**：渲染层统一走 host-api/api-client，不感知底层协议细节
+- **主进程掌控传输策略**：WS/HTTP 选择与 IPC 回退在主进程集中处理，提升稳定性
+- **优雅恢复**：内置重连、超时、退避逻辑，自动处理瞬时故障
 - **安全存储**：API 密钥和敏感数据利用操作系统原生的安全存储机制
-- **热重载**：开发模式支持即时 UI 更新，无需重启网关
+- **CORS 安全**：本地 HTTP 请求由主进程代理，避免渲染进程跨域问题
 
 ---