# Changelog

本项目所有重大变更都将记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)。

## [1.0.15] - 2026-03-13

### 修复
- **QQBot 插件 3 层死锁修复**: 解决插件安装后因 uid 权限→安全策略阻止→配置校验失败的连锁问题
  - 自动检测插件 blocked/loaded/目录存在 3 种状态
  - 插件安装后自动 `chown root:root` 修复权限
  - 安装失败但目录存在时不再阻断配置流程

### 新增
- **覆盖安装防护**: 离线安装器在覆盖安装前先停止已有服务，避免文件被占用
- **离线 .run 安装包**: 构建包含 Node.js + OpenClaw + LuCI 插件的全合一自解压包，用户**无需联网**即可完成安装
- **musl 架构支持**: 离线包支持 x86_64-musl、aarch64-musl 两种架构 (OpenWrt/iStoreOS 均使用 musl)
- **依赖预下载脚本** (`scripts/download_deps.sh`): 在构建机上预下载所有离线依赖
- **离线构建脚本** (`scripts/build_offline_run.sh`): 将预下载的依赖打包为各架构的离线 .run
- **GitHub Actions CI** (`.github/workflows/build-offline.yml`): 离线包自动构建 + 发布
- **node_modules 精简**: 自动删除文档、测试、TypeScript 源码等非必要文件，减小 30%+ 体积
- **磁盘空间预检查**: 安装前检测可用空间是否满足 500MB 最低要求
- **架构/libc 自动检测**: 安装时自动校验当前设备是否匹配安装包架构

### 文档
- **README**: 添加离线安装方式（无需联网），更新目录结构

### 变更
- **离线包不依赖 curl/openssl/git**: 离线安装模式下 opkg 注册的依赖简化为 luci-compat + luci-base

## [1.0.14] - 2026-03-12

### 备份管理增强 & QQ 机器人支持

#### 新增
- **备份列表可视化**: LuCI「💾 备份/恢复」对话框现在展示所有备份的结构化列表：
  - 📄 仅配置 / 📦 完整备份 类型标签（从 manifest.json 读取 `onlyConfig` 字段精确判断）
  - 备份时间、文件大小
  - 每个备份支持**单独恢复**和**删除**操作
  - 创建/删除备份后列表自动刷新
- **备份删除 API**: Controller 新增 `action=delete` 操作（含路径穿越安全校验）
- **QQ 机器人配置**: `oc-config.sh` 渠道菜单新增「QQ 机器人」选项（选项 1，推荐国内用户），支持：
  - 自动安装 `@tencent-connect/openclaw-qqbot` 插件
  - App ID / App Secret 输入校验
  - 通过 `openclaw channels add` CLI 一键配置
- **消息渠道状态显示**: 状态面板新增「消息渠道」行，自动检测已配置的渠道（QQ、Telegram、Discord、飞书、Slack）

#### 变更
- **备份恢复**: 从"从最新备份恢复"改为在列表中选择任意备份进行恢复
- **描述文本**: 各页面描述新增"QQ"渠道说明

#### 修复
- **JS 语法错误导致所有按钮失效**: 备份对话框 HTML 被错误地插入 `<script>` 标签内部，导致 JavaScript 语法错误。修复: 在对话框 HTML 前后正确分割 `<script>` 标签

## [1.0.13] - 2026-03-12

### 适配 OpenClaw v2026.3.8 & 新增备份/恢复功能

#### 新增
- **配置备份/恢复**: LuCI 基本设置页「💾 备份/恢复」按钮，弹出对话框支持：
  - 📄 仅配置文件备份（~2KB，包含模型、渠道、插件设置）
  - 📦 完整备份（配置 + 状态数据）
  - 🔄 从最新备份恢复配置（自动重启服务）
- **Shell 备份菜单**: `oc-config.sh` 主菜单新增「8) 💾 备份/还原配置」，支持：
  - 创建仅配置 / 完整备份
  - 验证备份完整性 (`openclaw backup verify`)
  - 列出已有备份文件
  - 从最新备份恢复配置（交互确认 + 自动重启）
- **命令行备份**: `oc-config.sh --backup` 快捷参数，适合 cron 定时任务
- **OpenClaw 版本显示**: 状态面板新增 OpenClaw 版本行（从 package.json 读取）

#### 修复
- **备份文件路径**: 备份文件统一保存到 `~/.openclaw/backups/` 目录（OpenClaw CLI 默认输出到 CWD）
- **完整备份失败**: 含未注册插件的 channel ID 时，`backup create` 因 config invalid 失败；改用 `--no-include-workspace` 跳过工作区发现

#### 变更
- **OC_TESTED_VERSION**: 2026.3.2 → 2026.3.8
- **Control UI iframe 资源查找**: `patch_iframe_headers()` 扩展搜索路径，覆盖 `$NODE_BASE/lib/node_modules`、pnpm 全局存储，并使用 `readlink -f` 解析 v2026.3.8 新增的符号链接资源路径
- **Gateway 入口查找**: `get_oc_entry()` 新增 `readlink -f` 符号链接解析，兼容 v2026.3.8 的 bundled 插件优先级调整
- **配置同步清理**: `sync_uci_to_json()` 自动删除 v2026.3.7/3.8 已废弃的配置字段：
  - `gateway.controlUi.dangerouslyAllowCors`
  - `gateway.controlUi.dangerouslyAllowRemoteConnections`
  - `commands.ownerDisplay`

#### 兼容性说明
- **v2026.3.7 BREAKING CHANGE**: `gateway.auth.mode` 必须显式指定（不再有默认值）。本插件已在 v1.0.3 起始终写入 `"mode": "token"`，无需用户操作
- **v2026.3.8**: Control UI 资源分发改为符号链接方式，本版本已完整适配

## [1.0.12] - 2026-03-11

### 移除 OpenClaw 版本检测 & 修复 BusyBox tar 兼容性

#### 变更
- **「检测升级」按钮**: 不再检查 OpenClaw (npm) 版本，仅检查插件 (luci-app-openclaw) 是否有新版本
- **「检测升级」显示更新内容**: 检测到新插件版本时，直接展示该版本的 Release Notes，告知用户升级了什么
- **状态面板**: 移除「OpenClaw」版本显示行，保留 Node.js 和插件版本
- **内部清理**: 移除 `get_openclaw_version()` 函数、`action_do_update`、`action_upgrade_log` 等已废弃后端 API

#### 修复
- **BusyBox tar 兼容性** (#18, #30): `openclaw-env` 安装 Node.js 时的解压命令优先使用 GNU tar `--strip-components=1`；若不支持则自动回退到 BusyBox tar 兼容方式（解压到临时目录后移动），无需用户手动安装 `tar`
- **插件升级网络错误提示**: 下载后检测文件内容，若 GitHub 返回 `Not Found`（GFW 拦截等情况）则显示明确提示，并附手动下载链接

## [1.0.11] - 2026-03-09

### 修复 Telegram 配对后无法使用的严重 Bug

#### 修复
- **Telegram 配置流程**: Token 保存后强制重启网关（不再可选），确保 Bot Token 立即生效后再进入配对流程
- **Telegram 配对流程**: 配对成功后自动重启网关，确保配对关系立即生效，用户可以直接开始对话

## [1.0.10] - 2026-03-08

### 新增腾讯云大模型 Coding Plan 套餐支持

#### 新增
- **腾讯云 Coding Plan 套餐**: 新增菜单选项 13，支持一键配置腾讯云大模型 Coding Plan 套餐
  - Base URL: `https://api.lkeap.cloud.tencent.com/coding/v3`，Provider: `lkeap`
  - 支持全部 8 个套餐模型: tc-code-latest (智能路由)、hunyuan-t1、hunyuan-turbos、hunyuan-2.0-thinking、hunyuan-2.0-instruct、glm-5、kimi-k2.5、minimax-m2.5
  - 按类别分组展示: 智能推荐 / 推理模型 / 旗舰模型 / 第三方模型

#### 修复
- **Coding Plan 配置信息修正**: 订阅地址更正为官方页面，移除不必要的 Base URL 显示

## [1.0.9] - 2026-03-08

### 插件一键升级 & 百炼模型列表扩充

#### 新增
- **插件一键升级**: LuCI 界面"检测升级"发现新版后，可直接点击"⬆️ 升级插件"按钮完成在线升级
  - 后台自动从 GitHub Releases 下载 `.run` 安装包并执行
  - 实时升级日志显示，带容错处理 (安装过程替换 LuCI 文件导致 API 暂时不可用时自动判定成功)
  - 同时保留"📥 手动下载"链接作为备选
- **百炼按量付费模型列表扩充**: 从 4 个模型扩充至 16 个，按类别分组显示
  - 千问商业版: qwen-max、qwen-plus (Qwen3.5)、qwen-flash (Qwen3.5)、qwen-turbo、qwen-long (1000万Token上下文)
  - 千问Coder: qwen3-coder-plus (100万上下文)、qwen3-coder-flash
  - 推理模型: qwq-plus
  - 千问开源版: qwen3-235b-a22b、qwen3-32b、qwen3-30b-a3b
  - 第三方模型: deepseek-r1、deepseek-v3、kimi-k2.5、glm-5、MiniMax-M2.5

#### 修复
- **CBI 底部按钮未隐藏**: "保存并应用/保存/复位"按钮在基本设置页仍然显示
  - 根因: `m.submit = false` 和 `m.reset = false` 不被 CBI 框架识别
  - 修复: 改为 `m.pageaction = false` (dispatcher.lua 第 294 行检查的正确属性)
- **插件升级后配置管理无法连接**: 升级后 PTY WebSocket 一直转圈 "等待服务就绪"
  - 根因: `.run` 安装器覆盖 `/etc/config/openclaw` 导致 `pty_token` 丢失，PTY 认证失败
  - 修复: 升级时保留用户 UCI 配置 (仅首次安装部署默认配置)；安装后自动重启 PTY 服务

## [1.0.8] - 2026-03-07

### 修复第三方模型配置导致 Gateway 崩溃 & 新增 Coding Plan 套餐支持

#### 修复
- **EACCES 权限错误** (#8): Web PTY 以 root 运行，创建的目录 (`sessions/`, `auth-profiles.json` 等) 归 root 所有，Gateway 以 `openclaw` 用户运行时无法写入，报 `EACCES: permission denied, mkdir`
  - `oc-config.sh`: `auth_set_apikey`、`json_set`、备份目录创建后均执行 `chown openclaw:openclaw`
  - `web-pty.js`: 子进程退出时自动 `chown -R openclaw:openclaw` 整个数据目录
- **第三方模型 404/405 错误** (#11, #13, #14, #15): DeepSeek、xAI Grok、Groq 等 OpenAI 兼容提供商配置后返回 404/405
  - 根因: 这些提供商缺少 `register_custom_provider` 调用，未写入 `baseUrl` 导致 Gateway 请求发到错误地址
  - 修复: 为 DeepSeek、xAI、Groq 快速配置补充 `register_custom_provider` 调用
- **API 类型错误导致 Gateway 崩溃**: `register_custom_provider` 中 `api` 值设为 `openai-chat-completions`，但该值在 OpenClaw v2026.3.2 中不存在
  - 正确值为 `openai-completions`，错误值会导致 Gateway 启动时 JSON schema 校验失败，进入 crash loop
  - 有效 api 类型: `openai-completions` | `openai-responses` | `openai-codex-responses` | `anthropic-messages` | `google-generative-ai` | `github-copilot` | `bedrock-converse-stream` | `ollama`

#### 新增
- **阿里云 Coding Plan 套餐快速配置**: 千问配置菜单新增 Coding Plan 选项 (选项 c，默认推荐)
  - Provider: `bailian`，Base URL: `https://coding.dashscope.aliyuncs.com/v1`
  - 一键注册套餐内全部模型: qwen3.5-plus、qwen3-coder-plus、qwen3-coder-next、qwen3-max、MiniMax-M2.5、glm-5、glm-4.7、kimi-k2.5
  - contextWindow / maxTokens 按阿里云官方文档设定 (最大 100万上下文)
  - 参考: [阿里云 Coding Plan 文档](https://help.aliyun.com/zh/model-studio/openclaw-coding-plan)

#### 变更
- **千问配置菜单重构**: 从 2 种模式扩展为 3 种
  - `a)` Qwen Portal OAuth (官方向导)
  - `b)` 百炼按量付费 API Key (`sk-xxx` + `dashscope.aliyuncs.com`)
  - `c)` Coding Plan 套餐 (`sk-sp-xxx` + `coding.dashscope.aliyuncs.com`) ★ 默认推荐
  - 明确提示两套 API Key / Base URL 不互通
- **`register_custom_provider` 增强**: 新增可选参数 `context_window` (默认 128000) 和 `max_tokens` (默认 32000)

## [1.0.7] - 2026-03-06

### 修复依赖包名错误 & 补充 GNU tar 依赖 (感谢 [@esir](https://github.com/esirplayground) 建议)

#### 修复
- **依赖包名修正**: `util-linux-script` 在 OpenWrt/iStoreOS 软件源中不存在，正确的包名是 `script-utils` (提供 `/usr/bin/script` 命令)。此错误会导致通过 iStore/opkg 安装插件时依赖解析失败
- **补充 GNU tar 依赖**: `openclaw-env` 安装脚本使用 `tar --strip-components=1` 解压 Node.js，但 busybox 内置的 tar 不支持该参数。新增 `tar` (GNU tar) 为必需依赖，确保解压操作正常

#### 变更
- `Makefile`: `LUCI_DEPENDS` 中 `+util-linux-script` → `+script-utils +tar`
- `scripts/build_ipk.sh`: 同步更新 Depends 字段
- `scripts/build_run.sh`: 同步更新 Depends 字段

### 修复重启服务时 Gateway crash loop 端口冲突

#### 修复
- **端口冲突 crash loop**: OpenClaw gateway 的架构是主进程 (`openclaw`) fork 出子进程 (`openclaw-gateway`) 监听端口，restart 时 procd 只杀主进程，子进程退出慢导致新实例端口冲突反复崩溃
  - `stop_service()`: 从空函数改为主动清理 `openclaw-gateway` 子进程 + 等待端口释放 (最长 8 秒)
  - `start_service()`: 启动前预检查端口，清理残留进程后再注册 procd 实例
  - `reload_service()`: stop 和 start 之间增加等待确保内核回收端口
  - LuCI controller: restart 改为先同步 stop 等端口释放，再后台 start
  - procd respawn 间隔从 5s → 10s，降低连续端口冲突概率

## [1.0.6] - 2026-03-06

### 修复 Docker 环境下安装失败 "mkdir: can't create directory: Directory not empty"

#### 修复
- **OverlayFS 兼容性**: iStoreOS/OpenWrt 安装 Docker 后，Docker 的 bind mount (`/overlay/upper/opt/docker`) 导致 OverlayFS 合并视图中 `/opt` 目录完全不可写，所有 `mkdir`/`touch`/`ln` 操作均报 "Directory not empty"
  - 新增 `_oc_fix_opt()` 检测函数，自动检测 `/opt` 是否可写
  - 不可写时自动执行 `mount --bind /overlay/upper/opt /opt` 绕过 OverlayFS 冲突
  - 三重保障: `uci-defaults` (首次安装)、`init.d` (每次开机)、`openclaw-env` (手动操作) 均包含修复逻辑
  - 正常系统 (无 Docker) 不受影响，检测到可写后直接跳过
- **openclaw-env**: 新增 `ensure_mkdir()` 安全目录创建函数，替代所有裸 `mkdir -p` 调用

## [1.0.5] - 2026-03-05

### 修复配置管理页面 "spawn script ENOENT" 启动失败 (#3, #4)

#### 修复
- **Web PTY 启动失败**: `web-pty.js` 硬编码依赖 `script` 命令 (来自 `util-linux-script`)，但部分 OpenWrt 固件默认不包含该命令，导致 `spawn script ENOENT` 错误并无限循环重启
  - 新增 `script` 命令自动检测，不存在时回退到 `sh` 直接执行 `oc-config.sh`
  - 新增连续失败计数器 (最多 5 次)，防止启动失败时的无限重试循环
  - 失败时向用户终端显示明确的错误提示和修复命令
- **Makefile 依赖补全**: `LUCI_DEPENDS` 新增 `+util-linux-script`，确保新安装自动拉取 `script` 命令

## [1.0.4] - 2026-03-05

### 适配 OpenClaw 2026.3.2

#### 破坏性变更修复
- **tools.profile 默认值变更**: 2026.3.2 将 `tools.profile` 默认从 `coding` 改为 `messaging`
  - `sync_uci_to_json()` 每次启动强制写入 `tools.profile=coding`
  - `openclaw-env init_openclaw()` onboard 命令添加 `--tools-profile coding`
  - `openclaw-env do_factory_reset()` onboard 命令添加 `--tools-profile coding`
  - `oc-config.sh` 工厂重置 onboard 命令添加 `--tools-profile coding`
  - `oc-config.sh` 工厂重置配置写入新增 `tools.profile=coding`
- **ACP dispatch 默认启用**: 2026.3.2 默认开启 ACP dispatch，路由器内存有限可能导致 OOM
  - `sync_uci_to_json()` 每次启动强制写入 `acp.dispatch.enabled=false`
  - `openclaw-env do_factory_reset()` 配置写入新增 `acp.dispatch.enabled=false`
  - `oc-config.sh` 工厂重置配置写入新增 `acp.dispatch.enabled=false`

#### 新增
- 健康检查集成 `openclaw config validate --json` 官方配置验证命令
- 健康检查新增 `gateway health --json` CLI 深度检查 (v2026.3.2 HTTP `/health` 已被 SPA 接管)

#### 修复
- **Ollama 配置适配**: `api` 从废弃的 `openai-chat-completions` 改为原生 `ollama` API 类型
- **Ollama baseUrl 格式**: 去掉 `/v1` 后缀，使用官方原生地址格式 (`http://host:11434`)
- **Ollama apiKey 对齐**: 从 `ollama` 改为官方默认值 `ollama-local`
- **启动自动迁移**: `sync_uci_to_json` 自动将旧版 Ollama 配置迁移到 v2026.3.2 格式

#### 改进
- 配置管理页面移除「菜单功能说明」信息框，减少视觉干扰
- `OC_TESTED_VERSION` 更新至 `2026.3.2`

## [1.0.3] - 2026-03-05

### 修复
- **P0** 配置管理写入错误的 JSON 路径导致 Gateway 崩溃且无法恢复 (#1)
  - `json_set models.openai.apiKey` 在 `openclaw.json` 创建了非法的顶层 `models` 键
  - OpenClaw 2026.3.1 严格校验配置 schema，拒绝启动并报 `Unknown config keys: models.openai`
  - 修复: API Key 改写入 `auth-profiles.json`，模型注册到 `agents.defaults.models`
  - 影响: 所有 11 个供应商的快速配置 (OpenAI/Anthropic/Gemini/OpenRouter/DeepSeek/GitHub Copilot/Qwen/xAI/Groq/SiliconFlow/自定义)
- **P0** 恢复默认配置 → "清除模型配置" 未清理 `auth-profiles.json` 认证信息
- **P1** 健康检查新增自动修复: 检测并移除旧版错误写入的顶层 `models` 无效键
- **P1** `set_active_model` 手动切换模型时未注册到 `agents.defaults.models`

### 新增
- **Ollama 本地模型支持**: 快速配置菜单新增 Ollama 选项 (12)，支持 localhost/局域网连接、自动检测连通性、自动列出已安装模型、兼容 OpenAI chat completions 格式
- `openclaw-env factory-reset` 非交互式恢复出厂设置命令
- `auth_set_apikey` 函数: 正确写入 API Key 到 `auth-profiles.json`
- `register_and_set_model` 函数: 注册模型到 `agents.defaults.models` 并设为默认
- `register_custom_provider` 函数: 为需要 `baseUrl` 的 OpenAI 兼容供应商注册 `models.providers`
- 「检测升级」同时检查 OpenClaw 和**插件版本** (通过 GitHub API 获取最新 release)
- 页面加载时自动静默检查更新，有新版本时「检测升级」按钮显示橙色小红点提醒
- 状态面板显示当前安装的插件版本号
- 构建/安装流程部署 `VERSION` 文件到 `/usr/share/openclaw/VERSION`
- `openclaw-env setup` 安装环境时自动安装 Gemini CLI (Google OAuth 依赖)

### 改进
- 使用指南顺序调整: ② 配置管理 → ③ Web 控制台 (首次使用更合理的引导顺序)
- Gemini CLI 安装从配置向导选项 1 移至环境安装阶段，避免进入向导时临时等待

## [1.0.2] - 2026-03-02

### 修复
- **P0** ARM64 musl: Gateway 崩溃循环 — `process.execPath` 返回 musl 链接器路径导致 `child_process.fork()` 失败
  - 使用 `patchelf` 直接修改 node ELF 二进制的 interpreter 和 rpath，替代 ld-musl wrapper 方案
  - 子进程通过 `process.execPath` fork 时可正确找到 node 二进制
- **P0** ARM64 musl: Unicode property escapes 正则失败 (`\p{Emoji_Presentation}`) — 缺少 `NODE_ICU_DATA` 环境变量
  - init.d、openclaw-env、oc-config.sh 所有入口均添加 `NODE_ICU_DATA` 环境变量

### 改进
- `build-node-musl.sh` 构建验证阶段新增 `process.execPath` 输出检查

## [1.0.1] - 2026-03-02

### 修复
- **P0** web-pty.js `loadAuthToken` 读取错误的 UCI key `luci_token` → `pty_token`
- **P0** init.d `get_oc_entry()` 管道子 shell 导致返回值丢失，改用临时文件重定向
- **P1** Gateway procd respawn 无限重试 (`3600 5 0`) → 限制最多 5 次 (`3600 5 5`)
- **P1** Telegram 配对流程管道子 shell 变量丢失，改用临时文件避免子 shell
- **P1** `openclaw.lua` PID 提取 `sed` 正则不可靠，改用 `awk` + `split`
- **P2** init.d 和 uci-defaults 弱 token fallback (`echo "auto_$(date +%s)"`) → `dd if=/dev/urandom`
- **P2** `oc-config.sh` 恢复出厂 `timeout` 命令可能不存在，添加 `command -v` 检查和降级方案
- **P2** web-pty.js SIGTERM 不清理 HTTPS server，统一 `shutdown()` 函数

### 新增
- GitHub Copilot 配置新增 OAuth 授权登录方式 (通过 `copilot-proxy` 插件)
- `uci-defaults` 首次安装时自动生成 `pty_token`
- Web 控制台和状态面板显示当前活跃模型名称

### 改进
- Qwen 使用 `models.dashscope` 键名、SiliconFlow 使用 `models.siliconflow`，避免 `models.custom` 键冲突
- `get_openclaw_version()` 从 `package.json` 读取版本号，不再每次启动 Node.js 进程
- PTY 终端 WebSocket 重连策略改为无限重连 (`MAX_RETRY=Infinity`)
- Makefile `PKG_VERSION` 从 `VERSION` 文件动态读取

## [1.0.0] - 2026-03-02

### 新增
- LuCI 管理界面：基本设置、配置管理（Web 终端）、Web 控制台
- 一键安装 Node.js + OpenClaw 运行环境
- 支持 x86_64 和 aarch64 架构，glibc / musl 自动检测
- 支持 12+ AI 模型提供商配置向导
- 支持 Telegram / Discord / 飞书 / Slack 消息渠道
- `.run` 自解压包和 `.ipk` 安装包两种分发方式
- OpenWrt SDK feeds 集成支持
- GitHub Actions 自动构建与发布

### 安全
- WebSocket PTY 服务添加 token 认证
- WebSocket 最大并发会话限制（默认 5）
- PTY 服务默认绑定 127.0.0.1，不对外暴露
- Token 不再嵌入 HTML 源码，改为 AJAX 动态获取
- sync_uci_to_json 通过环境变量传递 token，避免 ps 泄露
- 所有渠道 Token 输入统一 sanitize_input 清洗

### 修复
- Telegram Bot Token 粘贴时被 bracketed paste 转义序列污染
- Web PTY 终端粘贴包含 ANSI 转义序列问题
- 恢复出厂配置流程异常退出
- Gemini CLI OAuth 登录在 OpenWrt 上失败
- init.d status_service() 在无 netstat 的系统上报错
- Makefile 损坏导致 OpenWrt SDK 编译失败

### 改进
- 所有 AI 提供商模型列表更新到最新版本
- UID/GID 动态分配，避免与已有系统用户冲突
- 版本号统一由 VERSION 文件管理
- README.md 完善安装说明、FAQ 和项目结构