Skip to main content

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

强制规范 [MANDATORY]

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

步骤 1:检测平台与架构

平台支持说明:
  • macOS (Darwin) — 完整支持,参考 install-macos.md
  • Windows — 完整支持,参考 install-windows.md
  • Linux — 当前不提供安装手册。如检测到 Linux,告知用户此 skill 暂不支持 Linux,需自行按发行版的包管理器安装所需工具
macOS 架构标记:如果 ARCH=arm64(Apple Silicon),后续安装 Homebrew 时必须执行 eval "$(/opt/homebrew/bin/brew shellenv)",否则所有 brew 安装的工具都无法找到。

步骤 2:全量环境快照

在安装任何东西之前,先一次性探测系统已有的全部工具和版本,避免重复安装和误判。
已安装的工具直接跳过,仅安装缺失的部分。

步骤 3:检测网络环境

安装工具前必须确认网络连通性。国内用户访问境外源(GitHub、npm、Homebrew、PyPI)经常超时,必须优先配置镜像
判定规则:
  • 任一源不可达 → 必须先配置镜像(见平台手册「第 0 层:网络环境配置」)
  • 任一源响应超过 2 秒 → 强烈建议配置镜像
  • 全部可达且速度正常 → 可直接安装

步骤 4:检测前置依赖链

安装任何工具前,沿依赖链自底向上检测,缺失的先补上:

步骤 5:加载平台安装手册执行安装

根据当前平台读取对应手册:
  • macOS → 阅读 {baseDir}/references/install-macos.md
  • Windows → 阅读 {baseDir}/references/install-windows.md
在手册中查找目标工具的章节,按命令执行安装。

步骤 6:安装后验证

验证失败 → 排查错误并重试(参考手册末尾「常见问题排查」章节)。验证成功 → 告知用户安装结果。

需用户交互的步骤

以下操作大模型无法完全自动化,必须提前告知用户:
  • macOS 安装 Xcode CLT: 先用 sudo -n true 检测 sudo 是否免密可用。sudo 可用时使用 softwareupdate 非交互安装(Agent 全自动完成);sudo 不可用时输出完整操作指引让用户在自己终端执行。详见 install-macos.md 第 1 层
  • macOS .pkg 降级安装: sudo installer -pkg 需要 sudo 免密。sudo 不可用时输出 curl + sudo installer 的分步指引让用户复制粘贴执行
  • Windows 10 安装 Scoop 前可能需修改 PowerShell 执行策略
  • 部分 API Key 需要用户到服务商网站注册获取

用户操作指引规范 [MANDATORY]

当 Agent 无法自动完成某个安装步骤时,禁止输出模糊的指引(如”请访问官网下载安装”)。必须输出小白用户可直接操作的完整指引:
  1. 一句话说清原因 — 为什么需要用户操作(如”当前终端没有管理员权限”)
  2. 编号步骤 — 每步只做一件事,动作明确
  3. 命令用代码块包裹 — 用户可直接复制粘贴到自己的终端
  4. 完整 URL / 完整命令 — 不要用”请去官网”,直接给 curl -LO "https://..." 等可执行命令
  5. 解释密码输入行为 — 小白用户不知道 sudo 输密码时屏幕不显示字符,必须说明
  6. 说明预期输出 — 让用户知道操作是否成功(如”应该输出 v22.12.0”)
  7. 明确回复方式 — “完成后请回复’已安装’”
详细模板和示例见 install-macos.md 第 1 层「用户手动操作指引规范」章节。

包管理器选择决策树 [MANDATORY]

安装第 1 层包管理器时,必须按以下决策树选择,不可随意混用:

macOS 决策树

Windows 决策树

原则:检测到什么就用什么,不要在已有包管理器的系统上安装新的包管理器。

跨平台工具名称差异 [重要]

以下工具在 macOS 和 Windows 上的命令名称不同,检测时需注意:

无需安装的 Skill

以下 skill 不依赖外部 CLI 工具,无需执行安装流程:

特殊依赖说明

  • coding-agent: 支持 anyBins 模式,安装 claude / codex / opencode / pi 任意一个即可,无需全部安装
  • openai-whisper: 同时依赖 python3+pip3 ffmpeg 两个运行时,安装时两者都需要检测和补齐
  • session-logs: 依赖 jqrg(ripgrep),两者都需要安装

基础运行时查询表

当工具需要前置运行时时,查此表确认运行时安装方式。

包管理器查询表

安装运行时和 CLI 的前提——包管理器本身的安装方式。

注意事项

  • 平台标记为 darwin 的 skill 仅 macOS 可用(apple-notes、apple-reminders、model-usage、peekaboo、camsnap)
  • tmux 在 Windows 上不可用(如需终端复用,可在 WSL 内安装)
  • 环境变量类依赖(API Key)无法通过命令安装,需引导用户到服务商网站注册获取
  • 国内用户安装前务必先配置镜像源,否则 Homebrew/npm/pip/Go 等工具下载极易超时失败
  • 安装命令的详细参数、备选方案和常见问题排查见各平台 reference 文件
  • macOS 14+ (Sonoma) 不再预装 Python 3,python3 可能是一个 stub,需用 python3 -c "import sys" 验证真实性
  • Windows 上 pythonpip 是标准命令名,不要使用 python3/pip3