作者望宸、澄潭、计缘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 DesktopWindows/macOS或 Docker EngineLinux或 Podman Desktop替代方案。最低 2C GB 内存。如果希望部署较多 Worker 体验更强大的 Agent Teams 能力建议 4C8GB 内存。OpenClaw 内存占用较高Docker Desktop 用户可在 Settings → Resources 中调整。二、项目实操1、如何查看当前 HiClaw 版本执行以下命令查看已安装的版本dockerexechiclaw-managercat/opt/hiclaw/agent/.builtin-version重新执行安装脚本即可原地升级数据和配置会保留。默认升级到最新版本。HICLAW_VERSION0.2.0bash(curl-sSLhttps://higress.ai/hiclaw/install.sh)2、Windows 下执行安装脚本出现闪退如果在 Windows 下执行 PowerShell 安装脚本后窗口立即关闭请先确认是否已安装 Docker Desktop。如果已安装请确认 Docker Desktop 是否已启动并完全加载脚本需要连接 Docker 守护进程Docker Desktop 未运行时会直接失败退出。3、Manager Agent 启动超时或失败安装完成后如果 Manager Agent 迟迟没有响应进容器查看日志dockerexec-ithiclaw-managercat/var/log/hiclaw/manager-agent.log情况一日志中有进程退出记录可能是 Docker VM 分配的内存不足。建议将内存调整到 4GB 以上Docker Desktop → Settings → Resources → Memory。调整后重新执行安装命令。情况二日志中没有进程退出但某些组件起不来可能是配置脏数据导致的。建议到原安装目录重新执行安装命令选择删除重装bash(curl-sSLhttps://higress.ai/hiclaw/install.sh)安装脚本检测到已有安装时会询问处理方式选择删除后重装即可清除脏数据。情况三Mac M 系列芯片 低版本 Docker如果你使用的是搭载 Apple M 系列芯片M1/M2/M3/M4的 Mac且 Docker Desktop 版本低于 4.39.0Manager 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-sonnetManager 会使用模型切换技能完成配置更新。如果切换没有成功可能是 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-sonnetManager 会自动更新该 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 日志# Managerdockerexec-ithiclaw-managerls.openclaw/agents/main/sessions/# Worker将 worker-name 替换为实际容器名dockerexec-itworker-namels.openclaw/agents/main/sessions/该目录下的.jsonl文件由 OpenClaw 实时写入记录了完整的 Agent 执行过程包括 LLM 调用、工具使用、推理步骤等。后续我们将上线 Team 看板用于查看日志和对话。11、在房间里和 Manager 聊天没有响应或返回错误状态码如果 Manager 没有响应或者返回了 404、503 等状态码查看 Higress AI 网关日志dockerexec-ithiclaw-managercat/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 查看# Managerdockerexec-ithiclaw-manager openclaw tui# Worker将 worker-name 替换为实际容器名dockerexec-itworker-nameopenclaw tui进入 TUI 后输入/sessions查看所有 session切换到对应聊天记录的 session尝试对话观察是否有报错如果 session 确实卡住了可以尝试用/reset重置 session看是否恢复正常。检查模型配置可能是模型的上下文窗口大小配置不正确导致窗口耗尽前没有及时压缩。请参考如何切换 Manager 的模型和如何切换 Worker 的模型进行正确配置。14、如何对接飞书/钉钉/企业微信/Discord/TelegramHiClaw Manager 基于 OpenClaw 构建原生支持多种消息渠道。要对接其他渠道方法一直接修改配置Manager 的工作目录是宿主机上的~/hiclaw-manager里面的openclaw.json可以直接编辑。参照 OpenClaw 渠道文档 中各平台的配置格式进行配置。修改后重启 Manager 容器使配置生效dockerrestart hiclaw-manager方法二让 Manager 学习你现有的 OpenClaw 配置如果你已经在其他地方使用 OpenClaw 接入了其他渠道可以让 Manager 读取你现有的配置告诉 Manager 文件位置在 Element Web 中告诉 Manager 你的 OpenClaw 配置文件路径例如 “我的 OpenClaw 配置在/home/user/my-openclaw.json”Manager 会直接读取。通过附件发送在 Element Web 或其他 Matrix 客户端中把配置文件作为附件上传发送给 ManagerManager 会接收并读取。然后让 Manager 帮你在它的配置里添加相同的渠道。三、近期的 Roadmap1、轻量级 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。2、Team 管理中心开箱即用的可视化控制台用于观察和管控整个 Agent Team实时观测每个 Agent 的工作过程细节可视化对话、工具调用、思考过程主动打断发现问题时可随时打断指定 Agent 的工作接管或调整方向任务时间线谁在什么时候做了什么完整历史记录资源监控每个 Worker 的 CPU/内存使用情况目标让 Agent Teams 像人类团队一样透明可控——没有黑盒。3、通用 MCP 服务支持目前 Worker 通过 Higress MCP 网关 mcporter 访问 GitHub只需使用 Higress 签发的 token真实的 GitHub PAT 永远不会暴露给 Worker。这个安全的模式可以扩展到任意 MCP 服务预置 MCP 连接器GitHub、Slack、Notion、Linear 等常用服务自定义 MCP 集成接入自己的 MCP 服务由 Higress 统一管理认证细粒度权限控制Manager 可按 Worker 授予/撤销 MCP 服务访问权限目标任何支持 MCP 协议的工具都能安全地暴露给 Worker凭证零泄露。四、征集实践教程由于多样化的安装环境和多层次的使用场景带来了大量的咨询。特此征集文字类和视频类的教程。安装和部署环境可任选Mac、Window 或 Linux 环境Docker Desktop、Docker EngineLinux或 Podman Desktop本地 PC 部署、本地盒子部署、云端部署本地访问、公网访问应用场景可任选不限于以下场景项目协作、社交媒体托管、软件开发、内容创作、项目管理、研究和学习、情感陪护等。教程入选后您将获得社区 Contributor 身份和纪念品流量推广包括线上媒体和 HiClaw 线下沙龙的受邀分享嘉宾推荐给 DataWhale 和极客时间等主流 AI 媒体联系方式微信max_0928或钉钉如下