HiClaw Star 激增，全网征集实践教程

阿里-于怀

216人浏览 · 2026-03-11 14:45:00

阿里-于怀 · 2026-03-11 14:45:00 发布

作者：望宸、澄潭、计缘

HiClaw 上周开源后，Star 迅速飙涨，同时，多样化的安装环境和多层次的使用场景也带来了大量的咨询。在此，感谢各位开发者提供的建议，我们迅速整理了 FAQ，并已发布到 GitHub，方便大家检索。同时，我们新增两个自动化服务工具：

1、有问题，提 issue：每天10点和18点，HiClaw GitHub 会有一只龙虾🦞，对所有 issue 进行答复，。

2、有问题，艾特机器人：推荐加入钉群(163855016601)，钉群服务机器人将于下周上线，提供自助答疑服务。

一、项目选型

1、HiClaw 和其他 xxClaw 有哪些不同？

HiClaw 并不和其他 xxClaw 对标，HiClaw 是一个多 Agent 协作系统。

每个 Claw 支持用户自定义，可以是 OpenClaw，也可以是 Copaw、NanoClaw、ZeroClaw 或是企业自建的 Agent，目前预装的是 OpenClaw。
引入了 Manger Claw 的角色，不用真人去管理每个干活的 Worker Claw，节省管理成本。
使用 Element IM 客户端+Tuwunel IM 服务器（均基于 Matrix 实时通信协议），通信协议和原生的不同，节省钉钉、飞书 IM 的接入和企业内的审批成本，方便用户快速体验在 IM 的交互环境中体验模型服务的“爽感”，同时支持以 OpenClaw 原生的方式接入 IM。
引入 MinIO 共享文件系统，用于 Agent 之间的信息共享，真人之间的协作，共同记忆也是基于共享文件系统。
引入 Higress AI Gateway，入口和各类凭证风险降低了，减少了用户对原生龙虾在安全上的顾虑。

2、HiClaw 能用百炼 Coding Plan 么？每个龙虾支持使用不同的模型服务么？

HiClaw 配置过程中，模型服务接入的默认选型是百炼 Coding Plan。每个 Worker 龙虾的模型服务，可以通过 Manager 龙虾来进行分配，也可以在 Higress 控制台进行配置。

3、能用于企业内的数字员工么？即企业里每个员工一套 Claw 系统，使用本地存储或者集中存储。

可以的，但是部署方式需要企业自行解决；后续会和阿里云的云产品，例如函数计算 FC 合作，推出云端的企业级部署方案。

4、我不想用 Element IM 客户端，直接接钉钉或飞书，可以吗？

可以的，安装目录下有 hiclaw-manager，可以手动配 openclaw.json，跟 OpenClaw 的接入方式是一样的。

5、Manager 和 Workers 之间，Worker 和 Worker 之间，环境是隔离的吗？

是的，HiClaw Manager 和 Workers 均各自运行在完全隔离的容器里，不持有任何真实凭证，这样做的好处是：

Skills 隔离，避免混用。
Memory 隔离，避免记忆混淆。
放心 Worker 放心地从上万个公开技能库里按需获取能力，Skills 能延展 HiClaw 的使用场景。

6、我已经安装并在使用 OpenClaw，有平滑迁移方案么？

因为 HiClaw 的定位并不是对标或替换 OpenClaw，是不冲突的，不存在迁移方案。此外，用户安装 HiClaw 后，基于 HiClaw 的 Manager + Workers 的协作网络，可以将原有的 OpenClaw 作为 Worker 纳管进来。

7、OpenClaw 上安装的 Skills，以及插件，HiClaw 是否支持？

插件和 Skills 都支持，进入 Manager 容器执行 OpenClaw 的插件和 Skills 配置命令就可以。但要暴露端口给宿主机的，考虑安全原因，暂不支持。

8、安装 HiClaw，有哪些环境要求？

支持 Mac、Window 和 Linux 环境，其中，Window 环境要求是 PowerShell 7+。（推荐使用 Mac）
下载并安装 Docker Desktop（Windows/macOS）或 Docker Engine（Linux）或 Podman Desktop（替代方案）。
最低 2C GB 内存。如果希望部署较多 Worker 体验更强大的 Agent Teams 能力，建议 4C8GB 内存。OpenClaw 内存占用较高，Docker Desktop 用户可在 Settings → Resources 中调整。

二、项目实操

1、如何查看当前 HiClaw 版本？

执行以下命令查看已安装的版本：

docker exec hiclaw-manager cat /opt/hiclaw/agent/.builtin-version

重新执行安装脚本，即可原地升级，数据和配置会保留。默认升级到最新版本。

HICLAW_VERSION=0.2.0 bash <(curl -sSL https://higress.ai/hiclaw/install.sh)

2、Windows 下执行安装脚本，出现闪退？

如果在 Windows 下执行 PowerShell 安装脚本后窗口立即关闭，请先确认是否已安装 Docker Desktop。如果已安装，请确认 Docker Desktop 是否已启动并完全加载，脚本需要连接 Docker 守护进程，Docker Desktop 未运行时会直接失败退出。

3、Manager Agent 启动超时或失败？

安装完成后如果 Manager Agent 迟迟没有响应，进容器查看日志：

docker exec -it hiclaw-manager cat /var/log/hiclaw/manager-agent.log

情况一：日志中有进程退出记录

可能是 Docker VM 分配的内存不足。建议将内存调整到 4GB 以上：Docker Desktop → Settings → Resources → Memory。调整后重新执行安装命令。

情况二：日志中没有进程退出，但某些组件起不来

可能是配置脏数据导致的。建议到原安装目录重新执行安装命令，选择删除重装：

bash <(curl -sSL https://higress.ai/hiclaw/install.sh)

安装脚本检测到已有安装时会询问处理方式，选择删除后重装即可清除脏数据。

情况三：Mac M 系列芯片 + 低版本 Docker

如果你使用的是搭载 Apple M 系列芯片（M1/M2/M3/M4）的 Mac，且 Docker Desktop 版本低于 4.39.0，Manager Agent 可能无法正常启动。

解决方案：升级 Docker Desktop 到 4.39.0 或更高版本。如果你使用的是 Podman，则不受此问题影响。

4、局域网其他电脑如何访问 Web 端？

访问 Element Web

在局域网其他电脑的浏览器中输入：

http://<局域网IP>:18088

浏览器可能会提示"不安全"或"不支持"，忽略提示直接点 Continue 进入即可。

修改 Matrix Server 地址

默认配置的 Matrix Server 域名解析到 localhost，在其他电脑上无法连通。登录 Element Web 时，需要将 Matrix Server 地址改为：

http://<局域网IP>:18080

例如局域网 IP 是 192.168.1.100，则填写 http://192.168.1.100:18080。

5、本地访问 Matrix 服务器不通

官方教程提供的房间是走本地 127.0.0.1，这是本地回环网卡。*-local.hiclaw.io 域名默认解析到 127.0.0.1，开启代理后请求会被转发到代理服务器，无法到达本地服务。

请检查浏览器或系统是否开启了代理。关闭代理，或将 *-local.hiclaw.io / 127.0.0.1 加入代理的绕过列表即可。

6、如何主动指挥 Worker

创建 Worker 后，Manager 会自动将你和 Worker 拉入同一个群聊房间。在群聊中，必须 @ Worker 才能让它响应，没有 @ 的消息会被忽略。在 Element 等客户端中，输入 @ 后再输入 Worker 昵称的首字母，才会出现补全列表，选择对应用户即可。

也可以点击 Worker 的头像，进入私聊。私聊中不需要 @，每条消息都会触发 Worker 响应。但注意：私聊对 Manager 不可见，Manager 不会感知到这部分对话内容。

7、如何切换 Manager 的模型

让 Manager 切换（推荐）

OpenClaw 需要在配置中设置模型的上下文窗口大小（contextWindow）。HiClaw 默认使用 qwen3.5-plus 的 1M token 窗口。如果切换到窗口更小的模型但没有更新这个设置，当对话接近窗口上限时，OpenClaw 不知道何时压缩上下文，可能导致 session 无法使用。

为此，HiClaw 给 Manager 配备了模型切换技能，会根据模型名自动修改 OpenClaw 配置中的 contextWindow 和 maxTokens。

切换步骤

在 Higress 控制台配置好模型供应商后，直接告诉 Manager 模型名即可："切换到 claude-3-5-sonnet"Manager 会使用模型切换技能完成配置更新。

如果切换没有成功？可能是 Manager 没有自动调用模型切换技能。可以主动告诉它：“用模型切换技能帮我切换到 claude-3-5-sonnet”。

让 Higress AI 控制台切换

单供应商情况

在 Higress 控制台，将 default-ai-route 这个路由配置到你的模型供应商。然后直接告诉 Manager 你想使用的具体模型名（例如 qwen3.5-plus）。Manager 会先用该模型名发起一次联通测试，测试通过后自动完成切换。

多供应商情况

在 Higress 控制台，创建多条 AI 路由，每条路由配置不同的模型名匹配规则（前缀或正则），分别指向对应的供应商。之后的流程与单供应商完全一致——告诉 Manager 模型名，它会自动完成测试和切换。

参考：Higress AI 快速开始 — 控制台配置

8、如何切换 Worker 的模型

流程与切换 Manager 模型类似，两种情况都由 Manager 代为操作。

创建时指定：在让 Manager 创建 Worker 时直接说明模型，例如"帮我创建一个名为 alice 的 Worker，使用 qwen3.5-plus"。

创建后修改：随时告诉 Manager 切换某个 Worker 的模型，例如"把 alice 的模型切换为 claude-3-5-sonnet"，Manager 会自动更新该 Worker 的配置。

切换前请确保 Higress 的 default-ai-route 已配置好目标模型名到对应供应商的路由。

9、HiClaw 支持发送和接收文件吗？

接收你发送的文件：支持。在 Element Web 中点击附件按钮上传文件，Manager 或 Worker 会收到 Matrix 媒体消息并可以读取其内容。

向你发送文件：支持。当你要求 Manager（或 Worker）发送文件时——例如任务产物、生成的报告或它能访问的任意文件——它会将文件上传到 Matrix 媒体服务器，并以可下载附件的形式发送到房间中，你在 Element Web 里点击即可下载。

10、为什么 Manager/Worker 一直显示"输入中"？

这是正常现象，说明底层的 OpenClaw Agent 引擎正在执行任务。HiClaw 设定的单次任务超时时间为 30 分钟，Agent 最长会持续执行 30 分钟。

如果想查看 Agent 的执行细节，可以进入 Manager 或 Worker 容器，查看 session 日志：

# Manager
docker exec -it hiclaw-manager ls .openclaw/agents/main/sessions/

# Worker（将 <worker-name> 替换为实际容器名）
docker exec -it <worker-name> ls .openclaw/agents/main/sessions/

该目录下的 .jsonl 文件由 OpenClaw 实时写入，记录了完整的 Agent 执行过程，包括 LLM 调用、工具使用、推理步骤等。

后续，我们将上线 Team 看板，用于查看日志和对话。

11、在房间里和 Manager 聊天没有响应或返回错误状态码

如果 Manager 没有响应，或者返回了 404、503 等状态码，查看 Higress AI 网关日志：

docker exec -it hiclaw-manager cat /var/log/hiclaw/higress-gateway.log

在日志中搜索对应的状态码，常见原因：

503：容器内网络环境问题，导致外网 LLM 服务不可达。
404：模型名称填写有误。

要判断是后端服务出错还是 Higress 自身配置问题，查看日志中的 upstream_host 字段：如果该字段有值，说明请求已到达后端，异常状态码是由上游服务返回的；如果为空，说明 Higress 本身无法路由该请求。

12、HTTP 401: invalid access token or token expired

检查 HiClaw 安装过程中，API 联通性是否通过。未通过如下：

若出现以上情况，需要检查模型 API，我们这里以百炼 Coding Plan 为例：

通过的效果如下，通过后不会再报 401。

13、Manager/Worker 不回复消息怎么办

如果给 Manager 或 Worker 发送消息后没有回复，可以按以下步骤排查：

检查是否正在工作

如果一直不回复，且没有显示"输入中"，绝大多数原因是 Agent 正在工作。

OpenClaw 限制"输入中"状态最多持续 2 分钟，工作超过 2 分钟就不会再显示"输入中"了。

如何确认消息已入队列：

发送消息后，查看消息右边是否有一个 m 小图标
这个图标表示 Manager 已读
出现这个图标就说明消息已入队列，会在当前任务执行完后继续处理该消息

IM异步协作的方式是OpenClaw的精髓所在，不用一直盯着它干活，带着耳机，听到滴滴的声音，说明他干完活跟你汇报了，去看一眼就好

检查聊天环境

私聊 vs 群聊：

如果是私聊（只有你和一个 Agent），每条消息都会触发 Agent 响应
如果是 2 人以上的房间（群聊），必须 @ Agent才能让它响应，没有 @ 的消息会被忽略

检查 Session 状态

可能是 OpenClaw session 卡住了。进入 Manager 或 Worker 容器，使用 OpenClaw TUI 查看：

# Manager
docker exec -it hiclaw-manager openclaw tui

# Worker（将 <worker-name> 替换为实际容器名）
docker exec -it <worker-name> openclaw tui

进入 TUI 后：

输入 /sessions 查看所有 session
切换到对应聊天记录的 session
尝试对话，观察是否有报错

如果 session 确实卡住了，可以尝试用/reset 重置 session，看是否恢复正常。

检查模型配置

可能是模型的上下文窗口大小配置不正确，导致窗口耗尽前没有及时压缩。请参考 如何切换 Manager 的模型 和 如何切换 Worker 的模型 进行正确配置。

14、如何对接飞书/钉钉/企业微信/Discord/Telegram

HiClaw Manager 基于 OpenClaw 构建，原生支持多种消息渠道。要对接其他渠道：

方法一：直接修改配置

Manager 的工作目录是宿主机上的 ~/hiclaw-manager，里面的 openclaw.json 可以直接编辑。参照 OpenClaw 渠道文档中各平台的配置格式进行配置。

修改后重启 Manager 容器使配置生效：

docker restart hiclaw-manager

方法二：让 Manager 学习你现有的 OpenClaw 配置

如果你已经在其他地方使用 OpenClaw 接入了其他渠道，可以让 Manager 读取你现有的配置：

告诉 Manager 文件位置：在 Element Web 中告诉 Manager 你的 OpenClaw 配置文件路径（例如 “我的 OpenClaw 配置在 /home/user/my-openclaw.json”），Manager 会直接读取。
通过附件发送：在 Element Web 或其他 Matrix 客户端中，把配置文件作为附件上传发送给 Manager，Manager 会接收并读取。

然后让 Manager 帮你在它的配置里添加相同的渠道。

三、近期的 Roadmap

1、轻量级 Worker 运行时

目前 Worker 基于 OpenClaw 运行，内存占用较高（约 500MB+）。我们计划支持更轻量的 Agent 运行时：

CoPaw（最新代码已支持）：AgentScope 团队开发的轻量 Agent 运行时，支持本地模型（llama.cpp/MLX/Ollama）和多渠道接入，内存占用比 OpenClaw 更低
ZeroClaw：基于 Rust 的超轻量运行时，3.4MB 二进制，冷启动 <10ms，专为边缘和资源受限环境设计
NanoClaw：极简 OpenClaw 替代品，<4000 行代码，基于容器隔离，使用 Anthropic Agents SDK

目标：将单 Worker 内存占用从 ~500MB 降至 <100MB，在相同硬件上支持更多 Worker。