@next-open-ai/openclawx 0.8.10 → 0.8.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 windwithlife
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,56 @@
 # OpenClawX
+
 基于自已的OpenBot重构而来
+
 [![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**一个桌面级OpenClaw实现** 是基于 Agent Skills的**一体化 AI 助手平台**，核心部分支持 CLI、WebSocket 网关与桌面端。除提供可自我升级扩展的 AI Agent 引擎及多通道、多终端接入外，后续将支持 MCP 以降低 Token 消耗与大模型幻觉，并接入现有AI Agent 生态，成为一个互联互通的Agent平台。
+---
+
+## 📚 文档导航
+
+完整使用说明请进入 **[使用文档入口](docs/README.md)**。文档结构如下：
+
+| 分类 | 文档 | 说明 |
+|------|------|------|
+| **入门** | [快速开始](docs/guides/getting-started.md) | 5 分钟跑通：安装、首次对话、桌面/通道入口 |
+| | [安装与部署](docs/guides/installation.md) | npm、Docker、Desktop 安装包及环境要求 |
+| **使用指南** | [CLI 使用](docs/guides/cli-usage.md) | 命令行对话、登录、模型与技能、开机自启 |
+| | [桌面端使用](docs/guides/desktop-usage.md) | Desktop 安装与启动、智能体/会话/技能/设置 |
+| | [Web 与 Gateway](docs/guides/gateway-web.md) | 启动网关、端口与路径、Web 端连接 |
+| **配置** | [配置概览](docs/configuration/config-overview.md) | 配置目录、config.json 与 agents.json |
+| | [智能体配置](docs/configuration/agents.md) | 本机/Coze/OpenClawX 执行方式与模型 |
+| | [通道配置](docs/configuration/channels.md) | 飞书、钉钉、Telegram 启用与配置项 |
+| **功能说明** | [代理模式与多节点](docs/features/proxy-mode.md) | Coze 接入、OpenClawX 多节点协作 |
+| | [技能系统](docs/features/skills.md) | Agent Skills 规范与扩展 |
+| **参考** | [常见问题](docs/reference/faq.md) | 安装失败、端口占用、通道不回复等 FAQ |
+
+<details>
+<summary><strong>📂 文档树结构</strong></summary>
+
+```
+docs/
+├── README.md                   → 文档入口与导航
+├── guides/                     → 使用指南
+│   ├── getting-started.md      快速开始
+│   ├── installation.md         安装与部署
+│   ├── cli-usage.md            CLI 使用
+│   ├── desktop-usage.md        桌面端使用
+│   └── gateway-web.md          Web 与 Gateway
+├── configuration/              → 配置说明
+│   ├── config-overview.md      配置概览
+│   ├── agents.md              智能体配置
+│   └── channels.md            通道配置（飞书/钉钉/Telegram）
+├── features/                   → 功能说明
+│   ├── proxy-mode.md          代理模式与多节点协作
+│   └── skills.md              技能系统
+├── reference/                  → 参考
+│   └── faq.md                 常见问题
+└── channel-streaming-design.md 通道流式设计（开发参考）
+```
+
+</details>
 
 ---
 
@@ -18,8 +64,10 @@
 | **长期记忆** | 向量存储（Vectra）+ 本地嵌入，支持经验总结与会话压缩（compaction） |
 | **多端接入** | CLI、WebSocket 网关、Electron 桌面端，同一套 Agent 核心；各端技术栈见下方「各端技术栈」 |
 | **多通道接入** | 飞书、钉钉、Telegram 等 IM 通道，Gateway 根据配置注册；入站经统一格式进 Agent，回复经通道回传 |
+| **代理模式** | 智能体执行方式可选 **本机** / **Coze** / **OpenClawX**；本机使用当前模型与 Skills，代理则将对话转发至对应平台 |
+| **Coze 接入** | 支持 Coze 国内站（api.coze.cn）与国际站（api.coze.com）；按站点分别配置 Bot ID 与 Access Token（PAT/OAuth/JWT），桌面端与通道均可选用 Coze 智能体 |
+| **OpenClawX 多节点协作** | 可将智能体代理到另一台 OpenClawX 实例（baseUrl + 可选 API Key），实现多节点分工、负载与协作 |
 | **MCP（规划中）** | 为降低 Token 消耗与大模型幻觉，后续将支持 MCP（Model Context Protocol） |
-| **生态接入（规划中）** | 接入现有 AI Agent 生态，下一步计划接入 Coze 生态 |
 
 ---
 
@@ -45,14 +93,17 @@
 ┌─────────────────┐    ┌─────────────────────────────┐    ┌─────────────────────┐
 │  Agent 核心      │    │  Desktop Backend (NestJS)   │    │  Memory / 向量存储   │
 │  AgentManager   │    │  server-api/*               │    │  Vectra + 嵌入       │
-│  pi-coding-agent│    │  Agents · Skills · Tasks    │    │  compaction 扩展     │
-│  pi-ai 多模型   │    │  Auth · Users · Workspace   │    │  sql.js              │
+│  执行方式:      │    │  Agents · Skills · Tasks    │    │  compaction 扩展     │
+│  local/coze/    │    │  Auth · Users · Workspace   │    │  sql.js              │
+│  openclawx(代理)│    │                             │    │                     │
+│  pi-coding-agent│    │                             │    │                     │
+│  pi-ai 多模型   │    │                             │    │                     │
 └────────┬────────┘    └─────────────────────────────┘    └─────────────────────┘
          │
          ▼
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │  Tools: read/write/edit · bash · find/grep/ls · browser · install-skill ·   │
-│         save-experience (写入记忆)                                            │
+│         save-experience (写入记忆) · Proxy(local/coze/openclawx)             │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -60,121 +111,18 @@
 - **WebSocket Gateway**（`src/gateway/`）：单进程内嵌 Nest，对外提供 WebSocket（JSON-RPC）与 HTTP；按 path 分流：`/server-api` 走 Nest、`/ws` 为 Agent 对话、`/ws/voice`/`/sse`/`/channel` 为扩展占位，其余为静态资源。根据配置注册**飞书、钉钉、Telegram** 等通道，入站消息经统一格式进入 Agent，回复经该通道发回对应平台。供 Web/移动端连接；支持以开机/登录自启方式常驻（Linux cron、macOS LaunchAgent、Windows 计划任务）。
 - **Desktop 后端**（`src/server/`）：NestJS HTTP API，即 **server-api**；可被 Gateway 内嵌或独立监听（默认端口 38081）。会话、智能体配置、技能、任务、工作区、鉴权等由本模块提供。
 - **Desktop**：Electron 包一层 Vue 前端 + 上述后端；通过 Gateway 或直连 Desktop 后端与 Agent 通信。
-- **Agent 核心**：统一由 `AgentManager` 管理会话、技能注入与工具注册；记忆与 compaction 作为扩展参与 system prompt 与经验写入。
-
-### 项目目录结构
-
-```
-openbot/
-├── src/                    # 源码（构建输出 dist/）
-│   ├── core/               # 公共核心，CLI 与 Gateway 共用
-│   │   ├── agent/          # AgentManager、run、技能与配置
-│   │   ├── config/         # 桌面配置（~/.openbot/desktop）
-│   │   ├── memory/         # 向量存储、嵌入、compaction
-│   │   ├── installer/      # 技能安装
-│   │   └── tools/          # 内置工具（browser、install-skill、save-experience 等）
-│   ├── cli/                # CLI 入口与 service 子命令
-│   │   ├── cli.ts          # 主入口，构建为 dist/cli/cli.js
-│   │   └── service.ts      # 开机自启 install/uninstall/stop
-│   ├── gateway/            # WebSocket 网关（内嵌 Nest、path 分流）
-│   ├── server/             # Desktop 后端（NestJS）
-│   ├── cli.ts              # 兼容入口，仅转发到 cli/cli.js
-│   └── index.ts            # 包导出
-├── apps/
-│   ├── desktop/            # Electron + Vue 桌面端
-│   ├── web/                # 预留
-│   ├── mobile/             # 预留
-│   ├── miniprogram/        # 预留
-│   └── browser-extension/  # 预留
-├── deploy/                 # Docker、K8s 等部署
-├── test/                   # 单元与 e2e 测试
-├── examples/               # 示例（含 workspace、gateway-client）
-└── skills/                 # 内置技能（find-skills、agent-browser）
-```
-
-### 目录与模块对应
-
-| 目录 | 说明 |
-|------|------|
-| `src/core/` | **公共核心**：`agent/`（AgentManager、pi-coding-agent）、`config/`（桌面配置）、`memory/`、`installer/`、`tools/`；CLI 与 Gateway 共用。 |
-| `src/cli/` | **CLI**：`cli.ts` 主入口（构建为 `dist/cli/cli.js`），`service.ts` 提供开机自启（install/uninstall/stop）。 |
-| `src/gateway/` | **WebSocket 网关**：单进程内嵌 Nest，按 path 分流：`/server-api`、`/ws`、`/ws/voice`、`/sse`、`/channel`、`/health`、静态资源（`apps/desktop/renderer/dist`）；通道适配（feishu、dingtalk、telegram）在 `channel/adapters/`。 |
-| `src/server/` | **Desktop 后端**（NestJS），HTTP API 前缀 `server-api`；可内嵌到 Gateway 或独立监听。 |
-| `apps/desktop/` | **桌面端**（Electron + Vue），前端构建产物由 Gateway 提供。 |
-| `deploy/` | Dockerfile、K8s 等部署配置。 |
-| `test/` | 单元与 e2e 测试（config、gateway、server、installer）。 |
-| `examples/` | 示例工作区、gateway 客户端等。真实工作区根目录为 `~/.openbot/workspace/`。 |
-| `skills/` | 内置技能（SKILL.md 规范）。 |
-
----
+- **Agent 核心**：统一由 `AgentManager` 管理会话、技能注入与工具注册；**执行方式**可为 **local**（本机 pi-coding-agent + Skills）、**coze**（代理至 Coze 国内/国际站）、**openclawx**（代理至其他 OpenClawX 节点，多节点协作）。记忆与 compaction 作为扩展参与 system prompt 与经验写入。
 
 ## 各端技术栈
 
-### CLI
-
-| 类别 | 技术 |
-|------|------|
-| 运行时 | Node.js 20+ |
-| 语言 | TypeScript 5.7 |
-| 入口 | `openbot`（bin → `dist/cli/cli.js`） |
-| 框架 | Commander（子命令：`gateway`、`login`、`config`、`service`） |
-| 配置 | `~/.openbot/agent`（API Key、模型、技能等）；`~/.openbot/desktop`（与桌面共用） |
-| 开机自启 | `openbot service install` / `uninstall`（Linux cron、macOS LaunchAgent、Windows 计划任务）；`openbot service stop` 停止当前 gateway |
-
-### WebSocket Gateway
-
-| 类别 | 技术 |
+| 端 | 技术 |
 |------|------|
-| 协议 | JSON-RPC over WebSocket（`ws`） |
-| 端口 | 默认 38080，可 `-p` 指定 |
-| 架构 | 单进程内嵌 Nest；按 path 分流：`/server-api`、`/ws`、`/ws/voice`、`/sse`、`/channel`、`/health`、静态资源 |
-| 职责 | 连接管理、消息路由、鉴权钩子、静态资源（Desktop 前端） |
-| 方法 | `connect`、`agent.chat`、`agent.cancel`、`subscribe_session`、`unsubscribe_session` 等 |
-
-### Agent 核心
-
-| 类别 | 技术 |
-|------|------|
-| 智能体 | @mariozechner/pi-coding-agent |
-| 模型/Provider | @mariozechner/pi-ai（DeepSeek、DashScope、OpenAI 等） |
-| 工具 | read/write/edit、bash、find/grep/ls、browser、install-skill、save-experience |
-| 技能 | SKILL.md 规范，多路径加载，formatSkillsForPrompt 注入 system prompt |
-
-### Desktop 后端（NestJS）
-
-| 类别 | 技术 |
-|------|------|
-| 框架 | NestJS 10、Express、Socket.io |
-| 前缀 | `server-api` |
-| 模块 | Database · Agents · AgentConfig · Skills · Config · Auth · Users · Workspace · Tasks · Usage |
-| 数据 | sql.js（SQLite WASM，无需预编译） |
-
-### Desktop 前端（Electron + Vue）
-
-| 类别 | 技术 |
-|------|------|
-| 壳子 | Electron 28 |
-| 前端 | Vue 3、Vue Router、Pinia |
-| 构建 | Vite 5 |
-| 通信 | axios、socket.io-client |
-| 视图 | Dashboard、Agents、AgentChat/AgentDetail、Sessions、Skills、Settings、Tasks、WorkResults、Workspace、Login |
-| 国际化 | 自研 useI18n + locales (zh/en) |
-
-### 记忆与向量
-
-| 类别 | 技术 |
-|------|------|
-| 向量索引 | Vectra（LocalIndex） |
-| 嵌入 | 远端 API（config.json 中 RAG 知识库配置的 embedding 模型；未配置时长记忆空转） |
-| 扩展 | compaction-extension（会话压缩、摘要入 prompt） |
-| 持久化 | 与 agent 目录一致的 memory 目录、sql.js（若用于元数据） |
-
-### 内置技能
-
-| 技能 | 说明 |
-|------|------|
-| find-skills | 发现与安装 Cursor/Agent 技能 |
-| agent-browser | 浏览器自动化（Playwright/agent-browser CLI） |
+| **CLI** | Node.js 20+、TypeScript 5.7、Commander（gateway/login/config/service）；`openbot` 入口，配置 `~/.openbot/desktop`，支持开机自启 |
+| **WebSocket Gateway** | JSON-RPC over WebSocket，默认 38080；单进程内嵌 Nest，path 分流（/server-api、/ws、/channel 等）；连接管理、通道（飞书/钉钉/Telegram） |
+| **Agent 核心** | pi-coding-agent、pi-ai 多模型；执行方式 local/coze/openclawx；工具 read/write/bash/browser 等，SKILL.md 技能注入 |
+| **Desktop 后端** | NestJS 10、Express、Socket.io，前缀 `server-api`；sql.js；Agents·Skills·Config·Auth·Workspace·Tasks |
+| **Desktop 前端** | Electron 28、Vue 3、Pinia、Vite 5；Dashboard、Agents、Sessions、Skills、Settings、Tasks、Workspace |
+| **记忆与向量** | Vectra 向量索引、远端嵌入、compaction 会话压缩、memory 目录持久化 |
 
 ---
 
@@ -298,7 +246,7 @@ openbot --model deepseek-chat --provider deepseek "写一段 TypeScript 示例"
 CLI 与桌面端共用**桌面配置**（`~/.openbot/desktop/`）。主要文件：
 
 - **config.json**：全局缺省 provider/model、**defaultModelItemCode**（缺省模型在 configuredModels 中的唯一标识）、缺省智能体 id（`defaultAgentId`）、各 provider 的 API Key/baseUrl、已配置模型列表（configuredModels）等。
-- **agents.json**：智能体列表；每个智能体可配置 provider、model、**modelItemCode**（匹配 configuredModels）、工作区。
+- **agents.json**：智能体列表；每个智能体可配置 provider、model、**modelItemCode**（匹配 configuredModels）、工作区。**执行方式**可为 **local** / **coze** / **openclawx**。Coze 代理：`execution: "coze"`，并配置 **region**（`cn` 国内 / `com` 国际）、**coze.cn** / **coze.com**（各含 botId、apiKey），不暴露 endpoint。OpenClawX 代理：`execution: "openclawx"`，配置 **openclawx.baseUrl**、**openclawx.apiKey**（可选）。
 - **provider-support.json**：Provider 与模型目录，供设置页下拉选择。
 
 | 操作 | 命令 | 说明 |
@@ -394,6 +342,19 @@ openclawx gateway --port 38080
 
 未配置或未启用某通道时，Gateway 会跳过该通道启动；若已启用但必填项为空，控制台会提示到「设置 → 通道」检查。
 
+### 2.4.1 代理模式与多节点协作
+
+智能体除在本机运行（**local**）外，可配置为**代理模式**，将对话转发至 Coze 或另一台 OpenClawX，实现生态接入与多节点协作。
+
+| 模式 | 说明 | 配置要点 |
+|------|------|----------|
+| **local** | 本机执行，使用当前模型的 pi-coding-agent 与 Skills | 默认；无需额外配置 |
+| **coze** | 代理至 Coze 平台 | 在桌面端「智能体 → 编辑 → 执行方式」选 Coze；**站点**选国内(cn)或国际(com)；分别填写该站点的 **Bot ID**、**Access Token**（PAT / OAuth 2.0 / JWT 等）。`agents.json` 中对应智能体为 `"execution": "coze"`，并含 `coze.region`、`coze.cn` / `coze.com`（botId、apiKey） |
+| **openclawx** | 代理至其他 OpenClawX 实例（多节点） | 执行方式选 OpenClawX；填写目标实例 **baseUrl**（如 `http://另一台机器:38080`）、可选 **API Key**。`agents.json` 中为 `"execution": "openclawx"`，含 `openclawx.baseUrl`、`openclawx.apiKey`（可选） |
+
+- **入口**：桌面端「设置」→「智能体」中新建/编辑智能体时可选择执行方式；通道使用的默认智能体也可设为 Coze 或 OpenClawX 代理。
+- **多节点**：多台机器各跑一个 OpenClawX Gateway，将部分智能体指向对方 baseUrl，即可实现分工、专机专用或负载均衡。
+
 ---
 
 ## 2.5 即将支持
@@ -414,8 +375,9 @@ openclawx gateway --port 38080
 
 | 方向 | 说明 |
 |------|------|
-| **MCP** | 支持 MCP 协议，降低 Token 消耗与大模型幻觉，与 Skill 自我发现/迭代形成互补 |
-| **Coze 生态** | 接入现有 AI Agent 生态，下一步计划接入 Coze |
+| **MCP** | 规划中：支持 MCP 协议，降低 Token 消耗与大模型幻觉，与 Skill 自我发现/迭代形成互补 |
+| **Coze 生态** | **已支持**：智能体执行方式可选 coze，按站点（国内 cn / 国际 com）配置 Bot ID 与 Access Token，桌面端与通道均可使用 |
+| **OpenClawX 多节点** | **已支持**：执行方式可选 openclawx，通过 baseUrl（及可选 apiKey）将对话代理到另一 OpenClawX 实例，实现多节点协作与负载分工 |
 
 文档与发布节奏后续更新。
 
@@ -547,18 +509,19 @@ npm run test:memory
 
 ---
 
-## 各端技术栈
+### 社区与交流
+
+扫码加入交流群：
 
-详见上文「各端技术栈」章节（CLI、WebSocket Gateway、Agent 核心、Desktop 后端/前端、记忆与向量、内置技能）。
+![OpenClawX 交流群](docs/group-1.png)
 
 ---
 
-## 内置技能
+### 社区与交流
 
-| 技能 | 说明 |
-|------|------|
-| find-skills | 发现与安装 Cursor/Agent 技能 |
-| agent-browser | 浏览器自动化（Playwright/agent-browser CLI） |
+扫码加入交流群：
+
+![OpenClawX 交流群](docs/group-1.png)
 
 ---