# Changelog v1.0.8

Record image-affecting changes to `manager/`, `worker/`, `openclaw-base/` here before the next release.

---

**What's New**

- **OpenClaw Upgrade to v2026.3.8** — Upgraded the bundled OpenClaw to v2026.3.8, widely regarded as the most stable release by the community. This brings improved reliability and performance to the underlying agent runtime.

- **Alibaba Cloud Native Deployment** — Added Alibaba Cloud native deployment support with a unified cloud/local abstraction layer, including CoPaw worker support for cloud deployment. Manager Dockerfile.aliyun now sets `ENV HOME=/root/manager-workspace` so the agent writes workspace files to the correct directory.

- **Env Var Placeholder Rendering** — SKILL.md and AGENTS.md now render `${VAR}` placeholders at startup via `envsubst`, so AI agents read plain text instead of raw environment variable references.

- **Unified AI Gateway URL** — Refactored all scripts to use a single `HICLAW_AI_GATEWAY_SERVER` env var in `hiclaw-env.sh`, removing duplicated cloud/local branching from `create-worker`, `generate-worker-config`, and `model-switch` scripts.

- **Control UI Token Security** — Control UI now uses URL hash redirect for token injection, and Manager generates a distinct `hooks.token` on first boot with proper base64 encoding (`-w 0`) to prevent JSON parse errors.

- **Worker Import System** — New `hiclaw-import.sh` / `hiclaw-import.ps1` scripts and migration skill allow importing Workers from external sources, with automated analysis and zip generation for seamless migration.

- **Agent Docs Progressive Disclosure** — Restructured SKILL.md and AGENTS.md into a `references/` directory structure for progressive disclosure, reducing token consumption. Added GitHub bug report template.

- **Debug Log Export Tool** — New `export-debug-log.py` helps diagnose why an Agent's behavior doesn't meet expectations. It exports Matrix messages and agent session logs (OpenClaw / CoPaw) in one command, letting you trace the full conversation context, tool calls, and decision flow that led to an unexpected outcome. Supports time range (`--range 1h/1d`), container/room filtering, and built-in PII auto-redaction for safe sharing in bug reports.

- **Install Step-Back Navigation** — Install scripts (sh/ps1) now support step-back navigation, allowing users to go back to previous steps during installation instead of restarting.

- **Docker Layer Optimization** — Reordered Dockerfile layer ordering for Manager, Worker, and CoPaw images to maximize cache hits and speed up upgrade pulls.

- **Worker Security Hardening** — Added mirror loop safeguard and security hardening for Workers, preventing agents from entering infinite mirror loops.

- **Higress mergeConsecutiveMessages** — Enabled `mergeConsecutiveMessages` for all LLM providers in Higress gateway config, improving compatibility with models that reject consecutive same-role messages.

- **Infinite Task Loop Prevention** — Improved error guidance in task-management and model-switch skills to prevent agents from entering infinite task loops.

**Bug Fixes**

- Fixed GPT-5 model LLM connectivity tests — use `max_completion_tokens` instead of `max_tokens` for GPT-5 models; also removed `max_tokens=1` from LLM connectivity tests across install scripts.

- Fixed Worker name handling in `create-worker.sh` — normalize worker name to lowercase to match Tuwunel's username storage behavior, fixing invite failures when names contain uppercase letters; added validation to reject invalid characters before Matrix registration.

- Fixed welcome message readiness in Aliyun deployment — use gateway health check instead of Matrix room member polling, with timeout increased to 300s.

- Fixed skill removal cleanup — Manager's `--remove-skill` now deletes MinIO files and notifies worker; worker prunes stale skill dirs while preserving builtins.

---

**新增功能**

- **OpenClaw 升级至 v2026.3.8** — 将内置 OpenClaw 升级至 v2026.3.8，这是社区评价最稳定的新版本，带来了更好的可靠性和性能。

- **阿里云原生部署** — 新增阿里云原生部署支持，提供统一的云/本地抽象层，包括 CoPaw Worker 的云端部署支持。Manager Dockerfile.aliyun 现在设置 `ENV HOME=/root/manager-workspace`，确保 Agent 将工作区文件写入正确目录。

- **环境变量占位符渲染** — SKILL.md 和 AGENTS.md 现在在启动时通过 `envsubst` 渲染 `${VAR}` 占位符，AI Agent 读取的是纯文本而非原始环境变量引用。

- **统一 AI Gateway URL** — 重构所有脚本使用统一的 `HICLAW_AI_GATEWAY_SERVER` 环境变量，移除 `create-worker`、`generate-worker-config` 和 `model-switch` 脚本中重复的云/本地分支逻辑。

- **Control UI Token 安全增强** — Control UI 现在使用 URL hash 重定向注入 token，Manager 首次启动时生成独立的 `hooks.token`，并使用 `base64 -w 0` 编码防止 JSON 解析错误。

- **Worker 导入系统** — 新增 `hiclaw-import.sh` / `hiclaw-import.ps1` 脚本和 migration skill，支持从外部导入 Worker，提供自动化分析和 zip 生成实现无缝迁移。

- **Agent 文档渐进式披露** — 将 SKILL.md 和 AGENTS.md 重构为 `references/` 目录结构实现渐进式披露，降低 token 消耗。新增 GitHub bug report 模板。

- **Debug Log 导出工具** — 新增 `export-debug-log.py`，帮助诊断 Agent 行为不达预期的原因。一条命令即可导出 Matrix 消息和 Agent 会话日志（OpenClaw / CoPaw），让你追溯完整的对话上下文、工具调用和决策流程，定位问题根因。支持时间范围过滤（`--range 1h/1d`）、容器/房间过滤，内置 PII 自动脱敏，可安全用于 bug report 分享。

- **安装脚本回退导航** — 安装脚本（sh/ps1）现在支持回退导航，用户可以在安装过程中返回上一步而无需重新开始。

- **Docker 镜像层优化** — 重排 Manager、Worker 和 CoPaw 的 Dockerfile 层顺序，最大化缓存命中率，加速升级拉取。

- **Worker 安全加固** — 新增 mirror loop 防护和安全硬化，防止 Agent 进入无限镜像循环。

- **Higress 消息合并** — 为 Higress 网关所有 LLM provider 启用 `mergeConsecutiveMessages`，提升对拒绝连续同角色消息的模型的兼容性。

- **无限任务循环防护** — 改进 task-management 和 model-switch skill 的错误引导，防止 Agent 陷入无限任务循环。

**Bug 修复**

- 修复 GPT-5 模型 LLM 连通性测试 — 对 GPT-5 模型使用 `max_completion_tokens` 替代 `max_tokens`；同时移除安装脚本中 LLM 连通性测试的 `max_tokens=1`。

- 修复 `create-worker.sh` 中 Worker 名称处理 — 将 Worker 名称规范化为小写以匹配 Tuwunel 的用户名存储行为，修复名称含大写字母时的邀请失败问题；新增验证逻辑拒绝无效字符。

- 修复阿里云部署中欢迎消息就绪检测 — 使用网关健康检查替代 Matrix 房间成员轮询，超时时间增加至 300 秒。

- 修复技能移除清理 — Manager 的 `--remove-skill` 现在删除 MinIO 文件并通知 Worker；Worker 清理过时技能目录同时保留内置技能。

---

- feat: upgrade openclaw to v2026.3.8 ([7dea227](https://github.com/alibaba/hiclaw/commit/7dea227))
- feat(cloud): add Alibaba Cloud native deployment support with unified cloud/local abstraction layer ([b98dcc8](https://github.com/alibaba/hiclaw/commit/b98dcc8))
- feat(cloud): add CoPaw worker support for cloud deployment ([58a012f](https://github.com/alibaba/hiclaw/commit/58a012f))
- feat(agent): render env var placeholders in SKILL.md/AGENTS.md at startup via envsubst ([7d18776](https://github.com/alibaba/hiclaw/commit/7d18776))
- refactor(manager): unify AI Gateway URL into `HICLAW_AI_GATEWAY_SERVER` in hiclaw-env.sh ([4046019](https://github.com/alibaba/hiclaw/commit/4046019))
- fix(manager): use distinct hooks.token on first boot ([ac731a7](https://github.com/alibaba/hiclaw/commit/ac731a7))
- fix(manager): use base64 -w 0 for hooks.token to prevent JSON parse error ([d8ac9e8](https://github.com/alibaba/hiclaw/commit/d8ac9e8))
- fix: use URL hash redirect for Control UI token injection ([b3df8fe](https://github.com/alibaba/hiclaw/commit/b3df8fe))
- fix(manager): use max_completion_tokens for GPT-5 models in LLM connectivity tests ([f3c6529](https://github.com/alibaba/hiclaw/commit/f3c6529))
- fix: remove max_tokens=1 from LLM connectivity tests ([4fc97bd](https://github.com/alibaba/hiclaw/commit/4fc97bd))
- fix(install): remove max_tokens=1 from LLM connectivity test in ps1 ([7ff5182](https://github.com/alibaba/hiclaw/commit/7ff5182))
- fix(manager): normalize worker name to lowercase in create-worker.sh ([0bd2f58](https://github.com/alibaba/hiclaw/commit/0bd2f58))
- fix(manager): add worker name validation and set HOME in Dockerfile.aliyun ([d800790](https://github.com/alibaba/hiclaw/commit/d800790))
- fix(manager): use gateway health check for welcome message readiness in Aliyun deployment ([ca83687](https://github.com/alibaba/hiclaw/commit/ca83687))
- fix(sync): clean up removed skills from MinIO, worker local, and active_skills ([67ddcb6](https://github.com/alibaba/hiclaw/commit/67ddcb6))
- feat: add Worker import system and migration skill ([f7c9e55](https://github.com/alibaba/hiclaw/commit/f7c9e55))
- feat: optimize agent docs, add debug log export and bug report template ([4abd8cc](https://github.com/alibaba/hiclaw/commit/4abd8cc))
- feat(install): add step-back navigation support ([9938330](https://github.com/alibaba/hiclaw/commit/9938330))
- perf(docker): optimize layer ordering for faster upgrade pulls ([c82c2af](https://github.com/alibaba/hiclaw/commit/c82c2af))
- feat(agent): add mirror loop safeguard and security hardening for workers ([ba60e95](https://github.com/alibaba/hiclaw/commit/ba60e95))
- feat(higress): enable mergeConsecutiveMessages for all LLM providers ([8c44c5b](https://github.com/alibaba/hiclaw/commit/8c44c5b))
- fix(manager): improve error guidance and prevent infinite task loops ([586ff51](https://github.com/alibaba/hiclaw/commit/586ff51))
