OpenClaw 如何使用 Skills

作者：CSDN博客
一、为什么说"不装 Skills 等于白部署"？

OpenClaw 本体只是大脑，Skills 才是它的四肢和工具箱。

---

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

在安装任何 Skills 之前，先把这几条通用命令记牢，后面会反复用到：
# 查看所有已安装的 Skills 状态（确认正常启用）
openclaw skills list --eligible

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

# 卸载不需要的 Skills
openclaw skills uninstall <skill-slug>

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

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

# 查看某个 Skills 的详细信息
openclaw skills info <skill-slug>
三、7 大高频报错避坑指南（新手必看）

以下是 2026 年最常见的 7 类报错，附核心原因和解决方法，遇到问题直接对号入座。

---

❌ 问题 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 <skill-slug>
如果提示内存不足，先添加虚拟内存后重启服务再试。也可以换用备选安装命令：
openclaw skills install <skill-slug>

---

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

现象：执行 openclaw gateway start 后提示 Port 18789 is already in use。
解决方案：
# 查找占用端口的程序 PID
lsof -i:18789

# 终止该进程（替换为实际 PID）
kill -9 程序PID

# 重启服务
openclaw gateway restart
如果无法终止该进程，可以改端口：
nano ~/.openclaw/openclaw.json
# 修改 "server":{"port":18790}，保存后重启
openclaw gateway restart

---

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

现象：openclaw skills list 显示已安装，但状态为 not ready，指令无响应。
根本原因：Skills 未启用、缺少依赖或配置未生效。
解决方案：
# 手动启用 Skills
openclaw skills enable <skill-slug>

# 安装所需依赖
openclaw skills install-deps <skill-slug>

# 重启服务
openclaw gateway restart

# 再次确认状态
openclaw skills list --status ready

---

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

现象：登录 Web 控制台时提示"未授权，Token 无效或过期"。
解决方案：
# 重新生成 Token（有效期 365 天）
openclaw token generate --expire 365d
复制终端输出的完整 Token，确保无多余空格，重新登录。若仍失败，重启网关服务：
openclaw gateway restart

---

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

现象：执行邮件发送指令，提示"邮件发送失败"。
根本原因：SMTP 配置错误、授权码有误或端口未放行。
解决方案：

重新配置，核对 SMTP 地址和端口：

QQ 邮箱：smtp.qq.com，端口 465
163 邮箱：smtp.163.com，端口 465

确认使用的是授权码而非登录密码（需在邮箱设置中开启第三方授权）
放行端口并重启：

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

---

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

现象：重启服务器后执行 openclaw status 显示 stopped。
解决方案：
# 重新设置开机自启
openclaw gateway enable

# 验证配置（显示"yes"即成功）
openclaw gateway is-enabled

# 启动服务
openclaw gateway start

# 确认所有必装 Skills 已启用
openclaw skills list --status ready

---

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