skill-isolator

为不同项目提供独立的技能配置和隔离管理，实现技能按需加载、项目间完全隔离。

快速开始

1️⃣ 创建项目配置

在项目根目录创建 .openclaw-skills.json：

# 使用交互向导
node scripts/init-project-config.js

# 或手动创建（最小配置）
echo '{"skills":["weather"],"excludeGlobal":true}' > .openclaw-skills.json

2️⃣ 同步技能

# 自动检测并安装缺失技能
node scripts/sync-project-skills.js

3️⃣ 验证配置

node scripts/validate-config.js

核心功能

配置文件详解

完整示例

{
  "name": "my-project",
  "skills": [
    { "name": "feishu-doc", "version": "latest" },
    { "name": "weather", "version": "1.2.0" },
    "stock-analyzer"
  ],
  "excludeGlobal": true,
  "sources": [
    {
      "name": "clawhub",
      "type": "registry",
      "priority": 1,
      "enabled": true
    },
    {
      "name": "local",
      "type": "filesystem",
      "priority": 2,
      "paths": ["~/.openclaw/skills", "~/my-skills"]
    }
  ],
  "cache": {
    "enabled": true,
    "ttlHours": 24
  },
  "autoSync": {
    "onProjectEnter": true,
    "onSkillMissing": true
  }
}

字段说明

技能格式

{
  "skills": [
    "weather",                          // 简单格式 - 最新版本的技能
    { "name": "feishu-doc" },           // 对象格式 - 最新版本
    { "name": "stock-analyzer", "version": "1.2.0" }  // 锁定版本
  ]
}

来源类型

命令接口

同步与状态

配置管理

工作流程

项目加载流程

1. 检测当前工作目录
   ↓
2. 向上查找最近的 .openclaw-skills.json
   ↓
3. 解析技能列表和来源配置
   ↓
4. 检查每个技能是否已安装
   ↓
5. 缺失技能 → 按源优先级查找并安装
   ↓
6. 激活配置的技能
   ↓
7. 缓存加载状态

技能安装流程

1. 遍历配置的技能列表
   ↓
2. 检查技能是否已安装（多目录检测）
   ↓
3. 未安装 → 按优先级遍历来源
   ↓
4. 找到技能 → 下载/克隆
   ↓
5. 验证技能格式（SKILL.md 必需）
   ↓
6. 安装到本地技能目录
   ↓
7. 更新缓存

脚本工具

sync-project-skills.js

同步项目技能的主脚本。

# 基本用法
node scripts/sync-project-skills.js

# 强制重新同步（忽略缓存）
node scripts/sync-project-skills.js --force

# 显示详细信息
node scripts/sync-project-skills.js --verbose

# 组合使用
node scripts/sync-project-skills.js --force --verbose

参数：

• --force, -f: 强制重新同步，忽略缓存
• --verbose, -v: 显示详细信息

validate-config.js

验证配置文件格式和完整性。

# 验证当前目录配置
node scripts/validate-config.js

# 验证指定文件
node scripts/validate-config.js path/to/config.json

验证内容：

• JSON 格式正确性
• 必需字段存在性
• 字段类型正确性
• 来源类型有效性
• 重复技能检测

init-project-config.js

交互式配置创建向导。

node scripts/init-project-config.js

引导内容：

• 项目名称
• 技能列表
• 是否排除全局技能
• 技能来源配置
• 缓存设置
• 自动同步设置

缓存机制

缓存位置

~/.openclaw/cache/skills.json

缓存内容

{
  "skills": {
    "weather": { "installed": true, "timestamp": 1710000000000 },
    "feishu-doc": { "installed": true, "timestamp": 1710000000000 }
  },
  "sources": {
    "clawhub": { "reachable": true, "lastCheck": 1710000000000 }
  },
  "lastSync": 1710000000000
}

缓存策略

错误处理

最佳实践

1️⃣ 配置最小化

只配置项目真正需要的技能：

{
  "skills": ["feishu-doc", "weather"],
  "excludeGlobal": true
}

2️⃣ 版本锁定

生产项目锁定技能版本：

{
  "skills": [
    { "name": "feishu-doc", "version": "2.1.0" },
    { "name": "weather", "version": "1.0.3" }
  ]
}

3️⃣ 本地开发

开发中的技能使用本地源：

{
  "sources": [
    { "name": "local-dev", "type": "filesystem", "paths": ["~/dev/my-skills"], "priority": 1 }
  ]
}

4️⃣ 团队共享

提交配置到版本控制：

git add .openclaw-skills.json
git commit -m "Add project skill configuration"

故障排查

技能未加载

# 1. 检查配置文件是否存在
ls .openclaw-skills.json

# 2. 验证配置格式
node scripts/validate-config.js

# 3. 强制同步
node scripts/sync-project-skills.js --force --verbose

安装失败

# 1. 检查网络连接
ping clawhub.com

# 2. 检查技能目录权限
ls -la ~/.openclaw/skills/

# 3. 查看详细日志
node scripts/sync-project-skills.js --verbose

配置错误

# 验证配置并查看示例
node scripts/validate-config.js

文件位置

与其他技能协作

clawhub

本技能依赖 clawhub 技能来安装 registry 源的技能。确保 clawhub 技能已安装。

skill-creator

创建新技能后，可以用本技能将新技能添加到项目配置中。

更新历史

许可证

MIT License