merge: beta/v3.3.14-beta.0 into main

Author: 2ue

openspec/changes/add-openclaw-support/design.md

@@ -0,0 +1,133 @@
+## 背景与约束
+本次变更是跨模块的新增能力，涉及 `types/core/cli/aicoding/desktop/sync/export-import`。现有系统中：
+- OpenClaw 尚未纳入工具管理。
+- `gmn` / `aicoding` 当前平台列表不含 OpenClaw。
+- Sync 与导入导出均为固定工具集合，缺少 OpenClaw。
+- Sync 核心与 CLI 展示存在集合口径偏差，需要同步收敛。
+- 导入导出当前校验语义偏“强约束”，与“缺失跳过”目标需明确统一规则。
+
+同时必须满足：
+- 路径不可写死 OS 或机器目录，需适配 `HOME_DIR`/`~`。
+- 保持现有工具行为不变，不引入回归。
+- OpenClaw 写入策略为直接覆盖写入。
+
+## 目标
+1. 让 OpenClaw 具备与现有工具一致的 Provider 管理体验（CLI + Desktop）。
+2. 让 `ccman gmn` / `aicoding` 可选配置 OpenClaw，但默认不选中。
+3. 让 Sync / Export / Import 将 OpenClaw 纳入管理。
+4. 全程保持现有工具链行为兼容。
+
+## 非目标
+1. 不改造 OpenClaw 的 Gateway / Telegram / WhatsApp 远程渠道能力。
+2. 不对现有工具（Codex/Claude/Gemini/OpenCode）的写入策略做语义变更。
+3. 不进行全量架构重构（仅做增量接入）。
+
+## 关键设计决策
+
+### 决策 1：新增独立工具类型 `openclaw`
+- 在 `@ccman/types` 与 `@ccman/core` 的工具类型中增加 `openclaw`。
+- 在 `tool-manager` 的映射中新增 `openclaw` 配置条目，独立配置文件为 `~/.ccman/openclaw.json`。
+- 保持现有类型与流程兼容，不修改现有工具 key。
+
+原因：
+- 复用现有 Provider 管理模型，避免为 OpenClaw 设计特例存储层。
+- 将新增影响限制在“新增分支”，不侵入现有分支。
+
+### 决策 2：OpenClaw writer 采用“模板+覆盖写入”策略
+- 目标文件：
+  - `~/.openclaw/openclaw.json`
+  - `~/.openclaw/agents/main/agent/models.json`
+- 模板来源：
+  - `packages/core/templates/openclaw/openclaw.base.template.json`
+  - `packages/core/templates/openclaw/models.base.template.json`
+- 模板加载策略：
+  - 优先读取模板文件（与现有 writer 一致）
+  - 读取失败或打包后缺失时，使用内置回退模板继续写入
+- 每次切换 Provider 时，直接覆盖写入两份文件（不与历史文件深度合并）。
+- 覆盖字段至少包含：
+  - `providers.<provider>.baseUrl/apiKey/api/authHeader/headers/models`
+  - `agents.defaults.model.primary`
+  - `agents.defaults.workspace`（来自 `HOME_DIR`）
+- OpenClaw 的 GMN 默认端点固定为 `https://gmn.chuangzuoli.com/v1`（仅 OpenClaw 使用 `/v1`）。
+
+原因：
+- 用户已明确要求 OpenClaw 采用直接覆盖策略。
+- 与手工教程的“关键字段对齐”目标一致，实现可预测。
+- 模板文件与现有 Codex/Gemini/OpenCode writer 的模板机制一致，便于后续升级字段。
+
+### 决策 3：路径解析统一复用 `paths` 机制
+- 在 `core/paths.ts` 新增 OpenClaw 路径 getter：
+  - `getOpenClawDir()`
+  - `getOpenClawConfigPath()`
+  - `getOpenClawModelsPath()`
+- 生产使用 `os.homedir()`，开发/测试复用现有逻辑。
+
+原因：
+- 防止出现 Ubuntu 路径写死。
+- 保持测试环境可控，便于单测隔离。
+
+### 决策 4：`gmn` / `aicoding` 平台策略
+- 新增 `openclaw` 可选平台。
+- 默认平台维持现状，不默认选中 `openclaw`。
+- `all` 语义包含 `openclaw`。
+- `aicoding` 模式优先级明确为：
+  - OpenClaw 永远按“直接覆盖”写入（不受保护模式影响）
+  - Codex/OpenCode 保持既有“保护/全覆盖”语义不变
+- `ccman gmn` 与 `aicoding` 在 OpenClaw 上的 GMN 端点一致（`/v1`）。
+
+原因：
+- 满足“包含但不默认选中”的业务要求。
+- 兼顾向后兼容与可发现性。
+
+### 决策 5：Sync / Export / Import 的兼容扩展
+- Sync：
+  - 将 `openclaw.json` 纳入上传/下载/合并
+  - CLI 的 `status/upload` 展示集合与核心同步集合保持一致
+- Export/Import：
+  - 将 `openclaw.json` 纳入可导出/可导入集合
+  - 校验语义调整为“支持集合中至少一个文件存在即可执行”
+  - 对缺失文件采用“跳过”而非失败（保持旧包可导入）
+
+原因：
+- 用户明确要求纳入统一管理。
+- 通过“存在即处理，不存在跳过”保持当前用户路径无破坏。
+- 通过“展示集合 == 实际集合”避免 Sync 认知偏差。
+
+### 决策 6：Desktop 增量接入 OpenClaw 页面与 IPC
+- Main/Preload 增加 `openclaw:*` IPC 与 API 暴露。
+- Renderer 增加 OpenClaw 页面、导航项、卡片、预置管理入口。
+- 同步更新所有工具联合类型与分支判断（App、Modal、ProviderForm、ProviderGrid、Dashboard、Sidebar、Config API）。
+- 配置文件编辑面板增加 OpenClaw 相关文件读取展示。
+
+原因：
+- 与现有桌面端架构一致（每个工具独立 API + 页面）。
+- 最小风险复用现有组件模式。
+
+### 决策 7：历史脚本边界（`scripts/setup-gmn*.mjs`）本次不改行为
+- 本次仅保证 `ccman gmn` 与 `aicoding` 两条主链路接入 OpenClaw 并语义一致。
+- `scripts/setup-gmn.mjs` 与 `scripts/setup-gmn-standalone.mjs` 不做行为改造，避免扩大变更面。
+- 文档明确其“历史脚本/可选脚本”定位，避免与主链路规则冲突。
+
+原因：
+- 用户目标聚焦 CLI、gmn、aicoding、desktop、sync、import/export 主流程。
+- 控制风险，避免在同一变更中引入脚本链路回归。
+
+## 一致性与回归控制
+1. 采用“新增分支，不改旧分支”策略，已有工具代码仅做必要的类型扩展。
+2. 对所有新增逻辑补充单元测试与关键集成路径验证。
+3. 对 `gmn` / `aicoding` 默认值保持不变，避免脚本行为突变。
+4. 对 Sync/导入导出采用向后兼容读取策略，旧数据结构继续可用。
+5. 强制校验“Sync 展示集合与核心集合一致”，避免核心与 CLI/Desktop 文案分叉。
+6. OpenClaw writer 强制具备“模板文件读取失败时的内置回退”能力，避免打包环境故障。
+
+## 风险与缓解
+1. 风险：OpenClaw 覆盖写入导致用户手工字段丢失。
+   缓解：在文档与命令提示中明确“覆盖策略”；必要时提供备份。
+2. 风险：类型扩展波及范围大（Desktop 多处联合类型）。
+   缓解：分层修改（types -> core -> preload/main -> renderer），每层做编译验证。
+3. 风险：Sync 扩容影响既有工具流程。
+   缓解：仅新增 `openclaw` 项，不改变既有工具处理顺序与加密逻辑。
+4. 风险：`/v1` 端点策略误用到其他平台导致行为变化。
+   缓解：在 `gmn` / `aicoding` 中将端点策略显式区分为“OpenClaw 专用”。
+5. 风险：aicoding 的模式语义因 OpenClaw 接入变得不清晰。
+   缓解：文档与实现同时固定“OpenClaw 覆盖优先，其他平台语义不变”。

openspec/changes/add-openclaw-support/proposal.md

@@ -0,0 +1,54 @@
+# 变更提案：新增 OpenClaw 配置能力（CLI / GMN / aicoding / Desktop / Sync / 导入导出）
+
+## 背景
+当前 ccman 仅支持 Codex、Claude、Gemini、OpenCode 的服务商配置管理，缺少 OpenClaw 的统一管理能力。用户只能在其他机器或脚本中手动维护 OpenClaw 相关 JSON，无法通过 ccman 的 CLI、Desktop、GMN 一键流程和同步能力进行统一管理。
+
+同时，现有 OpenClaw 教程路径带有 Ubuntu 示例路径，实际实现必须改为跨机器路径策略（基于 `HOME_DIR` / `~`），避免路径写死。
+此外，当前项目在“核心能力与展示层口径”上已存在少量不一致（例如 Sync 核心工具集合与 CLI 展示、导入导出校验语义），本次新增 OpenClaw 需要一并补齐口径，避免分叉扩大。
+
+## 目标
+在不破坏现有工具行为的前提下，为 ccman 增加 OpenClaw 的完整配置管理链路：
+- CLI 管理命令
+- `ccman gmn` 一键配置（可选但默认不勾选）
+- `aicoding` 一键配置（可选但默认不勾选）
+- Desktop 图形化管理
+- WebDAV 同步纳入 OpenClaw
+- 导入导出纳入 OpenClaw
+
+## 本次变更范围
+1. 新增 OpenClaw 工具类型与配置管理（`~/.ccman/openclaw.json`）。
+2. 新增 OpenClaw writer，写入：
+- `~/.openclaw/openclaw.json`
+- `~/.openclaw/agents/main/agent/models.json`
+3. 在 `packages/core/templates/openclaw/` 新增基础模板文件：
+- `openclaw.base.template.json`
+- `models.base.template.json`
+4. OpenClaw 写入策略采用“直接覆盖写入”（不做深度合并）。
+5. CLI 增加 `ccman openclaw` 命令入口（可包含短别名），并在 `ccman` 无参交互主菜单中新增 OpenClaw 选项。
+6. `ccman gmn` 与 `aicoding` 增加 `openclaw` 平台选项，但默认平台保持现状（不默认选中 `openclaw`）。
+7. Desktop 新增 OpenClaw 管理入口（Provider CRUD、切换、预置、配置查看/编辑）。
+8. Sync / Export / Import 增加 OpenClaw 配置文件管理，保持对旧数据和旧流程兼容。
+9. 明确 OpenClaw 的 GMN 端点策略：`openclaw` 使用 `https://gmn.chuangzuoli.com/v1`，不改变其他平台现有端点策略。
+10. 明确 `aicoding` 与 OpenClaw 的优先级规则：即使处于保护模式，OpenClaw 仍按“直接覆盖”策略写入。
+11. 对 Sync 的核心集合与 CLI 状态/上传展示文案做一致性收敛（展示集合与实际同步集合一致）。
+12. 导入导出校验语义调整为“支持集合中至少一个文件存在即可执行；缺失文件跳过”，保持旧包兼容。
+13. 明确本次不改造历史 `scripts/setup-gmn*.mjs` 行为，仅保证 `ccman gmn` 与 `aicoding` 两条主链路一致。
+
+## 兼容性与风险控制
+- 现有命令与现有工具配置行为保持不变（Codex/Claude/Gemini/OpenCode/MCP 不回归）。
+- 新能力以“增量接入”为主：新增 OpenClaw 路径、常量、manager、writer，不重构现有核心流程。
+- OpenClaw 写入优先从 `packages/core/templates/openclaw/` 读取模板，并提供内置回退模板，适配打包场景。
+- 对同步与导入导出采用“文件存在即处理，不存在跳过”的兼容策略，避免旧用户报错。
+- 路径解析统一走现有 `paths` 机制（生产环境 `os.homedir()`，开发/测试环境复用当前规则），确保跨机器一致性。
+- `aicoding` 中仅对 OpenClaw 采用“覆盖优先”，Codex/OpenCode 继续遵循既有保护/覆盖模式语义。
+
+## 影响范围
+- 受影响规范：`openclaw-integration`
+- 受影响代码（预估）：
+  - `packages/types`
+  - `packages/core`
+  - `packages/cli`
+  - `packages/aicoding`
+  - `packages/desktop`
+  - `scripts`（仅文档/边界声明）
+  - `README` / 相关文档

openspec/changes/add-openclaw-support/specs/openclaw-integration/spec.md

@@ -0,0 +1,94 @@
+## ADDED Requirements
+### Requirement: OpenClaw Provider 管理能力
+系统 SHALL 提供 OpenClaw 的 Provider 管理能力，并与现有工具保持一致的增删改查、切换、克隆行为。
+
+#### Scenario: 使用 CLI 管理 OpenClaw Provider
+- **WHEN** 用户执行 `ccman openclaw` 相关 CLI 命令（添加、编辑、删除、切换、克隆、查看）
+- **THEN** 系统 SHALL 在 `~/.ccman/openclaw.json` 中正确维护 Provider 数据与当前激活项
+
+#### Scenario: 无参数启动时主菜单可见 OpenClaw
+- **WHEN** 用户执行 `ccman` 且未带子命令进入交互主菜单
+- **THEN** 系统 SHALL 展示 OpenClaw 管理入口
+
+#### Scenario: 使用 Desktop 管理 OpenClaw Provider
+- **WHEN** 用户在 Desktop 中进入 OpenClaw 页面并执行 Provider 操作
+- **THEN** 系统 SHALL 通过与 CLI 等价的核心逻辑完成配置管理并刷新界面状态
+
+### Requirement: OpenClaw 配置文件覆盖写入
+系统 SHALL 在切换 OpenClaw 当前 Provider 时，直接覆盖写入 OpenClaw 目标配置文件，并写入 GMN/OpenAI Responses 所需关键字段。
+
+#### Scenario: 使用 core 模板生成 OpenClaw 配置
+- **WHEN** 系统执行 OpenClaw 配置写入
+- **THEN** 系统 SHALL 使用 `packages/core/templates/openclaw/openclaw.base.template.json` 与 `packages/core/templates/openclaw/models.base.template.json` 作为模板来源
+
+#### Scenario: 切换 Provider 时覆盖写入目标文件
+- **WHEN** 用户切换到某个 OpenClaw Provider
+- **THEN** 系统 SHALL 覆盖写入 `~/.openclaw/openclaw.json` 与 `~/.openclaw/agents/main/agent/models.json`
+- **AND** 写入内容 SHALL 包含 `baseUrl`、`apiKey`、`api=openai-responses`、`authHeader`、`headers`、`models`、`agents.defaults.model.primary`
+
+#### Scenario: 路径按 HOME_DIR 解析
+- **WHEN** 系统在不同机器或不同环境（生产/开发/测试）执行 OpenClaw 写入
+- **THEN** 系统 SHALL 基于 HOME_DIR 语义解析路径，不依赖固定 Ubuntu 绝对路径
+
+#### Scenario: 模板文件缺失时使用内置回退
+- **WHEN** 运行环境无法读取 OpenClaw 模板文件
+- **THEN** 系统 SHALL 使用内置回退模板继续完成写入
+- **AND** 回退写入结果 SHALL 仍包含 OpenClaw 必需关键字段
+
+### Requirement: GMN 与 aicoding 支持 OpenClaw 平台选项
+系统 SHALL 在 `ccman gmn` 与 `aicoding` 中提供 `openclaw` 平台选项，但默认选择中不包含 `openclaw`。
+
+#### Scenario: 默认平台不包含 OpenClaw
+- **WHEN** 用户直接执行 `ccman gmn` 或 `aicoding` 且不显式指定平台
+- **THEN** 系统 SHALL 使用既有默认平台集合
+- **AND** 默认集合 SHALL NOT 包含 `openclaw`
+
+#### Scenario: 显式选择 OpenClaw 平台
+- **WHEN** 用户在平台参数或交互中选择 `openclaw`
+- **THEN** 系统 SHALL 执行 OpenClaw 配置写入流程
+
+#### Scenario: 选择 all 时包含 OpenClaw
+- **WHEN** 用户选择 `all`
+- **THEN** 系统 SHALL 将 `openclaw` 纳入执行平台集合
+
+#### Scenario: OpenClaw 使用 GMN `/v1` 端点
+- **WHEN** 用户通过 `ccman gmn` 或 `aicoding` 配置 `openclaw`
+- **THEN** 系统 SHALL 对 OpenClaw 写入 `baseUrl=https://gmn.chuangzuoli.com/v1`
+- **AND** 其他既有平台 SHALL 继续使用其原有端点策略
+
+#### Scenario: aicoding 保护模式下 OpenClaw 仍覆盖写入
+- **WHEN** 用户在 `aicoding` 保护模式中选择 `openclaw`
+- **THEN** 系统 SHALL 对 OpenClaw 执行直接覆盖写入
+- **AND** 其他平台 SHALL 保持既有保护/覆盖语义
+
+### Requirement: Sync 纳入 OpenClaw 配置
+系统 SHALL 在上传、下载、合并同步流程中纳入 OpenClaw 配置文件，并保持现有工具同步行为不变。
+
+#### Scenario: 上传同步包含 OpenClaw
+- **WHEN** 用户执行上传同步
+- **THEN** 系统 SHALL 将 OpenClaw 配置上传到远端并沿用现有加密/解密策略
+
+#### Scenario: 下载与合并兼容旧数据
+- **WHEN** 远端或本地缺失 OpenClaw 配置文件
+- **THEN** 系统 SHALL 跳过 OpenClaw 处理而非中断整个同步流程
+
+#### Scenario: Sync 展示集合与实际同步集合一致
+- **WHEN** 用户执行 Sync 状态查询或上传前检查
+- **THEN** 系统 SHALL 展示与实际同步处理一致的工具集合
+- **AND** 展示集合 SHALL 包含 OpenClaw
+
+### Requirement: 导入导出纳入 OpenClaw 配置
+系统 SHALL 在导出与导入流程中支持 OpenClaw 配置文件，并保持旧导入包可用。
+
+#### Scenario: 导出包含 OpenClaw 配置
+- **WHEN** 本地存在 OpenClaw 配置文件
+- **THEN** 系统 SHALL 在导出目录中包含 OpenClaw 配置文件
+
+#### Scenario: 导入兼容无 OpenClaw 的旧包
+- **WHEN** 用户导入的配置包不包含 OpenClaw 文件
+- **THEN** 系统 SHALL 继续完成其他已有配置文件的导入，不因缺失 OpenClaw 而失败
+
+#### Scenario: 支持集合至少一个文件即可导入导出
+- **WHEN** 导入目录或导出源中仅存在支持集合中的单个配置文件（例如仅 `openclaw.json`）
+- **THEN** 系统 SHALL 允许执行并处理该文件
+- **AND** 对支持集合中缺失的其他文件 SHALL 跳过处理而非失败

openspec/changes/add-openclaw-support/tasks.md

@@ -0,0 +1,40 @@
+## 1. Core 与类型
+- [x] 1.1 在 `@ccman/types` 与 `@ccman/core` 增加 `openclaw` 工具类型与常量映射
+- [x] 1.2 在 `core/paths` 增加 OpenClaw 路径解析（`~/.openclaw`、`openclaw.json`、`models.json`）
+- [x] 1.3 在 `packages/core/templates/openclaw/` 新增 `openclaw.base.template.json` 与 `models.base.template.json`
+- [x] 1.4 新增 OpenClaw presets 与 writer（基于模板直接覆盖写入两份目标文件）
+- [x] 1.5 将 OpenClaw manager 接入 `tool-manager` 与 `core` 对外导出
+- [x] 1.6 OpenClaw writer 补充“模板文件缺失时使用内置回退”的实现与测试
+- [x] 1.7 为 OpenClaw writer 和 manager 增加测试（包含覆盖写入与关键字段断言）
+
+## 2. CLI 与一键配置
+- [x] 2.1 新增 `ccman openclaw` CLI 命令入口（含对应子命令与可选短别名）
+- [x] 2.2 在 `ccman` 无参交互主菜单中增加 OpenClaw 选项
+- [x] 2.3 将 `ccman gmn` 增加 `openclaw` 平台（可选但默认不选中）
+- [x] 2.4 将 `aicoding` 增加 `openclaw` 平台（可选但默认不选中）
+- [x] 2.5 在 `ccman gmn` 与 `aicoding` 中明确 OpenClaw GMN 端点为 `https://gmn.chuangzuoli.com/v1`（仅 OpenClaw 使用 `/v1`）
+- [x] 2.6 在 `aicoding` 中实现 OpenClaw 覆盖优先规则（不受保护模式影响）
+- [x] 2.7 更新 CLI / aicoding 帮助与文档说明（默认不选中 + 覆盖策略 + `/v1` 规则）
+
+## 3. Desktop
+- [x] 3.1 Main 进程增加 `openclaw:*` IPC 处理器与配置文件读取入口
+- [x] 3.2 Preload 暴露 `openclaw` API 与类型声明
+- [x] 3.3 Renderer 增加 OpenClaw 页面、导航、Dashboard 卡片、Add/Edit/Clone 流程接入
+- [x] 3.4 同步更新 Desktop 各处工具联合类型与分支逻辑（App/Modal/Form/Grid/Config API）
+- [x] 3.5 配置文件编辑写入流程保证 OpenClaw 深层路径可创建（避免目录不存在写入失败）
+- [x] 3.6 预置服务商页面增加 OpenClaw 分组与使用流程
+
+## 4. Sync / 导入导出
+- [x] 4.1 Sync 上传/下载/合并纳入 `openclaw.json`
+- [x] 4.2 Sync CLI 的 `status/upload` 展示集合与核心同步集合保持一致
+- [x] 4.3 Export/Import 纳入 `openclaw.json`
+- [x] 4.4 Export/Import 校验调整为“支持集合至少一个文件存在即可执行”
+- [x] 4.5 对缺失 OpenClaw 文件保持兼容（跳过而非报错）
+- [x] 4.6 补充 Sync 与导入导出相关测试（含缺失文件、单文件导入导出场景）
+
+## 5. 验证与发布准备
+- [x] 5.1 运行 typecheck / test，确认无回归
+- [x] 5.2 补充 README 与关键路径示例（尤其是覆盖写入策略、`/v1` 规则与平台默认值）
+- [ ] 5.3 人工验证：CLI、gmn、aicoding、Desktop、sync、import/export 端到端流程
+- [x] 5.4 文档中统一术语为 `openclaw`（清理 `openclawd` 残留）
+- [ ] 5.5 明确历史 `scripts/setup-gmn*.mjs` 不在本次行为改造范围

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccmam",
-  "version": "3.3.13",
+  "version": "3.3.14-beta.3",
   "private": true,
   "description": "Manage Codex, Claude Code, Gemini CLI, and MCP API service provider configurations",
   "scripts": {