OpenClaw Skills 安装全流程：目录区别、ClawHub 登录、限流、远程服务器回调失败一次讲透

OpenClaw Skills 安装全流程目录区别、ClawHub 登录、限流、远程服务器回调失败一次讲透前言在 OpenClaw 真正开始“装技能”之前很多人都会先踩进几个非常典型的坑先手动创建了~/.openclaw/skills结果用 ClawHub 安装后却发现 skill 跑到了~/.openclaw/workspace/skills以为 PDF、Python、Office 都必须靠 skills结果发现很多能力其实已经是 OpenClaw 的内置工具在云服务器上执行npx clawhub login浏览器跳转后却提示127.0.0.1 refused to connect直接npx clawhub install ...结果报Rate limit exceeded误把openclaw dashboard打印出来的 token 当成 ClawHub 的登录 token安装完 skill 之后WebUI 新会话里却找不到怀疑自己是不是装错目录了。这篇文章就基于一次完整的真实排障过程把OpenClaw 安装和管理 skills 的整套逻辑从头梳理清楚先分清工具、skills、plugins 和 channels 的边界再讲清目录关系、ClawHub 的正确登录方式、远程服务器场景下的认证方法以及安装后的验证和排障步骤。本文的目标不是“堆命令”而是让整个流程一次讲清后续再装 PDF、Office、Python、自动化类 skills 时都不再反复踩坑。一、先说结论很多需求并不一定要先装 skill这是整个流程里最容易忽略的一点。OpenClaw 现在已经提供了一批一等工具first-class tools比如exec、browser、canvas、nodes、pdf、image、cron等。官方文档明确说明这些一等工具已经取代了很多旧式openclaw-*skills模型应优先直接使用这些工具而不是凡事都先找 skill。[1]这意味着PDF 解析很多场景下先看内置pdf工具是否已经够用[1]运行 Python / Shell很多任务直接通过exec就能完成不一定必须安装 Python 类 skill[1]浏览器操作、截图、页面提取优先用内置browser[1]定时任务优先用内置cron[1]所以正确姿势不是“先装一堆 skill 再说”而是先确认 OpenClaw 内置工具能不能解决内置工具不够再去找 skill如果是接飞书、Telegram、Slack、微信这类平台很多情况其实应该找channel / plugin而不是普通 skill。[2]二、先分清四类能力tools、skills、plugins、channels很多安装混乱本质上不是不会敲命令而是没先把概念理清。1. ToolsOpenClaw 内置能力这是 OpenClaw 自带的工具层比如exec、pdf、browser、canvas、nodes。它们通常不需要额外安装。[1]2. Skills任务能力包官方文档给出的定义很直接一个 skill 本质上就是一个包含SKILL.md的目录可以附带脚本、资源文件和元数据。OpenClaw 会在加载时根据环境、配置、二进制依赖等条件决定是否启用。[3]3. Plugins扩展机制插件负责扩展 OpenClaw 的运行时能力比如某些渠道、认证、工具接入、特殊运行时能力等。官方提供了openclaw plugins list和openclaw plugins install这样的命令。[4]4. Channels消息平台接入飞书、Telegram、Slack、WhatsApp、LINE、Matrix 等大多属于渠道层不是普通 skill。[2]三、技能目录为什么会有两个~/.openclaw/skills和~/.openclaw/workspace/skills这是整个 skill 安装过程中最容易让人困惑的问题。OpenClaw 官方文档写得很清楚skills 的加载位置有三层[3]Bundled skills随安装包自带Managed/local skills~/.openclaw/skillsWorkspace skillsworkspace/skills。而且优先级是workspace/skills ~/.openclaw/skills bundled skills也就是说~/.openclaw/skills是共享目录适合多个 agent / 多个 workspace 共用[3]~/.openclaw/workspace/skills是当前工作区专用目录只对当前 workspace 生效[3]如果同名 skill 同时出现在两个位置workspace 版本优先生效。[3]这对实际安装有什么影响如果你手动执行了mkdir-p~/.openclaw/skillschmod-R755~/.openclaw/skills这个目录当然没有问题但它不是 ClawHub 默认优先安装的目标。官方 ClawHub 文档说明ClawHub 默认会把 skills 安装到当前工作目录下的./skills如果检测到 OpenClaw 已配置 workspace就会退回使用该 workspace并把 skill 安装到workspace/skills。[5]所以你看到Installed nano-pdf - /home/openclaw/.openclaw/workspace/skills/nano-pdf这是正常行为不是装错了。怎么选择目录策略我的建议非常简单绝大多数个人使用场景就让 ClawHub 默认装到~/.openclaw/workspace/skills多个 agent 共享一批通用 skill再考虑把稳定通用的 skill 放进~/.openclaw/skills不要为了“目录整齐”而强行改默认安装逻辑。四、正式安装前先做这 3 个检查1. 列出当前 skillsopenclaw skills list2. 看当前 skills 状态openclaw skills check如果你的版本支持可以再试openclaw skills check--json官方 CLI 文档写明skills check用来查看 ready 和 missing requirements 的概况并支持--eligible、--json、-v/--verbose等参数。[6]不过实测某些安装版本可能会出现-v不被识别的情况。如果你碰到error: unknown option -v不要慌这通常是文档版本与本机 CLI 版本存在差异。此时最稳妥的做法是先用openclaw skills check或--json跑openclaw --version确认版本必要时执行openclaw update再重试。[6]3. 看当前插件列表openclaw plugins list如果你后面要装的其实是平台能力、渠道能力这一步很有帮助。[4]五、去哪里找实用 skills首选 ClawHubOpenClaw 官方已经把答案写得很明确ClawHub 是 OpenClaw 的公共技能仓库。它的定位包括[5]公共 skill registry技能版本化存储搜索、标签、安装、更新、发布的统一入口。安装 ClawHub CLInpmi-gclawhub或者不全局安装直接用npx clawhubsubcommand常用搜索方式npx clawhub searchpdfnpx clawhub searchpythonnpx clawhub searchdocxnpx clawhub searchxlsx excel spreadsheetnpx clawhub searchpptx powerpointnpx clawhub searchoffice安装一个 skillnpx clawhubinstallskill-slug官方 quick start 也就是这条路径搜索 → 安装 → 开新会话加载。[5]六、远程服务器上最容易踩的坑npx clawhub login回调到 127.0.0.1 失败如果你是在本地电脑上直接运行 OpenClaw这个问题通常不会出现。但如果你是在腾讯云 / 阿里云 / VPS / 远程 Ubuntu上执行npx clawhub login然后把终端打印出来的授权链接复制到你自己电脑的浏览器里打开就很容易看到127.0.0.1 refused to connect为什么会这样因为浏览器登录流会回调到执行命令那台机器的 127.0.0.1。ClawHub 官方文档明确支持两种登录方式[5]clawhub login浏览器流clawhub login --token tokenAPI token 流如果命令是在云服务器上执行而浏览器却在你自己的电脑上打开那么浏览器跳回的127.0.0.1其实是你本地电脑不是服务器于是自然连接失败。解决方案 A最推荐直接用 token 登录这也是远程服务器场景下最省心的方法。先去 ClawHub 官网登录 GitHub 账号然后在设置页生成ClawHub API token再执行npx clawhub login--token你的ClawHub-API-Token然后检查npx clawhubwhoami如果能正确显示你的账号就说明登录成功。ClawHub 官方命令文档也明确列出了login --token和whoami。[5]解决方案 B继续用浏览器流但做 SSH 端口转发如果你就是想用浏览器登录流也可以。但你必须把服务器上的本地回调端口通过 SSH 隧道转回本机。例如回调端口是32893就在本地电脑执行ssh-N-L32893:127.0.0.1:32893 openclaw你的服务器IP然后再把npx clawhub login打印出来的链接复制到浏览器里打开。不过说实话既然 token 登录已经足够稳定远程服务器场景下真没必要继续折腾回调流。七、为什么openclaw dashboard打印出来的 token 不能拿来给 ClawHub 登录这是另一个非常高频的误区。执行openclaw dashboard终端通常会打印出类似这样的地址http://localhost:18789/#tokenxxxx这个 token 是OpenClaw Gateway / Dashboard 的访问 token用于 WebUI 或 Control UI 连接你的 OpenClaw 网关。官方 Dashboard 文档明确说明如果 UI 提示认证就要填gateway.auth.token。[7]而clawhub login --token token这里要求的是ClawHub 的 API token这是另一个系统、另一类认证。官方 ClawHub 文档里说得也很清楚--token token是粘贴 API token。[5]一句话区分openclaw dashboard打印的 token给 OpenClaw WebUI / Gateway 用[7]clawhub login --token用的 token给 ClawHub CLI 用。[5]这两个 token不能混用。八、为什么未登录时容易遇到Rate limit exceeded在真实安装过程中一个很常见的场景是npx clawhubinstallnano-pdf结果终端报Rate limit exceeded从实践上看这往往出现在未登录 ClawHub的状态下。也就是说匿名访问公共 skill registry 更容易撞到频率限制而切换成带 API token 的登录状态后安装通常就能恢复正常。因此更稳妥的习惯是先登录再search再install装完后用whoami和skills list做确认。完整流程如下npx clawhub login--token你的ClawHub-API-Tokennpx clawhubwhoaminpx clawhub searchpdfnpx clawhubinstallnano-pdf安装成功后的典型输出Installed nano-pdf - /home/openclaw/.openclaw/workspace/skills/nano-pdf这说明 skill 已经被装进当前 workspace并不是出错。[5]九、安装 skill 的标准流程一套能复用的终端操作顺序这一套顺序适合 Ubuntu 云服务器也适合本地 Linux / WSL2。第一步确认 OpenClaw 本身可用openclaw status openclaw gateway status openclaw models status如果 WebUI 经常发消息没回复官方排障建议也是先看status、models status和logs --follow。[8]第二步先确认内置工具能否覆盖需求PDF先看内置pdf[1]执行 Python / 脚本先看内置exec[1]浏览器自动化先看browser[1]第三步搜索 skillnpx clawhub searchpdfnpx clawhub searchpythonnpx clawhub searchoffice第四步登录 ClawHubnpx clawhub login--token你的ClawHub-API-Tokennpx clawhubwhoami第五步安装 skillnpx clawhubinstallnano-pdf第六步验证 skill 是否被 OpenClaw 识别openclaw skills list openclaw skills info nano-pdf openclaw skills check第七步重启或开新会话官方 quick start 里明确提到安装后需要start a new OpenClaw session这样新 skill 才会被拾取。[5]最稳妥的做法是sudosystemctl restart openclaw-gateway.service然后在 WebUI 里新建一个全新会话再测试这个 skill。十、Office、PDF、Python 这几类需求应该怎么选1. PDF优先看内置pdf是否够用。官方工具清单已经明确列出pdf工具。[1]如果你需要更强的本地处理能力比如专门的 PDF 转换、特定格式提取再去 ClawHub 搜pdf相关 skills。2. Python很多人一提到 Python 就本能地去找 skill但 OpenClaw 的exec已经可以直接在 workspace 里运行 shell 命令。[1]如果你的目标只是批量处理文件跑脚本调用 Python 环境做简单数据处理那很多时候根本不需要额外的 Python skill。3. OfficeWord / Excel / PPT这类能力更可能需要特定 skill特定 plugin或依赖宿主机本身安装的 CLI / Python 库。因此 Office 类需求最稳妥的方式是在 ClawHub 里搜docx / xlsx / pptx / office安装后跑openclaw skills check看 skill 是否还缺系统依赖。十一、安装完为什么 WebUI 里还是看不到 skill这是另一个非常高频的问题。常见原因 1没开新会话ClawHub 官方 quick start 已经明确提到安装 skill 后要start a new OpenClaw session。[5]常见原因 2skill 已安装但环境不满足OpenClaw 官方 skills 文档写得很清楚skills 在加载时会根据环境、配置和二进制存在与否做过滤。[3]所以“文件夹已经在那儿”并不等于“skill 一定 ready”。常见原因 3你测试的是旧会话尤其是在 WebUI 中旧会话可能延续旧上下文。最简单的排除办法就是新建会话重新发一个明确要求使用 skill 的指令同时在服务器上观察日志openclaw logs--follow官方排障文档也建议当 Gateway 正常但回复没到时重点看openclaw logs --follow。[8]十二、给个人用户的最优实践我建议这样管理 skills如果你现在只有一台服务器、一个主 agent那么最省事的管理策略是推荐方案ClawHub 安装的 skill继续走默认目录~/.openclaw/workspace/skills长期复用、自己维护的通用 skill再考虑放进~/.openclaw/skills不要把所有 skill 都手动拷来拷去优先先用内置 tools再补外部 skills。为什么这样最稳因为这与官方的目录优先级、workspace 加载逻辑以及 ClawHub 的默认行为是一致的。[3][5]十三、建议直接收藏的一组命令1. 基础检查openclaw status openclaw gateway status openclaw models status openclaw logs--follow2. skills / plugins 检查openclaw skills list openclaw skills check openclaw plugins list3. 搜索与安装npx clawhubwhoaminpx clawhub searchpdfnpx clawhub searchofficenpx clawhub searchpythonnpx clawhubinstallskill-slug4. 安装后刷新sudosystemctl restart openclaw-gateway.service十四、最后总结OpenClaw 的 skills 系统并不复杂真正让人觉得复杂的往往是以下几件事叠在一起没先区分内置 tools 和外部 skills没搞清~/.openclaw/skills与~/.openclaw/workspace/skills的层级关系在远程服务器上误用了浏览器回调登录把 Dashboard token 和 ClawHub token 混为一谈还没登录 ClawHub 就直接 install结果碰到 rate limit安装之后没开新会话、没重启服务、没检查依赖误以为 skill 没装成功。真正顺手的操作路径其实很简单先看内置工具 → 再去 ClawHub 搜索 → 用 API token 登录 → 安装到 workspace/skills → 新开会话或重启服务 → 用skills list / skills check验证。只要把这条链路走顺后面再扩展 PDF、Office、Python、自动化类 skills效率会高很多也不会再反复掉进相同的坑里。参考资料OpenClaw 官方 Tools 文档exec、pdf、browser、cron等一等工具清单与说明https://docs.openclaw.ai/toolsOpenClaw 官方 Channels 文档平台接入属于 channels / plugins 的范围https://docs.openclaw.ai/channelsOpenClaw 官方 Skills 文档skills 加载位置、优先级、shared 与 workspace 的区别https://docs.openclaw.ai/tools/skillsOpenClaw 官方 Plugin 文档插件列表、安装与运行方式https://docs.openclaw.ai/tools/pluginOpenClaw 官方 ClawHub 文档搜索、安装、login --token、whoami、workspace 安装策略https://docs.openclaw.ai/tools/clawhubOpenClaw 官方 CLI 文档skills check、skills list、skills info命令说明https://docs.openclaw.ai/cliOpenClaw 官方 Dashboard 文档WebUI / Gateway token 的使用方式https://docs.openclaw.ai/web/dashboardOpenClaw 官方 FAQ / Troubleshootingstatus、models status、logs --follow的排障路径https://docs.openclaw.ai/help/faq