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 再说”，而是：

  1. 先确认 OpenClaw 内置工具能不能解决；
  2. 内置工具不够，再去找 skill；
  3. 如果是接飞书、Telegram、Slack、微信这类平台，很多情况其实应该找 channel / plugin，而不是普通 skill。[2]

二、先分清四类能力：tools、skills、plugins、channels

很多安装混乱，本质上不是不会敲命令，而是没先把概念理清。

1. Tools：OpenClaw 内置能力

这是 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]

  1. Bundled skills：随安装包自带；
  2. Managed/local skills：~/.openclaw/skills；
  3. Workspace skills：<workspace>/skills。

而且优先级是：

<workspace>/skills  >  ~/.openclaw/skills  >  bundled skills

也就是说：

  • ~/.openclaw/skills 是 共享目录，适合多个 agent / 多个 workspace 共用；[3]
  • ~/.openclaw/workspace/skills 是 当前工作区专用目录，只对当前 workspace 生效；[3]
  • 如果同名 skill 同时出现在两个位置，workspace 版本优先生效。[3]

这对实际安装有什么影响？

如果你手动执行了：

mkdir -p ~/.openclaw/skills
chmod -R 755 ~/.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. 列出当前 skills

openclaw skills list

2. 看当前 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：首选 ClawHub

OpenClaw 官方已经把答案写得很明确：ClawHub 是 OpenClaw 的公共技能仓库。它的定位包括：[5]

  • 公共 skill registry；
  • 技能版本化存储；
  • 搜索、标签、安装、更新、发布的统一入口。

安装 ClawHub CLI

npm i -g clawhub

或者不全局安装，直接用：

npx clawhub <subcommand>

常用搜索方式

npx clawhub search "pdf"
npx clawhub search "python"
npx clawhub search "docx"
npx clawhub search "xlsx excel spreadsheet"
npx clawhub search "pptx powerpoint"
npx clawhub search "office"

安装一个 skill

npx clawhub install <skill-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 <token>（API token 流）

如果命令是在云服务器上执行，而浏览器却在你自己的电脑上打开，那么浏览器跳回的 127.0.0.1 其实是你本地电脑，不是服务器，于是自然连接失败。

解决方案 A：最推荐，直接用 token 登录

这也是远程服务器场景下最省心的方法。

先去 ClawHub 官网登录 GitHub 账号，然后在设置页生成 ClawHub API token，再执行：

npx clawhub login --token <你的ClawHub-API-Token>

然后检查：

npx clawhub whoami

如果能正确显示你的账号，就说明登录成功。ClawHub 官方命令文档也明确列出了 login --token 和 whoami。[5]

解决方案 B：继续用浏览器流，但做 SSH 端口转发

如果你就是想用浏览器登录流，也可以。但你必须把服务器上的本地回调端口通过 SSH 隧道转回本机。

例如回调端口是 32893，就在本地电脑执行：

ssh -N -L 32893:127.0.0.1:32893 openclaw@你的服务器IP

然后再把 npx clawhub login 打印出来的链接复制到浏览器里打开。

不过说实话，既然 token 登录已经足够稳定，远程服务器场景下真没必要继续折腾回调流。

七、为什么 openclaw dashboard 打印出来的 token 不能拿来给 ClawHub 登录

这是另一个非常高频的误区。

执行：

openclaw dashboard

终端通常会打印出类似这样的地址：

http://localhost:18789/#token=xxxx

这个 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 clawhub install nano-pdf

结果终端报：

Rate limit exceeded

从实践上看，这往往出现在 未登录 ClawHub 的状态下。也就是说，匿名访问公共 skill registry 更容易撞到频率限制；而切换成带 API token 的登录状态后，安装通常就能恢复正常。

因此更稳妥的习惯是：

  1. 先登录；
  2. 再 search；
  3. 再 install；
  4. 装完后用 whoami 和 skills list 做确认。

完整流程如下：

npx clawhub login --token <你的ClawHub-API-Token>
npx clawhub whoami
npx clawhub search "pdf"
npx clawhub install nano-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]

第三步：搜索 skill

npx clawhub search "pdf"
npx clawhub search "python"
npx clawhub search "office"

第四步：登录 ClawHub

npx clawhub login --token <你的ClawHub-API-Token>
npx clawhub whoami

第五步：安装 skill

npx clawhub install nano-pdf

第六步：验证 skill 是否被 OpenClaw 识别

openclaw skills list
openclaw skills info nano-pdf
openclaw skills check

第七步：重启或开新会话

官方 quick start 里明确提到，安装后需要 start a new OpenClaw session，这样新 skill 才会被拾取。[5]

最稳妥的做法是：

sudo systemctl 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. Office（Word / Excel / PPT）

这类能力更可能需要：

  • 特定 skill；
  • 特定 plugin；
  • 或依赖宿主机本身安装的 CLI / Python 库。

因此 Office 类需求最稳妥的方式是：

  1. 在 ClawHub 里搜 docx / xlsx / pptx / office；
  2. 安装后跑 openclaw skills check；
  3. 看 skill 是否还缺系统依赖。

十一、安装完为什么 WebUI 里还是看不到 skill

这是另一个非常高频的问题。

常见原因 1：没开新会话

ClawHub 官方 quick start 已经明确提到：安装 skill 后，要 start a new OpenClaw session。[5]

常见原因 2：skill 已安装，但环境不满足

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 --follow

2. skills / plugins 检查

openclaw skills list
openclaw skills check
openclaw plugins list

3. 搜索与安装

npx clawhub whoami
npx clawhub search "pdf"
npx clawhub search "office"
npx clawhub search "python"
npx clawhub install <skill-slug>

4. 安装后刷新

sudo systemctl 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，效率会高很多，也不会再反复掉进相同的坑里。

参考资料

  1. OpenClaw 官方 Tools 文档：exec、pdf、browser、cron 等一等工具清单与说明
    https://docs.openclaw.ai/tools
  2. OpenClaw 官方 Channels 文档：平台接入属于 channels / plugins 的范围
    https://docs.openclaw.ai/channels
  3. OpenClaw 官方 Skills 文档：skills 加载位置、优先级、shared 与 workspace 的区别
    https://docs.openclaw.ai/tools/skills
  4. OpenClaw 官方 Plugin 文档：插件列表、安装与运行方式
    https://docs.openclaw.ai/tools/plugin
  5. OpenClaw 官方 ClawHub 文档：搜索、安装、login --token、whoami、workspace 安装策略
    https://docs.openclaw.ai/tools/clawhub
  6. OpenClaw 官方 CLI 文档：skills check、skills list、skills info 命令说明
    https://docs.openclaw.ai/cli
  7. OpenClaw 官方 Dashboard 文档：WebUI / Gateway token 的使用方式
    https://docs.openclaw.ai/web/dashboard
  8. OpenClaw 官方 FAQ / Troubleshooting：status、models status、logs --follow 的排障路径
    https://docs.openclaw.ai/help/faq
# linux
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

OpenClaw+GLM-4.7-Flash语音交互：对接Whisper实现语音控制

本文介绍了如何在星图GPU平台上自动化部署【ollama】GLM-4.7-Flash镜像，构建语音交互系统。该系统结合Whisper语音识别与GLM-4.7-Flash的指令理解能力，实现智能家居控制等场景的语音操作，提升日常任务执行效率。

avatar 龙虾开发者社区

学生党福音：OpenClaw+nanobot搭建学习监督助手

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，构建智能学习监督助手。该方案利用轻量级模型实现网课进度跟踪、自动生成练习题和错题整理功能，特别适合学生群体通过QQ机器人实现移动端学习管理，显著提升学习效率。

avatar 龙虾开发者社区

OpenClaw创意工坊：用nanobot镜像生成技术海报文案

本文介绍了如何在星图GPU平台上自动化部署🐈 nanobot：超轻量级OpenClaw镜像，快速生成技术海报文案。该镜像基于Qwen3-4B模型，能将复杂技术术语转化为通俗表达，适用于技术活动宣传、社交媒体推广等场景，显著提升内容创作效率。

avatar 龙虾开发者社区