1. HiClaw 本地安装前，先搞清楚它到底解决什么问题
如果你最近在折腾 OpenClaw，大概率遇到过这几个场景：每个 Agent 都要单独配一份 API Key，GitHub PAT 和 LLM Key 散落在不同目录里；一个 Agent 又写前端又写后端还兼文档，skills/目录越堆越乱，MEMORY.md里各种记忆混在一起，每次加载都塞进一堆无关上下文；想给 SubAgent 手动分配任务、手动同步进度，结果自己成了 Agents 的“保姆”。HiClaw 就是冲着这些痛点来的。
HiClaw 可以理解为 Team 版的 OpenClaw，核心是在 OpenClaw 基础上引入了一个 Manager Agent 角色。它不直接干活，而是帮你管理 Worker Agent 团队。你可以只用 Manager 处理简单问答，也可以让 Manager 把复杂任务拆解后分派给专业 Worker，每个 Worker 有独立的 Skills 和 Memory，技能和记忆完全隔离，不会互相污染。
对想快速体验 OpenClaw 团队协作能力的开发者来说，HiClaw 的价值在于：它把 LLM 接入、消息服务器、共享文件系统这些原本需要自己拼装的组件做成了 All-in-One 打包。原生 OpenClaw 像一台组装电脑，你得自己买显卡、显示器再装驱动；HiClaw 更像一台开箱即用的笔记本，开机就能干活。这篇就聚焦本地安装，给出可复制的命令、依赖清单和启动验证步骤，并说明怎么通过 TaoToken 统一 Key/API 通道完成模型接入，最后用一次团队任务协作演示验证安装成功。
安装前你需要准备的东西不多：一台能跑 Docker 的机器（macOS、Linux、Windows 都行），Docker 版本建议 20.10 以上，至少 4GB 可用内存，以及一个可用的 LLM API Key。HiClaw 的安装脚本会把 Higress AI Gateway、Tuwunel Matrix Server、Element Web、MinIO 这些组件都封装进容器，屏蔽操作系统差异，所以真正需要你手动填的配置很少。下面按步骤来。
2. TaoToken 前置准备：统一 Key 与 API 通道
在跑安装脚本之前，先把模型接入这条链路理清楚。HiClaw 的 LLM 接入走的是 Higress AI Gateway，一个入口可以切换不同模型供应商，凭证集中管理，API Key 只需要配置一次，所有 Agent 共享。Worker 只拿到调用权限，永远接触不到真实的 API Key。这个设计对本地安装很友好，因为你不用在每个 Worker 里重复填 Key。
我这边习惯用 TaoToken 作为统一的模型通道，原因是它把 Key 管理和 API 入口收敛到一处，配合 HiClaw 的 Gateway 用起来比较顺。你需要先拿到一个可用的 API Key，然后确认 Base URL 指向https://taotoken.net/api。注意这个地址不带任何查询参数，配置时直接填这个就行。
具体操作上，先到 TaoToken 控制台创建一个 API Key。打开 API Keys 页面（https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite），登录后点创建，把生成的 Key 复制下来，后面安装脚本会用到。如果你还没决定用哪个模型，可以先到模型对话页面（https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite）试一下不同模型的响应风格，再决定 Manager 和 Worker 分别用哪个。
这里有个关键点：HiClaw 的 Manager 和 Worker 可以按任务分配不同模型。比如代码开发任务用能力强的模型，信息收集任务用轻量模型，成本能差出好几倍。TaoToken 的好处是同一个 Key 可以调用多个模型，你在 Higress Console 里切换模型供应商时不用换 Key，只改 Model ID 就行。所以前置准备其实就三件事：拿到 Key、确认 Base URL、想好 Manager 和 Worker 的模型分配策略。
如果你打算长期跑编码类或 Agent 类任务，可以顺手看一下 Coding Plan（https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite），它针对长时间编码场景做了额度优化，比按量计费更适合持续跑 Worker 的情况。接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite，里面有 Base URL、Key、Model ID 三件套的完整说明，配置前扫一眼能少踩坑。
3. 可复制配置：安装命令与 Gateway 接入片段
先把安装命令跑起来。macOS / Linux 用这条：
bash <(curl -sSL https://higress.ai/hiclaw/install.sh)Windows 用 PowerShell 7+：
Set-ExecutionPolicy Bypass -Scope Process -Force; Invoke-Expression ((New-Object System.Net.WebClient).DownloadString('https://higress.ai/hiclaw/install.ps1'))这个脚本会做几件事：检测你的时区自动选择最近的镜像仓库，用 Docker 拉起所有组件，然后提示你输入 LLM API Key。安装完成后你会看到几个关键端口：Higress Gateway 在 18080，Higress Console 在 18001，Element Web 也在 18080，MinIO 在 9000 和 9001。浏览器访问http://127.0.0.1:18080就能打开 Element Web 登录对话。
接下来是重点：把 TaoToken 的模型通道接进 Higress AI Gateway。安装脚本跑完后，打开 Higress Console（http://127.0.0.1:18001），找到 AI Gateway 的模型供应商配置。如果你更习惯直接改配置文件，HiClaw 的 Gateway 配置走的是 Higress 的标准格式，可以在容器挂载的配置目录里找到对应的 YAML。下面给一个可复制的配置片段，把 TaoToken 作为 OpenAI 兼容供应商接进去：
providers: - name: taotoken type: openai baseUrl: https://taotoken.net/api apiKey: ${TAOTOKEN_API_KEY} models: - id: claude-sonnet-4-20250514 name: Claude Sonnet - id: gpt-4o-mini name: GPT-4o mini如果你用的是 JSON 格式的配置（部分版本走 settings 风格），对应片段是这样：
{ "provider": "taotoken", "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的Key", "modelId": "claude-sonnet-4-20250514", "fallbackModelId": "gpt-4o-mini" }这里的三件套要记牢：Base URL 填https://taotoken.net/api，Key 填你在控制台创建的那串，Model ID 填具体模型标识。Manager 建议用能力强的模型，Worker 可以按任务类型分配，比如信息收集类 Worker 用轻量模型。配置保存后，Higress Gateway 会热加载，不需要重启整个 HiClaw。
如果你在配置里用了环境变量${TAOTOKEN_API_KEY}，记得在启动容器时通过-e传入，或者在.env文件里定义。HiClaw 的安装脚本默认会把配置写到用户目录下的隐藏文件夹，你可以用docker inspect找到实际挂载路径。改完配置后，在 Console 里点一下测试连接，确认 Gateway 能正常拉到模型列表，再进行下一步。
4. 验证请求：从启动到团队任务协作演示
配置接好后，先做一次最小验证。打开浏览器访问http://127.0.0.1:18080，用安装时显示的用户名和密码登录 Element Web。你会看到一个名为 Manager 的对话。先发一条简单消息测试模型通道是否通：
你好，帮我确认一下当前使用的模型和可用工具如果 Manager 正常回复，说明 TaoToken 的 Key、Base URL、Model ID 三件套都生效了。如果没回复，先看 Higress Console 的日志，大概率是 Key 或 Base URL 填错，排查方法放在下一节。
接下来创建第一个 Worker。在 Manager 对话里输入：
帮我创建一个前端 Worker，名字叫 aliceManager 会自动完成配置、技能分配，并在 Matrix 里拉起一个项目群。然后给一个真实任务：
启动项目：一个简单的待办事项 Web 应用，alice 负责前端，你负责协调Manager 会拆解任务、分配给 alice，并在群里同步进度。你可以在 Element Web 里看到 Manager 和 alice 的完整协作过程，所有消息都在同一个 Room 里，全程透明。如果发现问题，直接 @alice 就能介入修正。
想验证移动端，下载 FluffyChat（iOS、Android、全平台都有），登录时选“其他服务器”，填入你的 Matrix 服务器地址（安装时显示的地址，通常是http://你的IP:18080），用同样的账号登录，就能在手机上查看 Worker 进度。这一步能验证 HiClaw 内置的 Tuwunel Matrix Server 是否正常工作。
最后做一次完整验证：让 Manager 创建一个后端 Worker，分配一个依赖前端的任务，观察两个 Worker 是否通过 MinIO 共享文件系统交换中间产物，而群聊里只保留有意义的沟通和决策记录。如果群聊上下文没有因为文件交换而膨胀，说明 MinIO 共享文件系统接好了。到这里，本地安装和模型接入就算跑通了。
5. 本篇常见错排查：401、local proxy failed 与 reading choices
安装和接入过程中最容易卡在几个报错上，逐个说。
401 Unauthorized：这个最常见，基本是 Key 或 Base URL 的问题。先确认你在 Higress Console 里填的 Base URL 是https://taotoken.net/api，注意结尾没有多余的斜杠，也没有带任何查询参数。然后确认 Key 没有多余空格，复制时别把换行带进去。如果用的是环境变量，用docker exec进容器echo $TAOTOKEN_API_KEY看一下实际值。还有一种情况是 Key 权限不对，到 TaoToken 控制台确认这个 Key 有对应模型的调用权限。
local proxy failed：这个报错通常出现在 Gateway 转发阶段，说明 Higress 到上游的连接没建立起来。先检查容器网络，docker ps看 Higress Gateway 容器是否正常运行。然后确认你的机器能访问https://taotoken.net/api，可以用curl -I https://taotoken.net/api测一下连通性。如果容器里访问不了但宿主机能访问，多半是 Docker 网络配置问题，检查一下容器的 DNS 设置。另外确认没有其他进程占用 18080 或 18001 端口。
reading choices 相关报错：这个一般出现在模型返回格式解析阶段，说明请求发出去了但响应结构不符合预期。先确认 Model ID 填对了，不同模型的响应字段名可能不一样。如果你在配置里同时写了modelId和fallbackModelId，确认两个都是有效模型。还有一种情况是请求超时导致响应被截断，可以在 Gateway 配置里把超时时间调大，比如从默认的 30 秒调到 120 秒。
OAuth 相关报错：如果你在 Element Web 登录时遇到 OAuth 问题，先确认用的是安装时显示的用户名和密码，而不是自己注册的账号。HiClaw 的 Tuwunel Matrix Server 在安装时会自动创建管理员账号，密码在安装输出里。如果密码丢了，可以重新跑一次安装脚本，或者进容器重置。移动端 FluffyChat 登录时选“其他服务器”，填的地址要和 Element Web 一致，协议头别漏。
Worker 不响应：如果 Manager 正常但 Worker 没反应，先看 Worker 容器是否启动。docker ps里应该能看到对应的 Worker 容器。然后检查 Worker 的 Consumer Token 是否有效，这个 Token 是 Manager 自动分配的，一般不用手动改。如果 Worker 一直卡住，在群里 @Manager 让它检查 Worker 状态，Manager 有 Heartbeat 自动监工机制，能发现卡住的 Worker 并提醒你。
6. 接入完成后，怎么把 HiClaw 用顺
安装跑通只是第一步，真正用起来还有几个习惯值得养成。第一，Manager 和 Worker 的模型分配别一刀切。代码开发类任务用能力强的模型，信息收集、格式整理类任务用轻量模型，成本能差出好几倍。TaoToken 同一个 Key 可以调多个模型，你在 Higress Console 里按 Worker 角色配不同 Model ID 就行。
第二，善用 MinIO 共享文件系统。Agent 之间的大量协作，比如文件交换、代码片段、临时数据，都走 MinIO，不要往群聊里发。这样群聊上下文始终保持在合理规模，不会因为文件交换迅速膨胀。你可以在 Manager 对话里明确要求“中间产物走共享文件系统，群聊只发决策和结果”。
第三，移动端接入用 FluffyChat 或 Element Mobile，登录时选“其他服务器”填 Matrix 地址。这样你不在电脑前也能随时查看进度、随时干预。HiClaw 内置的 Matrix Server 不需要申请飞书或钉钉机器人，省掉了审批流程。
如果你打算长期跑团队协作任务，可以到 Coding Plan 页面（https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite）看一下额度方案，比按量计费更适合持续跑 Worker 的场景。接入过程中遇到配置问题，先翻接入文档（https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite），Base URL、Key、Model ID 三件套的说明都在里面。需要新建或管理 Key 就去 API Keys 页面（https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite）。想先试试不同模型的手感，模型对话页面（https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite）可以直接开聊。
最后提醒一句：HiClaw 的 Worker 运行在完全隔离的容器里，不持有任何真实凭证，这是它相对原生 OpenClaw 最大的安全改进。所以配置时别图省事把真实 Key 直接塞进 Worker 的环境变量，走 Gateway 代理才是正确姿势。安装脚本默认就是这么设计的，你只要把 TaoToken 的 Key 配在 Gateway 层，Worker 那边什么都不用改。
