文章

在 macOS 上补齐 Codex、Claude、Copilot 终端 CLI，并顺手解决 Homebrew 安装慢

记录一次在 macOS 上为 Codex、Claude、Copilot 补齐终端命令入口的排障过程，以及如何顺手解决 Homebrew 安装慢的问题。

2026年5月12日

title: 在 macOS 上补齐 Codex、Claude、Copilot 终端 CLI，并顺手解决 Homebrew 安装慢 pubDate: 2026-05-02 description: 记录一次在 macOS 上为 Codex、Claude、Copilot 补齐终端命令入口的排障过程，以及如何顺手解决 Homebrew 安装慢的问题。 tags:

macOS
CLI
Homebrew
Node.js
AI Tools

最近在一台 macOS 开发机上配置几个常用的 AI 命令行工具，表面上看都是同一种报错：

Error: codex is not installed
Error: claude is not installed
Error: copilot is not installed

但真正动手排查后会发现，这三类问题的根因其实并不一样：

有的是工具已经存在，只是终端里没有稳定的命令入口。
有的是安装脚本下载了二进制，但没有真正落地到可执行路径。
有的是 CLI 已经安装成功，但运行时版本不满足要求。

这篇文章把这次处理过程整理成一份可复用的排障记录。

问题一：Codex 已存在，但终端仍提示未安装

先看 codex。

终端里直接执行：

which codex
codex --version

最开始的结果很容易让人困惑：系统里其实已经有一份 codex，但它来自 VS Code 扩展目录，不一定能作为稳定的全局终端命令使用。

排查时可以重点看两件事：

codex 是否真的在 PATH 里。
全局安装后，npm 是否创建了 /usr/local/bin/codex 这样的命令入口。

官方安装方式是：

npm i -g @openai/codex

这次安装完成后，包本身已经进入全局 npm 目录，但 /usr/local/bin/codex 没有被正确创建。继续查看包定义后，能确认可执行入口实际在：

/usr/local/lib/node_modules/@openai/codex/bin/codex.js

所以最终修复方式很简单，补一个标准软链接：

ln -sf /usr/local/lib/node_modules/@openai/codex/bin/codex.js /usr/local/bin/codex

然后再验证：

zsh -lic 'which codex && codex --version'

验证通过后，codex 就能在普通终端里稳定使用了。

问题二：Claude 安装脚本下载了文件，但命令仍不可用

claude 的情况更有迷惑性。

官方 Quickstart 推荐的是安装脚本方式，但这次执行后，下载产物只落到了：

~/.claude/downloads/claude-2.1.126-darwin-x64

也就是说，主程序下载下来了，但命令入口没有完成配置。进一步尝试直接把这份文件放进 /usr/local/bin 后，又会遇到另一个问题：它在当前机器上表现为未签名二进制，直接运行并不稳定。

这时候最稳的做法不是继续和那份下载文件较劲，而是看本机是否已经存在可用的官方 Claude Code 二进制。结果发现，VS Code 扩展目录里就有一份能正常运行的版本：

/Users/用户名/.vscode/extensions/anthropic.claude-code-2.1.126-darwin-x64/resources/native-binary/claude

直接把终端入口指向它：

ln -sf /Users/用户名/.vscode/extensions/anthropic.claude-code-2.1.126-darwin-x64/resources/native-binary/claude /usr/local/bin/claude

再验证：

zsh -lic 'which claude && claude --version'

这样处理的好处是改动小，而且不需要额外改 shell 配置。

需要注意的是，这种方式依赖 VS Code 扩展路径。如果以后升级或卸载 Claude Code 扩展，这个软链接可能需要重新指向新的版本目录。

问题三：Copilot 安装成功，但运行时报 Node 版本过低

copilot 这次是最典型的“安装成功但不能用”。

先按官方页面安装：

npm install -g @github/copilot

安装本身没有问题，但执行 copilot --version 时会直接报：

GitHub Copilot CLI requires Node.js v24 or higher. Currently using v22.22.2.

这说明根因已经非常明确了：

CLI 包安装成功。
当前系统默认 node 版本过低。

处理这个问题时，我不建议直接把系统默认 Node 替换掉，尤其是在已经有其他项目依赖现有 Node 版本的情况下。更稳妥的做法是安装一份隔离的 node@24：

brew install node@24

node@24 是 keg-only，不会直接覆盖当前默认 Node。装好之后，再用它自带的 npm 重新安装 Copilot CLI：

/usr/local/opt/node@24/bin/npm install -g @github/copilot

这样 /usr/local/bin/copilot 会由官方安装流程自己创建，而运行时也满足要求。

最后验证：

zsh -lic 'which copilot && copilot --version'

这样既解决了 Copilot 的版本要求，又没有破坏系统现有的 Node 22 环境。

顺手处理：为什么 `brew install` 会感觉特别慢

在安装这些工具的过程中，很容易顺手发现另一个常见痛点：brew install 很慢。

这台机器上的主要原因其实很直接：

没有给 Homebrew 配置代理。
每次安装前都会先自动更新。

如果本地已经有可用代理，最省事的处理方式不是先折腾镜像，而是先把代理和免自动更新加到 shell 配置里。

例如在 ~/.zshrc 中加入：

export http_proxy="http://127.0.0.1:6478"
export https_proxy="http://127.0.0.1:6478"
export all_proxy="socks5://127.0.0.1:6478"
export HOMEBREW_NO_AUTO_UPDATE=1

如果还顺便维护国内常用包管理源，也可以一起放进去：

export NPM_CONFIG_REGISTRY="https://registry.npmmirror.com"
export PIP_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"

然后用新的登录 shell 验证：

zsh -lic 'printf "http_proxy=%s\nhttps_proxy=%s\nall_proxy=%s\nHOMEBREW_NO_AUTO_UPDATE=%s\n" "$http_proxy" "$https_proxy" "$all_proxy" "$HOMEBREW_NO_AUTO_UPDATE"'

这样做的效果通常很直接：

Homebrew 不会在每次安装前先跑一轮自动更新。
访问国外资源时会直接走本地代理。
brew install、npm install、pip install 的体验都会明显顺很多。

一个更通用的排查思路

这次配置下来，一个很有用的结论是：不要把“命令不可用”直接理解成“软件没有安装”。

更稳妥的排查顺序通常是：

先看命令是否真的不存在：

which 命令名
命令名 --version

再看它是不是只存在于某个扩展、IDE 或私有目录里。
如果用了 npm install -g，检查全局包是否真的安装成功，以及 bin 入口有没有被正确创建。
如果命令执行时报错，再区分是签名问题、权限问题，还是运行时版本问题。

尤其是 Node 生态下的 CLI，最容易遇到的并不是“装不上”，而是：

包已安装，但命令链接没创建。
命令存在，但脚本路径不对。
运行时 Node 版本不满足要求。

把这几个层次分开之后，很多问题都会从“看起来很玄学”变成“其实很好修”。

最终状态

处理完成后，这台机器上的三个命令都已经能在新终端里直接使用：

codex --version
claude --version
copilot --version

同时，Homebrew 和常见包管理器也已经默认带上代理，安装体验比之前顺畅很多。

如果你也在配置一台新的 macOS 开发机，遇到类似的“明明装了，但终端还是说没装”，建议优先从命令入口、真实二进制位置和运行时版本这三个方向排查，通常会比反复重装更快。