\r \r

Env Doctor — OpenClaw Skill 全链路环境诊断与安装\r

\r

强制规范 [MANDATORY]\r

\r 所有 CLI、工具、运行时、包管理器的安装操作必须遵循以下流程，不可跳过任何步骤：\r \r

步骤 1：检测平台与架构\r

\r

# macOS / Linux\r
OS="$(uname -s)"   # Darwin / Linux\r
ARCH="$(uname -m)" # arm64 / x86_64\r
echo "平台: $OS, 架构: $ARCH"\r
```\r
\r
```powershell\r
# Windows (PowerShell)\r
$OS = "Windows"\r
$ARCH = if ([Environment]::Is64BitOperatingSystem) { "x64" } else { "x86" }\r
$WinVer = [System.Environment]::OSVersion.Version\r
Write-Host "平台: $OS, 架构: $ARCH, Windows 版本: $($WinVer.Major).$($WinVer.Minor).$($WinVer.Build)"\r
```\r
\r
**平台支持说明**:\r
- **macOS (Darwin)** — 完整支持，参考 `install-macos.md`\r
- **Windows** — 完整支持，参考 `install-windows.md`\r
- **Linux** — 当前不提供安装手册。如检测到 Linux，告知用户此 skill 暂不支持 Linux，需自行按发行版的包管理器安装所需工具\r
\r
**macOS 架构标记**：如果 `ARCH=arm64`（Apple Silicon），后续安装 Homebrew 时**必须**执行 `eval "$(/opt/homebrew/bin/brew shellenv)"`，否则所有 brew 安装的工具都无法找到。\r
\r
### 步骤 2：全量环境快照\r
\r
在安装任何东西之前，**先一次性探测系统已有的全部工具和版本**，避免重复安装和误判。\r
\r
```bash\r
# macOS — 全量环境快照\r
echo "=== 系统环境快照 ==="\r
echo "--- 平台 ---"\r
echo "OS: $(uname -s), ARCH: $(uname -m), macOS: $(sw_vers -productVersion 2>/dev/null || echo 'N/A')"\r
echo ""\r
echo "--- Xcode CLT ---"\r
xcode-select -p >/dev/null 2>&1 && echo "xcode-select: 已安装 ($(xcode-select -p))" || echo "xcode-select: 未安装"\r
echo ""\r
echo "--- sudo 免密可用性 ---"\r
sudo -n true 2>/dev/null && echo "SUDO_OK=true" || echo "SUDO_OK=false (需使用非 sudo 安装方式)"\r
echo ""\r
echo "--- 包管理器 ---"\r
command -v brew >/dev/null 2>&1 && echo "brew: $(brew --version 2>&1 | head -1)" || echo "brew: 未安装"\r
echo ""\r
echo "--- 基础运行时 ---"\r
for cmd in node npm python3 pip3 go uv; do\r
  if command -v "$cmd" >/dev/null 2>&1; then\r
    ver="$("$cmd" --version 2>&1 | head -1)"\r
    echo "$cmd: $ver"\r
  else\r
    echo "$cmd: 未安装"\r
  fi\r
done\r
echo ""\r
echo "--- python3 真实性检测 ---"\r
python3 -c "import sys; print('python3 可用:', sys.version)" 2>/dev/null || echo "python3: 不可用或为 Xcode CLT stub"\r
echo ""\r
echo "--- CLI 工具 ---"\r
for cmd in curl git gh jq rg ffmpeg tmux whisper memo remindctl clawhub claude codex himalaya uv; do\r
  if command -v "$cmd" >/dev/null 2>&1; then\r
    echo "$cmd: 已安装"\r
  else\r
    echo "$cmd: 未安装"\r
  fi\r
done\r
```\r
\r
```powershell\r
# Windows — 全量环境快照（先切 UTF-8 防乱码）\r
chcp 65001 >nul\r
Write-Host "=== 系统环境快照 ==="\r
Write-Host "--- 平台 ---"\r
$ver = [System.Environment]::OSVersion.Version\r
Write-Host "OS: Windows, Build: $($ver.Major).$($ver.Minor).$($ver.Build), Arch: $(if ([Environment]::Is64BitOperatingSystem) {'x64'} else {'x86'})"\r
Write-Host ""\r
Write-Host "--- Shell 环境 ---"\r
Write-Host "当前 Shell: $($PSVersionTable.PSVersion) (PowerShell)"\r
$policy = Get-ExecutionPolicy -Scope CurrentUser\r
Write-Host "执行策略 (CurrentUser): $policy"\r
Write-Host ""\r
Write-Host "--- 包管理器 ---"\r
foreach ($pm in @("scoop", "winget", "choco")) {\r
    $c = Get-Command $pm -ErrorAction SilentlyContinue\r
    if ($c) { Write-Host "$pm`: 已安装" } else { Write-Host "$pm`: 未安装" }\r
}\r
Write-Host ""\r
Write-Host "--- 基础运行时 ---"\r
foreach ($cmd in @("node", "npm", "python", "pip", "go", "uv", "curl.exe", "git")) {\r
    $c = Get-Command $cmd -ErrorAction SilentlyContinue\r
    if ($c) {\r
        try { $v = & $cmd --version 2>&1 | Select-Object -First 1; Write-Host "$cmd`: $v" }\r
        catch { Write-Host "$cmd`: 已安装 (版本获取失败)" }\r
    } else { Write-Host "$cmd`: 未安装" }\r
}\r
Write-Host ""\r
Write-Host "--- CLI 工具 ---"\r
foreach ($cmd in @("gh", "jq", "rg", "ffmpeg", "whisper", "clawhub", "claude", "codex", "himalaya")) {\r
    $c = Get-Command $cmd -ErrorAction SilentlyContinue\r
    if ($c) { Write-Host "$cmd`: 已安装" } else { Write-Host "$cmd`: 未安装" }\r
}\r
```\r
\r
**已安装的工具直接跳过**，仅安装缺失的部分。\r
\r
### 步骤 3：检测网络环境\r
\r
安装工具前必须确认网络连通性。国内用户访问境外源（GitHub、npm、Homebrew、PyPI）经常超时，**必须优先配置镜像**。\r
\r
```bash\r
# macOS — 网络检测（超时 3 秒判定可达性）\r
echo "=== 网络连通性检测 ==="\r
NEED_MIRROR=false\r
for url in "https://github.com" "https://raw.githubusercontent.com" "https://registry.npmjs.org" "https://pypi.org"; do\r
  if curl -sI --connect-timeout 3 "$url" > /dev/null 2>&1; then\r
    echo "可达: $url"\r
  else\r
    echo "不可达: $url"\r
    NEED_MIRROR=true\r
  fi\r
done\r
if [ "$NEED_MIRROR" = true ]; then\r
  echo ">>> 检测到境外源不可达，必须先配置镜像再继续安装 \x3C\x3C\x3C"\r
fi\r
```\r
\r
```powershell\r
# Windows — 网络检测（先切 UTF-8 防乱码）\r
chcp 65001 >nul\r
Write-Host "=== 网络连通性检测 ==="\r
@("https://github.com", "https://raw.githubusercontent.com", "https://registry.npmjs.org", "https://pypi.org") | ForEach-Object {\r
    try {\r
        $sw = [System.Diagnostics.Stopwatch]::StartNew()\r
        Invoke-WebRequest -Uri $_ -TimeoutSec 3 -UseBasicParsing | Out-Null\r
        $sw.Stop()\r
        if ($sw.ElapsedMilliseconds -gt 2000) {\r
            "慢速 ($($sw.ElapsedMilliseconds)ms): $_ — 建议配置镜像"\r
        } else {\r
            "可达 ($($sw.ElapsedMilliseconds)ms): $_"\r
        }\r
    } catch { "不可达: $_ — 必须配置镜像" }\r
}\r
```\r
\r
**判定规则**:\r
- 任一源**不可达** → 必须先配置镜像（见平台手册「第 0 层：网络环境配置」）\r
- 任一源**响应超过 2 秒** → 强烈建议配置镜像\r
- 全部可达且速度正常 → 可直接安装\r
\r
### 步骤 4：检测前置依赖链\r
\r
安装任何工具前，沿依赖链**自底向上**检测，缺失的先补上：\r
\r
```\r
第 0 层 网络环境   镜像源 / 代理（国内用户必须优先配置）\r
  ↓\r
第 1 层 包管理器   brew(macOS) / scoop(Windows)\r
  ↓\r
第 2 层 基础运行时  node+npm / python3+pip3 / go / uv\r
  ↓\r
第 3 层 目标 CLI   gh / ffmpeg / clawhub / whisper / ...\r
  ↓\r
第 4 层 环境变量   OPENAI_API_KEY / GEMINI_API_KEY / ...\r
```\r
\r
### 步骤 5：加载平台安装手册执行安装\r
\r
根据当前平台读取对应手册：\r
\r
- macOS → 阅读 `{baseDir}/references/install-macos.md`\r
- Windows → 阅读 `{baseDir}/references/install-windows.md`\r
\r
在手册中查找目标工具的章节，按命令执行安装。\r
\r
### 步骤 6：安装后验证\r
\r
```bash\r
\x3C工具名> --version  # 或等效验证命令\r
```\r
\r
验证失败 → 排查错误并重试（参考手册末尾「常见问题排查」章节）。验证成功 → 告知用户安装结果。\r
\r
### 需用户交互的步骤\r
\r
以下操作大模型**无法完全自动化**，必须提前告知用户：\r
\r
- macOS 安装 Xcode CLT: 先用 `sudo -n true` 检测 sudo 是否免密可用。**sudo 可用时**使用 `softwareupdate` 非交互安装（Agent 全自动完成）；**sudo 不可用时**输出完整操作指引让用户在自己终端执行。详见 install-macos.md 第 1 层\r
- macOS .pkg 降级安装: `sudo installer -pkg` 需要 sudo 免密。sudo 不可用时输出 curl + sudo installer 的分步指引让用户复制粘贴执行\r
- Windows 10 安装 Scoop 前可能需修改 PowerShell 执行策略\r
- 部分 API Key 需要用户到服务商网站注册获取\r
\r
### 用户操作指引规范 [MANDATORY]\r
\r
当 Agent 无法自动完成某个安装步骤时，**禁止**输出模糊的指引（如"请访问官网下载安装"）。**必须**输出小白用户可直接操作的完整指引：\r
\r
1. **一句话说清原因** — 为什么需要用户操作（如"当前终端没有管理员权限"）\r
2. **编号步骤** — 每步只做一件事，动作明确\r
3. **命令用代码块包裹** — 用户可直接复制粘贴到自己的终端\r
4. **完整 URL / 完整命令** — 不要用"请去官网"，直接给 `curl -LO "https://..."` 等可执行命令\r
5. **解释密码输入行为** — 小白用户不知道 sudo 输密码时屏幕不显示字符，必须说明\r
6. **说明预期输出** — 让用户知道操作是否成功（如"应该输出 v22.12.0"）\r
7. **明确回复方式** — "完成后请回复'已安装'"\r
\r
详细模板和示例见 install-macos.md 第 1 层「用户手动操作指引规范」章节。\r
\r
---\r
\r
## 包管理器选择决策树 [MANDATORY]\r
\r
安装第 1 层包管理器时，**必须**按以下决策树选择，不可随意混用：\r
\r
### macOS 决策树\r
\r
```\r
1. command -v brew → 存在？ → 直接使用 Homebrew\r
2. 不存在 → 安装 Homebrew（见手册第 1 层）\r
3. Homebrew 安装失败（网络超时等）→ 使用降级方案：\r
   - 基础运行时（node/python/go）→ 从官网下载 .pkg 安装包直接安装（见手册「降级方案」章节）\r
   - 其他 CLI 工具 → 暂无法安装，告知用户需先解决网络问题或手动安装 Homebrew\r
```\r
\r
### Windows 决策树\r
\r
```\r
1. 检测已有包管理器（按优先级）：\r
   a. Get-Command scoop  → 存在？ → 使用 Scoop\r
   b. Get-Command winget → 存在？ → 使用 winget\r
   c. Get-Command choco  → 存在？ → 使用 Chocolatey\r
2. 全部不存在 → 安装 Scoop（首选，无需管理员权限）\r
3. Scoop 安装失败（网络超时）→ 降级方案：\r
   a. 尝试 Scoop 国内镜像安装（见手册第 1 层）\r
   b. 检测 winget 是否可用（Windows 11 预装）→ 用 winget\r
   c. 基础运行时（node/python/go）→ 从官网下载 .msi 安装包直接安装（见手册「降级方案」章节）\r
   d. 如果用户有管理员权限 → 尝试 Chocolatey\r
```\r
\r
**原则：检测到什么就用什么，不要在已有包管理器的系统上安装新的包管理器。**\r
\r
---\r
\r
## 跨平台工具名称差异 [重要]\r
\r
以下工具在 macOS 和 Windows 上的命令名称不同，检测时需注意：\r
\r
| 工具 | macOS 命令 | Windows 命令 | 说明 |\r
|------|-----------|-------------|------|\r
| Python | `python3` | `python` | Windows 上 `python3` 通常不存在 |\r
| pip | `pip3` | `pip` | 与 Python 命令保持一致 |\r
| curl | `curl` | `curl.exe` | Windows PowerShell 中 `curl` 是 `Invoke-WebRequest` 的别名 |\r
\r
---\r
\r
## 无需安装的 Skill\r
\r
以下 skill 不依赖外部 CLI 工具，无需执行安装流程：\r
\r
| Skill | 说明 |\r
|-------|------|\r
| canvas | 内置功能，在连接的 OpenClaw 节点上显示 HTML 内容 |\r
| healthcheck | 内置功能，主机安全加固和风险配置 |\r
| qclaw-skill-creator | 内置功能，创建或更新 AgentSkill |\r
| weather | 仅依赖 `curl`，macOS/Windows 均预装 |\r
| openai-whisper-api | 仅依赖 `curl`（macOS 预装 / Windows 预装 `curl.exe`），另需 `OPENAI_API_KEY` 环境变量 |\r
| voice-call | 需通过 `openclaw.json` 配置 `plugins.entries.voice-call.enabled: true` 启用，无需安装外部工具 |\r
\r
## 特殊依赖说明\r
\r
- **coding-agent**: 支持 `anyBins` 模式，安装 claude / codex / opencode / pi **任意一个**即可，无需全部安装\r
- **openai-whisper**: 同时依赖 `python3+pip3` **和** `ffmpeg` 两个运行时，安装时两者都需要检测和补齐\r
- **session-logs**: 依赖 `jq` 和 `rg`（ripgrep），两者都需要安装\r
\r
---\r
\r
## 基础运行时查询表\r
\r
当工具需要前置运行时时，查此表确认运行时安装方式。\r
\r
| 运行时 | macOS (Homebrew) | macOS (降级: .pkg 直装) | Windows (Scoop) | Windows (winget) | Windows (降级: 官网安装包) |\r
|--------|-----------------|------------------------|-----------------|-----------------|-------------------------|\r
| node+npm | `brew install node` | 从 https://nodejs.org/ 下载 .pkg | `scoop install nodejs` | `winget install OpenJS.NodeJS.LTS` | 从 https://nodejs.org/ 下载 .msi |\r
| python3+pip3 | `brew install python` | 从 https://mirrors.huaweicloud.com/python/3.12.8/ 下载 .pkg | `scoop install python` | `winget install Python.Python.3.12` | 从 https://mirrors.huaweicloud.com/python/3.12.8/ 下载 .exe |\r
| go | `brew install go` | 从 https://go.dev/dl/ 下载 .pkg | `scoop install go` | `winget install GoLang.Go` | 从 https://go.dev/dl/ 下载 .msi |\r
| 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` |\r
\r
## 包管理器查询表\r
\r
安装运行时和 CLI 的前提——包管理器本身的安装方式。\r
\r
| 包管理器 | 平台 | 检测 | 安装（国内首选） | 安装（海外/直连） |\r
|---------|------|------|----------------|-----------------|\r
| Homebrew | macOS | `command -v brew` | 先安装 Xcode CLT（见手册第 1 层决策流程），再 `/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)"` | 先安装 Xcode CLT（见手册第 1 层决策流程），再 `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` |\r
| 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` |\r
| winget | Windows 11 | `Get-Command winget` | 预装；Windows 10 从 Microsoft Store 安装 "App Installer" | 同左 |\r
\r
## 注意事项\r
\r
- 平台标记为 `darwin` 的 skill 仅 macOS 可用（apple-notes、apple-reminders、model-usage、peekaboo、camsnap）\r
- `tmux` 在 Windows 上不可用（如需终端复用，可在 WSL 内安装）\r
- 环境变量类依赖（API Key）无法通过命令安装，需引导用户到服务商网站注册获取\r
- **国内用户安装前务必先配置镜像源**，否则 Homebrew/npm/pip/Go 等工具下载极易超时失败\r
- 安装命令的详细参数、备选方案和常见问题排查见各平台 reference 文件\r
- macOS 14+ (Sonoma) 不再预装 Python 3，`python3` 可能是一个 stub，需用 `python3 -c "import sys"` 验证真实性\r
- Windows 上 `python` 和 `pip` 是标准命令名，不要使用 `python3`/`pip3`\r