github alibaba/hiclaw v1.0.7
on GitHub

latest release: v1.0.8
8 days ago

What's New

  • Worker Availability & Auto-Recovery — New find-worker.sh consolidates worker availability checks (registry + state + lifecycle + SOUL.md) into a single call. New ensure-ready action in lifecycle-worker.sh auto-starts stopped or auto-recreates missing Workers before sending messages. HEARTBEAT Steps 2/3/4 now call ensure-ready before contacting Workers, preventing messages sent to stopped containers.

  • Delegation-First Principle — Manager now explicitly prioritizes assigning tasks to Workers over self-execution. Task-management SKILL.md Step 0 decision flow marks Worker delegation as preferred and self-execution as last resort.

  • Finite vs Infinite Task Management — Task-management SKILL.md adds a decision guide for finite vs infinite tasks. Idle detection now considers infinite tasks as active — Workers with active infinite tasks are no longer auto-stopped. HEARTBEAT Steps 5/6 updated accordingly.

  • Admin Notification Unification — New resolve-notify-channel.sh unifies admin notification channel resolution (primary-channel → Matrix DM fallback). New manage-primary-channel.sh provides validated, atomic primary-channel.json operations (confirm/reset/show). HEARTBEAT and channel-management SKILL.md now use these scripts instead of inline logic.

  • Known Models & Hot-Switch — All known models are pre-configured in openclaw.json templates, so switching between them is a hot-reload (no restart). New known-models.json and upgrade-path merge ensures existing deployments get missing models on Manager restart. Model-switch scripts detect known vs unknown models via the models array instead of overwriting models[0].

  • Model Alias Support — All known models get agents.defaults.models alias entries (e.g. "hiclaw-gateway/claude-sonnet-4-6": {"alias": "claude-sonnet-4-6"}). Templates, upgrade merge, and model-switch scripts all generate aliases. Worker upgrade merge is now unconditional and idempotent (diff-based push).

  • CoPaw E2EE Support — Full end-to-end encryption for CoPaw Matrix channels: bridge encryption flag from openclaw.json, create matrix-nio client with crypto store, handle encrypted media events (Image/Audio/Video/File), auto-upload E2E keys, auto-query device keys on sync, ignore unverified devices for bot use case. Dependency upgraded to matrix-nio[e2e].

  • CoPaw Markdown Rendering — Matrix messages now render Markdown as HTML using markdown-it-py (same engine as OpenClaw) with linkify, breaks, strikethrough, and table support.

  • Configurable Worker Idle Timeout — New HICLAW_WORKER_IDLE_TIMEOUT env var (default: 720 minutes = 12 hours) controls Worker idle auto-stop timeout, configurable via install script and persisted in hiclaw-manager.env.

Bug Fixes

  • Fixed hiclaw-sync: Permission denied after upgrade — replaced symlink with /bin/sh wrapper so execution does not depend on +x permission bit (MinIO does not preserve Unix permissions); added chmod +x in hiclaw-sync.sh and entrypoint fallback sync to restore script permissions after pull.

  • Fixed upgrade pulling both openclaw and copaw worker images when the other runtime's image exists locally, ensuring all worker containers get updated regardless of the selected default runtime.

  • Fixed Worker builtin-upgrade notification spam — added cooldown (default 1h) to prevent repeated Matrix messages wasting Worker tokens when Manager crash-loops.

  • Fixed CoPaw duplicate skills after upgrade — removes stale customized_skills/ copies when a newer CoPaw version ships the same skill as a builtin.

  • Fixed Worker AGENTS.md @mention protocol — require @mention when replying to Manager progress inquiries; changed phase completion to task-only completion notification (TASK_COMPLETED format).

  • Fixed CoPaw skill sync — now mirrors entire skill directory (including scripts/ and references/) instead of only pulling SKILL.md, matching OpenClaw worker's mc mirror behavior; restores +x on .sh files after pull.

  • Fixed Worker AGENTS.md upgrade — now uses builtin-section merge instead of mc cp overwrite, preserving Worker's custom content after <!-- hiclaw-builtin-end --> marker; legacy files without markers are overwritten and gain marker protection on first upgrade.

  • Fixed CoPaw inner config sync — .copaw/AGENTS.md and .copaw/SOUL.md changes now sync back to outer layer before MinIO push (previously Agent modifications were silently lost on restart or re-bridge).

  • Fixed CoPaw _sync_skills — now mirrors full skill directories (SKILL.md + scripts/ + references/) from outer skills/ to inner .copaw/active_skills/.

  • Fixed Worker/CoPaw E2EE re-login on restart — Workers now call m.login.password on startup to get a fresh access token and device ID, preventing Element Web from rejecting key distribution when the identity key changes after crypto storage cleanup. Manager writes Matrix password directly to MinIO, Workers read it via mc cat at startup; includes migration for existing workers.

  • Fixed .openclaw/matrix/** and .openclaw/canvas/** excluded from MinIO sync — Matrix crypto SQLite corrupts when synced via object storage (no POSIX file locks); canvas is regenerated on startup.

  • Fixed Manager/Worker .openclaw/matrix cleanup on startup — prevents "database disk image is malformed" errors after unclean shutdown; E2EE sessions are automatically re-negotiated.

  • Fixed manage-state.sh executed action no longer errors when infinite task is missing from active_tasks (backward compat with legacy tasks).

  • Fixed CoPaw slash commands in group rooms — skip history prepend when message starts with / so command parser recognises the command; strip @mention prefix before slash command detection.

  • Fixed CoPaw E2EE key maintenance in sync loop — keys_claim and send_to_device_messages were missing, preventing Olm session establishment; also fixed catch-up sync not actually suppressing callbacks.

  • Fixed CoPaw sync token persistence — persist Matrix sync token to disk and restore on restart, preventing replaying old messages after container restart.

  • Fixed Worker openclaw.json upgrade now adds missing encryption field for existing workers (previously only new workers got it from template).

  • Fixed TOOLS.md channel-management first-contact trigger corrected from "first time" to "channel mismatch", added show command.

  • Fixed TOOLS.md clarification of copaw runtime vs deployment mode (copaw ≠ remote), added Deployment column to runtime table.

新增功能

  • Worker 可用性检查与自动恢复 — 新增 find-worker.sh 将 Worker 可用性检查（注册表 + 状态 + 生命周期 + SOUL.md）整合为单次调用。lifecycle-worker.sh 新增 ensure-ready 动作，在发送消息前自动启动已停止或自动重建缺失的 Worker。HEARTBEAT 步骤 2/3/4 现在在联系 Worker 前调用 ensure-ready，避免向已停止的容器发送消息。

  • 委派优先原则 — Manager 现在明确优先将任务分配给 Worker 而非自行执行。task-management SKILL.md 步骤 0 决策流将 Worker 委派标记为首选，自行执行作为最后手段。

  • 有限/无限任务管理 — task-management SKILL.md 新增有限任务与无限任务的决策指南。空闲检测现在将无限任务视为活跃状态 — 有活跃无限任务的 Worker 不再被自动停止。HEARTBEAT 步骤 5/6 相应更新。

  • 管理员通知统一 — 新增 resolve-notify-channel.sh 统一管理员通知频道解析（primary-channel → Matrix DM 回退）。新增 manage-primary-channel.sh 提供经过验证的原子化 primary-channel.json 操作（confirm/reset/show）。HEARTBEAT 和 channel-management SKILL.md 现在使用这些脚本替代内联逻辑。

  • 已知模型与热切换 — 所有已知模型预配置在 openclaw.json 模板中，切换已知模型无需重启（热加载）。新增 known-models.json 和升级路径合并，确保现有部署在 Manager 重启时获得缺失的模型。模型切换脚本通过 models 数组检测已知/未知模型，而非覆盖 models[0]。

  • 模型别名支持 — 所有已知模型获得 agents.defaults.models 别名条目（如 "hiclaw-gateway/claude-sonnet-4-6": {"alias": "claude-sonnet-4-6"}）。模板、升级合并和模型切换脚本均生成别名。Worker 升级合并现在是无条件且幂等的（基于 diff 推送）。

  • CoPaw E2EE 支持 — CoPaw Matrix 频道全面支持端到端加密：从 openclaw.json 桥接 encryption 标志，启用时创建带 crypto store 的 matrix-nio 客户端，处理加密媒体事件（图片/音频/视频/文件），自动上传 E2E 密钥，同步时自动查询设备密钥，对 bot 场景忽略未验证设备。依赖升级至 matrix-nio[e2e]。

  • CoPaw Markdown 渲染 — Matrix 消息现在使用 markdown-it-py（与 OpenClaw 相同引擎）将 Markdown 渲染为 HTML，支持 linkify、换行、删除线和表格。

  • 可配置 Worker 空闲超时 — 新增 HICLAW_WORKER_IDLE_TIMEOUT 环境变量（默认：720 分钟 = 12 小时）控制 Worker 空闲自动停止超时，可通过安装脚本配置并持久化到 hiclaw-manager.env。

Bug 修复

  • 修复升级后 hiclaw-sync: Permission denied — 用 /bin/sh 包装器替代符号链接，使执行不依赖 +x 权限位（MinIO 不保留 Unix 权限）；在 hiclaw-sync.sh 和入口点回退同步中添加 chmod +x 恢复脚本权限。

  • 修复升级时同时拉取 openclaw 和 copaw worker 镜像的问题 — 当另一运行时的镜像本地存在时，确保所有 worker 容器都能更新。

  • 修复 Worker 内置升级通知刷屏 — 添加冷却时间（默认 1 小时），防止 Manager 崩溃循环时重复发送 Matrix 消息浪费 Worker token。

  • 修复 CoPaw 升级后技能重复 — 当新版 CoPaw 将同一技能作为内置技能发布时，移除过时的 customized_skills/ 副本。

  • 修复 Worker AGENTS.md @mention 协议 — 回复 Manager 进度询问时要求 @mention；阶段完成改为仅任务完成通知（TASK_COMPLETED 格式）。

  • 修复 CoPaw 技能同步 — 现在镜像整个技能目录（包括 scripts/ 和 references/）而非仅拉取 SKILL.md，与 OpenClaw worker 的 mc mirror 行为一致；拉取后恢复 .sh 文件的 +x 权限。

  • 修复 Worker AGENTS.md 升级 — 现在使用 builtin-section 合并替代 mc cp 覆盖，保留 <!-- hiclaw-builtin-end --> 标记后的 Worker 自定义内容；无标记的旧文件在首次升级时被覆盖并获得标记保护。

  • 修复 CoPaw 内部配置同步 — .copaw/AGENTS.md 和 .copaw/SOUL.md 的修改现在在 MinIO 推送前同步回外层（此前 Agent 对这些文件的修改在重启或重新桥接后会静默丢失）。

  • 修复 CoPaw _sync_skills — 现在从外层 skills/ 到内层 .copaw/active_skills/ 镜像完整技能目录（SKILL.md + scripts/ + references/）。

  • 修复 Worker/CoPaw 重启时 E2EE 重新登录 — Worker 启动时调用 m.login.password 获取新的 access token 和 device ID，防止 Element Web 在 crypto 存储清理后因 identity key 变化拒绝密钥分发。Manager 将 Matrix 密码直接写入 MinIO，Worker 启动时通过 mc cat 读取；包含现有 worker 的迁移。

  • 修复 .openclaw/matrix/** 和 .openclaw/canvas/** 从 MinIO 同步中排除 — Matrix crypto SQLite 通过对象存储同步会损坏（无 POSIX 文件锁）；canvas 在启动时重新生成。

  • 修复 Manager/Worker 启动时清理 .openclaw/matrix — 防止非正常关闭后出现 "database disk image is malformed" 错误；E2EE 会话自动重新协商。

  • 修复 manage-state.sh executed 动作在 active_tasks 中缺少无限任务时不再报错（向后兼容旧任务）。

  • 修复 CoPaw 群聊中的斜杠命令 — 消息以 / 开头时跳过历史前置，使命令解析器能识别命令；在斜杠命令检测前去除 @mention 前缀。

  • 修复 CoPaw E2EE 同步循环中的密钥维护 — 此前缺少 keys_claim 和 send_to_device_messages，导致无法建立 Olm 会话；同时修复 catch-up 同步未实际抑制回调的问题。

  • 修复 CoPaw 同步令牌持久化 — 将 Matrix 同步令牌持久化到磁盘并在重启时恢复，防止容器重启后重放旧消息。

  • 修复 Worker openclaw.json 升级现在为现有 worker 添加缺失的 encryption 字段（此前仅新 worker 从模板获得）。

  • 修复 TOOLS.md channel-management 首次联系触发条件从 "first time" 更正为 "channel mismatch"，新增 show 命令。

  • 修复 TOOLS.md 澄清 copaw 运行时与部署模式（copaw ≠ remote），在运行时表中新增 Deployment 列。

Commit Log

  • feat(copaw): convert Markdown to HTML in Matrix messages using markdown-it-py (same engine as OpenClaw) with linkify, breaks, strikethrough, and table support (490f314)
  • feat(manager): add find-worker.sh to consolidate worker availability check (registry + state + lifecycle + SOUL.md) into a single script call (5fe1ce8)
  • fix(manager): lifecycle-worker.sh idle detection now considers infinite tasks — Workers with active infinite tasks are no longer auto-stopped (8a5a3a4)
  • fix(manager): HEARTBEAT.md Steps 5/6 updated to treat infinite tasks as active for idle detection and anomaly checks (8a5a3a4)
  • feat(manager): task-management SKILL.md adds finite vs infinite decision guide for the Agent (8a5a3a4)
  • feat(manager): add resolve-notify-channel.sh to unify admin notification channel resolution (primary-channel → Matrix DM fallback) (a6a9dfd)
  • feat(manager): add manage-primary-channel.sh for validated, atomic primary-channel.json operations (confirm/reset/show) (a6a9dfd)
  • feat(manager): task-management SKILL.md adds admin notification step on finite task completion (a6a9dfd)
  • feat(manager): project-management SKILL.md adds admin notification step on project task completion (a6a9dfd)
  • refactor(manager): HEARTBEAT.md Step 7 and Step 1 now use resolve-notify-channel.sh instead of inline channel resolution (a6a9dfd)
  • refactor(manager): channel-management SKILL.md replaces all manual cat/jq writes with manage-primary-channel.sh calls (a6a9dfd)
  • fix(manager): TOOLS.md channel-management first-contact trigger corrected from "first time" to "channel mismatch", added show command (bf8ee85)
  • fix(manager): TOOLS.md clarifies copaw runtime vs deployment mode (copaw ≠ remote), adds Deployment column to runtime table (bf8ee85)
  • feat(manager): TOOLS.md task-management fewshot now includes infinite task trigger scenario (bf8ee85)
  • fix(manager): manage-state.sh executed action no longer errors when infinite task is missing from active_tasks (backward compat with legacy tasks) (54a519d)
  • feat(manager): add delegation-first principle to SOUL.md — Manager prioritizes assigning tasks to Workers over self-execution (39dd290)
  • feat(manager): task-management SKILL.md Step 0 decision flow now explicitly marks Worker delegation as preferred and self-execution as last resort (39dd290)
  • fix(worker): fix hiclaw-sync: Permission denied after upgrade — replace symlink with /bin/sh wrapper so execution does not depend on +x permission bit (fe27103)
  • fix(install): upgrade now pulls both openclaw and copaw worker images when the other runtime's image exists locally (c1ea3ab)
  • fix(manager): add cooldown (default 1h) to worker builtin-upgrade notification (7598108)
  • fix(copaw): deduplicate customized skills that shadow builtins after upgrade (5b5cacb)
  • docs(manager): improve CoPaw console documentation in SKILL.md — add trigger keywords, description, and scope notes; restructure TOOLS.md (1e132ca)
  • fix(manager): worker AGENTS.md @mention protocol — require @mention when replying to Manager progress inquiries; change phase completion to task-only completion notification (189be17)
  • fix(copaw): skill sync now mirrors entire skill directory (including scripts/ and references/) instead of only pulling SKILL.md (f257ab9)
  • feat(manager): pre-configure all known models in openclaw.json templates — switching between known models is now a hot-reload (e5a2091)
  • feat(manager): model-switch and worker-model-switch scripts detect known vs unknown models via openclaw.json models array (e5a2091)
  • feat(manager): model-switch and worker-model-switch SKILL.md updated — Agent checks script output for RESTART_REQUIRED (e5a2091)
  • feat(manager): add known-models.json and upgrade-path merge — on Manager restart, existing openclaw.json gets missing known models merged in (2a1052b)
  • feat(copaw): add E2EE support — bridge encryption flag from openclaw.json, create matrix-nio client with crypto store when enabled, handle encrypted media events, auto-upload E2E keys (0434a1b)
  • fix(copaw): upgrade matrix-nio dependency to matrix-nio[e2e] to include olm/peewee/atomicwrites for E2EE support (0434a1b)
  • fix(manager): worker openclaw.json upgrade now adds missing encryption field for existing workers (0434a1b)
  • fix(copaw): persist Matrix sync token to disk and restore on restart — prevents replaying old messages after container restart (0434a1b)
  • fix(copaw): add full E2EE key maintenance to sync loop — keys_claim and send_to_device_messages were missing (bff48f2)
  • fix(copaw): slash commands in group rooms — skip history prepend when message starts with "/" so command parser recognises the command (bff48f2)
  • feat(manager): add model alias support to openclaw.json — all known models get agents.defaults.models alias entries (899ef20)
  • feat(manager): unify model switch to always require restart (ac41983)
  • fix(worker): exclude .openclaw/matrix/** and .openclaw/canvas/** from MinIO sync (cd1c239)
  • fix(manager/worker): clean .openclaw/matrix on startup — prevents "database disk image is malformed" errors (cd1c239)
  • fix(manager): Worker AGENTS.md upgrade now uses builtin-section merge instead of mc cp overwrite (c20ab54)
  • fix(copaw): inner .copaw/AGENTS.md and .copaw/SOUL.md changes now sync back to outer layer before MinIO push (c20ab54)
  • fix(copaw): _sync_skills now mirrors full skill directories from outer skills/ to inner .copaw/active_skills/ (c20ab54)
  • fix(worker/copaw): E2EE re-login on restart — Workers now call m.login.password on startup to get a fresh access token and device ID (410bd61)
  • feat(manager): add ensure-ready action to lifecycle-worker.sh — checks container status and auto-starts or auto-recreates a Worker before sending messages (4bf806b)
  • feat(install): add HICLAW_WORKER_IDLE_TIMEOUT env var (default: 720 minutes = 12 hours) to control Worker idle auto-stop timeout (4bf806b)

Docker Images

Multi-architecture images (amd64 + arm64): 

# Manager
docker pull higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/hiclaw-manager:v1.0.7

# Worker
docker pull higress-registry.cn-hangzhou.cr.aliyuncs.com/higress/hiclaw-worker:v1.0.7

Quick Start

macOS / Linux

bash <(curl -fsSL https://raw.githubusercontent.com/alibaba/hiclaw/main/install/hiclaw-install.sh)

Windows (PowerShell 7+)

Set-ExecutionPolicy Bypass -Scope Process -Force; $c=New-Object Net.WebClient; $c.Encoding=[Text.Encoding]::UTF8; iex $c.DownloadString('https://higress.ai/hiclaw/install.ps1')

Documentation

For more details, see the installation guide.

Check out latest releases or
releases around alibaba/hiclaw v1.0.7

Don't miss a new hiclaw release

NewReleases is sending notifications on new releases.

Get notifications