OpenClaw 安装 skills 报 command not found:从 PATH 到 clawhub 的排查与修复 1. 先别急着重装OpenClaw 安装 skills 报 command not found 的真实场景你敲下clawhub install github终端回你一句zsh: command not found: clawhub或者 Windows PowerShell 里蹦出「clawhub 不是内部或外部命令」。这时候很多人第一反应是「是不是没装成功」于是npm install -g clawhub又跑一遍结果还是同样的报错。问题往往不在安装本身而在系统根本找不到这个可执行文件。OpenClaw 是一套面向智能体Agent的本地运行框架它通过 skills 机制把外部能力挂载进来而 clawhub 就是管理这些 skills 的命令行工具。你可以把 OpenClaw 理解成一台主机clawhub 是往主机上插拔扩展卡的工具skills 就是那些扩展卡。command not found意味着系统在 PATH 环境变量列出的目录里翻遍了也没找到 clawhub 这个程序。这个报错的影响范围比想象中大你没法用 CLI 安装或卸载技能没法访问 ClawHub 技能市场里的技能包手动拷贝进去的技能也可能因为 Gateway 没重新加载而不生效。适合阅读本文的人包括刚在 macOS 或 Windows 上装完 OpenClaw 的新手、用 nvm 管理 Node 版本导致路径漂移的开发者、以及在 Docker 或云服务器上部署 OpenClaw 的运维同学。我试过在一台 M 系列 Mac 上排查这个问题最后发现是 Homebrew 装的 Node 和 nvm 装的 Node 打架npm 全局 bin 目录压根没进 PATH。下面按「先定位、再修复、后验证」的顺序把 PATH、clawhub 可执行文件位置、安装目录权限这三条线一次讲清楚。2. 定位根因PATH、clawhub 路径与权限三件套2.1 用四条诊断命令锁定问题层级动手改配置之前先跑几条命令把问题范围缩小。这比盲目重装高效得多。# 诊断 1npm 全局安装前缀在哪 npm config get prefix # 诊断 2clawhub 到底装没装 npm list -g clawhub # 诊断 3当前 PATH 里有哪些目录 echo $PATH # macOS / Linux $env:PATH # Windows PowerShell # 诊断 4OpenClaw 主程序是否正常 openclaw --version这四条命令的输出组合起来基本能判断你属于哪一类故障。如果npm list -g clawhub返回 empty说明根本没装上如果它显示了版本号但which clawhub找不到那就是 PATH 的问题如果npm config get prefix指向一个你没权限写入的目录那就是权限问题。2.2 三类根因的典型症状对照错误类型占比典型症状未安装 clawhub35%npm list -g clawhub返回 emptyPATH 环境变量缺失40%安装成功但命令找不到npm 全局路径异常15%自定义过 npm prefix 路径终端会话未刷新5%安装后未重启终端权限不足3%EACCES 权限错误Node.js 版本不兼容2%Node 18 或 22PATH 缺失占了大头这跟 Node 版本管理器nvm、fnm、volta的普及直接相关。这些工具会把 npm 全局目录放在用户目录下而不是系统默认的/usr/local一旦 shell 配置没同步命令就「消失」了。2.3 为什么 clawhub 和 openclaw skills 是两套入口这里有个容易混淆的点clawhub 是独立的 CLI 工具而openclaw skills是主程序内置的命令集。两者最终都操作~/.openclaw/workspace/skills/这个目录但入口不同。理解这一点很关键因为当 clawhub 暂时修不好时你可以用内置命令先顶上不至于卡死。# 内置命令替代方案 openclaw skills list # 替代 clawhub list openclaw skills install github # 替代 clawhub install github openclaw skills uninstall github openclaw skills reload # 无需重启 Gateway3. 可复制配置修复 PATH 与 clawhub 路径3.1 macOS / Linux 下的 PATH 修复先拿到 npm 全局 bin 路径再写进 shell 配置文件。注意 macOS 默认是 zshLinux 常见 bash。# 步骤 1获取 npm 全局 bin 路径 npm config get prefix # 输出示例/usr/local 或 /Users/yourname/.nvm/versions/node/v20.11.0 # 步骤 2追加到 shell 配置zsh 用户 echo export PATH$(npm config get prefix)/bin:$PATH ~/.zshrc # bash 用户 echo export PATH$(npm config get prefix)/bin:$PATH ~/.bashrc # 步骤 3立即生效 source ~/.zshrc # 或 source ~/.bashrc # 步骤 4验证 which clawhub # 期望输出/usr/local/bin/clawhub 或类似路径如果你用 nvm 管理 Node还要确保 nvm 的加载脚本在 PATH 之前执行否则每次开新终端都会丢路径。# nvm 用户补充配置 echo export NVM_DIR$HOME/.nvm ~/.zshrc echo [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh ~/.zshrc source ~/.zshrc3.2 Windows 下的 PATH 修复Windows 分命令行和图形界面两种改法。命令行方式需要管理员权限的 PowerShell。# 步骤 1获取 npm 全局路径 npm config get prefix # 输出示例C:\Users\YourName\AppData\Roaming\npm # 步骤 2写入用户级 PATH [Environment]::SetEnvironmentVariable( Path, [Environment]::GetEnvironmentVariable(Path, User) ;C:\Users\YourName\AppData\Roaming\npm, User ) # 步骤 3关闭所有终端窗口后重新打开必须 # 步骤 4验证 Get-Command clawhub图形界面路径Win S 搜索「环境变量」→ 编辑系统环境变量 → 环境变量 → 在「用户变量」里找到 Path → 编辑 → 新建 → 粘贴npm config get prefix的输出 → 确定保存 → 重启所有终端。3.3 用 JSON 配置固化 OpenClaw 的模型接入skills 装好之后OpenClaw 要调用模型才能真正跑起来。这里给一份可复制的配置片段把 Base URL、API Key、Model ID 三件套写清楚。配置文件通常放在~/.openclaw/config.json。{ provider: { baseUrl: https://taotoken.net/api, apiKey: sk-你的密钥, modelId: claude-sonnet-4-20250514 }, skills: { workspace: ~/.openclaw/workspace/skills, autoReload: true } }如果你更习惯 TOML 风格等价写法如下[provider] baseUrl https://taotoken.net/api apiKey sk-你的密钥 modelId claude-sonnet-4-20250514 [skills] workspace ~/.openclaw/workspace/skills autoReload trueAPI Key 在控制台创建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclawhub_path_fix 。拿到 Key 后填进上面的apiKey字段即可。Model ID 要跟你实际开通的模型对齐别照抄示例。3.4 权限修复与软链接兜底当 npm 全局目录属于 root 而你在普通用户下操作时会出现 EACCES。修复方式是把目录所有权改回当前用户。# 修复 npm 全局目录权限macOS / Linux sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share} # 或者用 npm 官方修复参数 sudo npm install -g clawhub --unsafe-permtrue --allow-root如果 PATH 已经配好但系统仍找不到可以手动建软链接兜底# macOS / Linux 软链接 sudo ln -s $(npm config get prefix)/bin/clawhub /usr/local/bin/clawhub ls -la /usr/local/bin/clawhub clawhub --version4. 验证请求从 clawhub 到 skills 加载的完整链路4.1 命令识别与版本检查修完 PATH 后先确认命令能被识别再看版本。# 1. 命令识别 which clawhub # macOS / Linux where.exe clawhub # Windows # 2. 版本检查 clawhub --version # 期望输出类似clawhub/2.1.0 darwin-arm64 node-v20.11.0版本号里带平台和 Node 版本信息如果平台显示darwin-arm64而你是 Intel Mac说明装错了架构需要重装。4.2 搜索与安装 skills# 3. 搜索技能 clawhub search github # 4. 安装官方 github skill clawhub install github # 5. 验证安装结果 clawhub list | grep github ls ~/.openclaw/workspace/skills/github/clawhub list能列出已安装技能ls能确认文件真的落盘了。两个都对上说明安装环节没问题。4.3 重启 Gateway 并确认加载skills 装完不会自动生效需要让 Gateway 重新加载。# 6. 重启 Gateway openclaw gateway restart # 7. 查看日志确认加载 openclaw gateway logs | grep -i skill.*loaded日志里出现skill loaded字样才算真正跑通。如果日志里报模型调用失败回到 3.3 节检查 Base URL 和 API Key 是否填对。想先验证模型通道是否通畅可以直接用模型对话页面发一条测试消息https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclawhub_path_fix 。4.4 一次完整的成功输出长什么样把上面的步骤串起来一次成功的安装流程输出大致是这样$ clawhub --version clawhub/2.1.0 linux-x64 node-v20.11.0 $ clawhub install github ✔ Resolving skill github ✔ Downloading skill package ✔ Installing to ~/.openclaw/workspace/skills/github ✔ Skill github installed successfully $ openclaw gateway restart Gateway restarted, loading 3 skills... skill github loaded看到skill github loaded这条链路就通了。5. 本篇常见错排查401、local proxy failed 与 OAuth 报错5.1 401 UnauthorizedKey 没填对或没生效这是接入模型时最常见的报错。终端或日志里出现401 Unauthorized说明请求发出去了但鉴权没过。// 检查 config.json 里的 apiKey 字段 { provider: { baseUrl: https://taotoken.net/api, apiKey: sk-这里必须是完整密钥不能有空格或换行, modelId: claude-sonnet-4-20250514 } }排查顺序确认 Key 是从控制台复制完整、没有多余空格确认baseUrl结尾没有多加斜杠确认 Model ID 跟 Key 所属的模型一致。改完配置后重启 Gateway 再试。5.2 local proxy failed本地代理配置冲突日志里出现local proxy failed或连接被拒绝通常是本地网络配置或端口占用导致。检查是否有其他程序占用了 OpenClaw 需要的端口确认baseUrl指向的地址在当前网络下可达。如果你在容器里跑注意容器内的网络跟宿主机不同localhost在容器里指向容器自己。5.3 reading choices 报错响应结构不匹配reading choices类报错一般出现在模型返回格式跟客户端预期不一致时。常见原因是 Model ID 填成了不兼容的模型或者 baseUrl 指向了错误的端点。把 Model ID 换成你确认可用的模型重新发一次请求。5.4 OAuth 相关报错认证流程未完成如果日志里出现 OAuth 字样说明当前走的是 OAuth 认证路径但授权没走完。检查你的配置是否混用了 API Key 和 OAuth 两种方式。用 API Key 接入时配置里不应该再出现 OAuth 相关字段。5.5 报错速查表错误提示快速解决方案command not found: clawhubnpm install -g clawhub 重启终端EACCES: permission deniedsudo chown -R $(whoami) ~/.npmclawhub install 超时配置镜像源后重试安装成功但 clawhub list 为空检查~/.openclaw/workspace/skills/权限Skill 安装后 Gateway 不加载openclaw skills reload或重启 Gateway401 Unauthorized检查 apiKey 与 baseUrl 配置local proxy failed检查端口占用与网络可达性reading choices核对 Model ID 与端点npm ERR! code ENOENT重装 Node.js确保版本 18-225.6 终极重置方案如果以上都试过还是不行执行一次干净的重装npm uninstall -g clawhub openclaw npm cache clean --force npm install -g openclaw clawhub # 重新配置 PATH 并重启终端6. 长期跑 Agent 的接入建议与 CTAskills 装好只是第一步真正让 OpenClaw 稳定干活靠的是模型通道稳定。如果你打算长期跑编码类或 Agent 类任务建议用 Coding Plan 把额度固定下来避免按次调用时断时续https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclawhub_path_fix 。接入文档里有各语言 SDK 的完整示例遇到配置字段不确定时直接对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclawhub_path_fix 。控制台可以管理多个 Key方便给不同项目分配独立凭证https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclawhub_path_fix 。最后分享一个实用习惯每次改完 PATH 或 config.json先跑clawhub --version和openclaw gateway logs | grep -i loaded两条命令确认状态再开始正式任务。这两条命令花不了十秒能省掉后面半小时的排查。