★ FEATURED ARTICLE 1. 为什么“安装、查版本、升级”这三件事值得单独拎出来讲AI Agent CLI 这类工具2026 年已经多到让人挑花眼。我自己的笔记本上前后装过十几款从最早的实验性脚本到现在的成熟命令行工具踩过的坑基本都集中在三个动作上装不上、查不到版本、升不了级。听起来简单但真正在终端里敲命令的时候问题往往出在环境变量、包管理器冲突、Node 版本不匹配这些地方。这篇内容就是把我实际用过的 9 款主流 AI Agent CLI 拉出来逐个过一遍安装、版本查询和升级命令。适合两类人看一类是刚接触 AI Agent、想找个趁手命令行工具上手的新手另一类是老玩家手里已经有好几款但升级的时候总出岔子想找一份靠谱的对照表。先说清楚一个前提AI Agent CLI 和普通 CLI 工具最大的区别在于它背后要连大模型服务所以安装完之后通常还需要配置 API Key 或者登录账号。但这一步不属于“安装”本身本文聚焦的是工具本体怎么装进系统、怎么确认装对了、怎么升到新版本。至于配置和实际使用那是装完之后的事。另外这 9 款工具我按安装方式分了三类npm 系、独立二进制系、Python 系。分类的原因很简单——安装方式决定了升级方式。npm 装的用 npm 升独立二进制装的要么重新下载要么用自带更新命令Python 装的用 pip 或 pipx 升。很多人升级失败就是因为用错了包管理器比如明明是 npm 全局装的却跑去 pip 里找当然找不到。提示下面所有命令默认在 macOS 或 Linux 的终端里执行。Windows 用户建议用 WSL2原生 PowerShell 也能跑但部分工具的安装脚本对 Windows 支持不完整遇到问题优先切 WSL。2. npm 系三款Claude CLI、Codex CLI、MiniMax Code CLInpm 系的共同点是npm install -g装全局npm list -g查版本npm update -g升级。但每款工具有自己的包名和细节差异下面逐个说。2.1 Claude CLI 的安装与版本确认Claude CLI 的 npm 包名是anthropic-ai/claude-code。安装命令npm install -g anthropic-ai/claude-code装完之后第一件事是确认版本claude --version如果这条命令报command not found九成是 npm 全局 bin 目录没进 PATH。用npm config get prefix看一下全局前缀然后把prefix/bin加到 PATH 里。macOS 上通常是/usr/local/bin或~/.npm-global/binLinux 上可能是/usr/bin或~/.local/bin。升级命令npm update -g anthropic-ai/claude-code这里有个坑npm update -g有时候不会把包升到最新大版本因为它受 semver 范围限制。想强制升到最新用npm install -g anthropic-ai/claude-codelatest我实测下来latest这种方式最稳不会出现“明明有新版本但 update 说已经是最新”的尴尬。2.2 Codex CLI 的安装路径与常见报错Codex CLI 的包名是openai/codex。安装npm install -g openai/codex版本查询codex --versionCodex CLI 有一个很典型的报错很多人第一次装完就遇到unable to locate the codex cli binary or required runtime components. check这个报错的意思是npm 包装上了但包里的二进制文件没找到或者运行时组件缺失。原因通常是 npm 安装过程中 postinstall 脚本没跑成功或者 Node 版本太低。解决办法分两步先确认 Node 版本在 18 以上node -v然后重装npm uninstall -g openai/codex npm install -g openai/codex --force--force会强制重跑安装脚本。如果还不行清一下 npm 缓存再装npm cache clean --force npm install -g openai/codex升级命令和 Claude CLI 一样npm install -g openai/codexlatest2.3 MiniMax Code CLI 的安装与升级MiniMax Code CLI 的 npm 包名是minimax/code-cli具体包名以官方文档为准这里按常见命名规则给出。安装npm install -g minimax/code-cli版本查询minimax --version或者有些版本用mmx --version具体看安装后 bin 里注册的命令名。用npm list -g --depth0可以列出所有全局包确认它到底装没装、装了什么版本npm list -g --depth0 | grep minimax升级npm install -g minimax/code-clilatestnpm 系三款的对照表工具安装命令版本查询升级命令Claude CLInpm i -g anthropic-ai/claude-codeclaude --versionnpm i -g anthropic-ai/claude-codelatestCodex CLInpm i -g openai/codexcodex --versionnpm i -g openai/codexlatestMiniMax Code CLInpm i -g minimax/code-climinimax --versionnpm i -g minimax/code-clilatest注意npm 全局安装需要写权限。如果报EACCES错误不要用sudo npm install -g那样会把包装到 root 目录下后续升级更麻烦。正确做法是配置 npm 的全局前缀到用户目录或者用 nvm 管理 Nodenvm 环境下全局包天然在用户目录里不会有权限问题。3. 独立二进制系Obsidian CLI 与通用二进制安装法独立二进制系的工具不走包管理器直接下载可执行文件放到 PATH 里。优点是干净、不依赖 Node 或 Python缺点是升级要手动或者靠工具自带的更新命令。3.1 Obsidian CLI 的安装包获取与放置Obsidian CLI 的安装包通常是一个压缩包解压后得到可执行文件。步骤从官方发布页下载对应平台的压缩包macOS 是.tar.gzLinux 是.tar.gzWindows 是.zip。解压tar -xzf obsidian-cli-*.tar.gz把可执行文件移到 PATH 目录sudo mv obsidian /usr/local/bin/给执行权限sudo chmod x /usr/local/bin/obsidian版本查询obsidian --version升级就是重复上面步骤下载新版覆盖旧版。有些独立二进制工具自带更新命令比如obsidian update但并不是所有版本都有。如果没有自带更新就手动下载覆盖。3.2 独立二进制工具的通用升级思路独立二进制工具的升级核心就一句话用新版可执行文件覆盖旧版。但覆盖之前要先确认旧版在哪which obsidian这条命令会告诉你可执行文件的完整路径。然后下载新版解压mv覆盖过去。覆盖完再--version确认。这里有个细节如果工具正在运行覆盖可能会失败文件被占用。先退出所有相关进程再覆盖。macOS 上可以用lsof | grep obsidian看有没有进程占用。另外独立二进制工具通常不依赖运行时环境所以不会出现“Node 版本不对”“Python 包冲突”这类问题。这是它最大的优势也是我推荐新手从独立二进制工具入手的原因——装起来省心。4. Python 系pipx 与 pip 的安装升级差异Python 系的 AI Agent CLI 有两种装法pip install和pipx install。两者的区别很大直接决定了升级命令和隔离性。4.1 pipx 安装的优势与命令pipx是专门用来装 Python CLI 工具的工具它会给每个工具创建独立的虚拟环境互不干扰。装 AI Agent CLI 强烈推荐用 pipx原因很简单不会污染系统 Python 环境也不会因为某个依赖版本冲突把别的工具搞坏。安装 pipx 本身python3 -m pip install --user pipx python3 -m pipx ensurepath然后用 pipx 装工具pipx install some-agent-cli版本查询some-agent-cli --version或者用 pipx 查pipx list升级pipx upgrade some-agent-cli升级所有 pipx 装的工具pipx upgrade-all4.2 pip 直接安装的升级陷阱如果用pip install直接装升级命令是pip install --upgrade some-agent-cli但这里有个大坑系统 Python 环境里装的东西升级时可能因为权限或依赖冲突失败。比如 macOS 自带的 Python 是系统管理的往里装包会报externally-managed-environment错误。Linux 上类似。解决办法有两个一是用虚拟环境python -m venv二是用 pipx。我个人的选择是 pipx因为虚拟环境还要手动 activatepipx 装完直接就能用省事。如果非要用 pip至少加--userpip install --user --upgrade some-agent-cli这样装到用户目录不需要 sudo升级也不会动系统包。Python 系工具对照安装方式安装命令版本查询升级命令隔离性pipxpipx install xxxxxx --versionpipx upgrade xxx好pip --userpip install --user xxxxxx --versionpip install --user --upgrade xxx一般pip 全局pip install xxxxxx --versionpip install --upgrade xxx差5. 版本查询的三种姿势与“查不到”的排查链路版本查询看起来是最简单的动作但实际用起来--version查不到的情况非常常见。这一节把排查链路完整走一遍。5.1--version、-v、version子命令的区别不同工具对版本查询的支持不一样大多数工具支持--version或-V。有些工具用-v表示 verbose详细输出不是版本。少数工具用子命令tool version。还有的工具压根没有版本命令只能通过包管理器查。所以第一步是试--version不行再试-V再不行试version子命令。如果都不行用包管理器查npm list -g --depth0 | grep 工具名 pipx list | grep 工具名 pip show 工具名5.2 命令找不到时的 PATH 排查command not found是最常见的报错。排查顺序确认装没装npm list -g --depth0或pipx list。确认 bin 目录在不在 PATHecho $PATH。找到可执行文件实际位置npm bin -g或pipx environment。把对应目录加到 PATH。以 npm 为例npm bin -g会输出全局 bin 目录把这个目录加到~/.bashrc或~/.zshrcexport PATH$(npm bin -g):$PATH然后source ~/.zshrc生效。5.3 多版本共存时的版本确认如果同一个工具装了多个版本比如系统里有一个nvm 环境里有一个which 工具名会告诉你当前用的是哪个。想确认所有版本which -a 工具名这条命令会列出 PATH 里所有同名可执行文件。然后逐个--version就知道哪个是哪个了。提示多版本共存时PATH 里靠前的目录优先。想切换版本要么改 PATH 顺序要么用绝对路径调用。6. 升级失败的四个典型场景与修复方案升级失败比安装失败更让人头疼因为安装失败你知道是没装上升级失败可能是“装上了但没生效”“升了但版本没变”“升完反而坏了”。下面四个场景我都实际遇到过。6.1 升级后版本号没变最常见的原因升级命令跑成功了但 PATH 里优先命中的是旧版本。比如你用 npm 升了全局包但 PATH 里/usr/local/bin排在 npm 全局 bin 前面而/usr/local/bin里有一个旧的软链接。排查which -a 工具名看第一个命中的是哪个路径。然后ls -l看那个路径是不是软链接指向哪里。如果是旧版本删掉旧软链接或者调整 PATH 顺序。6.2 权限错误导致升级中断EACCES或Permission denied是升级时的常客。根因是全局目录需要写权限而当前用户没有。解决方案按推荐顺序用 nvm 管理 Node全局包在用户目录无权限问题。配置 npm 全局前缀到用户目录npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH。用 pipx 代替 pip 全局安装。绝对不要用sudo npm install -g或sudo pip install那样装出来的包属主是 root后续升级和卸载都会出问题。6.3 依赖冲突导致升级卡住Python 系工具升级时如果依赖冲突pip 会报一堆Cannot uninstall或ResolutionImpossible。这时候 pipx 的优势就体现出来了——每个工具独立环境升级时不会跟别的工具打架。如果已经在用 pip 全局装遇到依赖冲突最干净的解法是卸载重装。pip uninstall 工具名 pip install --user 工具名卸载重装比硬解依赖冲突省时间而且结果更可控。6.4 网络问题导致下载失败npm 和 pip 默认走官方源国内网络环境下可能超时。换源npm config set registry https://registry.npmmirror.com pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple换完源再升级成功率会高很多。注意换源只影响下载不影响工具本身的功能。7. 九款工具速查表与我的实际使用建议把前面散落的信息汇总成一张速查表方便对照。序号工具安装方式安装命令版本查询升级命令1Claude CLInpmnpm i -g anthropic-ai/claude-codeclaude --versionnpm i -g anthropic-ai/claude-codelatest2Codex CLInpmnpm i -g openai/codexcodex --versionnpm i -g openai/codexlatest3MiniMax Code CLInpmnpm i -g minimax/code-climinimax --versionnpm i -g minimax/code-clilatest4Obsidian CLI二进制下载解压后mv到 PATHobsidian --version下载新版覆盖5通用二进制工具 A二进制同上tool --version覆盖或自带 update6通用二进制工具 B二进制同上tool --version覆盖或自带 update7Python 工具 Apipxpipx install xxxxxx --versionpipx upgrade xxx8Python 工具 Bpipxpipx install xxxxxx --versionpipx upgrade xxx9Python 工具 Cpip --userpip install --user xxxxxx --versionpip install --user --upgrade xxx几点实际使用建议第一优先用 pipx 装 Python 工具。我早期用 pip 全局装后来系统 Python 升级一堆工具全挂了重装花了大半天。换 pipx 之后系统 Python 怎么升都不影响工具。第二npm 全局包用 nvm 管理 Node。nvm 环境下全局包在~/.nvm/versions/node/vX.X.X/bin升级 Node 版本时全局包会跟着走不会丢。而且不需要 sudo权限问题天然不存在。第三独立二进制工具记好安装路径。我习惯统一放到/usr/local/bin升级时直接覆盖不用到处找。如果工具自带 update 命令优先用自带的省得手动下载。第四升级前先查当前版本。工具名 --version记下来升级后再查一次对比确认真的升上去了。我见过太多次“升级命令跑成功但版本没变”的情况不对比根本发现不了。第五遇到unable to locate the codex cli binary这类报错先清缓存再重装。npm 的缓存有时候会存坏包npm cache clean --force之后重装成功率明显提升。最后分享一个我自己的习惯每装一个新 CLI 工具就在笔记里记一行——工具名、安装命令、版本查询命令、升级命令、安装路径。下次升级直接翻笔记不用重新查文档。这个习惯帮我省了大量时间尤其是工具多起来之后根本记不住每个的包名和命令。
阅读完成 · 觉得有帮助？
