1. SkillHub 安装前的环境准备在开始安装 SkillHub 之前我们需要确保系统环境满足基本要求。SkillHub 是一个基于 Python 的 CLI 工具集因此 Python 环境的正确配置是首要条件。1.1 Python 3.12 的安装与验证Python 3.12 是 SkillHub 运行的基础依赖以下是详细的安装步骤下载 Python 3.12 安装包访问 Python 官方下载页面https://www.python.org/downloads/选择与您操作系统匹配的 3.12.x 版本对于 Windows 用户建议下载 Windows installer (64-bit)macOS 用户可以选择 macOS 64-bit universal2 installer安装过程中的关键选项勾选 Add python.exe to PATH这将允许在命令行中直接调用 Python选择 Customize installation 确保安装 pip 和 Python 测试套件高级选项中建议勾选 Install for all users需要管理员权限安装后验证 打开命令行Windows 的 CMD/PowerShell 或 macOS/Linux 的终端执行python --version应返回类似Python 3.12.x的版本信息。如果系统同时存在多个 Python 版本可能需要使用python3 --version注意如果遇到 python is not recognized 错误说明 PATH 环境变量未正确配置。可以重新运行安装程序选择 Modify 并确认 PATH 选项已勾选或手动将 Python 安装目录如C:\Python312和 Scripts 目录如C:\Python312\Scripts添加到系统 PATH。1.2 系统权限与依赖检查SkillHub 安装过程中会创建多个目录和文件需要确保有足够的权限Windows 系统建议以管理员身份运行 PowerShell检查执行策略是否允许脚本运行Get-ExecutionPolicy如果返回 Restricted需要设置为 RemoteSignedSet-ExecutionPolicy RemoteSigned -Scope CurrentUser类 Unix 系统macOS/Linux确保对/usr/local/bin或~/.local/bin有写入权限可能需要使用 sudo 或调整目录权限sudo chown -R $(whoami) /usr/local/bin2. SkillHub 安装脚本解析SkillHub 的安装过程主要通过 PowerShell 脚本实现自动化理解其工作原理有助于排查可能的问题。2.1 安装脚本的执行流程原始脚本的主要执行步骤可分为三个阶段下载阶段从腾讯云 COS 存储桶下载最新的 SkillHub 安装包tar.gz 格式使用 System.Net.Http.HttpClient 进行下载超时设置为 2 分钟下载完成后验证文件大小通过 $tarBytes.LengthPython 环境检测通过 Get-Command 查找系统 PATH 中的 python 可执行文件如果未找到 Python脚本会报错退出并提示安装 Python找到的 Python 路径会存储在 $pythonCmd 变量中Python 安装脚本生成与执行将 Base64 编码的 tar 包内容嵌入 Python 脚本在临时目录生成 Python 安装脚本文件名包含随机数防冲突使用检测到的 Python 解释器执行该脚本2.2 关键目录结构与功能安装过程中会创建以下目录结构~/ ├── .skillhub/ # 主配置目录 │ ├── skills_store_cli.py # 核心 CLI 入口 │ ├── skills_upgrade.py # 升级脚本 │ ├── version.json # 版本信息 │ ├── metadata.json # 元数据 │ └── config.json # 配置文件 ├── .local/bin/ # 可执行文件目录PATH │ ├── skillhub.py # Unix 系统入口 │ ├── oc-skills.py # 别名入口 │ ├── skillhub.bat # Windows 入口 │ └── oc-skills.bat # Windows 别名入口 └── .openclaw/ # 工作区目录 └── workspace/ └── skills/ ├── find-skills/ # 技能存储 └── skillhub-preference/ # 偏好设置3. 手动安装步骤详解对于无法直接运行 PowerShell 脚本的环境可以按照以下步骤手动安装。3.1 获取安装包直接下载安装包curl -LO https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/latest.tar.gz或使用 wgetwget https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/latest.tar.gz验证下载完整性可选sha256sum latest.tar.gz应与官方提供的校验和一致。3.2 解压与安装创建目标目录mkdir -p ~/.skillhub ~/.local/bin ~/.openclaw/workspace/skills/{find-skills,skillhub-preference}解压并安装核心文件import tarfile, os, stat with tarfile.open(latest.tar.gz, r:gz) as tar: tar.extract(cli/skills_store_cli.py, path~/.skillhub) tar.extract(cli/skills_upgrade.py, path~/.skillhub) tar.extract(cli/version.json, path~/.skillhub) tar.extract(cli/metadata.json, path~/.skillhub) # 创建 CLI 入口 with open(~/.local/bin/skillhub.py, w) as f: f.write(#!/usr/bin/env python3 import os, sys cli os.path.join(os.path.expanduser(~), .skillhub, skills_store_cli.py) os.execv(sys.executable, [sys.executable, cli] sys.argv[1:]) ) os.chmod(~/.local/bin/skillhub.py, os.stat(~/.local/bin/skillhub.py).st_mode | stat.S_IXUSR)3.3 环境变量配置确保~/.local/bin在系统 PATH 中Linux/macOS 编辑~/.bashrc或~/.zshrcexport PATH$HOME/.local/bin:$PATH然后执行source ~/.bashrcWindows 通过系统属性 → 高级 → 环境变量在用户变量中添加%USERPROFILE%\.local\bin4. 常见问题与解决方案4.1 Python 环境问题问题现象执行脚本时报错 Python NOT FOUND解决方案确认 Python 3.12 已正确安装检查 PATH 环境变量是否包含 Python 安装目录尝试使用完整路径调用 Python$pythonCmd C:\Python312\python.exe4.2 网络连接问题问题现象下载阶段卡顿或失败解决方案检查网络连接特别是对腾讯云服务的访问尝试手动下载安装包并修改脚本$tarBytes [System.IO.File]::ReadAllBytes(C:\path\to\latest.tar.gz)使用代理如需$handler New-Object System.Net.Http.HttpClientHandler $handler.Proxy [System.Net.WebRequest]::GetSystemWebProxy() $handler.UseProxy $true4.3 文件权限问题问题现象安装过程中出现 Permission denied 错误解决方案Windows 系统以管理员身份运行 PowerShell类 Unix 系统使用 sudo 或调整目标目录权限sudo chown -R $(whoami) ~/.skillhub ~/.local/bin检查防病毒软件是否阻止了文件操作5. 安装后测试与验证完成安装后应进行基本功能测试以确保安装成功。5.1 基本功能测试检查版本信息skillhub --version应返回类似skillhub 1.x.x的版本信息。测试帮助命令skillhub --help应显示可用的命令列表和简要说明。验证技能目录ls ~/.openclaw/workspace/skills/find-skills应包含至少一个 .md 文件如 SKILL.md。5.2 环境集成检查确认可执行文件位置which skillhub应返回~/.local/bin/skillhub或等效路径。检查 Python 模块导入python -c from skillhub import core; print(core.__version__)应无报错并返回版本号。6. 进阶配置与优化6.1 自定义安装路径如需更改默认安装路径可以修改 Python 安装脚本中的以下变量home os.path.expanduser(~) # 修改此行指定自定义路径 base os.path.join(home, .skillhub) # 主目录 binDir os.path.join(home, .local, bin) # 可执行文件目录6.2 代理配置如果处于内网环境可能需要配置代理修改~/.skillhub/config.json{ self_update_url: https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/version.json, proxy: { http: http://your.proxy:port, https: http://your.proxy:port } }或在环境变量中设置export HTTP_PROXYhttp://your.proxy:port export HTTPS_PROXYhttp://your.proxy:port6.3 自动更新设置SkillHub 支持自动更新检查启用每日更新检查skillhub config set auto_update_check true手动触发更新skillhub update查看更新日志skillhub changelog7. 卸载与清理如需完全移除 SkillHub可执行以下步骤删除安装的文件rm -rf ~/.skillhub ~/.openclaw/workspace/skills/find-skills移除可执行文件rm ~/.local/bin/skillhub.py ~/.local/bin/oc-skills.py rm ~/.local/bin/skillhub.bat ~/.local/bin/oc-skills.bat清理 Python 缓存可选python -m pip cache purge检查并清理环境变量中对 SkillHub 的引用