🛠 AI 工具官方安装命令速查
各工具的官方推荐安装方式汇总，不经过第三方脚本
📦 Claude Code
前提：Node.js 18+
npm install -g @anthropic-ai/claude-code
📖 官方文档：docs.anthropic.com/en/docs/claude-code
🚀 Codex CLI
前提：Node.js 18+
npm install -g @openai/codex
📦 GitHub：github.com/openai/codex
🔓 OpenCode CLI
前提：Node.js 18+
npm install -g @opencode-ai/cli
🌐 官网：opencode.ai
🧠 Hermes Agent
前提：Python 3.10+
pip install hermes-agent
📖 官方文档：github.com/NousResearch/hermes-agent
🖥 系统兼容矩阵
以下为各工具官方声明支持的系统环境：
| 系统/环境 | 官方支持 | 状态 | 说明 |
|---|---|---|---|
| macOS 13+ | Node.js / Homebrew | ✅ 完全支持 | M1/M2/M3 原生支持 |
| macOS < 12 | 需手动升级 Node.js | ⚠ 部分支持 | Node.js 18+ 可能需额外配置 |
| WSL2 (Ubuntu) | Node.js / npm | ✅ 完全支持 | Windows 用户首选方案 |
| WSL1 | 官方建议升级 WSL2 | ⚠ 不推荐 | 建议升级到 WSL2 |
| Ubuntu 20.04+ | Node.js / npm | ✅ 完全支持 | 最推荐的 Linux 发行版 |
| Ubuntu < 20.04 | 需手动安装 Node.js 18+ | ⚠ 部分支持 | 建议升级系统 |
| Debian 11+ | Node.js / npm | ✅ 完全支持 | |
| Fedora / RHEL / CentOS / Rocky / Alma | Node.js / npm | ⚠ 部分支持 | 通过 dnf 安装 Node.js |
| Arch / Manjaro / EndeavourOS | Node.js / npm | ⚠ 部分支持 | 通过 pacman 安装 Node.js |
| Windows 原生（cmd/PowerShell） | 不支持 | ❌ 不支持 | 需安装 WSL2 |
| 其他 Linux（openSUSE, Alpine...） | 需自行编译 Node.js | ❌ 不推荐 | 缺少官方包支持 |
| 非 x86_64/ARM64 | 取决于工具 | ❌ 不推荐 | 多数 npm 包仅支持主流架构 |
🩺 FAQ
Q1: 装完就能直接用吗？
工具装好之后，还需要配置 API Key 才能调用 AI。详见：Claude Code 配置与认证、Hermes Agent 配置。
Q2: Windows 用户怎么用？
原生 Windows 不支持这些 CLI 工具。请先安装 WSL2（Windows Subsystem for Linux），然后在 WSL 的 Ubuntu 终端中运行安装命令。安装 WSL2 只需一条命令：wsl --install（管理员 PowerShell）。
Q3: npm install -g 需要 sudo 吗？
取决于你的 Node.js 安装方式。如果用系统包管理器（如 apt）安装的 Node.js，全局安装通常需要 sudo。推荐使用 nvm 管理 Node.js 版本，无需 sudo。
Q4: 如何验证安装成功？
安装后运行对应的版本检查命令：claude --version、codex --version、opencode --version、hermes-agent --version。能输出版本号即表示安装成功。
Q5: Ubuntu 20.04 以下能用吗？
可能可以，但需要手动安装 Node.js 18+。Ubuntu 20.04 以下自带的 Node.js 版本太旧，建议升级系统或换用更新的版本。
Q6: 国内网络下载 npm 包很慢怎么办？
设置 npm 镜像：npm config set registry https://registry.npmmirror.com，然后再执行安装命令。对于 pip（Hermes Agent），可使用 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple hermes-agent。
Q7: 安装失败怎么办？
先检查 Node.js / Python 版本是否满足前提条件，然后确认网络能访问 npm registry / PyPI。国内用户可能需要配置镜像或科学上网。详见 常见问题与故障排除。
⚠ 常见安装问题与避坑
| 坑 | 正确做法 |
|---|---|
| Windows 上直接跑，一堆报错 | 必须先装 WSL2，在 Ubuntu 终端里运行 npm/pip 安装命令 |
| 国内的网络下载 npm 包很慢 / 卡住 | 设置 npm 镜像：npm config set registry https://registry.npmmirror.com，再重新安装 |
| 全局安装提示权限不足（EACCES） | 使用 nvm 管理 Node.js 避免 sudo，或使用 sudo npm install -g |
| 装了 Claude Code 但 claude 命令找不到 | 关闭终端重开，或运行 source ~/.bashrc（Linux）/ source ~/.zshrc（macOS） |
| npm 报 SSL 证书错误 | 确认系统时间正确，老系统可能需 apt-get install ca-certificates |
| 公司网络有防火墙拦截 | 检查是否允许访问 registry.npmjs.org 和 pypi.org，或联系 IT 放行 |
标签：#AI #教程 #安装命令 #ClaudeCode #Codex #OpenCode #HermesAgent