06. OpenClaw Skills 问题排查完全指南

适用于 OpenClaw v2026.2 | 本文适合使用和开发 Skills 的用户。

TL;DR: 安装 Skills：openclaw skill install <name>。查看已安装：openclaw skill list。调试 Skills：openclaw skill debug <name>。Skills 目录：~/.openclaw/workspace/skills/。发布到 ClawHub：openclaw skill publish。

常见问题速查表

问题	症状	快速解决
安装失败	`Skill not found`	检查名称和网络
执行错误	`Skill execution failed`	查看日志和依赖
版本不兼容	`Incompatible version`	更新 OpenClaw 或 Skill
依赖缺失	`Module not found`	安装依赖包
权限错误	`Permission denied`	检查文件权限
配置错误	`Invalid configuration`	验证 SKILL.md

问题 1：Skills 安装失败

症状 1：找不到 Skill

$ openclaw skill install gmail-skill
Error: Skill 'gmail-skill' not found in ClawHub

解决方案

# 1. 搜索正确的 Skill 名称
openclaw skill search gmail

# 输出示例：
# Name                Description                    Downloads
# gmail               Gmail integration              12.5k
# gmail-advanced      Advanced Gmail features        3.2k
# gmail-sender        Send emails via Gmail          1.8k

# 2. 使用正确的名称安装
openclaw skill install gmail

# 3. 或从 GitHub 安装
openclaw skill install github:user/repo

# 4. 或从本地目录安装
openclaw skill install /path/to/skill

症状 2：网络错误

Error: Failed to fetch skill from ClawHub: Network error

解决方案

# 1. 检查网络连接
curl -I https://clawhub.com

# 2. 使用代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 3. 重试安装
openclaw skill install gmail

# 4. 或手动下载
# 访问 https://clawhub.com/skills/gmail
# 下载并解压到 ~/.openclaw/workspace/skills/gmail/

症状 3：权限错误

Error: EACCES: permission denied, mkdir '~/.openclaw/workspace/skills/gmail'

解决方案

# 检查目录权限
ls -la ~/.openclaw/workspace/skills/

# 修复权限
sudo chown -R $(whoami) ~/.openclaw/workspace/skills/

# 或重新创建目录
mkdir -p ~/.openclaw/workspace/skills
chmod 755 ~/.openclaw/workspace/skills

症状 4：已安装但未生效

$ openclaw skill list
✅ gmail (installed)

$ openclaw agent --message "发送邮件"
Error: No tool available for sending emails

解决方案

# 1. 重启 Gateway
openclaw gateway --restart

# 2. 检查 Skill 是否启用
openclaw skill show gmail --status

# 3. 手动启用
openclaw skill enable gmail

# 4. 检查配置
openclaw skill config gmail --validate

问题 2：Skills 执行错误

症状 1：依赖缺失

Error: Cannot find module 'nodemailer'
Error: Skill 'gmail' failed to load dependencies

解决方案

# 1. 查看 Skill 依赖
openclaw skill show gmail --dependencies

# 输出示例：
# Dependencies:
# - nodemailer: ^6.9.0
# - googleapis: ^120.0.0

# 2. 安装依赖
cd ~/.openclaw/workspace/skills/gmail
npm install

# 或使用 OpenClaw 命令
openclaw skill install-deps gmail

# 3. 如果依赖在全局
npm install -g nodemailer googleapis

症状 2：配置错误

Error: Skill 'gmail' configuration error: Missing required field 'credentials'

解决方案

# 1. 查看配置要求
openclaw skill show gmail --config-schema

# 输出示例：
# Configuration Schema:
# {
#   "credentials": {
#     "type": "object",
#     "required": true,
#     "properties": {
#       "clientId": {"type": "string"},
#       "clientSecret": {"type": "string"}
#     }
#   }
# }

# 2. 配置 Skill
openclaw skill config gmail --set credentials.clientId "your-client-id"
openclaw skill config gmail --set credentials.clientSecret "your-client-secret"

# 3. 或编辑配置文件
nano ~/.openclaw/workspace/skills/gmail/config.json

# 4. 验证配置
openclaw skill config gmail --validate

症状 3：执行超时

Error: Skill execution timeout after 30000ms

解决方案

# 1. 增加超时时间
openclaw config set skills.timeout 60000

# 2. 或在 Skill 中配置
# 编辑 SKILL.md
---
timeout: 60000
---

# 3. 检查网络或 API 响应时间
time curl -X POST https://gmail.googleapis.com/...

症状 4：权限不足

Error: Skill 'filesystem' access denied: Cannot read /etc/shadow

解决方案

# 1. 检查 Skill 权限需求
openclaw skill show filesystem --permissions

# 输出示例：
# Required Permissions:
# - filesystem.read
# - filesystem.write

# 2. 检查当前权限
openclaw config get agents.defaults.sandbox.allowlist

# 3. 添加必要权限
openclaw config set agents.defaults.sandbox.allowlist '["read", "write", "edit"]'

# 4. 或为特定 Skill 配置权限
openclaw skill config filesystem --set allowedPaths '["~/workspace", "~/documents"]'

问题 3：版本兼容性问题

症状 1：OpenClaw 版本过低

Error: Skill requires OpenClaw >= 2026.3.0, current version is 2026.2.26

解决方案

# 1. 检查当前版本
openclaw --version

# 2. 更新 OpenClaw
openclaw update

# 或使用 npm
npm update -g openclaw@latest

# 3. 如果无法更新，寻找兼容版本
openclaw skill search gmail --version-compatible 2026.2

# 4. 或安装旧版本 Skill
openclaw skill install [email protected]

症状 2：Node.js 版本不兼容

Error: Skill requires Node.js >= 20.0.0

解决方案

# 1. 检查 Node.js 版本
node --version

# 2. 升级 Node.js
nvm install 22
nvm use 22

# 3. 或使用 Docker 运行（自动包含正确版本）

症状 3：依赖版本冲突

Error: Dependency conflict: nodemailer@^6.9.0 conflicts with nodemailer@^7.0.0

解决方案

# 1. 查看依赖冲突
openclaw skill deps-check

# 2. 更新依赖
cd ~/.openclaw/workspace/skills/gmail
npm update

# 3. 或使用 --legacy-peer-deps
npm install --legacy-peer-deps

# 4. 或隔离 Skills（推荐）
# 每个 Skill 使用独立的 node_modules
openclaw config set skills.isolateDeps true

问题 4：自定义 Skills 开发问题

症状 1：SKILL.md 格式错误

Error: Invalid SKILL.md: Missing required field 'name'

解决方案

检查 SKILL.md 格式：

---
name: my-skill
version: 1.0.0
description: My custom skill
author: Your Name
minOpenClawVersion: 2026.2
dependencies:
  - axios@^1.6.0
tools:
  - name: my_tool
    description: My custom tool
    parameters:
      type: object
      properties:
        param1:
          type: string
          description: First parameter
      required:
        - param1
---

# My Skill

Description and usage instructions...

验证 SKILL.md：

# 验证格式
openclaw skill validate /path/to/skill

# 输出示例：
# ✅ name: valid
# ✅ version: valid
# ✅ description: valid
# ⚠️  author: recommended but not required
# ✅ tools: valid (1 tool defined)
# ✅ content: valid

症状 2：工具执行失败

Error: Tool 'my_tool' execution failed: TypeError: Cannot read property 'param1' of undefined

解决方案

检查工具实现：

// skill.js
module.exports = {
  tools: {
    my_tool: async (params, context) => {
      // 验证参数
      if (!params || !params.param1) {
        throw new Error('Missing required parameter: param1');
      }

      try {
        // 执行逻辑
        const result = await doSomething(params.param1);
        return result;
      } catch (error) {
        context.logger.error('Tool execution failed:', error);
        throw error;
      }
    }
  }
};

调试工具：

# 启用调试模式
openclaw skill debug my-skill --tool my_tool

# 测试工具
openclaw skill test my-skill --tool my_tool --params '{"param1": "test"}'

# 查看详细日志
openclaw logs --skill my-skill --verbose

症状 3：Skill 无法加载

Error: Failed to load skill 'my-skill': Cannot find module './skill'

解决方案

检查目录结构：

my-skill/
├── SKILL.md          # 必需
├── skill.js          # 主入口（或 index.js）
├── config.json       # 可选
├── package.json      # 如果有依赖
└── README.md         # 推荐

确保导出正确：

// skill.js
module.exports = {
  // 工具定义
  tools: {
    // ...
  },

  // 可选：初始化函数
  init: async (context) => {
    // 初始化逻辑
  },

  // 可选：清理函数
  cleanup: async () => {
    // 清理逻辑
  }
};

症状 4：配置验证失败

Error: Skill configuration validation failed: Invalid type for 'port' (expected number, got string)

解决方案

定义配置 Schema：

---
name: my-skill
configSchema:
  type: object
  properties:
    port:
      type: number
      default: 3000
      minimum: 1024
      maximum: 65535
    apiKey:
      type: string
      format: password
    debug:
      type: boolean
      default: false
  required:
    - apiKey
---

验证配置：

# 验证配置
openclaw skill config my-skill --validate

# 查看配置 Schema
openclaw skill show my-skill --config-schema

# 设置配置
openclaw skill config my-skill --set port 8080
openclaw skill config my-skill --set apiKey "your-key"

问题 5：ClawHub 集成问题

症状 1：无法发布到 ClawHub

Error: Failed to publish skill: Authentication failed

解决方案

# 1. 登录 ClawHub
openclaw login

# 或设置 API Token
export CLAWHUB_API_TOKEN="your-token"

# 2. 验证登录状态
openclaw whoami

# 3. 发布 Skill
openclaw skill publish my-skill

# 输出示例：
# Validating skill...
# ✅ SKILL.md valid
# ✅ Tools defined
# ✅ Dependencies resolved
# Publishing to ClawHub...
# ✅ Published successfully!
# URL: https://clawhub.com/skills/my-skill

症状 2：Skill 未出现在搜索结果

$ openclaw skill search my-skill
No results found

解决方案

# 1. 检查发布状态
openclaw skill show my-skill --status

# 2. 等待索引更新（最多 5 分钟）
sleep 300

# 3. 使用完整 ID 搜索
openclaw skill search user/my-skill

# 4. 直接访问
openclaw skill install user/my-skill

症状 3：更新 Skill 后版本未变

$ openclaw skill update my-skill
Skill already up to date (v1.0.0)

解决方案

# 1. 检查远程版本
openclaw skill show my-skill --remote

# 输出示例：
# Local:  1.0.0
# Remote: 1.1.0

# 2. 强制更新
openclaw skill update my-skill --force

# 3. 或重新安装
openclaw skill uninstall my-skill
openclaw skill install my-skill

Skills 管理最佳实践

1. 目录结构

~/.openclaw/workspace/skills/
├── gmail/
│   ├── SKILL.md
│   ├── skill.js
│   ├── config.json
│   ├── package.json
│   └── node_modules/
├── calendar/
│   ├── SKILL.md
│   └── ...
└── custom-skill/
    └── ...

2. 依赖管理

# 隔离依赖（推荐）
openclaw config set skills.isolateDeps true

# 定期更新依赖
for skill in ~/.openclaw/workspace/skills/*/; do
  cd "$skill"
  npm update
done

# 检查过期依赖
for skill in ~/.openclaw/workspace/skills/*/; do
  cd "$skill"
  npm outdated
done

3. 版本控制

# 为自定义 Skill 创建 Git 仓库
cd ~/.openclaw/workspace/skills/my-skill
git init
git add .
git commit -m "Initial commit"

# 推送到 GitHub
git remote add origin https://github.com/user/my-skill.git
git push -u origin main

4. 测试和调试

创建测试脚本 test-skill.sh：

#!/bin/bash

SKILL_NAME=$1

echo "Testing skill: $SKILL_NAME"

# 1. 验证 SKILL.md
echo "Validating SKILL.md..."
openclaw skill validate $SKILL_NAME

# 2. 检查配置
echo "Checking configuration..."
openclaw skill config $SKILL_NAME --validate

# 3. 测试工具
echo "Testing tools..."
openclaw skill test $SKILL_NAME --all

# 4. 运行集成测试
echo "Running integration tests..."
openclaw agent --message "Test $SKILL_NAME skill" --skill $SKILL_NAME

echo "Test completed"

5. Skills 清单

创建 skills-manifest.json：

{
  "skills": [
    {
      "name": "gmail",
      "version": "2.1.0",
      "enabled": true,
      "config": {
        "clientId": "xxx"
      }
    },
    {
      "name": "calendar",
      "version": "1.5.0",
      "enabled": true,
      "config": {}
    }
  ]
}

批量安装：

openclaw skill install-from-manifest skills-manifest.json

Skills 调试工具

完整调试流程

#!/bin/bash

SKILL_NAME=$1

echo "=== Skills 调试工具 ==="
echo

echo "1. 检查 Skill 安装..."
if openclaw skill list | grep -q "$SKILL_NAME"; then
    echo "✅ Skill 已安装"
    openclaw skill show $SKILL_NAME
else
    echo "❌ Skill 未安装"
    exit 1
fi
echo

echo "2. 验证 SKILL.md..."
openclaw skill validate $SKILL_NAME
echo

echo "3. 检查依赖..."
cd ~/.openclaw/workspace/skills/$SKILL_NAME
if [ -f "package.json" ]; then
    echo "依赖："
    cat package.json | jq '.dependencies'
    echo
    echo "检查安装："
    npm ls --depth=0
else
    echo "无外部依赖"
fi
echo

echo "4. 验证配置..."
openclaw skill config $SKILL_NAME --validate
openclaw skill config $SKILL_NAME --show
echo

echo "5. 测试工具..."
openclaw skill test $SKILL_NAME --all --verbose
echo

echo "6. 查看日志..."
openclaw logs --skill $SKILL_NAME --tail 20
echo

echo "=== 调试完成 ==="

小结

Skills 是扩展 OpenClaw 能力的核心机制：

安装问题：检查名称、网络、权限
执行错误：安装依赖、配置正确、检查权限
版本兼容：更新 OpenClaw、使用兼容版本
开发问题：遵循格式、调试工具、测试验证
ClawHub：登录认证、发布流程、版本管理

Skills 管理的核心原则：

版本控制：管理 Skill 版本和依赖
配置管理：正确配置和环境变量
测试驱动：开发时充分测试
文档完善：清晰的 SKILL.md 和 README

下一篇预告：07. 运行时问题排查 — 解决 Gateway 崩溃、会话异常、Agent 无响应等运行时问题。

更新记录：

2026-03-06：初版发布，涵盖 5 大类 Skills 问题

系列导航：

← 上一篇：安全问题排查
→ 下一篇：运行时问题排查
返回：问题排查系列索引

常见问题速查表

问题 1：Skills 安装失败

症状 1：找不到 Skill

解决方案

症状 2：网络错误

解决方案

症状 3：权限错误

解决方案

症状 4：已安装但未生效

解决方案

问题 2：Skills 执行错误

症状 1：依赖缺失

解决方案

症状 2：配置错误

解决方案

症状 3：执行超时

解决方案

症状 4：权限不足

解决方案

问题 3：版本兼容性问题

症状 1：OpenClaw 版本过低

解决方案

症状 2：Node.js 版本不兼容

解决方案

症状 3：依赖版本冲突

解决方案

问题 4：自定义 Skills 开发问题

症状 1：SKILL.md 格式错误

解决方案

症状 2：工具执行失败

解决方案

症状 3：Skill 无法加载

解决方案

症状 4：配置验证失败

解决方案

问题 5：ClawHub 集成问题

症状 1：无法发布到 ClawHub

解决方案

症状 2：Skill 未出现在搜索结果

解决方案

症状 3：更新 Skill 后版本未变

解决方案

Skills 管理最佳实践

1. 目录结构

2. 依赖管理

3. 版本控制

4. 测试和调试

5. Skills 清单

Skills 调试工具

完整调试流程

小结

🍪 Cookie 使用通知

Cookie 偏好设置

必要 Cookie

分析 Cookie

广告 Cookie