SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsqclaw-env

qclaw-env

Deployment & operations

View repository

Updated 10-16 08:46

About this skill

Env Doctor — OpenClaw Skill Full-Chain Environment Diagnosis and Installation

Mandatory Specification [MANDATORY]

All installation operations for CLIs, tools, runtimes, and package managersmustfollow the process below, and no step may be skipped:

Step 1: Detect Platform and Architecture

# macOS / Linux
OS="$(uname -s)"   # Darwin / Linux
ARCH="$(uname -m)" # arm64 / x86_64
echo "平台: $OS, 架构: $ARCH"

# Windows (PowerShell)
$OS = "Windows"
$ARCH = if ([Environment]::Is64BitOperatingSystem) { "x64" } else { "x86" }
$WinVer = [System.Environment]::OSVersion.Version
Write-Host "平台: $OS, 架构: $ARCH, Windows 版本: $($WinVer.Major).$($WinVer.Minor).$($WinVer.Build)"

Platform support notes:

  • macOS (Darwin) — Fully supported, refer to install-macos.md
  • Windows — Fully supported, refer to install-windows.md
  • Linux — No installation manual is currently provided. If Linux is detected, inform the user that this skill does not currently support Linux, and they need to install the required tools themselves according to their distribution's package manager

macOS architecture marker: If ARCH=arm64(Apple Silicon), when subsequently installing Homebrewmustexecute eval "$(/opt/homebrew/bin/brew shellenv)", otherwise all tools installed via brew will not be found.

Step 2: Full Environment Snapshot

Before installing anything,first probe all tools and versions already present on the system in one pass, to avoid duplicate installations and misjudgments.

# macOS — 全量环境快照
echo "=== 系统环境快照 ==="
echo "--- 平台 ---"
echo "OS: $(uname -s), ARCH: $(uname -m), macOS: $(sw_vers -productVersion 2>/dev/null || echo 'N/A')"
echo ""
echo "--- Xcode CLT ---"
xcode-select -p >/dev/null 2>&1 && echo "xcode-select: 已安装 ($(xcode-select -p))" || echo "xcode-select: 未安装"
echo ""
echo "--- sudo 免密可用性 ---"
sudo -n true 2>/dev/null && echo "SUDO_OK=true" || echo "SUDO_OK=false (需使用非 sudo 安装方式)"
echo ""
echo "--- 包管理器 ---"
command -v brew >/dev/null 2>&1 && echo "brew: $(brew --version 2>&1 | head -1)" || echo "brew: 未安装"
echo ""
echo "--- 基础运行时 ---"
for cmd in node npm python3 pip3 go uv; do
  if command -v "$cmd" >/dev/null 2>&1; then
    ver="$("$cmd" --version 2>&1 | head -1)"
    echo "$cmd: $ver"
  else
    echo "$cmd: 未安装"
  fi
done
echo ""
echo "--- python3 真实性检测 ---"
python3 -c "import sys; print('python3 可用:', sys.version)" 2>/dev/null || echo "python3: 不可用或为 Xcode CLT stub"
echo ""
echo "--- CLI 工具 ---"
for cmd in curl git gh jq rg ffmpeg tmux whisper memo remindctl clawhub claude codex himalaya uv; do
  if command -v "$cmd" >/dev/null 2>&1; then
    echo "$cmd: 已安装"
  else
    echo "$cmd: 未安装"
  fi
done

# Windows — 全量环境快照（先切 UTF-8 防乱码）
chcp 65001 >nul
Write-Host "=== 系统环境快照 ==="
Write-Host "--- 平台 ---"
$ver = [System.Environment]::OSVersion.Version
Write-Host "OS: Windows, Build: $($ver.Major).$($ver.Minor).$($ver.Build), Arch: $(if ([Environment]::Is64BitOperatingSystem) {'x64'} else {'x86'})"
Write-Host ""
Write-Host "--- Shell 环境 ---"
Write-Host "当前 Shell: $($PSVersionTable.PSVersion) (PowerShell)"
$policy = Get-ExecutionPolicy -Scope CurrentUser
Write-Host "执行策略 (CurrentUser): $policy"
Write-Host ""
Write-Host "--- 包管理器 ---"
foreach ($pm in @("scoop", "winget", "choco")) {
    $c = Get-Command $pm -ErrorAction SilentlyContinue
    if ($c) { Write-Host "$pm`: 已安装" } else { Write-Host "$pm`: 未安装" }
}
Write-Host ""
Write-Host "--- 基础运行时 ---"
foreach ($cmd in @("node", "npm", "python", "pip", "go", "uv", "curl.exe", "git")) {
    $c = Get-Command $cmd -ErrorAction SilentlyContinue
    if ($c) {
        try { $v = & $cmd --version 2>&1 | Select-Object -First 1; Write-Host "$cmd`: $v" }
        catch { Write-Host "$cmd`: 已安装 (版本获取失败)" }
    } else { Write-Host "$cmd`: 未安装" }
}
Write-Host ""
Write-Host "--- CLI 工具 ---"
foreach ($cmd in @("gh", "jq", "rg", "ffmpeg", "whisper", "clawhub", "claude", "codex", "himalaya")) {
    $c = Get-Command $cmd -ErrorAction SilentlyContinue
    if ($c) { Write-Host "$cmd`: 已安装" } else { Write-Host "$cmd`: 未安装" }
}

Tools already installed are skipped directly, and only the missing parts are installed.

Step 3: Detect Network Environment

Network connectivity must be confirmed before installing tools. Users in China often time out when accessing overseas sources (GitHub, npm, Homebrew, PyPI),so mirrors must be configured first。

# macOS — 网络检测（超时 3 秒判定可达性）
echo "=== 网络连通性检测 ==="
NEED_MIRROR=false
for url in "https://github.com" "https://raw.githubusercontent.com" "https://registry.npmjs.org" "https://pypi.org"; do
  if curl -sI --connect-timeout 3 "$url" > /dev/null 2>&1; then
    echo "可达: $url"
  else
    echo "不可达: $url"
    NEED_MIRROR=true
  fi
done
if [ "$NEED_MIRROR" = true ]; then
  echo ">>> 检测到境外源不可达，必须先配置镜像再继续安装 <<<"
fi

# Windows — 网络检测（先切 UTF-8 防乱码）
chcp 65001 >nul
Write-Host "=== 网络连通性检测 ==="
@("https://github.com", "https://raw.githubusercontent.com", "https://registry.npmjs.org", "https://pypi.org") | ForEach-Object {
    try {
        $sw = [System.Diagnostics.Stopwatch]::StartNew()
        Invoke-WebRequest -Uri $_ -TimeoutSec 3 -UseBasicParsing | Out-Null
        $sw.Stop()
        if ($sw.ElapsedMilliseconds -gt 2000) {
            "慢速 ($($sw.ElapsedMilliseconds)ms): $_ — 建议配置镜像"
        } else {
            "可达 ($($sw.ElapsedMilliseconds)ms): $_"
        }
    } catch { "不可达: $_ — 必须配置镜像" }
}

Determination rules:

  • Any sourceunreachable → mirrors must be configured first (see the platform manual "Layer 0: Network Environment Configuration")
  • Any sourceresponding in more than 2 seconds → configuring mirrors is strongly recommended
  • All reachable and speed normal → install directly

Step 4: Detect the Prerequisite Dependency Chain

Before installing any tool, along the dependency chainfrom the bottom updetect, and fill in any missing ones first:

第 0 层 网络环境   镜像源 / 代理（国内用户必须优先配置）
  ↓
第 1 层 包管理器   brew(macOS) / scoop(Windows)
  ↓
第 2 层 基础运行时  node+npm / python3+pip3 / go / uv
  ↓
第 3 层 目标 CLI   gh / ffmpeg / clawhub / whisper / ...
  ↓
第 4 层 环境变量   OPENAI_API_KEY / GEMINI_API_KEY / ...

Step 5: Load the Platform Installation Manual and Perform the Installation

Read the corresponding manual according to the current platform:

  • macOS → read {baseDir}/references/install-macos.md
  • Windows → read {baseDir}/references/install-windows.md

Find the section for the target tool in the manual, and execute the installation commands.

Step 6: Post-Installation Verification

<工具名> --version  # 或等效验证命令

Verification failed → troubleshoot the error and retry (refer to the "Common Troubleshooting" section at the end of the manual). Verification succeeded → inform the user of the installation result.

Steps requiring user interaction

The following operations the large modelcannot fully automate, and the user must be informed in advance:

  • macOS installing Xcode CLT: first use sudo -n true to detect whether sudo is available without a password.When sudo is availableuse softwareupdate for non-interactive installation (the Agent completes it fully automatically);When sudo is not availableoutput the complete operating instructions for the user to execute in their own terminal. See Layer 1 of install-macos.md
  • macOS .pkg downgrade installation: sudo installer -pkg Requires passwordless sudo. When sudo is unavailable, output step-by-step instructions for the curl + sudo installer so the user can copy and paste them to execute
  • Before installing Scoop on Windows 10, the PowerShell execution policy may need to be changed
  • Some API Keys require the user to register on the service provider's website to obtain them

User Operation Guidelines [MANDATORY]

When the Agent cannot automatically complete an installation step,forbiddento output vague instructions (such as "please visit the official website to download and install").mustoutput complete instructions that a novice user can directly follow:

  1. Explain the reason in one sentence — why user action is needed (such as "the current terminal does not have administrator privileges")
  2. Numbered steps — each step does only one thing, with clear actions
  3. Wrap commands in code blocks — the user can copy and paste them directly into their own terminal
  4. Complete URL / complete command — do not use "please go to the official website"; directly provide curl -LO "https://..." and other executable commands
  5. Explain password input behavior — novice users do not know that when entering a password for sudo, the screen does not display characters; this must be explained
  6. Explain the expected output — let the user know whether the operation succeeded (such as "it should output v22.12.0")
  7. Specify how to reply — "when finished, please reply 'installed'"

For detailed templates and examples, see the "User Manual Operation Guidelines" section in Layer 1 of install-macos.md.

Package Manager Selection Decision Tree [MANDATORY]

When installing a Layer 1 package manager,mustchoose according to the following decision tree; do not mix them arbitrarily:

macOS Decision Tree

1. command -v brew → 存在？ → 直接使用 Homebrew
2. 不存在 → 安装 Homebrew（见手册第 1 层）
3. Homebrew 安装失败（网络超时等）→ 使用降级方案：
   - 基础运行时（node/python/go）→ 从官网下载 .pkg 安装包直接安装（见手册「降级方案」章节）
   - 其他 CLI 工具 → 暂无法安装，告知用户需先解决网络问题或手动安装 Homebrew

Windows Decision Tree

1. 检测已有包管理器（按优先级）：
   a. Get-Command scoop  → 存在？ → 使用 Scoop
   b. Get-Command winget → 存在？ → 使用 winget
   c. Get-Command choco  → 存在？ → 使用 Chocolatey
2. 全部不存在 → 安装 Scoop（首选，无需管理员权限）
3. Scoop 安装失败（网络超时）→ 降级方案：
   a. 尝试 Scoop 国内镜像安装（见手册第 1 层）
   b. 检测 winget 是否可用（Windows 11 预装）→ 用 winget
   c. 基础运行时（node/python/go）→ 从官网下载 .msi 安装包直接安装（见手册「降级方案」章节）
   d. 如果用户有管理员权限 → 尝试 Chocolatey

Principle: use whatever is detected; do not install a new package manager on a system that already has one.

Cross-Platform Tool Name Differences [Important]

The following tools have different command names on macOS and Windows; pay attention when detecting:

Tool macOS Command Windows Command Description
Python python3 python On Windows, python3 usually does not exist
pip pip3 pip Consistent with the Python command
curl curl curl.exe In Windows PowerShell, curl is an alias for Invoke-WebRequest alias of

Skills That Do Not Require Installation

The following skills do not depend on external CLI tools and do not require an installation process:

Skill Description
canvas Built-in feature, displays HTML content on the connected OpenClaw node
healthcheck Built-in feature, host security hardening and risk configuration
skill-creator Built-in feature, create or update AgentSkill
weather Only depends on curl, preinstalled on both macOS/Windows
openai-whisper-api Only depends on curl(preinstalled on macOS / preinstalled on Windows curl.exe) and also requires the OPENAI_API_KEY environment variable
voice-call Must be enabled through the openclaw.json configuration plugins.entries.voice-call.enabled: true , no external tools need to be installed

Special Dependency Notes

  • coding-agent: supports anyBins mode; installing any oneof claude / codex / opencode / pi is sufficient; there is no need to install all of them
  • openai-whisper: depends on both python3+pip3 and ffmpeg two runtimes; both need to be detected and installed during setup
  • session-logs: depends on jq and rg(ripgrep); both need to be installed

Base Runtime Lookup Table

When a tool requires a prerequisite runtime, check this table to confirm how to install the runtime.

Runtime macOS (Homebrew) macOS (fallback: direct .pkg install) Windows (Scoop) Windows (winget) Windows (fallback: official website installer)
node+npm brew install node Download the .pkg from https://nodejs.org/ Download .pkg scoop install nodejs winget install OpenJS.NodeJS.LTS Download the .msi from https://nodejs.org/ Download .msi
python3+pip3 brew install python Download the .pkg from https://www.python.org/ Download .pkg scoop install python winget install Python.Python.3.12 Download the .exe from https://www.python.org/ Download .exe
go brew install go Download the .pkg from https://go.dev/dl/ Download .pkg scoop install go winget install GoLang.Go Download the .msi from https://go.dev/dl/ Download .msi
uv brew install uv curl -LsSf https://astral.sh/uv/install.sh | sh scoop install uv winget install astral-sh.uv irm https://astral.sh/uv/install.ps1 | iex

Package Manager Lookup Table

Prerequisite for installing runtimes and CLIs — how to install the package manager itself.

Package Manager Platform Detection Installation (preferred in China) Installation (overseas/direct connection)
Homebrew macOS command -v brew First install Xcode CLT (see the Layer 1 decision flow in the manual), then /bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)" First install Xcode CLT (see the Layer 1 decision flow in the manual), then /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Scoop Windows Get-Command scoop irm https://gitee.com/glsnames/scoop-installer/raw/master/bin/install.ps1 | iex Set-ExecutionPolicy RemoteSigned -Scope CurrentUser; irm get.scoop.sh | iex
winget Windows 11 Get-Command winget Preinstalled; on Windows 10, install "App Installer" from the Microsoft Store Same as left

Notes

  • Skills marked with platform darwin are available only on macOS (apple-notes, apple-reminders, model-usage, peekaboo, camsnap)
  • tmux is not available on Windows (if terminal multiplexing is needed, it can be installed inside WSL)
  • Environment variable dependencies (API keys) cannot be installed via commands; guide the user to register on the provider's website to obtain them
  • Users in China must configure a mirror source before installation, otherwise downloads for tools such as Homebrew/npm/pip/Go are highly likely to time out and fail
  • For detailed parameters of installation commands, alternatives, and troubleshooting of common issues, see the reference files for each platform
  • macOS 14+ (Sonoma) no longer comes with Python 3 preinstalled,python3 may be a stub; use python3 -c "import sys" to verify its authenticity
  • On Windows, python and pip are the standard command names; do not use python3/pip3