ClawHub

skill-isolator

Project-based skill isolation and management. Enables different projects to use different skill sets with automatic loading based on current working directory. Supports multiple skill sources (clawhub, local, git, url) with priority-based resolution, version locking, and auto-sync. Use when: (1) working in a project with .openclaw-skills.json, (2) need to manage project-specific skills, (3) want to isolate skills between projects, (4) need to install skills from clawhub or other sources.

Audits

Warn
ClawScanWarn

Agentic behavior and permission review.

Static analysisReview

Pattern checks against bundled files.

VirusTotalPending

Multi-engine malware detections and file reputation.

Install

openclaw skills install skill-isolator

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

核心功能

功能说明
🔒 项目隔离每个项目独立技能配置，切换项目自动切换技能
🌐 多源支持clawhub / local / git / url，优先级可配置
📦 版本控制支持锁定特定版本或 latest 自动更新
⚡ 自动同步进入项目时自动检测并安装缺失技能
💾 智能缓存减少重复下载，可配置 TTL
🎯 冲突解决项目配置 > 全局配置，同名技能取高优先级源

配置文件详解

完整示例

{
  "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
  }
}

字段说明

字段类型必需说明
namestring❌项目名称（用于显示）
skillsarray✅技能列表，支持字符串或对象格式
excludeGlobalboolean❌true 只用项目技能，false 项目 + 全局（默认 false）
sourcesarray❌技能来源列表，按优先级排序
cache.enabledboolean❌是否启用缓存（默认 true）
cache.ttlHoursnumber❌缓存过期时间（小时，默认 24）
autoSync.onProjectEnterboolean❌进入项目时自动同步（默认 true）
autoSync.onSkillMissingboolean❌发现缺失技能时自动安装（默认 true）

技能格式

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

来源类型

type说明必需字段示例
registry技能市场（clawhub）-{"name":"clawhub","type":"registry"}
filesystem本地目录paths{"type":"filesystem","paths":["~/.openclaw/skills"]}
gitGit 仓库repos{"type":"git","repos":["user/repo"]}
urlHTTP 下载baseUrl{"type":"url","baseUrl":"https://..."}

命令接口

同步与状态

命令说明
node scripts/sync-project-skills.js同步项目技能
node scripts/sync-project-skills.js --force强制重新同步
node scripts/sync-project-skills.js --verbose显示详细信息
node scripts/validate-config.js验证配置格式

配置管理

命令说明
node scripts/init-project-config.js交互式创建配置

工作流程

项目加载流程

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
}

缓存策略

场景行为
缓存有效直接使用，跳过网络请求
缓存过期重新检查源，更新缓存
--force忽略缓存，强制重新检查
缓存损坏自动重建

错误处理

错误原因解决方案
Config errorJSON 格式错误运行 validate-config.js 检查
Skill not found技能在配置源中不存在检查技能名称，确认源配置
Failed to install安装失败（网络/权限）检查网络连接和目录权限
Cache valid, skipping缓存未过期使用 --force 强制刷新

最佳实践

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

文件位置

文件位置
配置文件项目根目录/.openclaw-skills.json
缓存文件~/.openclaw/cache/skills.json
技能目录~/.openclaw/skills/
日志文件~/.openclaw/logs/skills.log

与其他技能协作

clawhub

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

skill-creator

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

更新历史

版本日期变更
1.0.02026-03-10初始版本，支持基础配置和多源安装

许可证

MIT License