OpenClaw 如何使用 Skills

一、为什么说“不装 Skills 等于白部署”？

这个说法绝不是危言耸听。你可以试着去理解它的逻辑：OpenClaw 本体只是一个聪明的大脑，它定义了思考和理解的能力。但想让这个大脑真正“做事”——无论是处理文件，还是发送邮件——它就必须要借助手脚和工具。没错，Skills 扮演的正是这个角色，它们是OpenClaw的四肢和工具箱。光有个聪明的大脑，没有执行能力，一切不过是纸上谈兵罢了。

二、Skills 管理：先掌握这几条核心命令

工欲善其事，必先利其器。在动手安装任何 Skills 之前，花两分钟记下这几条通用命令，后续几乎所有操作都绕不开它们，熟练使用能帮你节省大量时间：

# 查看所有已安装的 Skills 状态（确认正常启用）
openclaw skills list --eligible

# 安装 Skills（推荐使用 ClawHub CLI，更稳定）
npx clawhub@latest install # 官方推荐，适配 2026 版
openclaw skills install # 备用方式，兼容旧版

# 卸载不需要的 Skills
openclaw skills uninstall

# 启用 / 禁用 Skills（不用卸载，随时开关）
openclaw skills enable
openclaw skills disable

# 检查并更新所有已安装 Skills
npx skills check
npx skills update all

# 查看某个 Skills 的详细信息
openclaw skills info

三、7 大高频报错避坑指南（新手必看）

新手入门，难免会遇到各种报错。不必慌张，根据社区反馈和一线经验，下面总结的这7类问题是2026年最常见的“拦路虎”。每个问题都附上了根本原因和直截了当的解决方法，遇到问题时直接对号入座，基本都能解决。

❌ 问题 1：初始化提示 “API-Key invalid”（模型授权失败）

现象：系统初始化时，输入 API-Key 后却提示密钥无效，导致无法顺利对接阿里云百炼模型。

根本原因：问题通常出在三个地方：API-Key 本身输入有误、密钥已过期或被服务商禁用、或者在选择模型提供商时点错了选项。

解决方案：

• 务必仔细核对粘贴的 API-Key，注意区分大小写，并检查首尾是否不小心带上了空格。
• 登录阿里云百炼控制台 → 进入密钥管理页面，确认密钥状态为“启用”；如果显示已过期，果断删除并重新创建一个。
• 重新执行初始化命令，在模型提供商的选择环节，确保选中的是 “Qwen (OAuth)”，别错选成其他平台。

❌ 问题 2：Skills 安装提示“网络超时”或“安装失败”

现象：安装过程中跳出诸如 timeout、failed to download 或 npm install failed 这类令人头疼的报错。

根本原因：无非两点：一是国内网络访问海外注册源延迟过高导致超时；二是服务器自身内存不足，无法完成依赖安装。

解决方案：

# 配置国内镜像源加速下载
openclaw config set plugins.registry https://registry.npmmirror.com/openclaw-plugins

# 重新安装
npx clawhub@latest install

如果报错信息明确指向内存不足，那么先为服务器添加虚拟内存，然后重启服务再试一次。或者，也可以换用备选的安装命令试试运气：

openclaw skills install

❌ 问题 3：启动服务提示“端口 18789 被占用”

现象：执行启动命令 openclaw gateway start 后，系统提示 Port 18789 is already in use。

解决方案：这是一个典型的环境冲突问题，解决思路很清晰：

# 查找占用 18789 端口的程序进程 PID
lsof -i:18789

# 强制终止该进程（将“程序PID”替换为上一步查到的实际数字）
kill -9 程序PID

# 重启 OpenClaw 网关服务
openclaw gateway restart

万一那个占用的进程无法被终止（比如是系统关键进程），也别纠结，直接换个端口是最快的方法：

nano ~/.openclaw/openclaw.json
# 找到 “server”:{“port”:18789} 一行，将 18789 改为其他可用端口（如18790），保存文件
openclaw gateway restart

❌ 问题 4：Skills 安装成功但提示 “skill not ready”

现象：用 openclaw skills list 查看显示技能已安装，但状态却标注为 not ready，执行相关指令完全没有响应。

根本原因：技能虽然装上了，但可能处于“休眠”状态未被启用，或者缺少必要的运行依赖，再或者配置变更没有生效。

解决方案：按照这个顺序操作一遍：

# 第一步：手动启用该 Skills
openclaw skills enable

# 第二步：尝试安装其可能缺少的依赖
openclaw skills install-deps

# 第三步：重启网关服务，让所有配置生效
openclaw gateway restart

# 第四步：再次确认状态，应该显示为 ready
openclaw skills list --status ready

❌ 问题 5：Web 控制台登录提示 “unauthorized”（Token 无效）

现象：在浏览器打开 Web 控制台准备登录，却收到“未授权，Token 无效或过期”的提示。

解决方案：问题的核心在于访问令牌。重新生成一个就行了：

# 重新生成一个有效期为365天的新 Token
openclaw token generate --expire 365d

复制终端输出的完整 Token 字符串，注意别带上空格，然后粘贴到 Web 控制台的登录框里。如果这样还不行，很可能是网关服务状态异常，重启一下：

openclaw gateway restart

❌ 问题 6：Office-Automation 无法发送邮件

现象：调用邮件发送功能时，系统直接返回“邮件发送失败”。

根本原因：几乎可以肯定是 SMTP 服务配置出了问题。可能是服务器地址、端口填错了，也可能是授权码（注意，不是邮箱登录密码）有误，或者是服务器的防火墙没有放行相应端口。

解决方案：

• 重新检查并配置 SMTP 信息，尤其是以下关键参数：
  • QQ 邮箱：服务器 smtp.qq.com，端口 465 (使用 SSL)
  • 163 邮箱：服务器 smtp.163.com，端口 465 (使用 SSL)
• 务必确认你使用的是在邮箱设置中专门生成的“授权码”，而不是你的邮箱登录密码。
• 在服务器防火墙中放行 SMTP 所用的 465 端口，并重启服务使规则生效：

ufw allow 465/tcp && ufw reload
openclaw gateway restart

❌ 问题 7：服务器重启后，OpenClaw 与 Skills 无法自动启动

现象：服务器完成重启，重新登录后发现执行 openclaw status 显示服务状态为 stopped，并没有如预期般自动启动。

解决方案：这说明系统的开机自启服务没有正确配置或丢失了。重新设置一遍即可：

# 重新配置 OpenClaw 网关开机自启
openclaw gateway enable

# 验证配置是否成功（如果显示“yes”则成功）
openclaw gateway is-enabled

# 立即启动服务
openclaw gateway start

# 最后，确保你需要的所有 Skills 都已处于启用（ready）状态
openclaw skills list --status ready

四、进阶拓展：Skills 优化与自定义开发

???? 优化运行效率

系统用久了，难免会安装不少 Skills。把暂时用不到的关掉，可以立刻释放系统资源，运行更流畅。

# 查看所有已安装 Skills
openclaw skills list

# 禁用确定不用的 Skills
openclaw skills disable

另外，定期清理缓存也是个好习惯，能帮你腾出不少磁盘空间。

# 一键清理所有 Skills 的缓存
openclaw skills clean-cache

# 仅清理某个指定技能的缓存
openclaw skills clean-cache

????️ 自定义 Skills 开发（适合有开发能力的用户）

如果官方或社区的 Skills 都无法满足你的特定需求，那么自己动手开发一个，就是最高效的解决方案了。整个过程其实并不复杂，核心步骤就这几步：

① 创建开发目录
首先，为你的新技能建立一个专属的工作目录。

mkdir -p ~/.openclaw/skills/my-custom-skill
cd ~/.openclaw/skills/my-custom-skill

② 创建配置文件 skill.json
这是技能的“身份证”，定义了技能的基本信息。

nano skill.json

将以下内容写入文件，并根据你的实际情况修改名称、描述等字段：

{
“name”:”my-skill”,
“version”:”1.0.0”,
“description”:”自定义技能内容”,
“author”:”自定义作者”,
“dependencies”:{},
“entry”:”index.js”
}

③ 编写技能逻辑 index.js
在这里用 Node.js 代码实现你的核心业务功能，比如一个批量重命名文件的脚本。

④ 安装并启用自定义 Skills
开发完成后，就可以把它安装到你的 OpenClaw 系统中了。

# 安装本地目录下的自定义 Skills
openclaw skills install ~/.openclaw/skills/my-custom-skill

# 启用它
openclaw skills enable my-custom-skill

# 最后，验证是否安装成功并已就绪
openclaw skills list --eligible