@next-open-ai/openclawx 0.8.28 → 0.8.36

package/README.md

@@ -8,48 +8,50 @@
 
 ---
 
-## 📚 文档导航
+## 📚 文档导航 (Documentation)
 
-完整使用说明请进入 **[使用文档入口](docs/README.md)**。文档结构如下：
+**文档 (Documentation):** [中文 (Chinese)](docs/zh/README.md) · [English](docs/en/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 |
-| | [发布说明](docs/release-notes.md) | 各版本功能更新与问题修复记录 |
+| **入门** | [快速开始](docs/zh/guides/getting-started.md) | 5 分钟跑通：安装、首次对话、桌面/通道入口 |
+| | [安装与部署](docs/zh/guides/installation.md) | npm、Docker、Desktop 安装包及环境要求 |
+| **使用指南** | [CLI 使用](docs/zh/guides/cli-usage.md) | 命令行对话、登录、模型与技能、开机自启 |
+| | [桌面端使用](docs/zh/guides/desktop-usage.md) | Desktop 安装与启动、智能体/会话/技能/设置；对话内 `//` 指令查询与切换智能体 |
+| | [Web 与 Gateway](docs/zh/guides/gateway-web.md) | 启动网关、端口与路径、Web 端连接 |
+| | [使用场景](docs/zh/guides/usage-scenarios.md) | 整理下载目录、创建/切换智能体、B站下载助手、安装技能、MCP、定时任务等 |
+| **配置** | [配置概览](docs/zh/configuration/config-overview.md) | 配置目录、config.json 与 agents.json |
+| | [智能体配置](docs/zh/configuration/agents.md) | 本机/Coze/OpenClawX 执行方式与模型 |
+| | [通道配置](docs/zh/configuration/channels.md) | 飞书、钉钉、Telegram 启用与配置项 |
+| **功能说明** | [代理模式与多节点](docs/zh/features/proxy-mode.md) | Coze 接入、OpenClawX 多节点协作 |
+| | [技能系统](docs/zh/features/skills.md) | Agent Skills 规范与扩展 |
+| **参考** | [常见问题](docs/zh/reference/faq.md) | 安装失败、端口占用、通道不回复等 FAQ |
+| | [发布说明](docs/zh/release-notes.md) | 各版本功能更新与问题修复记录 |
 
 <details>
-<summary><strong>📂 文档树结构</strong></summary>
+<summary><strong>📂 文档树结构 (Doc structure)</strong></summary>
 
 ```
 docs/
-├── README.md                   → 文档入口与导航
-├── release-notes.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 通道流式设计（开发参考）
+├── README.md                   → 语言切换入口 (Language switcher)
+├── zh/                         → 中文文档 (Chinese)
+│   ├── README.md               文档入口与导航
+│   ├── release-notes.md        发布说明
+│   ├── guides/                 使用指南
+│   ├── configuration/          配置说明
+│   ├── features/               功能说明
+│   ├── reference/              参考
+│   └── channel-streaming-design.md
+└── en/                         → 英文文档 (English)
+    ├── README.md               Index and navigation
+    ├── release-notes.md        Release notes
+    ├── guides/                 Guides
+    ├── configuration/          Configuration
+    ├── features/                Features
+    ├── reference/              Reference
+    └── channel-streaming-design.md
 ```
 
 </details>
@@ -59,7 +61,7 @@ docs/
 - **Windows 安装失败 / 无法运行？**  
   - **Desktop 安装包**：若安装或启动报错（如缺少运行库、闪退），请安装 [Visual C++ Redistributable](https://learn.microsoft.com/zh-cn/cpp/windows/latest-supported-vc-redist)（选 x64）；若为杀毒/安全软件拦截，可尝试加入排除项或暂时关闭后重试。  
   - **npm 全局安装**：Windows 上若因 `node-llama-cpp` 等原生依赖安装失败，可使用 `npm install -g @next-open-ai/openclawx --ignore-scripts` 跳过可选原生模块，对 CLI/Gateway/Desktop 常规使用无影响；长记忆需单独配置在线 RAG 或本地环境。  
-- 更多问题（macOS 安装包「已损坏」、端口占用、通道不回复等）见 **[常见问题](docs/reference/faq.md)**；版本变更见 **[发布说明](docs/release-notes.md)**。
+- 更多问题（macOS 安装包「已损坏」、端口占用、通道不回复等）见 **[常见问题](docs/zh/reference/faq.md)**；版本变更见 **[发布说明](docs/zh/release-notes.md)**。
 
 ---
 
@@ -73,10 +75,10 @@ docs/
 | **长期记忆** | 向量存储（Vectra）+ 本地嵌入，支持经验总结与会话压缩（compaction） |
 | **多端接入** | CLI、WebSocket 网关、Electron 桌面端，同一套 Agent 核心；各端技术栈见下方「各端技术栈」 |
 | **多通道接入** | 飞书、钉钉、Telegram 等 IM 通道，Gateway 根据配置注册；入站经统一格式进 Agent，回复经通道回传 |
-| **代理模式** | 智能体执行方式可选 **本机** / **Coze** / **OpenClawX** / **OpenCode**；本机使用当前模型与 Skills，代理则将对话转发至对应平台 |
-| **Coze 接入** | 支持 Coze 国内站（api.coze.cn）与国际站（api.coze.com）；按站点分别配置 Bot ID 与 Access Token（PAT/OAuth/JWT），桌面端与通道均可选用 Coze 智能体 |
-| **OpenClawX 多节点协作** | 可将智能体代理到另一台 OpenClawX 实例（baseUrl + 可选 API Key），实现多节点分工、负载与协作 |
-| **OpenCode 代理** | 可将智能体代理至 [OpenCode](https://opencode.ai/) 官方 Server（本地 `opencode serve` 或远程）；支持流式回复、斜杠指令 `/init`、`/undo`、`/redo`、`/share`、`/help`，与 TUI 使用方式一致 |
+| **代理模式** | 智能体执行方式可选 **本机** / **Coze** / **OpenClawX** / **OpenCode**；本机使用当前模型与 Skills，**代理模式下本机 0 Token 消耗**，推理与消息处理在对方平台完成 |
+| **Coze 接入** | 支持 Coze 国内站（api.coze.cn）与国际站（api.coze.com）；按站点分别配置 Bot ID 与 Access Token（PAT/OAuth/JWT），桌面端与通道均可选用 Coze 智能体；**0 Token 消耗**，适合 Coze 侧大量消息与长对话场景 |
+| **OpenClawX 多节点协作** | 可将智能体代理到另一台 OpenClawX 实例（baseUrl + 可选 API Key），实现多节点分工、负载与协作；本机 0 Token 消耗 |
+| **OpenCode 代理** | 可将智能体代理至 [OpenCode](https://opencode.ai/) 官方 Server（本地 `opencode serve` 或远程）；支持流式回复、斜杠指令 `/init`、`/undo`、`/redo`、`/share`、`/help`，与 TUI 使用方式一致；**0 Token 消耗**，适合 OpenCode 侧大量代码与长上下文能力 |
 | **MCP** | 已支持 [MCP](https://modelcontextprotocol.io/)（Model Context Protocol）：智能体可配置 stdio/SSE 两种连接方式，按智能体绑定 MCP 服务器，会话内自动加载对应工具，降低 Token 消耗与大模型幻觉 |
 | **RPA（影刀）** | 通过 MCP 可接入影刀 RPA：在智能体 MCP 配置中添加 [yingdao-mcp-server](https://www.npmjs.com/package/yingdao-mcp-server)（命令 `npx -y yingdao-mcp-server`，可选 env 如 `RPA_MODEL`、`SHADOWBOT_PATH`、`USER_FOLDER`），即可在对话中调用影刀自动化能力 |
 
@@ -200,18 +202,49 @@ npm link   # 或 npm install -g . 本地全局安装
 
 ## 1.2 Docker 部署
 
-适用于：在服务器或容器环境中运行 **Gateway**，供 Web/其他客户端连接。
+适用于：在服务器或容器环境中运行 **Gateway**，供 Web/其他客户端连接。编排文件位于仓库 `deploy/` 目录。
+
+### 方式一：使用 CI 构建的镜像（推荐生产）
+
+镜像由 Drone CI（`.drone.yml`）构建并推送到镜像仓库。使用预构建镜像启动服务，暴露端口 **38080**：
+
+```bash
+# 在 deploy 目录下执行
+cd deploy
+docker compose up -d
+
+# 或从仓库根目录指定 compose 文件
+docker compose -f deploy/docker-compose.yaml up -d
+```
+
+默认使用镜像 `ccr.ccs.tencentyun.com/windwithlife/openclawx:latest`。若需指定版本，可修改 `deploy/docker-compose.yaml` 中 `image` 的 tag（如 `0.8.32`、`0.8.28`、`0.8.26` 或 CI 生成的 `build-ci-openbot-<BUILD_NUMBER>`）。
 
-> **说明**：Docker 镜像与编排正在规划中，当前推荐使用 npm 全局安装后执行 `openbot gateway` 部署网关。
+### 方式二：本地构建并运行（开发/无 CI 时）
 
-规划中的使用方式示例：
+不依赖镜像仓库，在本地从源码构建镜像并启动：
 
 ```bash
-# 示例（以实际仓库/镜像名为准）
-# docker pull next-open-ai/openclawx
-# docker run -p 38080:38080 -e OPENAI_API_KEY=xxx next-open-ai/openclawx gateway
+# 在仓库根目录执行（构建上下文为仓库根）
+docker compose -f deploy/docker-compose-dev.yaml up --build -d
+
+# 或在 deploy 目录下
+cd deploy
+docker compose -f docker-compose-dev.yaml up --build -d
 ```
 
+构建完成后服务同样监听 **38080** 端口，镜像名为 `openclawx:dev`，容器名为 `openclawx-dev`。
+
+### 配置与数据持久化
+
+- Gateway 默认从容器内 `~/.openbot/desktop/` 读取配置（智能体、模型、通道等）。若需持久化或预置配置，可在 compose 中挂载宿主机目录，例如在 `deploy/docker-compose.yaml` 或 `deploy/docker-compose-dev.yaml` 的 `openclawx` 服务下增加：
+
+  ```yaml
+  volumes:
+    - ./openbot-desktop:/root/.openbot/desktop
+  ```
+
+- API Key 等敏感信息也可通过环境变量传入（若 CLI/桌面端支持从环境变量读取），在 compose 的 `environment` 中配置即可。
+
 ---
 
 ## 1.3 Desktop 安装包
@@ -363,7 +396,7 @@ openclawx gateway --port 38080
 
 ### 2.4.1 代理模式与多节点协作
 
-智能体除在本机运行（**local**）外，可配置为**代理模式**，将对话转发至 Coze 或另一台 OpenClawX，实现生态接入与多节点协作。
+智能体除在本机运行（**local**）外，可配置为**代理模式**，将对话转发至 Coze、OpenCode 或另一台 OpenClawX，实现生态接入与多节点协作。**代理智能体为本机 0 Token 消耗模式**：推理与消息处理均在对方平台完成，本机仅做转发与展示，不占用本机模型 API 的 Token。特别适合 **Coze**、**OpenCode** 等具备大量消息、长上下文或代码协作能力的平台，在桌面端与通道中直接使用其能力而无需消耗本机配额。
 
 | 模式 | 说明 | 配置要点 |
 |------|------|----------|