@next-open-ai/openclawx 0.8.28 → 0.8.32

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) | 整理下载目录、创建/切换智能体、安装技能、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)**。
 
 ---
 
@@ -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.28` 或 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 安装包