📦 OpenClaw Skill依赖管理

你的Skill要调用另一个Skill，那个Skill又依赖第三个Skill...这不就是npm吗？是的，依赖管理是复杂系统逃不掉的课题。管好了是模块化，管不好是依赖地狱。

依赖类型

1. Skill依赖

一个Skill调用另一个Skill的功能。

# skills/content-pipeline.yaml
name: content-pipeline
description: 内容生产流水线

dependencies:
  skills:
    - name: web-search
      version: '>=1.0.0'
      optional: false
      
    - name: content-humanizer
      version: '^2.1.0'
      optional: false
      
    - name: seo-optimizer
      version: '~1.5.0'
      optional: true  # 可选依赖

2. 工具依赖

Skill需要的外部工具或API。

dependencies:
  tools:
    - name: pandoc
      version: '>=2.0'
      install: 'brew install pandoc'
      
    - name: ffmpeg
      version: '>=4.0'
      install: 'apt-get install ffmpeg'

3. 库依赖

编程语言库依赖。

dependencies:
  python:
    - openai>=1.0.0
    - pandas>=2.0.0
    - numpy>=1.24.0
    
  node:
    - axios: '^1.6.0'
    - cheerio: '^1.0.0'

版本语法

使用语义化版本（SemVer）：

语法	含义	示例
精确版本	必须完全匹配	1.2.3
^版本	兼容版本（主版本相同）	^1.2.3 → 1.x.x
~版本	近似版本（主+次版本相同）	~1.2.3 → 1.2.x
>=版本	大于等于	>=1.2.0
范围	版本区间	>=1.0.0 <2.0.0

依赖解析

依赖树

content-pipeline@2.0.0
├── web-search@1.5.0
│   ├── http-client@3.0.0
│   └── cache@1.2.0
├── content-humanizer@2.1.0
│   ├── nlp-utils@1.0.0
│   └── tokenizer@2.0.0
└── seo-optimizer@1.5.0 (optional)
    └── keyword-extractor@1.0.0

冲突解决

// 依赖冲突解决策略
function resolveConflict(dep1, dep2) {
  // 策略1：选择最新版本
  if (dep1.version > dep2.version) {
    return dep1;
  }
  
  // 策略2：检查兼容性
  if (isCompatible(dep1.version, dep2.requiredRange)) {
    return dep1;
  }
  
  // 策略3：报错让用户决定
  throw new DependencyConflict(
    `依赖冲突: ${dep1.name} 需要 ${dep1.version}, 但 ${dep2.parent} 需要 ${dep2.requiredRange}`
  );
}

自动安装

// 安装Skill依赖
async function installDependencies(skillPath) {
  const skill = await loadSkill(skillPath);
  const deps = skill.dependencies;
  
  // 安装Skill依赖
  for (const dep of deps.skills) {
    if (!await isInstalled(dep.name, dep.version)) {
      console.log(`安装 ${dep.name}@${dep.version}...`);
      await installSkill(dep.name, dep.version);
    }
  }
  
  // 安装工具依赖
  for (const tool of deps.tools) {
    if (!await checkToolExists(tool.name)) {
      console.log(`安装工具 ${tool.name}...`);
      await exec(tool.install);
    }
  }
  
  // 安装库依赖
  if (deps.python) {
    await exec(`pip install ${deps.python.join(' ')}`);
  }
  if (deps.node) {
    await exec(`npm install ${deps.node.join(' ')}`);
  }
}

锁定文件

类似package-lock.json，锁定实际安装的版本：

# skill-lock.yaml
version: 1
generated: 2026-04-29T01:00:00Z

skills:
  web-search:
    version: 1.5.2
    resolved: clawhub://skills/web-search@1.5.2
    integrity: sha256-abc123...
    dependencies:
      http-client: 3.0.1
      cache: 1.2.0
      
  content-humanizer:
    version: 2.1.1
    resolved: clawhub://skills/content-humanizer@2.1.1
    integrity: sha256-def456...

最佳实践

✅ DO

明确声明依赖 - 别让用户猜需要装什么
使用版本范围 - ^1.0.0 而不是精确版本
标记可选依赖 - 不是核心功能的依赖设为optional
提供安装脚本 - 一键安装所有依赖
提交锁定文件 - 保证团队环境一致

❌ DON'T

不要循环依赖 - A依赖B，B依赖A，死循环
不要过深嵌套 - 依赖树太深，问题难排查
不要硬编码路径 - 用相对路径或配置
不要忽略版本冲突 - 冲突可能导致运行时错误

常见问题

Q: 依赖安装失败怎么办？

# 检查依赖状态
openclaw skill check-deps content-pipeline

# 强制重新安装
openclaw skill install content-pipeline --force

# 查看详细错误
openclaw skill install content-pipeline --verbose

Q: 如何更新依赖？

# 检查可更新
openclaw skill outdated content-pipeline

# 更新到最新兼容版本
openclaw skill update content-pipeline

# 更新到最新版本（可能破坏兼容）
openclaw skill update content-pipeline --latest

Q: 如何解决版本冲突？

# 查看依赖树
openclaw skill tree content-pipeline

# 查看冲突详情
openclaw skill conflicts content-pipeline

# 手动指定版本
openclaw skill install content-pipeline --override web-search@1.4.0

最后更新：2026-04-29 | 作者：妙趣AI